neuromcp

Semantic memory for AI agents — local-first MCP server with hybrid search, governance, and consolidation.

npx neuromcp

Why

AI agents forget everything between sessions. The default MCP memory server stores flat key-value pairs with keyword search — fine for "remember my name is Bob", useless for "what was the architectural decision we made about authentication last week?"

neuromcp solves this with hybrid search (vector embeddings + full-text), memory governance (namespaces, trust levels, lineage tracking), and automatic consolidation (dedup, decay, prune) — all running locally in a single SQLite file. No cloud, no API keys, no infrastructure.

Before & After

How It Works

Query: "how does auth work in this project?"
                │
                ▼
    ┌───────────────────────┐
    │   Hybrid Search       │
    │                       │
    │  Vector (semantic)    │──→ "JWT tokens validated in middleware" (0.87)
    │  FTS (keyword)        │──→ "auth module uses passport.js"     (0.91)
    │                       │
    │  RRF Fusion           │──→ Combined ranking, best results first
    └───────────────────────┘
                │
                ▼
    Filters: namespace, category, trust, date range
                │
                ▼
    Top results returned to agent

Embeddings: Auto-detects Ollama at localhost:11434 for real semantic search (nomic-embed-text). Falls back to built-in ONNX model (bge-small-en-v1.5) for basic similarity. Zero config either way.

Storage: Single SQLite file (~/.neuromcp/memory.db), WAL mode for concurrent access, content-hash deduplication at write time.

Consolidation: Plan-then-commit pipeline — preview what will change before applying. Deduplicates near-identical memories, decays old memories' importance over time, prunes below-threshold, sweeps tombstoned records past TTL.

Real-World Example

You: Where were we with the payment integration?

Claude: [searches neuromcp for "payment integration"]

Found 3 relevant memories:
- (0.92) "Decided on Stripe over PayPal — better webhook reliability, 
         session from 2026-03-28"
- (0.87) "Payment webhook handler at src/api/webhooks/stripe.ts needs 
         idempotency keys — known bug, not yet fixed"
- (0.81) "Test coverage for payment module is at 64%, target is 80%"

Based on our previous sessions: we chose Stripe, the webhook handler 
needs idempotency keys (that's still open), and test coverage needs 
work. Want me to start with the idempotency fix?

Quick Start

npx neuromcp

Creates ~/.neuromcp/memory.db on first run. Downloads ONNX model automatically.

Recommended: Add Ollama for real semantic search

# Install Ollama from https://ollama.com, then:
ollama pull nomic-embed-text

neuromcp auto-detects it. No config needed.

Installation

Claude Code

// ~/.claude.json → mcpServers
{
  "neuromcp": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "neuromcp"]
  }
}

Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "neuromcp": {
      "command": "npx",
      "args": ["-y", "neuromcp"]
    }
  }
}

Cursor / Windsurf / Cline

Same format — add to your editor's MCP settings.

Per-project isolation

// .mcp.json in project root
{
  "mcpServers": {
    "neuromcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "neuromcp"],
      "env": {
        "NEUROMCP_DB_PATH": ".neuromcp/memory.db",
        "NEUROMCP_NAMESPACE": "my-project"
      }
    }
  }
}

MCP Surface

Tools (8)

Resources (13)

Prompts (3)

Memory Governance

Namespaces isolate memories by project, agent, or domain. Each memory belongs to exactly one namespace. Use NEUROMCP_NAMESPACE env var or specify per-operation.

Trust levels (high, medium, low, unverified) indicate confidence in the source. High-trust memories rank higher in search results and resist decay.

Soft delete tombstones memories instead of removing them. Tombstoned records survive for NEUROMCP_TOMBSTONE_TTL_DAYS (default 30) — recoverable until the next consolidation sweep.

Content hashing (SHA-256) deduplicates at write time. Identical content in the same namespace returns the existing memory instead of creating a duplicate.

Lineage tracking records source (user, auto, consolidation, claude-code, error), project ID, and agent ID per memory. Full audit trail for governance.

Configuration

All via environment variables. Defaults work for most setups.

Comparison

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT