Toon Memory — Claude Code MCP server: what it does, how to install
Offline persistent memory for coding assistants. Keeps architectural choices and project conventions intact between sessions via MCP.
claude mcp add --env TOON_MEMORY_KEY=<TOON_MEMORY_KEY> --env TOON_MEMORY_CAPTURE=<TOON_MEMORY_CAPTURE> --env TOON_MEMORY_SESSION_ID=<TOON_MEMORY_SESSION_ID> --env TOON_MEMORY_BRANCH=<TOON_MEMORY_BRANCH> --env TOON_MEMORY_NO_SESSION=<TOON_MEMORY_NO_SESSION> --transport stdio toon-memory -- npx -y toon-memoryWhat Toon Memory does
AI coding assistants tend to drop project context as soon as a session closes. Toon Memory writes decisions, architecture notes, and bug fixes to your local disk instead of a remote cloud. It keeps records inside .toon-memory/memory/ and appends that path to .gitignore. The specialized TOON data format cuts token overhead by 22% compared to JSON.
The server bundles 35 MCP tools. Functions like memory_smart_recall retrieve relevant context using BM25 scoring paired with graph centrality decay, bypassing external embeddings. Sessions can be saved via memory_checkpoint with a 7-day TTL, while sensitive records remain secured through AES-256-GCM encryption in memory_secret.
Running toon-memory init parses manifests like package.json or requirements.txt to build auto-tagging project vocabularies. If you plan to encrypt entries or sync with GitHub Gist, you must provide the TOON_MEMORY_KEY and GITHUB_TOKEN environment variables before starting.
What it helps with
- persist architecture choices and library decisions across sessions
- stop explaining project conventions to agents repeatedly
- link related codebase notes through graph connections
- deduplicate near-identical notes and archive stale entries
Example prompts for the agent
- Recall the decision we made regarding our validation library
- Save the database connection pool fix to memory with a backend tag
- Create a checkpoint of the current session decisions
How to install Toon Memory
Platform CLI
claude mcp add --env TOON_MEMORY_KEY=<TOON_MEMORY_KEY> --env TOON_MEMORY_CAPTURE=<TOON_MEMORY_CAPTURE> --env TOON_MEMORY_SESSION_ID=<TOON_MEMORY_SESSION_ID> --env TOON_MEMORY_BRANCH=<TOON_MEMORY_BRANCH> --env TOON_MEMORY_NO_SESSION=<TOON_MEMORY_NO_SESSION> --transport stdio toon-memory -- npx -y toon-memoryReplace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
codex mcp add toon-memory --env TOON_MEMORY_KEY=<TOON_MEMORY_KEY> --env TOON_MEMORY_CAPTURE=<TOON_MEMORY_CAPTURE> --env TOON_MEMORY_SESSION_ID=<TOON_MEMORY_SESSION_ID> --env TOON_MEMORY_BRANCH=<TOON_MEMORY_BRANCH> --env TOON_MEMORY_NO_SESSION=<TOON_MEMORY_NO_SESSION> -- npx -y toon-memoryReplace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"mcpServers": {
"toon-memory": {
"command": "npx",
"args": [
"-y",
"toon-memory"
],
"env": {
"TOON_MEMORY_KEY": "<TOON_MEMORY_KEY>",
"TOON_MEMORY_CAPTURE": "<TOON_MEMORY_CAPTURE>",
"TOON_MEMORY_SESSION_ID": "<TOON_MEMORY_SESSION_ID>",
"TOON_MEMORY_BRANCH": "<TOON_MEMORY_BRANCH>",
"TOON_MEMORY_NO_SESSION": "<TOON_MEMORY_NO_SESSION>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"servers": {
"toon-memory": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"toon-memory"
],
"env": {
"TOON_MEMORY_KEY": "<TOON_MEMORY_KEY>",
"TOON_MEMORY_CAPTURE": "<TOON_MEMORY_CAPTURE>",
"TOON_MEMORY_SESSION_ID": "<TOON_MEMORY_SESSION_ID>",
"TOON_MEMORY_BRANCH": "<TOON_MEMORY_BRANCH>",
"TOON_MEMORY_NO_SESSION": "<TOON_MEMORY_NO_SESSION>"
}
}
}
}Replace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
gemini mcp add -e TOON_MEMORY_KEY=<TOON_MEMORY_KEY> -e TOON_MEMORY_CAPTURE=<TOON_MEMORY_CAPTURE> -e TOON_MEMORY_SESSION_ID=<TOON_MEMORY_SESSION_ID> -e TOON_MEMORY_BRANCH=<TOON_MEMORY_BRANCH> -e TOON_MEMORY_NO_SESSION=<TOON_MEMORY_NO_SESSION> toon-memory npx -y toon-memoryReplace <…> with your own values. 1 more environment variable is in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Toon Memory
How to install Toon Memory in Claude Code?
Run claude mcp add toon-memory -e TOON_MEMORY_KEY=<TOON_MEMORY_KEY> -e GITHUB_TOKEN=<GITHUB_TOKEN> -- npx -y toon-memory in your terminal, replacing the placeholders with your own keys.
What does Toon Memory do?
It provides file-backed long-term memory for coding agents via the Model Context Protocol, letting assistants retain project rules and history across restarts.
Does the memory graph require external embeddings or an LLM?
No. The memory recall mechanism relies on BM25 term matching and node centrality decay locally, functioning without remote vector stores or model invocations.
