The Architecture Behind Memplex v0

Most "what we're building" posts are vague. This one isn't. Here's the actual architecture of Memplex v0, component by component.

The Desktop Agent

The capture layer of Memplex runs locally. It's a code-signed binary (macOS first, Windows and Linux to follow) that:

• Watches authorized source directories on the local filesystem
• Parses session artifacts from Claude Code and Codex CLI as they're written
• Extracts entities, decisions, and artifacts using a local extraction pipeline
• Writes structured memories to the Personal Graph

Why a local agent and not a cloud service:

• Latency: session ingestion happens at the speed of filesystem events, not network round-trips
• Privacy: raw session content never leaves the user's machine unless they explicitly choose to sync
• Resilience: the agent keeps working when the network doesn't

The agent is signed and auto-updates through a verified channel. The update mechanism itself is logged and inspectable.

The Personal Graph

The Personal Graph is the local store of structured memories. It's organized as:

• Entities — people, projects, decisions, artifacts, tasks. Each has typed fields and a confidence score.
• Edges — typed relationships between entities. "Decided by," "supersedes," "depends on," "owns," "blocks," etc.
• Lineage records — for every memory, a source artifact link, paragraph-level offsets where the source supports them, and a lifecycle state.
• ACL mirrors — for memories derived from connector sources (Phase B forward), a mirror of the source ACLs, revalidated at retrieval.

The graph is the substrate for all retrieval. It can be queried lexically (BM25 over the textual content), semantically (embeddings over entity descriptions and contents), and structurally (graph traversal over edges).

The Context Graph Explorer

The Explorer is the UI for the Personal Graph. It lets the user:

• Browse memories by entity, project, or time
• See lineage for any memory (click through to the source)
• Change lifecycle state (accept, verify, pin, revoke)
• Filter by source, scope, sensitivity
• Run ad-hoc queries

The explicit goal: the user can see everything Memplex sees. There is no hidden state. If a memory exists, the Explorer shows it.

Hybrid retrieval

Retrieval has three channels — lexical (BM25), semantic (embedding similarity), graph traversal — and a router that picks weights per query.

The router takes as input:

• The query text
• The task hint from the request
• The destination
• The scope and project

It outputs a retrieval plan: channel weights, filters, freshness windows, token budget allocation. The plan is executed against the graph. Results are merged, ranked, and trimmed to the token budget.

The plan is exposed via explain_inclusion so the user can inspect exactly how their query was reasoned about.

The MCP endpoint

Memplex exposes its retrieval surface as an MCP server. v0 ships three tools:

• search_context(query, scope, task_hint, destination, token_budget) — general-purpose retrieval. Returns a scoped pack with provenance.
• get_project_context(project_id, freshness_window, destination) — get the current state of a project: recent decisions, active artifacts, open questions.
• explain_inclusion(memory_id) — return the routing trace for a previously retrieved memory.

The endpoint runs locally by default, exposed to MCP clients on the same machine. Remote endpoints are a v1 feature; v0 keeps everything local-first.

What's intentionally not in v0

The temptation list, with explanations for why each is left out:

• Upload widget. Already covered elsewhere — autonomous ingestion or nothing.
• Plugin marketplace. Premature; we want to nail the core flow before opening up extensibility.
• Team / collaboration features. v0 is personal. Team graphs are a v1+ concern with significantly more complexity (shared scopes, cross-user ACLs, etc.).
• Mobile apps. Capture happens on the dev workstation. A mobile companion is interesting but doesn't unblock the core thesis.
• Custom embedding model. We use off-the-shelf embeddings. Training a specialized model is a v2 question, gated on whether we can prove the off-the-shelf models are actually limiting.
• Vector database. We don't need a separate one. The Personal Graph stores embeddings as fields on entities; retrieval is fast enough at the scales we care about.
• Chat interface. We are not building an AI assistant. We are building the substrate that AI assistants request context from.
• Notes UI. We are not a notes app. The Explorer is for inspection, not for free-form note-taking.

Each of these is a real tension. Each would expand the addressable use cases. None of them belong in v0.

What v0 is, in one sentence

A locally running context graph, populated autonomously from AI tool sessions and source connectors, queryable through three retrieval channels, exposed over MCP to any compatible AI client, with full lineage and per-destination scope enforcement.

That's the substrate. Everything else we build on top.