Memdex

memdex

Shared, token-saving memory for AI coding agents.

One SQLite file. Zero dependencies. Any MCP client. Claude Code, Codex, Cursor and DeepSeek can all remember the same things — and talk to each other.

Quick start · Adding agents · How it works · Tools · CLI · Configuration · Comparison · FAQ · 한국어

memdex is the memory coding agents share. One SQLite file, zero dependencies, no cloud. A session starts with what the last one left — summaries, decisions, messages, handoffs — instead of re-reading the same 3,000-token files and re-discovering the same pitfalls, while several agents work one repo without stepping on each other's edits.

pip install memdex-mcp        # PyPI name is memdex-mcp; the command is `memdex`

memdex connect # wires claude, codex, cursor, vs code, chatgpt, … (serve-check included) memdex brief # what the last session left for you — run it now

• A file summary written once stays valid until the file's content changes. Summaries are keyed to the sha256 of the content, not the path. The next session — or the next agent — gets a 100-token summary instead of the 3,000-token file, and is told the moment it goes stale.
• Notes know when they rot. Decisions, pitfalls and handoffs cite the files they're based on; when those files change, the note is flagged.
• Agents coordinate. claim what you're editing, post to other agents, read your inbox, leave a handoff for whoever comes next. All worktrees of a repository share one memory.

On a real 66-file site repo, memdex bench measures 154,105 tokens to read every file versus 3,471 tokens of outlines — 98% smaller, before an agent saves a single summary. Run memdex bench in your own checkout; the token count is chars / 4, an estimate, and the ratio is the point.

Listed in the official MCP Registry as io.github.ChoYugyeong/memdex and on PyPI as memdex-mcp.

Quick start

pipx install memdex-mcp        # PyPI name is memdex-mcp; the command is `memdex`

memdex connect --agent claude # write the MCP entry into the agents on this machine

Claude Code (user scope, every project) — when the claude CLI is on PATH, memdex connect runs this line for you, and prints it when it is not:

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

Everything else that keeps a config file — Claude Desktop, Cursor, VS Code (GitHub Copilot), Windsurf, Zed, Cline, Gemini CLI, Codex CLI, and DeepSeek Harness: memdex connect finds each one that is already installed, merges mcpServers.memdex into its config (servers.memdex with type: stdio for VS Code, context_servers.memdex for Zed, [mcp_servers.memdex] for Codex), preserves other settings, and saves a .bak before it writes. For DeepSeek Harness it adds a marked @deepseek-ai/dsh-mcp-client entry to each existing profile's cordis.patch.yml; only that managed block is replaced or removed. A client whose config folder does not exist is reported as not installed and left alone; an unreadable or malformed JSON/TOML config is left exactly as it was, and a Zed settings file with comments gets the block printed to paste instead of being rewritten (a rewrite would drop the comments). For DSH, a non-list root or a manual ID collision is also left untouched. --list shows what is installed and configured without writing, --dry-run shows the writes, --remove takes the entry out.

For DeepSeek Harness, run memdex connect --client deepseek-harness --agent deepseek --serve-check, then start a new Harness session. --serve-check verifies Memdex itself answers MCP initialize and tools/list; it does not claim the Harness loaded the plugin. Confirm the mcp__memdex__... tools appear in that session and call project_brief before delegating. The MCP entry runs the same Python package that ran connect, with the profile's current working directory as Memdex's project scope. A profile with a hand-written entry using id: memdex-memory, or a patch that is not a top-level YAML list, is left untouched for manual review.

If more than one Harness profile exists, connect stops before writing and asks for an explicit target: memdex connect --client deepseek-harness --profile desktop --agent deepseek --serve-check. The profile is the directory name under ~/.dsh/profiles (or $DSH_HOME/profiles); memdex connect --list shows the paths. This avoids silently adding the MCP server to every profile that happens to be installed.

`--serve-check` is the honest end of setup: after writing, memdex starts the server from the entry it just wrote and speaks MCP to it (initialize, then tools/list), so a wrong path, a missing interpreter or a database it cannot open is caught now instead of in the agent:

+ serve-check      memdex answered: 15 tools, protocol 2024-11-05

Any model, MCP or not — MCP clients join through memdex connect; a model that can only run shell commands joins with nothing to configure. Both paths are in Adding agents.

Team scope — put the config in the repo so everyone who clones it gets memdex:

memdex connect --project     # .vscode/mcp.json and .mcp.json, written with a bare `memdex` command

A committed config cannot carry this machine's absolute path, so project scope writes command: "memdex" and the teammate's PATH has to find it (pipx install memdex-mcp). With the claude CLI on PATH and --project, the CLI writes .mcp.json itself (claude mcp add memdex --scope project …) and memdex writes only the VS Code file, so one file never has two owners. --no-claude skips the CLI entirely, and --client claude-code runs only that step.

By hand, or for a client memdex does not know about:

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

Give each agent its own MEMDEX_AGENT name; its id becomes name@checkout (e.g. claude@myrepo-wt). memdex config --agent prints the snippets above, plus an optional Claude Code SessionStart hook that injects the project brief automatically.

That's it. The server sends its own usage instructions in the MCP initialize response, so agents know the workflow (brief → file_summary before reading → remember → handoff), and when to use the task ledger for substantial work, without extra prompting.

Adding agents

Every agent — MCP client or not — joins the same loop in the same four steps:

1. Name it. MEMDEX_AGENT becomes its id (name@checkout). Two agents sharing one name cannot see each other's messages, so each gets its own.
2. Wire it. MCP clients: one command (below). A model that can only run shell commands: nothing.
3. Verify. memdex doctor (✓ clients), codex mcp list for Codex, memdex connect --serve-check for the MCP handshake, memdex whoami for anything.
4. Work. Every agent, however it joined, uses the same basic loop: brief, claim, post/inbox, handoff. For substantial work with independently omittable outcomes, add a tasks tree before execution so blockers and incomplete branches stay visible.

MEMDEX_AGENT is a self-declared label, not an authenticated identity. A verified task means a different label recorded a peer check; it is a useful coordination signal, not cryptographic proof of who checked it.

For a long-running watcher, inbox --follow --poll 2 --notify-every 900 checks for messages every two seconds without consuming them, then prints a batch every 15 minutes. It flushes output before acknowledging the cursor; if the process stops between those steps, a numbered message may appear again, but is not lost. If a scheduler starts a fresh process on every check, use inbox --notify-every 900 instead. Its digest window is persisted per project and agent: the first check with unread messages opens a 15-minute window, later polls keep checking without consuming them, and due polls deliver the accumulated batch. Use the same agent id, project path, and interval on each run. The MCP inbox tool accepts the same notify_every value.

# a model with no MCP client, joining in ten seconds

MEMDEX_AGENT=codex memdex brief # what the last session left for you MEMDEX_AGENT=codex memdex claim src/store.py --intent "add retry" MEMDEX_AGENT=codex memdex task create --title "Retry support" --criterion "Retries are bounded and verified" MEMDEX_AGENT=codex memdex task create --parent 1 --title "Implement retry" --criterion "Retry path works" --owner codex MEMDEX_AGENT=codex memdex post "Retry work is underway" --group --to claude --task 1 MEMDEX_AGENT=codex memdex handoff "retry done" --next "wire timeout"

memdex connect --project puts the config in the repo so teammates get memdex on clone.

Sending to a specific chat

In the intended DeepSeek chat's shell, run memdex session routes --label "routing review". The CLI derives a project-local address from the checkout, agent and host conversation ID (DSH_SESSION_ID in DeepSeek or CODEX_THREAD_ID in Codex). Point both sides at the same project with `--path <che