local-memory-mcp

local-memory-mcp is a local MCP server that provides a persistent memory layer for Claude, ChatGPT, and other MCP-compatible AI assistants. The core problem it solves is that every new Claude or ChatGPT session starts from a blank slate, so the user's preferences, project context, and decisions are lost and must be repeatedly re-explained. The tool lets assistants store what is worth remembering, retrieve relevant context at the start of a new session, version and supersede memories as circumstances change, and send data nowhere.

Main capabilities

• Local vector search: self-hosted RAG based on ChromaDB, with no cloud backend required.
• Two-stage retrieval: bi-encoder recall (pulling a wider candidate pool by cosine similarity, top_k × RERANK_OVERFETCH), cross-encoder reranking (default cross-encoder/ms-marco-MiniLM-L-6-v2, loaded once and kept warm; if it cannot be loaded, it gracefully degrades to bi-encoder ordering).
• Adaptive result count: top_k is a target rather than a hard cap, and may be exceeded while relevance remains high, up to the RERANK_MAX_K limit; when the reranker cannot distinguish confidently, it falls back to bi-encoder ordering.
• Write path: after store / update writes a chunk, coordination checks for overlap/conflict and returns warnings and self-healing suggestions when the write looks risky.
• Read path: search is two-stage, and deprecated chunks remain hidden unless explicitly requested.
• Versioned updates: strategy="version" together with a supersedes chain.
• Source labeling: source_type distinguishes user_statement from ai_inference, making assistant inferences distinguishable from user statements.
• Soft delete: history is retained by default, with optional hard delete.
• Heuristic coordination and conflict logging.
• Warning-first write responses: structured warnings[] and self-healing fields.
• Health checks: for oversized chunks and unresolved conflicts.
• Local backup/restore: for the persistent vector database.
• Transports: stdio, SSE, and streamable-HTTP (/mcp).
• Optional authentication: none (local only), bearer, or oauth (issued tokens persist across restarts).

MCP tools store, search, update, delete, get_chunk, get_evolution_chain, get_recent, self_check, get_issues, backup/restore, and conflict resolution.

Usage Quick start (Docker, about 2 minutes): point the MCP client at http://localhost:8000/mcp That is sufficient. Docker by default publishes only to 127.0.0.1, keeping it private; before exposing the service outside the machine, bearer or OAuth authentication must be configured and placed behind conventional network controls. Other installation methods include Claude Desktop setup, ChatGPT setup, and manual Python installation. Retrieval requires no parameter tuning; simply pass in the query and a rough top_k. All retrieval parameters can be adjusted via the RERANK_* keys in config.json.

Example workflow Store a memory, then retrieve it later; bootstrap a new session by running several focused retrievals, then synthesize only the active, non-deprecated chunks into a brief summary for a new model instance to use. See the examples/ directory for more workflows.

Design philosophy (AIX) AIX (AI eXperience) means designing for the way LLMs actually consume context, rather than the way humans archive documents: prefer clear text chunks over rigid document schemas; keep metadata minimal but useful (timestamps, confidence, supersedes links, deprecation flags); preserve history with version chains rather than destructive overwrites; return warning-rich tool responses so the model can self-correct. The goal is practical retrieval quality and reliable AI behavior, not a perfect human taxonomy.

Privacy and deployment Local-first and user-controllable by default; data is stored in local ChromaDB files under the configured persist directory; no cloud backend is required, with optional remote access via a user-managed tunnel; never commit real secrets, use local configuration/environment variables.

Use cases Suitable for users who want an AI assistant to remember user preferences, project context, and decisions across sessions while requiring data to remain entirely local; suitable for integration with MCP-compatible clients such as Claude Desktop and ChatGPT.

Limitations The materials do not provide specific performance benchmarks, the maximum supported data scale, platform compatibility details, or pricing information. Docker by default allows only local access; remote exposure requires configuring authentication and network controls yourself.