local-memory-mcp

AI assistants forget everything when the conversation ends. This fixes that - locally.

No cloud. No subscription. No account. Your data stays on your machine.

local-memory-mcp gives Claude, ChatGPT, and other MCP-compatible assistants a persistent memory layer powered by local vector search (ChromaDB). Tell it something once. It remembers across sessions.

---

The problem it solves

Every new Claude or ChatGPT session starts blank. Your preferences, your project context, your decisions - gone. You re-explain yourself constantly.

local-memory-mcp is a local MCP server that lets your AI assistant:

• Store things worth remembering (“my deep work block is 6:30–9 AM”)
• Retrieve relevant context at the start of any new session
• Version and supersede memories as your situation changes
• Never send your data anywhere

It’s the memory layer AI assistants should have built in, but don’t.

---

Quickstart (Docker - 2 minutes)

git clone https://github.com/ptobey/local-memory-mcp.git
cd local-memory-mcp
docker compose up --build -d

Then point your MCP client at http://localhost:8000/mcp. Done.

The Docker default is intentionally private: it publishes only to 127.0.0.1. Before exposing it outside your machine, configure bearer or OAuth authentication and put it behind your normal network controls.

→ Claude Desktop setup · ChatGPT setup · Manual Python install

---

How it works

[Assistant via MCP Client]
            |
            v
[run_mcp_v1_stdio.py | run_mcp_v1_http_sse.py]
            |
            v
      [src/mcp_server_v1.py]
        /          |          \
       v           v           v
[vector_store.py] [reconciliation.py] [health_monitor.py]
       |                   |
       v                   v
 [Local ChromaDB]   [Reconciliation Log]

Write path: store/update writes a chunk → reconciliation checks for overlap/conflict → returns warnings and self-heal hints when a write looks risky.

Read path: search is two-stage — a fast bi-encoder pulls a wide candidate pool, a cross-encoder reranker reorders it for precision, and the number of results adapts to how much is genuinely relevant. Deprecated chunks stay hidden unless explicitly requested.

Retrieval pipeline

You never tune retrieval — just pass a query and a rough top_k:

1. Bi-encoder recall — embed the query and pull a wide candidate pool (top_k × RERANK_OVERFETCH) by cosine similarity.