McpEngramMemory.Core 0.7.0

<p align="center"> <img src="images/banner.svg" alt="MCP Engram Memory" width="900"/> </p>

<p align="center"> <a href="https://dotnet.microsoft.com/"><img src="https://img.shields.io/badge/.NET-8%20%7C%209%20%7C%2010-512BD4" alt=".NET"/></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"/></a> <a href="https://www.nuget.org/packages/McpEngramMemory.Core"><img src="https://img.shields.io/nuget/v/McpEngramMemory.Core" alt="NuGet"/></a> <a href="https://github.com/wyckit/mcp-engram-memory/packages"><img src="https://img.shields.io/badge/GitHub%20Packages-v0.7.0-blue" alt="GitHub Packages"/></a> <img src="https://img.shields.io/badge/tests-850%20passed-brightgreen" alt="Tests"/> <img src="https://img.shields.io/badge/MCP%20tools-52-blue" alt="MCP Tools"/> </p>

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, and hierarchical expert routing.

<p align="center"> <img src="images/features.svg" alt="Features" width="900"/> </p>

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

<p align="center"> <img src="images/graph-overview.png" alt="Memory graph overview — 1,207 nodes, 375 edges, 178 clusters" width="860"/> </p>

<p align="center"> <img src="images/graph-detail.png" alt="Memory graph connected-only detail view" width="860"/> </p>

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

<p align="center"> <img src="images/how-it-works.svg" alt="How It Works" width="900"/> </p>

<p align="center"> <img src="images/retrieval-pipeline.svg" alt="Retrieval Pipeline" width="900"/> </p>

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 (52)

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.7.0

# GitHub Packages
dotnet add package McpEngramMemory.Core --version 0.7.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    # 850 tests across 47 files

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