Skip to main content
Glama

🧠 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+ MCP SDK v2 Ollama Cost: $0 License: MIT

Quickstart Β· Demo Β· Use with Claude Desktop / Cursor Β· How it works


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.

Related MCP server: identity-storage-mcp

🎬 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:

$ 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 and pull two models (β‰ˆ2.8 GB):

# 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):

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:

uv run smoke_test.py
# recall mode: semantic | top hit: The user lives in Kolkata
# OK: all 4 tools work over MCP

4. Chat:

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:

{
  "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:

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.

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

License

MIT Β© Debojyoti De Majumder

Available Tools

4 tools
forgetA

Delete one memory by its id (ids come from recall or list_memories).

Inputs: memory_id (required). Returns: object

list_memoriesB

List the most recent memories, newest first.

Inputs: limit. Returns: object

recallA

Search long-term memory for facts relevant to the query.

Call this before answering anything that might depend on what you already know about the user or their projects.

Inputs: query (required), limit. Returns: object

rememberA

Save one durable fact to long-term memory.

Write it as a short standalone sentence that makes sense out of context, e.g. "The user's name is Priya and she works in Bengaluru." Use for preferences, personal facts, decisions and project details. Do not save small talk, secrets or passwords.

Inputs: text (required), tags. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers