# @vheins/local-memory-mcp

[![npm version](https://img.shields.io/npm/v/@vheins/local-memory-mcp.svg)](https://www.npmjs.com/package/@vheins/local-memory-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@vheins/local-memory-mcp.svg)](https://www.npmjs.com/package/@vheins/local-memory-mcp)
[![npm total downloads](https://img.shields.io/npm/dt/@vheins/local-memory-mcp.svg)](https://www.npmjs.com/package/@vheins/local-memory-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**MCP Local Memory Service** is a high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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:** One-call session context (`agent-context`), structured decision logging via `memory-write` (`type: "decision"`), LLM-driven knowledge synthesis (`synthesize`), and per-repo project summaries (`repo-summarize`).
- 📊 **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:** A single unified tool (`codebase-read`) with auto-detected modes — search ranked symbols (`query`), trace a symbol's definition and call sites (`name`), list the symbols declared in a file (`filePath`), or explore the architecture overview (`depth`). `codebase-index` builds and refreshes the tree-sitter index.

## 🔌 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.

```json
"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:**

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

2. **Add to your configuration:**
   ```json
   "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`, it often performs a network request to check for the latest version or re-downloads the package if it's not in the cache. Since MCP clients start and stop tools frequently, this can lead to hundreds of unnecessary downloads.
- **Installed binary**: By installing the package, you keep a permanent copy on your disk. The Agent reuses this local version instantly, providing a much smoother experience.

## 📊 Glassy Dashboard

Visualize and manage your Agent's memory through a modern web interface.

|                                               Dashboard Overview                                                |                                               Memories Management                                               |
| :-------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------: |
| ![Dashboard Overview](https://raw.githubusercontent.com/wiki/vheins/local-memory-mcp/screenshots/dashboard.png) | ![Memories Management](https://raw.githubusercontent.com/wiki/vheins/local-memory-mcp/screenshots/memories.png) |

|                                             Task Tracking                                              |                                               Available Tools & Reference                                                |
| :----------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |
| ![Task Tracking](https://raw.githubusercontent.com/wiki/vheins/local-memory-mcp/screenshots/tasks.png) | ![Available Tools & Reference](https://raw.githubusercontent.com/wiki/vheins/local-memory-mcp/screenshots/reference.png) |

### How to Run

```bash
local-memory-mcp dashboard
```

_If not installed globally, use:_ `npx @vheins/local-memory-mcp dashboard`

### Developer Workflow (Dashboard UI)

The dashboard UI is built with **Svelte 5 + Vite**. Source files live in `src/dashboard/ui/`.

```bash
# Start the API server (port 3456)
# Note: `npm run dashboard` serves the compiled bundle — run `npm run build` once first (`dist/dashboard/public/`)
npm run dashboard

# In a separate terminal, start the Svelte dev server (port 5173)
npm run dashboard:dev
# → Open http://localhost:5173 (proxies /api to :3456)

# Build Svelte UI for production (output → dist/dashboard/public/)
npm run dashboard:build

# Full production build (Svelte + TypeScript)
npm run build
```

> The server serves the compiled Svelte build from `dist/dashboard/public/` in production.

### Auto-launch Dashboard in IDEs

The dashboard can auto-start when you open a project in VS Code, Cursor, Windsurf, Zed, or JetBrains IDEs.

📖 **[See the auto-start guide →](https://github.com/vheins/local-memory-mcp/wiki/en/Auto-Start-Dashboard)**

## 📖 Documentation

- [Getting Started & Setup](https://github.com/vheins/local-memory-mcp/wiki/en/Getting-Started) — Installation & client configuration
- [Tool Reference & Usage Guide](https://github.com/vheins/local-memory-mcp/wiki/en/Tools-Reference) — Complete tool docs with examples and workflows
- [Troubleshooting Guide](https://github.com/vheins/local-memory-mcp/wiki/en/Troubleshooting) — Fix common issues
- [Features & How It Works](https://github.com/vheins/local-memory-mcp/wiki/en/Features) — Semantic search, anti-hallucination, memory decay
- [Hybrid Search Logic](https://github.com/vheins/local-memory-mcp/wiki/en/Hybrid-Search) — How search scoring works
- [Dashboard Guide](https://github.com/vheins/local-memory-mcp/wiki/en/Dashboard-Guide) — Web UI for memory & task management
- [Codebase Index — Feature Overview](https://github.com/vheins/local-memory-mcp/wiki/features/Codebase-Index) — Index, search, and trace source code symbols
- [Feature Deep-Dives](https://github.com/vheins/local-memory-mcp/wiki/Home) — memory, task, standard, handoff, agentic, knowledge graph, codebase index
- [Codebase Index — API Reference](.agents/documents/api/codebase-index.md) — Complete MCP tool documentation for the 2 unified Codebase Index tools (`codebase-index` + `codebase-read`)
- [MCP Protocol Reference](https://github.com/vheins/local-memory-mcp/wiki/en/MCP-Concepts) — Technical protocol details
- [Claude Code Integration](https://github.com/vheins/local-memory-mcp/wiki/en/Claude-Code-Integration) — Setup for Claude Code CLI
- [Codex (OpenAI) Integration](https://github.com/vheins/local-memory-mcp/wiki/en/Codex-Integration) — Setup for Codex CLI
- [Kiro Integration](https://github.com/vheins/local-memory-mcp/wiki/en/Kiro-Integration) — Setup for Kiro IDE
- [Auto-Start Dashboard in IDEs](https://github.com/vheins/local-memory-mcp/wiki/en/Auto-Start-Dashboard) — tasks.json for VS Code, Cursor, Windsurf, Zed, JetBrains

> User documentation lives on the **GitHub Wiki** (`https://github.com/vheins/local-memory-mcp/wiki/Home`). Contributor & developer docs (testing standard, API references, ops runbooks, design/optimization, audits) live in `.agents/documents/`.

> 🇮🇩 **Indonesian version available:** [`README.id.md`](README.id.md) & docs on the Wiki under [`id/`](https://github.com/vheins/local-memory-mcp/wiki/id/Getting-Started)

### 🤝 Community & Support

- [Contribution Guidelines](CONTRIBUTING.md) — How to report issues and contribute code
- [Code of Conduct](CODE_OF_CONDUCT.md) — Community standards for all contributors
- [Security Policy](SECURITY.md) — How to report a security vulnerability
- [Support](SUPPORT.md) — Where to get help (docs, issues, integrations)

## ⚠️ Disclaimer

**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND**, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

## ⚖️ License

MIT © Muhammad Rheza Alfin — see the full text in [LICENSE.md](LICENSE.md).

## 🙏 Acknowledgements

- **Knowledge Graph** inspired by [Beledarian/mcp-local-memory](https://github.com/Beledarian/mcp-local-memory) — the structured entity/relation graph concept builds on this project, reimplemented with its own schema and offline NLP extraction.

- **Codebase Index** inspired by [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) — the codebase indexing/search/trace capabilities build on this concept, reimplemented with tree-sitter WASM and unified tools.