Local Memory MCP Server 🧠

A lightweight, privacy-first, "Zero-Docker" memory server for AI agents. This server provides semantic search, keyword search, and a knowledge graph—all running natively on your local machine.

Key Features

• Hybrid Search: Semantic (Vector) search + Keyword (FTS5) search.
• Local Embeddings: Uses transformers.js (ONNX) to run all-MiniLM-L6-v2 locally on your CPU.
• Knowledge Graph: Structured entities and relations tables to link facts.
• Advanced Graph Traversal: Recursive queries to find "friends of friends" (Deep Graph).
• Mixed Clustering: "Gravity Center" clustering that groups relevant Memories and Entities together (#6.1).
• The Archivist: Configurable "Auto-Ingestion" strategies for automatic graph building.
• Privacy-First: Zero data leaves your machine. No mandatory cloud APIs.
• Resource Efficient: ~50MB - 200MB RAM usage. Optimized with Float32Array buffers.
• Enhanced NLP Extraction: Extracts complex concepts ("optimized WGSL"), adjectives ("pragmatic"), entities, and relations with robust pattern matching.
• Time Tunnel: Natural language date querying (e.g., "last week", "in 2025") for temporal recall.
• Todo System: Integrated task management with automatic context injection and memory archival.
• Entity Observations: Normalized storage with "Smart Append" for evolving entity knowledge.

🌐 Cross-Agent Shared Context

A core advantage of this server is its ability to serve as a centralized long-term memory pool for all your AI workflows.

Unlike standard agent memories that are ephemeral or locked to a single session, this server allows multiple MCP-enabled agents (e.g., Claude Code, IDE extensions, or custom CLIs) to:

• Share Knowledge: Information learned by one agent is instantly accessible to another.
• Maintain Consistency: Ensure all your AI tools operate from the same established facts and entity history.
• Persistent Intelligence: Your interaction history matures over time into a robust, structured knowledge base available across your entire local ecosystem.

---

🛠 Installation

1. Prerequisites

• Node.js: v18 or higher.
• Build Tools: Python and C++ build tools (required by better-sqlite3 native compilation).

[!IMPORTANT] Windows Users: You may need to have C++ Build Tools installed. Run: npm install --global --production windows-build-tools OR install "Desktop development with C++" via Visual Studio Installer. Failure to do this can result in gyp errors during installation.

📦 Installation & Setup

Method 1: Use via NPX (Recommended)

You can use the server directly without installing it globally, using npx. This is the easiest way to use it with MCP clients like Claude Desktop.

Add to your MCP Configuration:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@beledarian/mcp-local-memory"],
      "env": {
        "ARCHIVIST_STRATEGY": "nlp"
      }
    }
  }
}

Method 2: Install via NPM

Global installation provides the memory command:

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

# Usage
memory --help

### Method 3: Install from Source (For Contributors)

1.  **Clone the repository**:
    ```bash
    git clone https://github.com/Beledarian/mcp-local-memory.git
    cd mcp-local-memory
    ```
2.  **Install dependencies**:
    ```bash
    npm install
    ```
3.  **Build the project**:
    ```bash
    npm run build
    ```
4.  **Run the server**:
    ```bash
    npm start
    ```

---

## ⚙️ Configuration

Control the server behavior via environment variables:

| Variable | Options | Default | Description |
| :--- | :--- | :--- | :--- |
| `ARCHIVIST_STRATEGY` | `passive`, `nlp`, `llm` | `nlp` | Control automatic entity extraction behavior. `passive`=disabled, `nlp`=free offline extraction, `llm`=AI-powered extraction (~200 tokens per `remember_fact` call). Can be comma-separated (e.g., `nlp,llm`). |
| `MEMORY_DB_PATH` | Path to DB file | `./memory.db` | Location of the SQLite database. |
| `CONTEXT_WINDOW_LIMIT` | Integer | `500` | Max characters returned by `memory://current-context`. |
| `CONTEXT_MAX_ENTITIES` | Integer | `5` | Max high-importance entities in context. |
| `CONTEXT_MAX_MEMORIES` | Integer | `5` | Max recent memories in context. |
| `OLLAMA_URL` | URL string | `http://localhost:11434` | Full API Endpoint for the LLM strategy (e.g. `http://localhost:11434/api/generate`). |
| `USE_WORKER` | `true`, `false` | `true` | Run Archivist in a background thread to prevent blocking. |
| `ENABLE_CONSOLIDATE_TOOL` | `true`, `false` | `false` | Enable the `consolidate_context` tool for retrospective memory extraction. |
| `TAG_MATCH_BOOST` | Float | `0.15` | Score boost for exact tag matches in `recall` results. Higher = stronger tag priority. |
| `MEMORY_HALF_LIFE_WEEKS` | Float | `4.0` | Weeks until memory importance decays to 50%. Longer = slower decay. |
| `MEMORY_CONSOLIDATION_FACTOR` | Float | `1.0` | Strength of access-based consolidation. Higher = frequently-used memories resist decay more. |
| `MEMORY_SEMANTIC_WEIGHT` | Float | `0.7` | Balance between semantic similarity (0.7) and decayed importance (0.3) in recall ranking. |
| `EXTRACT_COMPLEX_CONCEPTS` | `true`, `false` | `true` | Enable extraction of modifier+noun phrases (e.g., "optimized WGSL"). Set to `false` to disable. |
| `CONTEXT_TODO_LIMIT` | Integer | `3` | Max pending todos shown in `memory://current-context`. |
| `EMBEDDING_CONCURRENCY` | Integer | `5` | Max concurrent embedding operations for `remember_facts`. Higher values = faster batch processing but more CPU/memory usage. |
| `EXTENSIONS_PATH` | Path to directory | (none) | Optional path to load custom tool extensions from external directory. Allows adding private/experimental tools without modifying the codebase. |



To enable AI-powered entity extraction, importance scoring, and auto-labeling, run [Ollama](https://ollama.com/) locally.

```json
{
  "mcpServers": {
    "local-memory": {
      "command": "wsl",
      "args": ["/home/username/.nvm/versions/node/v20.11.1/bin/node", "/home/username/mcp-local-memory/dist/index.js"],
      "env": {
        "MEMORY_DB_PATH": "/home/username/.memory/memory.db",
        "ARCHIVIST_STRATEGY": "nlp",
        "ARCHIVIST_LANGUAGE": "en"  // Optional: Default is 'en'
      }
    }
  }
}

Archivist Strategies (ARCHIVIST_STRATEGY)

You can combine multiple strategies by separating them with a comma (e.g. nlp,llm).

• passive: Manual only. The server waits for the Agent to call tools.
• nlp: (Open Source / Offline) Uses the compromise library to extract entities locally. Very fast, but less comprehensive.
• llm: (Ollama / Artificial Intelligence) Sends text to a local LLM (e.g., Llama 3) for deep understanding, relation extraction, and importance scoring. Requires running Ollama.

---

⚡ Performance Optimizations

Asynchronous Memory Operations

All memory saving operations are now non-blocking for instant responses:

• remember_fact: Returns immediately, processes embedding + archivist in background

  • Before: ~50-200ms blocking wait
  • After: Instant return (0ms)

• remember_facts: Parallel batch processing with concurrency limiting

  • Before: 7 facts × 200ms = ~1.4s (sequential)
  • After: ~200ms (parallel batches)
  • Speedup: ~7x faster
  • Configuration: Set EMBEDDING_CONCURRENCY env var (default: 5)

Natural Memory Evolution

Memories accessed frequently gain importance automatically:

• Each recall(): +0.05 importance boost (capped at 1.0)
• Fresh memories: Start at 0.5 importance
• After ~10 accesses: Become "cherished" (>0.7 importance)
• After ~20 accesses: Maximum importance (1.0)

This mimics hippocampus consolidation - frequently-used memories naturally rise to the top. No manual curation needed.

Official Extensions

This package includes first-party extensions to enhance memory management:

1. Soul Maintenance (extensions/soul_maintenance.ts): Implements a "biological" lifecycle where memories must earn importance through use and naturally decay over time unless immunized by core tags.

To use these official extensions, set your EXTENSIONS_PATH to the extensions folder inside the installed package:

# Example for npx usage
EXTENSIONS_PATH=./node_modules/@beledarian/mcp-local-memory/extensions

Setup:

1. Create a directory for your extensions (e.g., ./my-extensions/)
2. Add TypeScript/JavaScript modules with your custom tools
3. Set EXTENSIONS_PATH environment variable to your directory
4. Restart the server

Extension Format:

// my-extensions/my_tool.ts
import type { Database } from 'better-sqlite3';

export function handleMyTool(db: Database, args?: any) {
    // Your tool logic here
    return { result: "Custom tool output" };
}

export const MY_TOOL_TOOL = {
    name: "my_tool",
    description: "Description of what your tool does",
    inputSchema: {
        type: "object",
        properties: {
            // Define input parameters
        }
    }
};

Benefits:

• Keep experimental/private tools separate from the main codebase
• No need to rebuild or modify source code
• Easy to version control your extensions independently
• Perfect for personal customizations

---

💡 Recommended System Prompt

For effective agent interaction with this memory server, we recommend using a detailed system prompt.

• Quick Start: See docs/example_instructions.md
• Comprehensive Rules: See docs/detailed_prompt.md

---

🔧 Tools for Agents

The server exposes the following MCP tools:

Memory Management

• remember_fact(text, tags?): Saves a new piece of