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

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

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 (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 1.2.0

# GitHub Packages
dotnet add package McpEngramMemory.Core --version 1.2.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.23.0
• bge-micro-v2 ONNX (384-dim, MIT license)
• Microsoft.Data.Sqlite 8.0.11
• xUnit (tests)

License

MIT