The problem
Project decisions and constraints become scattered across sessions when switching coding agents. The memory bus exposes a shared read/write service, reducing repeated context preparation while retaining provenance.
How memory moves through the system
One project memory across AI tools
Route writes and queries separately through MCP, keeping source events, retrieval indexes and readable views distinct.
AI clients
Codex, Claude Code and other MCP clients read project facts and experience through shared tool interfaces.
- Input
- Task and retrieval request
- Output
- MCP tool invocation
Retrieval is local by default; remote embedding backends receive the configured text.
Three data representations
| Representation | Responsibility | Use |
|---|---|---|
| JSONL events | Durable record of memory changes | Trace origins and history |
| Local index | Retrieval access | Combine BM25 and local vectors |
| Markdown | Human-readable derived view | Read in an editor or Obsidian |
Obsidian is an optional reading interface. Retrieval, bridging, consolidation and management have separate service responsibilities, exposed to clients through MCP.
Five lifecycle tiers
Working, Session, Project, Shared and Archive hold immediate context, session history, project knowledge, reusable facts and archived memory. Consolidation must preserve provenance so provisional assumptions do not silently become established facts.
Local and remote processing
Default retrieval combines BM25 with local hash embeddings. Configuring a remote embedding provider sends the relevant text to that service, so data scope is an explicit deployment choice.
This project is retained as an open-source technical asset. See the repository for capabilities, deployment and remote embedding configuration.
My work and design choices
I independently built this local-first MCP memory service, organizing recording, retrieval and source lookup so different coding clients can access shared project memory.
Separate persistent events, search indexes and reading views. JSONL keeps change history, indexes serve retrieval, and Markdown makes the content readable. Derived views can be rebuilt; maintenance must account for consistency with the event record and preserve provenance when editing a view.
Keep provenance and lifecycle. Temporary context, project decisions and archived information require different retention. Keeping the source and state when organizing memory helps a reader judge whether an older fact is still applicable.
Verification needs to include cross-client use. The public repository provides the implementation and setup instructions. This case does not supply independent results for concurrent clients, failure recovery or long-term retrieval quality. Data sent to remote embedding services depends on the actual configuration.