local-memory
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@local-memory what do you remember about my location and preferred programming language?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π§ 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.
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 recall2. Clone and install (needs Python 3.10+ and uv):
git clone https://github.com/debojyoti10CC/local-memory-agent
cd local-memory-agent
uv sync3. 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 MCP4. Chat:
uv run agent.pyTell 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 |
|
Cursor |
|
VS Code |
|
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 searchThe 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 |
| Embeds the fact and stores the text plus its vector in SQLite |
| Embeds the query, ranks memories by cosine similarity, drops weak matches |
| Deletes one memory |
| Newest first |
Why
dict[str, Any]and notdict? In MCP Python SDK v2, only a parameteriseddict[str, β¦]gets an output schema andstructured_content. A baredictsilently 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)
Starts the memory server as a subprocess and opens an MCP
ClientSessionover stdio.Calls
list_tools()and converts each MCP tool into Ollama's function-calling format. MCP'sinput_schemais already JSON Schema, so it passes straight through asparameters.Runs the tool loop: ask the model; if it returns
tool_calls, run each one withsession.call_tool(), append the results asrole: "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 |
|
| Any Ollama model with tool support, e.g. |
|
| If you change it, delete |
|
| Where memories are stored |
|
| Ollama server URL |
| unset | Set to print tool calls without grey text |
π©Ί Troubleshooting
Symptom | Fix |
| Start Ollama (open the app, or run |
|
|
| Embedding model missing or Ollama is down: |
| That's v1 example code on SDK v2. |
Client only says | The server crashed on startup. Run |
Agent forgets to call | Small models sometimes skip tools. Try |
Windows: | Path too long. Clone to a shorter path such as |
πΊ Roadmap
Per-user memory (
user_idcolumn, 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: what broke or confused me while building this on the MCP Python SDK v2, with repros and suggested docs fixes.
License
MIT Β© Debojyoti De Majumder
Available Tools
4 toolsforgetA
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
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.
Maintenance
Related MCP Connectors
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceSQLite-backed memory storage for MCP agents with optional semantic search via OpenAI embeddings, enabling agents to remember, recall, and manage contextual information across sessions.26 npmMIT
- AlicenseAqualityDmaintenanceProvides persistent, inspectable memory storage for AI agents using SQLite. Agents can store, recall, and search memories across sessions via three MCP tools.3MIT
- AlicenseNot gradedqualityCmaintenanceProvides persistent semantic memory for AI agents via MCP, enabling them to remember, recall, list, update, and forget memories with vector-based similarity search.ISC
- AlicenseAqualityDmaintenanceProvides persistent, searchable memory for AI agents across any MCP-compatible client, storing project context, user preferences, and session learnings locally in SQLite with tools to save, retrieve, search, and manage them.12MIT