Skip to main content
Glama
README.md
<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.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP SDK v2](https://img.shields.io/badge/MCP%20Python%20SDK-v2-6E56CF)](https://github.com/modelcontextprotocol/python-sdk)
[![Ollama](https://img.shields.io/badge/runs%20on-Ollama-000000)](https://ollama.com)
[![Cost: $0](https://img.shields.io/badge/cost-%240-2ea44f)](#)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues