Metadata-Version: 2.5
Name: membo
Version: 0.1.0
Summary: Local-first persistent project context layer shared by AI coding agents over MCP
Project-URL: Homepage, https://github.com/amey-kadam/membo
Project-URL: Repository, https://github.com/amey-kadam/membo
Project-URL: Issues, https://github.com/amey-kadam/membo/issues
Author: Amey Kadam
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,context,knowledge-graph,mcp,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: mcp
Description-Content-Type: text/markdown

# 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

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

Then, once per project, from inside it:

```bash
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](AGENT_PROTOCOL.md) for
the full lifecycle.

## Tools

| Tool | |
|---|---|
| `context_load(task?)` | The handoff. Focus task + one hop out + blockers + rules + last sessions + live git. Not the whole graph. |
| `recall(query)` | Text search across memory. |
| `graph_query(name, depth)` | Why does this exist, what depends on it, what does it block. |
| `remember(type, name, body, ...)` | Record context. The single write path. |
| `task_update(name, status)` | todo / doing / blocked / done. |
| `session_end(summary, touched, next_action)` | The handoff record. |

## 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](https://github.com/tirth8205/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

```bash
.venv/bin/python -m membo.selfcheck
```
