Sinapt: The Architecture Before the Code

This is research in progress.

The first three Sinapt pieces did the manifesto work: the original synthesis named the cockpit fatigue, the second piece split the knowledge base from the future cockpit, and the third framed the market as the queryable company. Teams can lack a consistent, authorized retrieval interface across their tools. Agents then spend work reconstructing context that already exists elsewhere.

This is not that argument again.

This is the build update after several architecture passes. Two layers are now locked: the retrieval layer and the contract surfaces. The PoC has not run. Dogfood has not run. Nothing here is a victory lap. But the architecture has stopped being hand-wavy in the places where hand-wavy kills the product.

The hard part is not picking a vector database. That is the part everyone wants to argue about because it is legible. Pinecone, Weaviate, Turbopuffer, pgvector, OpenSearch, Qdrant. Fine. Useful debate. Not the core.

The hard part is making a company's knowledge retrievable by agents without leaking what they should not see, while exposing the right contracts to the right callers.

That is the product.

The proposed pipeline keeps canonical Markdown in S3 and derivative content and embeddings in Turbopuffer. Each external processor and retained derivative needs its own documented retention, deletion and training-use policy. Query-time authorization is one boundary; ingestion, derived records and revocation are others.

The design requires Aurora to compile the effective authorization filter before retrieval returns candidates. Only authorized candidates may reach the reranker or generator, and the audit must identify the policy state used. These are requirements to test in the PoC, not evidence that the unfinished system already enforces them.

Four surfaces, one policy compiler, no exceptions. The roadmap below maps Layer 2 (search engine) and Layer 5 (contract surfaces) — the two layers locked in this Phase 1 architecture lock-in — against the eight pending layers that complete the full build plan.

Retrieval Quality Is Not an MVP Upgrade

In the second Sinapt post, QMD was still the candidate cloud engine. That was correct for the thinking stage and wrong for the product stage. The architecture has moved.

Sinapt's cloud retrieval layer is now a Floor 4 RAG stack, in the language of RAG, From Crayons to PhD: hybrid retrieval, dense embeddings, reranking, contextualization, evaluation, permissions, and audit as one system. Not a vector search endpoint with a logo.

Quick gloss for the technical terms ahead. RAG = retrieval-augmented generation — the standard pattern of "search a knowledge base, hand the top results to an LLM, let it answer." Floor 4 in the Crayons-to-PhD framework names Sinapt’s proposed configuration: hybrid keyword + vector search, a reranker, and contextual retrieval at indexing time. Each component targets a different failure mode. The PoC must compare this configuration with simpler baselines and show which additions earn their latency and cost.

The public shape is locked:

• Turbopuffer — the proposed search engine. Run BM25 keyword and vector similarity queries, then combine their rankings with reciprocal rank fusion in the application. A namespace per tenant separates document/index containers. Turbopuffer documents separate indexes and object-storage prefixes, while its service normally shares compute across tenants. Namespace selection and per-document authorization still need enforcement and testing; this is not a guarantee against cross-tenant mistakes.
• Voyage voyage-3-large — the proposed embedder. Embeddings map text into vectors so similarity search can find related wording. The selected dimensions and model must be recorded in the evaluation; a model choice does not establish best-in-class retrieval for the Sinapt corpus.
• Voyage rerank-2.5 — the proposed second-pass ranker. It scores the query together with each authorized candidate and reorders the returned set. The PoC will measure whether that improves useful source retrieval; a reranker cannot guarantee the correct chunk lands first.
• Claude Haiku 4.5 — the proposed contextualizer and optional query rewriter. Anthropic’s September 2024 contextual-retrieval study reported a 49% relative reduction in top-20 retrieval failures for contextual embeddings plus contextual BM25, from 5.7% to 2.9%; adding its tested reranker reduced failures by 67%, to 1.9%. These were vendor experiments using their stated datasets and configurations, not Sinapt results or a measurement of this Haiku/Voyage stack. Contextual summaries and query rewrites must retain provenance and stay within the authorization of their source material.
• Amazon S3 — the proposed canonical Markdown corpus. Derivative indexes can be rebuilt from it, but S3 is not the only durable copy when an index stores content elsewhere. Encryption at rest protects a storage boundary; it does not prove what downstream model or indexing services retain or use for training. Training-use promises require verified provider terms, configuration and data-flow evidence across every processor.
• Aurora PostgreSQL Serverless v2 — the control plane. The boring database that owns the dangerous data: tenants, users, group memberships, collection ACLs, policy state, audit log. The retrieval engine never owns permissions. Aurora compiles the ACL filter (ACL = access control list — the rules for who can see what) for every query before it touches Turbopuffer.
• ECS Fargate, SQS, and EventBridge — the runtime plumbing. Fargate runs the REST + MCP services as containers without managing servers. SQS is the job queue for ingestion work. EventBridge fires events when sources change (a GitHub PR merges, a Linear ticket gets archived, a Granola transcript drops). Same deploy shape for one user and for enterprise — no "scale by rewriting."

That list is not meant to impress anyone. It is there because architecture without named parts is usually theater. The point is the retrieval shape, not vendor worship.

The unit Sinapt has to return is not "a similar chunk." It is the right chunk, from the right source, under the right permission boundary, with enough surrounding context for an agent to act on it and enough audit trail for a company to explain why it was visible.

This is why retrieval quality cannot be deferred to "after MVP." For a normal SaaS product, the first version can have a rough search box. Users forgive it because search is an accessory. In Sinapt, retrieval is the work. The daily user is not a human browsing pages. The daily user is an agent deciding whether a design decision exists, what the current policy says, which customer constraint matters, whether a code change violates a prior decision, or what happened in the meeting nobody wrote up.

Bad retrieval does not feel like bad search. It feels like a smart agent making a bad decision with confidence.

Retrieval shape is the moat. The engine is the commodity. Sinapt's job is not to ship the world's fastest vector database. Its proposed retrieval contract combines hybrid search, reranking, contextual retrieval, ACL-aware filtering and audit. The vendors are replaceable; retrieval stages must earn their slots in evaluation. Authorization and audit remain acceptance requirements even if a simpler search configuration performs better.

So the PoC does not get to pass because it can answer a few friendly demo questions. It has to run against a golden set from my own corpus, with QMD as the local baseline. If the cloud layer cannot match the local engine on the corpus that created Sinapt in the first place, the architecture is not ready to become a company product.

Permission-Aware Retrieval Is the Hard Part

The central invariant is simple:

You cannot leak a chunk the user was not allowed to read.

Everything else is implementation detail around that sentence.

The obvious failure mode in agentic RAG is to retrieve broadly, rerank broadly, and then filter late. That is wrong. If the reranker sees unauthorized chunks, the system has already failed. Maybe it does not return them. Maybe the final answer omits them. It still processed knowledge the caller was not allowed to access. In a real company, that is not a harmless internal detail. That is a permission leak with better UX.

Sinapt's retrieval path is locked around the opposite order.

1. Caller identity arrives. The request shows up with everything the policy compiler needs to know: user, workspace, tenant, which surface (MCP / REST / CLI / Web UI), requested scope, and whatever delegated authority applies to that request.
2. Aurora compiles the effective permission set. The control plane turns the caller's identity plus organization state plus source-level / collection-level / document-level ACLs into a single retrieval filter the engine can enforce. I'm not publishing the schema or compiler internals, but the responsibility is clear: produce one filter that captures every rule that applies to this caller right now.
3. Apply the filter to retrieval before candidates are returned. Unauthorized content must not enter the returned candidate set, downstream reranking, generation or caller-visible traces. The storage engine may still maintain shared internal structures; the enforceable boundary is authorized output and processing, not a claim that its internals never touch any other indexed data.
4. Voyage reranking only sees authorized candidates. The reranker can be very good at ranking quality because the policy layer has already reduced the world to what this caller can actually read. Quality and authorization are the same path, not two tracks.
5. The request is audited. Not as a compliance afterthought, but as part of the control plane: who asked, through which surface, under which scope, which sources were eligible, which chunks were used, what answer path was taken. The audit log is queryable — both for the customer's own compliance review and for debugging "why did I see this / why did I not see this."

That is the Glean invariant worth copying: the permission filter sits before retrieval. Search quality and authorization are not independent tracks. They are one path.

This also changes how query rewrite works. A model can help expand a vague query into something retrievable. It can add synonyms. It can infer that "the thing we decided in the April planning call" probably means a meeting transcript, a Linear thread, and a planning doc. But rewrite cannot become a jailbreak against scope. Haiku's job in the locked design is contextualization and policy-gated rewrite, not free-form exploration of the whole tenant.

The architecture has to assume agents will ask broad questions. That is their job. "Prepare me for this customer call." "Find every prior decision about billing." "Tell me what I need before touching the auth service." Those are not neat search queries. They are work requests. The system has to translate them into retrieval without letting broad language become broad access.

Four Surfaces, One Authorization Spine

The second locked layer is the surface contract. This matters because I got closer to the trap while designing Sinapt than I want to admit.

The trap is treating MCP as the universal API because MCP is exciting and agents are the primary users. That is almost right, which makes it dangerous.

Sinapt’s surface split is a product choice, not a protocol law: REST for durable integrations and MCP for agent tooling, backed by the same authorization layer.

The proposed remote MCP service uses Streamable HTTP with scoped authorization under the applicable MCP authorization specification. MCP clients can run in a headless service as well as an interactive agent. For this hosted deployment, stdio is reserved for local development and adapters; it is not inherently forbidden in production systems.

For the PoC, the MCP catalog is intentionally small. The MCP protocol defines three primitives a server can expose to AI clients: tools (actions the agent can invoke — create issue, search, send message), resources (named bits of content the agent can read — a document, a chunk, your audit log), and prompts (reusable prompt templates the server suggests for common workflows). Sinapt's PoC ships four tools: sinapt_answer, sinapt_retrieve_context, sinapt_prepare_agent_brief, and sinapt_save_note. The MVP target is eight tools, six resources, and four prompts. There is a hard catalog budget because bad MCP servers become tool junk drawers — eighty-seven vaguely-named tools are worse than four sharp ones, because the model spends context window searching the menu instead of solving the problem.

Sinapt chooses REST for CI jobs, scheduled workers, services, the CLI and web administration. The contract will specify schemas, typed errors, versioning and retry-safe operation identifiers, with OpenAPI-generated clients where appropriate. MCP applications also need explicit retry and idempotency semantics; choosing a transport does not supply those guarantees by itself.

A background program can own an MCP client independently of any chat. Sinapt nevertheless chooses REST for integrations that outlive an interactive session so their lifecycle and application contract are explicit. The same authorization rules must apply on both paths.

The CLI consumes REST. sinapt mcp serve exists only as a local-development stdio proxy for tools that need that shape. It is not the production architecture.

The web UI owns admin, curation, billing, and audit. It is not the daily query path. This was already the direction in the previous Sinapt posts, but the surface lock makes it stricter. Humans need a place to inspect collections, review sources, invite teammates, configure billing, and understand why an answer cited what it cited. That does not make the web app the product. The product is the knowledge layer agents call.

The important part: all four surfaces share one Aurora policy compiler.

MCP does not get its own authorization logic. REST does not get a looser path because "it is internal." The CLI does not bypass policy because it feels local. The web admin does not query a side channel because it is convenient.

Surfaces differ in presentation; authorization is uniform.

That sentence is the architecture. The rest is plumbing.

The Loop, the Connectors, and the Open Merge Problem

Two design details shown in the diagrams deserve further explanation.

Pluggable connectors, not a fixed list of six

The six connectors shown — Slack, Granola, GitHub, Linear, Notion / Drive, Filesystem / Gmail — are examples, not the full list. Layer 6 of Sinapt's architecture is the connector framework: a source / sink abstraction (each integration implements a contract), an event-handling pattern (webhook receivers vs polling workers vs scheduled jobs), and a workflow engine that orchestrates ingest jobs. New source types — Confluence, Zendesk, S3 buckets, custom internal databases, whatever — plug into the same shape: emit canonical markdown, declare ACL semantics, register on the event bus. The PoC starts with one trivial connector (filesystem watcher); the MVP adds GitHub + Slack + Linear; later phases add the rest. The architecture is not "Sinapt supports these six things." It is "Sinapt is the framework these six things plug into, plus the next sixty."

Ingest is a loop, not a pipeline

The diagram shows arrows flowing top-down — sources → S3 → chunker → embedder → Turbopuffer → reranker → authorized chunks. That is half the truth. The actual system is a cycle, not a pipeline.

Agent notes, proposed patches and archived summaries re-enter the ingest pipeline as derived content. Every derived record must retain the source revision and permission provenance. Its permitted readers must be no broader than the intersection allowed by its inputs unless an authorized declassification process explicitly changes that boundary.

That feedback loop is a proposed governed write path. Source deletion or permission revocation must propagate to derived summaries, chunks, indexes, caches and later retrievals. Until current authorization and dependency state can be established, affected content must fail closed. The PoC needs tests for revocation races and mixed-permission summaries; no implemented leak or completed permission guarantee is asserted here.

And the open problem that creates: multi-writer merge

Here is the honest part. We do not have a merge story yet.

In code, multiple people working on the same file is a solved problem — git gives us branches, three-way merges, blame, pull requests, review queues. The discipline is decades old. In a canonical-markdown KB written to by both humans and agents, none of that infrastructure exists out of the box. Two agents in two sessions both decide to update the same architecture decision doc. A Slack reindex refreshes a thread-derived section while an agent rewrites the same section as policy guidance. An admin in the Web UI edits a heading while a CLI script is mid-patch. Last-writer-wins is acceptable for a cache; it is not acceptable for canonical knowledge.

The plan in three phases — honest about what is deferred:

PoC: keep canonical writes minimal. sinapt_save_note is append-only with full provenance (session, agent identity, timestamp, citations). Agents never overwrite canonical docs. Connector ingests update source mirrors only. The merge problem is avoided, not solved.

MVP: sinapt_propose_doc_patch becomes the primary write path. Every patch targets a base revision, a section anchor, and a source revision vector. Optimistic locking: if the base still matches when the patch arrives, apply it; if not, attempt a structured merge at the heading level; if the same claim changed both ways, surface a conflict for human review in the Web UI. Auto-apply only fresh, non-overlapping, low-risk patches.

Production: canonical markdown lives in Git underneath. Sinapt does not expose Git ceremony to agents — Git handles the version mechanics (commits, merge bases, branches, blame, reverts, conflicts) and Sinapt provides the agent-native review layer. Important docs have explicit owners. Trivial edits auto-merge. High-stakes content goes through human review.

Retrieval and governed editing are separate capabilities. A useful comparison asks which writes each product permits, which revision preconditions it checks, what happens on concurrent edits, and how an operator audits or repairs a conflict. Sinapt has to answer those questions for its proposed canonical Markdown layer; a search integration alone does not answer them.

Sinapt’s agent-written merge policy remains an open design problem. These requirements do not establish that no other product has solved it.

QMD Became the Teacher, Not the Engine

QMD deserves a clean correction because it shaped the original Sinapt thinking.

QMD here means the existing open-source tobi/qmd project. Its upstream documentation describes local BM25 keyword search, vector search, query expansion, rank fusion and reranking. A selected evaluation mode must be named explicitly; the project as a whole is not a pure-BM25 engine.

But QMD is no longer the Sinapt cloud engine.

Its role is now threefold.

1. Local Markdown retrieval. The existing tobi/qmd project provides keyword search through qmd search, semantic search through qmd vsearch, and hybrid retrieval with reranking through qmd query. Record the version, models and chosen command when using it as a baseline.
2. Evaluation baseline for the PoC. Use the same authorized corpus and independently labeled questions to compare configurations. QMD results are a baseline, not ground truth: expected sources, answer criteria, authorization cases and abstention behavior must be judged separately. Include both keyword-only and hybrid modes if the comparison needs to isolate their contributions.
3. Possible Sinapt-specific open-source artifacts. A future release could contain original adapters, configuration or evaluation tooling created for Sinapt, with upstream attribution and applicable licenses preserved. QMD itself is already open source; this is not a proposal to release someone else’s project as Sinapt’s own.

But the cloud engine is now the Turbopuffer + Voyage + Haiku + S3 + Aurora stack. That is the product path. QMD was the teacher.

Why This Is a Product, Not a Wrapper Around Five Vendors

Let's be honest about what's actually new here.

The individual components are available elsewhere. Notion’s enterprise-search documentation identifies Turbopuffer as a vector store for connected-app embeddings. Glean’s December 22, 2025 Vercel post already described a remote MCP server exposing permission-aware enterprise context to compatible clients. Its March 2026 MCP update expanded an existing offering. A vendor list is not a moat; the proposed Sinapt workflow still has to prove useful.

So what is?

The moat starts past the demo line — where every part of the stack still works but the integration breaks in ways that take quarters to fix. Three honest claims.

One: cross-source ACL propagation. A real company runs on a dozen permission models at once. Slack channel membership, GitHub org / team / repo grants, Notion page inheritance, Google Drive link sharing, Linear project roles, S3 bucket policies — these are different languages with different semantics. The moment a Slack message gets moved to a private channel, a GitHub repo gets archived, or a Notion page loses an editor, the retrieval layer has to know in seconds. Using a vector store or reranker does not by itself establish correct synchronization of source permissions. Sinapt must implement and test that mapping for its chosen components. Compiling source permissions into a unified query-time filter and keeping it fresh as ACLs change is an integration requirement to validate, whether Sinapt builds a component or adopts a managed capability.

Two: apply authorization before downstream retrieval results leave the trusted boundary. If unauthorized chunks reach a reranker, prompt or trace, filtering the final answer is too late. Filtering only after selecting a fixed top-K can also reduce the number of useful authorized results. Sinapt’s proposed invariant is that the reranker receives only chunks the caller may read. The design compiles the filter in Aurora and supplies it to Turbopuffer’s first-stage retrieval; revocation and failure tests must establish that the implementation enforces the rule.

Agent workflows may retrieve repeatedly while planning, editing and verifying. Measure the actual query frequency and context use instead of assuming a fixed agent-to-human ratio or an industry-wide retrieval-effort percentage. The proposed contract includes bounded tools, trace continuity, permission evidence and evaluation of recall, ranking and abstention.

The honest competitive landscape:

• Glean offers permission-aware enterprise search and agent integration. Sinapt aims to serve workflows where multiple agent runtimes use a neutral knowledge layer. That is proposed positioning, not a demonstrated win over Glean.
• Microsoft 365 Copilot — Microsoft’s connector gallery lists more than 100 prebuilt connectors from Microsoft and partners, including services outside Microsoft 365 (checked September 20, 2026). A mixed application stack alone is therefore not a distinction. Sinapt’s proposed comparison is a neutral knowledge contract usable by multiple agent runtimes; that advantage remains to be tested.
• Pinecone Nexus — Pinecone describes a context compiler and KnowQL for typed, cited answers over governed enterprise knowledge, with source-permission filtering. That overlaps with Sinapt’s retrieval goals. The comparison should test the particular canonical Markdown editing, cross-source permission and agent-runtime workflows Sinapt proposes, rather than infer missing capabilities from a product summary.
• Notion AI and its cross-source connectors can reach beyond Notion’s native pages. The proposed Sinapt distinction is a neutral canonical knowledge layer for multiple agent runtimes. Whether that distinction matters to customers remains to be tested. Agent skills package procedures; they do not by themselves implement this storage and authorization design.
• DIY RAG gives teams control but leaves integration, evaluation, permissions and operations to them. Sinapt’s hypothesis is that an owned retrieval contract can be useful across models; no unsupported industry abandonment percentage establishes that case.

The moat is operational, not algorithmic. It is made of integration scars, regression tests for permission bugs, connector freshness tickets, eval harnesses, and an audit trail that customers can replay during a security review. Strong for regulated, multi-source, agent-heavy teams. Weak for small teams with one document store and no ACL complexity — for them, off-the-shelf managed RAG is the right answer.

That is the honest sell. Sinapt is not a vector database with marketing. It is the data-and-policy product around the vector database — which is the part that actually takes years to get right.

The one-line answer

The moat is agent-first across multi-source data with permission rigor — three legs, all needed.

Pull any one leg out and Sinapt becomes a different product:

Without the agent-first focus, Sinapt would compete more directly as an enterprise search product. Traceability and permissions still matter for human search, and existing products can also expose agent interfaces.

Without a neutral multi-runtime layer, the design overlaps more closely with knowledge features inside established platforms. Notion’s connectors already reach several external sources; cross-source access alone does not establish Sinapt’s differentiation.

Without enforceable authorization before returned candidates reach downstream processing, the system risks exposing restricted material. Permission regressions, stale ACLs and derived-content propagation must be tested for every connector; a particular leak is not asserted as inevitable.

Sinapt proposes to address agent workflows, multiple sources and permission-aware retrieval together. That is the design hypothesis. The PoC and later usage must establish whether it works and whether the resulting product is useful.

Synthetic Tests Answer Quality. Dogfood Answers Economics.

The next trap is cost modeling.

Human-search RAG cost models are too optimistic for agent-first products. They assume a user asks a question, reads an answer, and maybe asks a follow-up. That is not how agents behave when the knowledge layer is good.

Agents call memory as part of work loops. They retrieve before editing. They retrieve before planning. They retrieve before answering. They retrieve during verification. They retrieve again when the first answer exposes a second question. A human might run ten searches in a day. An agentic workflow can run that in one task.

So the synthetic spike and dogfood have different jobs.

The three-day synthetic spike answers quality and safety:

• Proposed quality gate: at least 80% of the independently graded questions should return an accepted source among the top five chunks. Report corpus coverage and failure cases. Falling below that target does not force hallucination: a well-designed agent may abstain, request clarification or retrieve again.
• Proposed authorization gate: zero unauthorized chunks observed in the reranker, generator or caller-visible results across the tested cases. Any violation fails the gate. Passing a finite test suite is necessary evidence, not proof that all possible permission states are safe.
• Proposed median end-to-end latency target: under 500 ms, measured from request to response. Include network time, query embedding, optional policy-gated rewrite, authorization checks, hybrid retrieval and rank fusion, reranking and serialization. Report tail latency and separate paths with optional work. The target has not been measured, and a two-second response does not mechanically determine whether an agent uses the tool.

Those gates are intentionally boring. If the system cannot return the right context quickly and respect permissions absolutely, no pricing model matters.

The five-day dogfood answers economics. Not with public cost numbers. Not with launch pricing. Not with a spreadsheet dressed up as conviction. Pricing stays in exploring mode until real usage patterns exist.

The question is call frequency. How often does a useful agent actually hit Sinapt when there is no local fallback and the cloud layer is the source of truth? What does one day of real work cost when the agent is allowed to use memory naturally? Where does caching help? Where does reranking dominate? Which query classes need answer synthesis and which only need context retrieval? How much does policy compilation cost under repeated loops?

That is what dogfood is for.

For agent-first products, cost is not a human-search spreadsheet with a new logo. The economics model has to come from actual agent call frequency, not from a human-search baseline that systematically under-predicts.

Phase Shape From Here

The phase shape is still the same, but now with sharper boundaries.

Phase 1 is architecture lock-in. That is the current phase. Layer 2, the search engine, is locked. Layer 5, the contract surfaces, is locked. Other layers still need the same treatment before the PoC begins. I am not trying to hide unfinished work behind confident prose. Locked means locked. Pending means pending.

Phase 2 is the PoC spike and dogfood. Single user. My corpus. Zero local fallback. The point is to force the cloud layer to stand on its own. If it quietly leans on QMD, the test is meaningless. The PoC either retrieves the right context, respects permissions, fits the latency envelope, and produces real usage economics, or the architecture changes.

Phase 3 is MVP. Multi-tenant. Stripe. First connectors. Web admin. The contract surfaces become more complete. MCP expands to the small MVP catalog. REST gets the SDK path. The policy compiler stops being a single-user control plane and becomes company infrastructure.

Phase 4 is public launch.

That is deliberately restrained. The first three Sinapt posts made the case for why the product should exist. This one is about whether the architecture is becoming serious enough to deserve implementation.

The answer is partially yes. Retrieval is locked. Surface contracts are locked. The permission invariant is locked. QMD's role is clarified. The cost question has been reframed around agent frequency instead of human search.

But the system has not earned louder language yet.

This is research in progress. The next step is not a launch, not a manifesto, not a victory lap. It is the spike, then dogfood, with the local baseline removed and the architecture forced to answer the only question that matters:

Can Sinapt make a company's knowledge retrievable by agents without leaking what those agents should not see?