@vheins/local-memory-mcp

MCP Local Memory Service is a high-performance Model Context Protocol (MCP) server that provides long-term, high-signal memory for AI Agents (such as Claude Desktop, Cursor, or Windsurf).

Built with a Local-First philosophy, this service stores architectural decisions, code patterns, and critical facts locally on your machine using SQLite and AI-powered Semantic Search.

🚀 Key Features

• 🧠 Semantic Search (V2): Find memories based on meaning, not just keywords, using the all-MiniLM-L6-v2 model locally with hybrid TF-IDF + vector ranking.
• 🔄 Tech-Stack Affinity: Share knowledge across repositories intelligently based on technology tags.
• 🛡️ Anti-Hallucination Guard: Strict similarity thresholds and decision conflict detection.
• 🧩 Knowledge Graph: Structured entities, relations, and observations with auto-extraction via offline NLP.
• 🕰️ Time Tunnel: Query memories with natural language dates ("yesterday", "last week").
• 📉 Soul Maintenance: Biological-style memory decay with tag immunization — automatically archives obsolete memories.
• 🤖 Agentic Tools: Agent-context recall, structured decision logging, session summarization.
• 📊 Glassy Dashboard: Visualize memories, tasks, handoffs, knowledge graph, and interaction logs through a modern Svelte 5 interface.
• 🔍 Codebase Index: Index and query source code structure — search for functions, classes, interfaces, types, and enums across your projects. Uses tree-sitter WASM for fast parsing with incremental updates.
• 🧭 Codebase Search & Trace: Search indexed symbols with ranked results (search_symbols), inspect file-level declarations (get_file_symbols), explore architecture overviews (get_architecture), and trace symbol definitions across your codebase (trace_symbol).

Drop-In Upstream Compatibility

Compatible with Beledarian/mcp-local-memory clients: remember_fact, remember_facts, recall, forget are built-in aliases.

🔌 MCP Usage & Configuration

Add this service to your AI Agent (Claude Desktop, Cursor, Windsurf, etc.) using one of the methods below.

💡 Recommendation: If your MCP runs frequently (agents, CI, automation), avoid npx and use a global or local install instead. It reduces unnecessary NPM downloads and speeds up Agent startup.

🚀 Quick Start (Zero Setup)

Best for first-time users or quick testing. This uses npx to run the server without any permanent setup.

"local-memory": {
  "command": "npx",
  "args": ["-y", "@vheins/local-memory-mcp"],
  "type": "stdio"
}

• Uses npx: Automatically handles the execution.
• Tradeoff: May re-download the package in some environments and is not optimal for frequent execution.

⚡ Recommended for Production / Frequent Usage

This method ensures the fastest startup times and maximum reliability for daily use.

1. Install globally:

   npm install -g @vheins/local-memory-mcp
   

2. Add to your configuration:

   "local-memory": {
     "command": "local-memory-mcp",
     "type": "stdio"
   }
   

• Faster startup: No network checks required on every start.
• No repeated downloads: Saves bandwidth and avoids NPM registry dependency.
• Better for automation: More stable for heavy-duty Agent workflows.

🧠 How It Works (Important Insight)

• npx usage: When you use npx,