local-memory
<div align="center">
# ๐ง Local Memory Agent
**Long-term memory for AI agents, over MCP. Free, private, and it runs on your laptop.**
Your agent remembers who you are across restarts. No API keys, no cloud, no bill.
[](https://www.python.org/)
[](https://github.com/modelcontextprotocol/python-sdk)
[](https://ollama.com)
[](#)
[](LICENSE)
[Quickstart](#-quickstart) ยท [Demo](#-see-it-work) ยท [Use with Claude Desktop / Cursor](#-plug-it-into-any-mcp-client) ยท [How it works](#-how-it-works)
</div>
---
## Why
Most agents forget you the moment the conversation ends. The usual fix is a hosted memory API: another key,
another bill, and your personal data on someone else's server.
**Local Memory Agent** is the minimal, fully local version, small enough to read in ten minutes:
- ๐งฉ **A standard MCP memory server**: `remember`, `recall`, `forget`, `list_memories`. Any MCP client can use it.
- ๐ **Semantic recall**: memories are embedded locally, so *"which city am I in?"* finds *"lives in Kolkata"*.
- ๐ค **An agent that decides for itself** when to save and when to look things up, using a local model's tool calling.
- ๐ **Private by default**: one SQLite file on your disk. Delete it and the memory is gone.
- ๐ **Degrades gracefully**: if Ollama is down, recall falls back to keyword search instead of failing.
- ๐ **Structured output**: tools return typed JSON (`structured_content`) as well as text, so clients can read results without parsing.
## ๐ฌ See it work
Three **separate processes**. Nothing carries over between them except `memory.db`.
Lines starting `[memory]` are tool calls the model chose to make on its own:
```text
$ uv run agent.py "Hi! I'm Debojyoti. I live in Kolkata, I mostly code in Python, and I'm building a DevRel portfolio focused on AI agents."
[memory] remember({"text": "The user's name is Debojyoti, lives in Kolkata, codes primarily in Python, and is building a DevRel portfolio focused on AI agents."})
Saved your details! Let's build that AI DevRel portfolio.
$ uv run agent.py "What do you remember about me? And which language should you use for code examples?"
[memory] recall({"query": "user's details", "limit": 1})
[memory] recall({"query": "user's preferred programming language", "limit": 1})
I remember that your name is Debojyoti, you live in Kolkata, you primarily code in Python, and you're building
a DevRel portfolio focused on AI agents. For code examples, I'll use Python.
$ uv run agent.py "Write me a one-line hello world."
print("Hello World")
```
*Recorded with `qwen3:4b` on a laptop RTX 3050 (6 GB).*
## ๐ Quickstart
About 10 minutes, most of it spent downloading the model.
**1. Install [Ollama](https://ollama.com/download) and pull two models** (โ2.8 GB):
```bash
# Windows: winget install Ollama.Ollama ยท macOS: brew install ollama
ollama pull qwen3:4b # the agent: a small model with tool calling
ollama pull nomic-embed-text # embeddings for semantic recall
```
**2. Clone and install** (needs Python 3.10+ and [uv](https://docs.astral.sh/uv/)):
```bash
git clone https://github.com/debojyoti10CC/local-memory-agent
cd local-memory-agent
uv sync
```
**3. Check the memory server**. This exercises all four tools over MCP, and no chat model is needed:
```bash
uv run smoke_test.py
# recall mode: semantic | top hit: The user lives in Kolkata
# OK: all 4 tools work over MCP
```
**4. Chat**:
```bash
uv run agent.py
```
Tell it about yourself, quit, start again and ask what it remembers. To start over, delete `memory.db`.
> **Hardware:** 8 GB RAM is enough. A GPU makes replies faster but isn't required.
## ๐ Plug it into any MCP client
`memory_server.py` is a standard MCP server, so Claude Desktop, Cursor, VS Code and any other MCP client can use it.
Add this to the client's MCP config, with an absolute path:
```json
{
"mcpServers": {
"local-memory": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/local-memory-agent", "memory_server.py"]
}
}
}
```
| Client | Config file |
|---|---|
| Claude Desktop | `claude_desktop_config.json` (Settings โ Developer โ Edit Config) |
| Cursor | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` (top-level key is `servers` instead of `mcpServers`) |
Every client that points at the same folder shares **one memory**: save a fact in Cursor and the local agent can recall it.
## ๐ How it works
```
you โโโบ agent.py โโโโโ MCP (stdio) โโโโโโบ memory_server.py โโโบ memory.db (SQLite)
โ โ
โผ โผ
Ollama ยท qwen3:4b Ollama ยท nomic-embed-text
decides when to call turns each memory into a vector
remember / recall for similarity search
```
### The memory server (`memory_server.py`, ~170 lines)
Each tool is a plain Python function. The MCP SDK builds the JSON schema from the type hints and uses the docstring as
the description the model reads when deciding what to call:
```python
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("local-memory")
@mcp.tool()
def remember(text: str, tags: list[str] | None = None) -> dict[str, Any]:
"""Save one durable fact to long-term memory. ..."""
```
| Tool | What it does |
|---|---|
| `remember(text, tags?)` | Embeds the fact and stores the text plus its vector in SQLite |
| `recall(query, limit?)` | Embeds the query, ranks memories by cosine similarity, drops weak matches |
| `forget(memory_id)` | Deletes one memory |
| `list_memories(limit?)` | Newest first |
> **Why `dict[str, Any]` and not `dict`?** In MCP Python SDK v2, only a parameterised `dict[str, โฆ]` gets an output
> schema and `structured_content`. A bare `dict` silently falls back to text only, even though the docs say otherwise.
> Details in the [friction report](docs/mcp-python-sdk-v2-friction-report.md).
**Why no vector database?** One person's memory is hundreds to a few thousand facts. Comparing a query against every
vector in plain Python takes milliseconds. Add an index when you need one, not before.
### The agent (`agent.py`, ~140 lines)
1. Starts the memory server as a subprocess and opens an MCP `ClientSession` over stdio.
2. Calls `list_tools()` and converts each MCP tool into Ollama's function-calling format. MCP's `input_schema` is
already JSON Schema, so it passes straight through as `parameters`.
3. Runs the tool loop: ask the model; if it returns `tool_calls`, run each one with `session.call_tool()`, append the
results as `role: "tool"` messages, and repeat until the model replies in text.
The **memory policy is just the system prompt**: recall before answering anything personal, and remember durable facts
as short sentences that start with "The user". Edit the prompt to change what gets remembered.
## โ๏ธ Configuration
| Env var | Default | Notes |
|---|---|---|
| `AGENT_MODEL` | `qwen3:4b` | Any Ollama model with tool support, e.g. `qwen3:8b`, `llama3.1:8b` |
| `EMBED_MODEL` | `nomic-embed-text` | If you change it, delete `memory.db` (vectors from different models can't be compared) |
| `MEMORY_DB` | `./memory.db` | Where memories are stored |
| `OLLAMA_HOST` | `http://localhost:11434` | Ollama server URL |
| `NO_COLOR` | unset | Set to print tool calls without grey text |
## ๐ฉบ Troubleshooting
| Symptom | Fix |
|---|---|
| `ConnectionError` / can't reach Ollama | Start Ollama (open the app, or run `ollama serve`) |
| `model "qwen3:4b" not found` | `ollama pull qwen3:4b` |
| `recall` returns `"mode": "keyword"` | Embedding model missing or Ollama is down: `ollama pull nomic-embed-text` |
| `No module named 'mcp.server.fastmcp'` | That's v1 example code on SDK v2. `FastMCP` is now `MCPServer` |
| Client only says `Connection closed` | The server crashed on startup. Run `uv run memory_server.py` directly to see the real error |
| Agent forgets to call `recall` | Small models sometimes skip tools. Try `AGENT_MODEL=qwen3:8b` |
| Windows: `failed to persist temporary file` during `uv sync` | Path too long. Clone to a shorter path such as `C:\dev\` |
## ๐บ Roadmap
- [ ] Per-user memory (`user_id` column, passed from the client)
- [ ] Update or merge a fact when it changes, instead of storing both versions
- [ ] Streamable HTTP transport, so several machines can share one memory
- [ ] Relationships between facts (graph memory), not just the facts
## ๐ Also in this repo
- [`docs/mcp-python-sdk-v2-friction-report.md`](docs/mcp-python-sdk-v2-friction-report.md): what broke or confused me while
building this on the MCP Python SDK v2, with repros and suggested docs fixes.
## License
[MIT](LICENSE) ยฉ Debojyoti De Majumder
TDQS
Scored across 4 tools
Each tool maps to a distinct memory operation: remember writes, recall searches semantically, list_memories enumerates recent items, and forget deletes by id. The descriptions reinforce the boundaries, so an agent can pick the right one without hesitation.
All names are snake_case and verb-led, which is easy to parse. The only deviation is list_memories (verb_noun) versus the single-verb remember/recall/forget, a minor inconsistency rather than a real problem.
Four tools is exactly right for a scoped long-term memory store, covering write, search, browse and delete without padding. Nothing feels redundant or missing at this size.
The full lifecycle is nearly covered: create, retrieve via search or listing, and delete. There is no dedicated update/edit tool, so correcting a fact requires forget-then-remember, a small gap agents can work around.