McpEngramMemory.Core 1.4.0

<p align="center"> <img src="images/banner.svg?v=1.4.0" 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> <img src="https://img.shields.io/badge/tests-1154%20non--live-brightgreen" alt="Tests"/> </p>

The local-first cognitive memory kernel for AI agents

Memory physics, not just storage. Most agent memory systems store context. Engram evolves context — topology-driven decay, consolidation, and contradiction handling, all running locally with zero external API.

<p align="center">

<img src="images/memory-graph.gif" alt="Engram memory graph clustering during a consolidation cycle: STM (amber) nodes migrating into LTM (blue) clusters, with pulse-highlight on retrieval" width="900"/> </p>

<p align="center"><em>The memory graph consolidating in real time — short-term (amber) memories cluster and promote to long-term (blue) during a sleep cycle.</em></p>

• Context Control — graph-Laplacian diffusion decays trivial chats so your context window doesn't choke on noise. Important, well-connected knowledge stays sharp; transient chatter fades.
• Contradiction Management — auto-detects when goals or architecture change, then archives the stale logic so the agent stops acting on decisions you already reversed.
• 100% Privacy-First — local ONNX embeddings + local SQLite. Your memory never leaves your machine. Zero external API, zero cloud, zero telemetry.

→ See the cold-start scorecard · Get started in 5 minutes

Quickstart

# Windows — clones, builds, and wires up your AI assistant automatically
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

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

<details> <summary>Other install options (manual clone · Docker · NuGet)</summary>

Manual clone

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

Add to your MCP client config:

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

Docker

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

NuGet library (embed the engine in your own .NET app)

dotnet add package McpEngramMemory.Core --version 1.4.0

See examples/ for ready-to-use config files.

</details>

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?v=1.2.0" alt="How It Works — store, search, link, route, with automatic diffusion subsystem and lifecycle transitions" width="900"/> </p>

<p align="center"> <img src="images/retrieval-pipeline.svg?v=1.2.0" alt="9-stage retrieval pipeline including v0.9.0 spectral re-ranking" width="900"/> </p>

AI Assistant Setup

Model execution belongs to the host harness, not the Engram server: expert profiles route to persona-backed memory namespaces, while the host model reasons over the retrieved evidence. See Model and Reasoning Routing for canonical task tiers, the current Codex model mapping, reasoning escalation rules, and ready-to-use profiles.

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

Full tool documentation: MCP Tools Reference

Environment Variables

NuGet / GitHub Packages

The server ships as a dotnet global tool, and the core engine as a library you can embed in your own .NET applications.

Server (global tool)

dotnet tool install --global McpEngramMemory --version 1.4.0
engram-memory

Core engine (library)

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

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

Optional: in-process synthesis

synthesize_memories generates through an ITextGenerator. The server ships one implementation — OllamaClient, talking to a local Ollama daemon. If you want generation fully in-process with no daemon, add the optional ONNX backend when embedding the library:

dotnet add package McpEngramMemory.Synthesis.Onnx --version 1.4.0

using McpEngramMemory.Core.Services.Synthesis;

ITextGenerator generator = new OnnxGenAiTextGenerator(modelDir); // stage a model first

It lives in its own package because ONNX Runtime GenAI ships native binaries for every platform it supports — roughly 500 MB. Keeping it separate means neither the McpEngramMemory tool nor a plain McpEngramMemory.Core install pays that cost. Stage a model with scripts/fetch-synthesis-model.ps1.

The McpEngramMemory server does not support SYNTHESIS_BACKEND=onnx; it fails at startup with a pointer to this package. In-process synthesis is for hosts embedding the Core library.

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.23.0
• bge-micro-v2 ONNX (384-dim, MIT license)
• Microsoft.Data.Sqlite 8.0.11
• xUnit (tests)

License

MIT