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.

• 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.
• Governed Core — a deterministic Root Constitution, versioned knowledge and provenance, Teacher/Verifier promotion, authorization-first retrieval planning, and citation-aware context manifests are available to embedding hosts.
• 100% Privacy-First — local ONNX embeddings + local SQLite. Your memory never leaves your machine. No telemetry, no analytics, no phone-home: the server makes no outbound network call at all in its default configuration. (The optional synthesis backend talks to a local Ollama daemon, and OLLAMA_URL can be pointed elsewhere if you choose to.)

→ 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

The embedding model (bge-micro-v2) ships inside the package — it is fetched from Hugging Face at build time, checksum-verified, and bundled, so installing the tool needs no model download and the server makes no network call to start.

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

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

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

Governed Core vs. MCP tools

The governed substrate lives in McpEngramMemory.Core: immutable Root/overlay Constitutions, versioned Knowledge and append-only Provenance, quarantined Teacher proposals, deterministic-first verification, atomic reference promotion, authorization-first retrieval planning, context manifests, profiles/loadouts, and Skill/Documentation/CodeGraph/Curriculum contracts.

The 63 MCP tools include the full-profile promote_knowledge adapter, which executes the Teacher → deterministic Verifier → Constitution receipt → atomic governed-store path. Context and other asset-management tools remain Core APIs for embedded hosts. Every tool call also passes through the global Constitution pre/post filter. Skill execution is delegated to a host-provided ISkillSandbox; Engram does not run arbitrary Skill code.

Identity is also host-owned. IPrincipalContext carries tenant and principal claims. The stdio server bootstraps it from MEMORY_TENANT_ID and AGENT_ID, which are process configuration rather than authentication. Empty tenant + default agent is explicit legacy-unisolated mode.

Tenant-aware memory CRUD is implemented. The cognitive graph, clusters, lifecycle support data, collapse history, and diffusion caches still use global bare IDs, so affected standard/full tools fail closed for non-empty tenants. This is containment, not full tenant-qualified graph support. See Cognitive Constitution and Governed Core and Security.

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

Full tool documentation: MCP Tools Reference

The server uses the ModelContextProtocol 2.2.0 SDK with negotiated protocol handling, a global request-filter pipeline, and explicit read-only/destructive/idempotent/open-world tool metadata. SDK package version and negotiated MCP protocol revision are not the same thing.

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.5.0
engram-memory

Core engine (library)

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

# GitHub Packages
dotnet add package McpEngramMemory.Core --version 1.5.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.5.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 2.2.0
• FastBertTokenizer 1.0.28
• Microsoft.ML.OnnxRuntime 1.29.0
• bge-micro-v2 ONNX (384-dim, MIT license)
• Microsoft.Data.Sqlite 10.0.11
• xUnit v3 (tests)

License

MIT