mcp-engram-memory

Give your AI agent persistent memory that survives across sessions. Store decisions, recall context, and build expertise — all locally, no cloud required.

A cognitive memory engine exposed as an MCP server with hybrid search (BM25 + vector), knowledge graph, lifecycle management, hierarchical expert routing, and a graph-aware memory-diffusion subsystem (v0.9.0) that drives spreading-activation decay, sleep-style consolidation, and spectral retrieval re-ranking — all from a single per-namespace eigenbasis of the graph Laplacian.

Quickstart

Option 1 — One-click setup script (clones, restores, and wires up Claude Code automatically)

# Windows PowerShell
irm https://raw.githubusercontent.com/wyckit/mcp-engram-memory/main/setup.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/wyckit/mcp-engram-memory/main/setup.sh | bash

Both scripts clone the repo, download the ONNX model, and patch ~/.claude.json with the MCP server entry. Optional flags: --profile minimal|standard|full, --storage json|sqlite, --agent-id <id>. Already cloned? Run pwsh setup.ps1 or bash setup.sh from the repo root.

Option 2 — Clone and configure manually

git clone https://github.com/wyckit/mcp-engram-memory.git
cd mcp-engram-memory
dotnet restore

Add to your MCP client config (Claude Code, Copilot, Gemini, Codex):

{
  "mcpServers": {
    "engram-memory": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/mcp-engram-memory/src/McpEngramMemory"],
      "env": { "MEMORY_TOOL_PROFILE": "minimal" }
    }
  }
}

Option 3 — Docker

docker build -t mcp-engram-memory .
docker run -i -v memory-data:/app/data mcp-engram-memory

Option 4 — NuGet library (embed the engine in your own app)

dotnet add package McpEngramMemory.Core --version 0.9.0

First run downloads a ~5.7 MB embedding model (bge-micro-v2) — subsequent starts are instant.

See examples/ for ready-to-use config files and AI assistant harness templates.

Memory Graph Visualizer

The built-in D3.js graph viewer lets you explore your memory graph interactively.

Generate a snapshot (call this MCP tool from any AI assistant):

get_graph_snapshot   →   save the JSON   →   open visualization/memory-graph.html

Features:

• Force-directed layout — related memories cluster together, typed edges (elaborates, contradicts, depends_on, …) shown in distinct neon colors
• Lifecycle colors — STM nodes amber, LTM nodes blue; cluster summaries marked with a dashed ring
• Convex-hull cluster overlays — cluster membership visible at a glance
• Search & highlight — type in the search bar to instantly dim non-matching nodes and pulse-highlight matches in gold; ‹ › buttons or Enter / Shift+Enter to cycle through results
• Zoom / pan / rotate — + / − / ⊡ buttons; scroll to zoom; right-click drag to rotate the whole graph
• Fractal density overlay — zooms out reveal a quadtree density map color-coded by lifecycle state
• Connected-only filter — hide isolated nodes to focus on the linked knowledge graph
• Drag-and-drop JSON loading — drop a snapshot file directly onto the viewer

The snapshot file is not committed (it's personal memory data). Generate a fresh one any time with get_graph_snapshot.

Tool Profiles

Control how many tools are exposed with MEMORY_TOOL_PROFILE:

At a Glance

System Layers

AI Assistant Setup

Copy the reference harness for your tool — each includes recall/store/routing patterns:

Claude Code users: Route memory sub-agents to Sonnet (model: "sonnet") and utility sub-agents to Haiku (model: "haiku") to maximize your subscription. See the harness for details.

For step-by-step setup prompts, see AI Assistant Setup.

Cost-Optimized Usage (Claude Code)

Opus thinks, Sonnet remembers, Haiku explores.

MCP Tools (65)

Full tool documentation: MCP Tools Reference

Environment Variables

NuGet / GitHub Packages

The core engine is available as a NuGet package for embedding in your own .NET applications:

# nuget.org
dotnet add package McpEngramMemory.Core --version 0.9.0

# GitHub Packages
dotnet add package McpEngramMemory.Core --version 0.9.0 \
  --source https://nuget.pkg.github.com/wyckit/index.json

using McpEngramMemory.Core.Services;
using McpEngramMemory.Core.Services.Storage;

var persistence = new PersistenceManager();
var embedding = new OnnxEmbeddingService();
var index = new CognitiveIndex(persistence);

// Store
var vector = embedding.Embed("The capital of France is Paris");
var entry = new CognitiveEntry("fact-1", vector, "default", "The capital of France is Paris", "facts");
index.Upsert(entry);

// Search
var results = index.Search(embedding.Embed("French capital"), "default", k: 5);

Documentation

Build & Test

cd mcp-engram-memory
dotnet build
dotnet test    # full suite, including slower MSA benchmark cases

Tech Stack

• .NET 8/9/10, C#
• ModelContextProtocol 1.0.0
• FastBertTokenizer 0.4.67
• Microsoft.ML.OnnxRuntime 1.17.0
• bge-micro-v2 ONNX (384-dim, MIT license)
• Microsoft.Data.Sqlite 8.0.11
• xUnit (tests)

License

MIT