Membo

A local-first, persistent project context layer that multiple AI coding agents share over MCP.

Git answers what the code is. Nothing answers what the project is — what is being built, why, what was decided, what is blocked, what happens next. So every new session starts with the user re-explaining the project to yet another agent.

Membo is an MCP server holding a project knowledge graph on your machine. Claude works on a project and stops; Codex connects to the same server, calls one tool, and has the current task, the architecture, past decisions, blockers, recent sessions, and the next action. No re-explaining.

Everything runs locally. Nothing is uploaded.

Install

pipx install /path/to/membo     # or: uv tool install /path/to/membo

Then, once per project, from inside it:

membo init

That writes the memory server into that project's .mcp.json (merging, so your other MCP servers are left alone) and creates .memory/. Restart your agent and it is connected.

The first context_load on a fresh project returns instructions telling the agent to seed itself: read the repo for what it can verify, then ask you for what it cannot. Point your agent at AGENT_PROTOCOL.md for the full lifecycle.

Tools

How it stores things

<project>/.memory/memory.db — SQLite, a generic nodes + edges graph. Per project, so it is committable, shareable with teammates, and it moves with the repo.

<project>/.memory/*.md — PROJECT.md, ARCHITECTURE.md, DECISIONS.md, BUSINESS_RULES.md, TASKS.md, KNOWN_ISSUES.md, SESSIONS.md, CURRENT_STATE.md. Generated from the DB after every write, never edited by hand. One-way DB→markdown, so there is no dual-write drift: humans read the markdown, agents read the graph, only one side is writable.

Two rules keep it honest:

• Git is read live, never ingested. context_load shells out to git on each call. Zero storage, never stale, git stays authoritative.
• Stated is not observed. Every node is observed (derived from git/files) or stated (an agent's assertion). Stated nodes render as _(stated)_, so a claim is never mistaken for a fact.

What it deliberately does not do

No AST parsing, no code graph. code-review-graph already does that well, incrementally, over MCP. Membo is the layer above: tasks, decisions, business meaning, history, handoffs. When the two are joined (by file path) you get code understanding and project intent; today they are separate servers.

Check

.venv/bin/python -m membo.selfcheck