SodaMem MCP
Long-term memory for agents: new facts supersede old ones, every answer traces to its source, and recall makes no LLM calls
- 203 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- `sodamem install` hooks send session turns to the chosen model provider for fact extraction, so conversation content leaves the machine
- The writing tools enabled by `SODAMEM_MCP_ALLOW_WRITE=true` let the agent change and delete stored facts
Install
- Works in
Manual install
pip install "sodamem[chroma,llm]"The Python path from the README. The MCP server also needs the `mcp` extra, and TypeScript has `npm i sodamem`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `sodamem install` hooks send session turns to the chosen model provider for fact extraction, so conversation content leaves the machine
- The writing tools enabled by `SODAMEM_MCP_ALLOW_WRITE=true` let the agent change and delete stored facts
This is third-party code. Review the repository files before installing.
What it does
SodaMem stores facts from an agent's conversations and returns them as a ready context block. If a user says they moved from Kauai to Oahu, the old fact is marked superseded rather than overwritten. Entity profiles are rebuilt on demand, and every line of an answer links to the turn it came from. Recall does not call a language model, so the same question gets the same answer. A model is needed only for writing: it extracts facts from the turns. Memory connects to agents in several ways. The MCP server exposes eight tools, six of them read-only, including `entity_timeline` with the history of one entity. The two writing tools, `add_memories` and `delete_memory`, appear with `SODAMEM_MCP_ALLOW_WRITE=true`. For Claude Code, GitHub Copilot CLI, Cursor and Codex CLI, `sodamem install` also adds hooks so memory is injected without the model deciding to call a tool.
Who it is for. Agent developers and people who work in Claude Code and Cursor a lot and want memory across sessions with a verifiable source for every fact.
Good fit when
- The agent forgets agreements between sessions and they should be injected at the start of work automatically
- Data changes: a user moved or switched stacks, and the stale fact must not surface in an answer
- An agent answer has to be checked: every context line leads to the turn it came from
- Several editors need one memory, held by a single background `sodamem daemon` process
Not a fit when
- A `CLAUDE.md` notes file is enough: a separate daemon and fact extraction would be overkill
- There is no model key for fact extraction: recall works without it, but storing facts does not
- You want memory fully on the agent vendor's side, with no process or store of your own
- You need automatic retention of every turn in Cursor or Codex CLI: there hooks give only a project brief at session start
Example request
Recall which package manager we picked for this repository and why, and show the turn it came from.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
SODAMEM_LLM_API_KEYsecret- Model provider key needed when storing facts. Not required for recall.
SODAMEM_MCP_ALLOW_WRITE- The value `true` enables the writing tools `add_memories` and `delete_memory`. The installer sets it in the client config.
SODAMEM_API_KEYsecret- Key of the HTTP service when self-hosting with Docker Compose.
Limitations
Only a process with a language-model key can store facts, while recall works without one. User stores are SQLite without WAL and are opened by one process, so clients go through a shared `sodamem daemon`, and the `--local-store` mode blocks a second client.
Full hooks exist only for Claude Code and GitHub Copilot CLI. Cursor and Codex CLI get a project brief at session start and write through `add_memories`, and other clients work through MCP tools only. The LongMemEval and LoCoMo numbers in the README were measured by the author on `deepseek-v4-flash`.
How to disable. Stop the daemon with the stop subcommand from the CLI help of `sodamem daemon` and remove the `sodamem` block from the client config. Before first editing a file, the installer leaves a `.sodamem-backup` copy beside it that can be restored.
FAQ
How do I connect SodaMem to Claude Code?
Run `sodamem daemon ensure`, then `sodamem install claude-code`. The installer adds MCP tools and hooks, merges the existing config with the new one and leaves a backup. The `--dry-run` flag shows what would change first.
Is a model key required?
Not for reading: search and context building make no LLM calls. Writing needs a key in variables such as `SODAMEM_LLM_API_KEY`, and `sodamem daemon ensure` says so up front instead of failing a write later.
Which tools does the agent see over MCP?
Eight tools. Six read, including `entity_timeline` and `explore_memory`. The writing `add_memories` and `delete_memory` are enabled by `SODAMEM_MCP_ALLOW_WRITE=true`, which `sodamem install` writes into the client config.
How is SodaMem different from basic-memory?
basic-memory keeps notes in Markdown files. SodaMem extracts facts from turns, stores them in SQLite, marks outdated ones as superseded and attaches a link to the source turn to every answer.
Can I run a shared service for a team?
Yes. The repository ships an HTTP service and a web console in the image: run `cp .env.example .env`, set `SODAMEM_API_KEY` and run `docker compose up -d`. A TypeScript client is available via `npm i sodamem`.
Discussion
No questions or reviews yet.
Related
MCP serversLong-term memory for agents: a remote MCP server, plugins for Claude Code, Cursor and Codex, and an API for your own apps
Shared local memory for AI agents: Claude Code, Codex, Cursor and others find the agreements of past sessions in it and record new ones
Agent memory as a graph of linked facts: decisions and errors outlive the session, with no vector database or paid API calls
Dual-path memory for agents: a knowledge graph on your machine, search on demand and hints before you ask, across sessions.
A long-term memory MCP server for AI agents: facts fade along a forgetting curve and related records are compressed into a summary
Membase keeps one shared memory for AI agents that Claude Code, Cursor and Codex read through MCP, an SDK or the membase command
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| SodaMem (this card) | yes | not required | 203 | |
| Basic Memory | no | not required | 4,566 | notes in Markdown files with a link graph, without superseding stale facts or source-turn links |
| MCP Memory Service | no | not required | 2,117 | self-hosted memory with semantic search and auto-consolidation, without marking superseded facts |
README in short
The README opens with an integrations table: Hermes Agent, DeepSeek Harness, any MCP client, LangGraph, CrewAI and OpenAI Agents SDK adapters, and the Vercel AI SDK. Benchmarks follow: 92.8 percent on LongMemEval with published answers and 86.88 percent on LoCoMo without per-question answers, then a Python quick start and Docker self-hosting.