memdex

Shared, token-saving memory for AI coding agents. Zero dependencies, one SQLite file, any MCP client.

한국어 README

Every new agent session starts from nothing: it re-reads the same files, re-runs the same searches and re-discovers the same pitfalls. When several agents (Claude Code, Codex, Cursor, DeepSeek, …) work on one machine, they also can't see what the others learned or are doing right now.

memdex fixes that with a small MCP server:

Measured on a real 800-file TypeScript repo: a 144 KB source file → 1.6 KB file_summary response (outline only, before any agent summary was saved).

Install

pipx install memdex-mcp        # or: pip install memdex-mcp

The PyPI name is memdex-mcp (plain memdex was taken); the command, package and MCP server are all memdex. From source: pipx install git+https://github.com/ChoYugyeong/memdex or pip install -e . in a checkout.

Python 3.9+. No other dependencies — the MCP stdio protocol is implemented directly, so it won't break across MCP SDK versions.

Connect your agents

memdex config --agent <name> prints these snippets.

Claude Code

claude mcp add memdex --scope user -e MEMDEX_AGENT=claude -- memdex serve

Optional: inject the brief at every session start (~/.claude/settings.json):

{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "memdex hook session-start --agent claude" } ] } ] } }

Any other MCP client (Claude Desktop, Cursor, Codex, Windsurf, DeepSeek harness, …)

{ "mcpServers": { "memdex": { "command": "memdex", "args": ["serve"], "env": { "MEMDEX_AGENT": "codex" } } } }

Give each agent its own MEMDEX_AGENT name. Its full id becomes name@checkout, e.g. claude@myrepo-wt.

Tools

The server sends usage instructions in its MCP initialize response, so agents know the workflow without extra prompting. The 12 tool schemas cost about 1,000 tokens per request.

CLI

Everything the MCP tools do is also a command, for shell-capable agents and for humans:

memdex brief --agent codex              # start of session: handoff, notes, inbox, claims
memdex file src/store.py                # cached summary + outline
memdex file src/store.py --summary "…"  # save a summary
memdex snippet src/store.py --query "def index"
memdex search "locked"
memdex remember pitfall "WAL mode needed" --body "…" --files src/store.py
memdex claim src/store.py --intent "refactor"
memdex post "store.py is mine for an hour" --to claude
memdex inbox
memdex handoff "Done X" --next "Y" --pitfalls "Z"
memdex index · memdex export --out notes/ · memdex stats

Where data lives

Everything is in ~/.memdex/memdex.db (override with MEMDEX_HOME). Nothing is written into your repositories, so memory never ends up in a commit. Files that look like secrets (.env*, *.pem, *.key, *secret*, *credential*, …), binaries, lockfiles, files over 512 KB and anything git ignores are never read.

A project is identified by its git common directory, so all worktrees of a repository share notes, messages and claims, while each worktree keeps its own file index.

Kensaku integration (optional)

Kensaku is a local, read-only desktop search engine that indexes file names, the full text of PDF/DOCX/EPUB, OCR'd screenshots and a semantic tier. memdex covers a project's source; Kensaku covers the rest of the machine. If kensaku-cli is on PATH (or MEMDEX_KENSAKU points to it), search appends Kensaku's content hits, scoped to the project unless everywhere is set. MEMDEX_KENSAKU=off disables it.

Semantic search (optional)

ollama pull bge-m3
export MEMDEX_EMBED=ollama:bge-m3   # MEMDEX_OLLAMA_URL defaults to http://localhost:11434

Notes and summaries get embedded when saved; search merges keyword and vector rankings. If Ollama is unreachable, memdex silently falls back to keyword search.

Development

python -m unittest discover tests

License

MIT