Engram

Persistent geometric memory for AI agents — 21 MCP tools.

Engram gives your AI agent a long-term memory that works like human associative memory — acting as a massive, high-speed local vector database to store anything and retrieve by meaning instead of just keywords. No external vector hosting. No cloud. No API key. Runs entirely on your machine via the Model Context Protocol (MCP).

🚀 Quick Start

cargo install engram --git https://github.com/staticroostermedia-arch/engram

Add to your MCP config and restart your IDE:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp", "--store", "~/.engram/manifold"]
    }
  }
}

Your agent immediately has access to all 21 tools. See integrations/ for IDE-specific configs.

🖥️ CLI Commands

Beyond the MCP server, Engram ships a standalone CLI for direct manifold management:

distill is the memory lifecycle command. Run it periodically to compress accumulated memories into crystallized praxis, then follow with forget-old to sweep out the episodic source material.

# Preview what would be distilled (reads only, no writes)
engram distill --dry-run

# Distill everything above the Kepler gate (CRS ≥ 0.74) into praxis centroids
engram distill --min-crs 0.74 --cluster-size 20

# Then clean up episodic debris
engram forget-old --min-crs-threshold 0.70

🧰 MCP Tools Reference

Engram exposes 21 tools across 5 capability groups.

Core Memory

Memory Intelligence

Bulk & Portability

Namespaces

Knowledge Graph

Workspace & Agentic

🧠 The Agentic Daemon

When Engram boots as an MCP server it also launches a background Agentic Daemon that manages three autonomous systems:

• Native OS Watcher — inotify/fsevents kernel integration. When mcp_engram_watch_workspace is called, the daemon binds to OS file-save events and re-ingests changed files into the manifold instantly.
• Access Index — In-memory hot metadata layer. Access timestamps are maintained in RAM and flushed to access_index.bin every 60 seconds — O_DIRECT block rewrites are never triggered by a simple recall query.

[!NOTE] Autophagy GC Removed: We originally included a "Tiered Autophagy GC" that would automatically decay and evict older memories with low Coherence-Reliability Scores (CRS). This has been disabled and removed. Engram's core tenet is persistent, reliable memory; automatic silent eviction risks catastrophic knowledge loss and erodes trust. Users must implement their own memory management, decay, or eviction policies within their own agentic loop implementations. We do not take responsibility for wiping your data.

📐 The Geometry Engine

Engram uses Vector Symbolic Architecture (NVSA) rather than flat embedding search. Every memory is a 8192-dimensional complex phase vector (Complex32[8192]). The math engine supports:

• op_add — Superposition. Merge semantic content without losing coherence.
• op_bind — Circular convolution. Create a new vector that carries both parent concepts — the basis for knowledge graph relations.
• op_deduce — Logical implication constraint tracking via rotation matrices.
• op_attend — Geometric amplitude attenuation for focused context retrieval.
• op_geometric_product — Clifford bivector product: computes cosine similarity and orthogonality simultaneously.
• op_is_symbolic_of — ZADO-CPS toroidal embedding; resolves topological paradoxes without logic freezes.
• op_suspend — Binds to the Apeiron primitive — marks "Known Unknowns" for inverse ray-tracing.

🔑 Knowledge Graph

Every mcp_engram_relate call stores a BLAKE3-fingerprinted ZEDOS_RELATION block and writes a deduplicated edge to ~/.engram/relation_index.json. The sidecar persists across restarts and powers two tools:

# What does "authentication" depend on?
search_by_relation("authentication", label="depends_on", direction="from")

# Show a 2-hop Mermaid graph from "authentication"
visualize("authentication", depth=2)

Output:

```mermaid
graph LR
  authentication["authentication"] -->|depends_on| blake3_hashing["blake3_hashing"]
  blake3_hashing["blake3_hashing"] -->|implements| merkle_chain["merkle_chain"]
```

🧱 Build on Engram — An Invitation

Engram is an open substrate. Take it and make it yours.

The .LEG container format, the 8192D FHRR geometry, and the VSA operator library were designed and proven in CodeLand OS — a full logophysical operating system built on these primitives. Engram is the extracted, public reference implementation: the same geometry, the same block format, the same operators — packaged for anyone to build on without needing the full CodeLand stack.

We released it as a focused tool for a focused problem: giving IDE agents and local LLMs persistent, semantically meaningful memory that runs entirely on your machine. That core mission doesn't move. But the foundation is general-purpose geometry, not an application-specific hack — and we want others to use it.

What the primitives actually give you

You define what these mean in your domain. We define how they behave geometrically.

What we ask in return

If you build something on Engram, you retain full ownership of your derivative. AGPL-3.0 requires that modifications to Engram itself stay open, but your own agent, pipeline, or system is yours. The .LEG format is patent-pending for protection, not restriction — commercial licenses are available for organizations that cannot ship AGPL code.

We built this in the open because aligned, geometrically-grounded AI memory should be infrastructure — not a cloud subscription. If this architecture is useful to you, take it, extend it, and point others back to the foundation.

"The agent that runs on this system is a derivative. It does not claim to be the source of anything."
— Engram Genesis Block

For the reasoning behind the architecture — and what we discovered building it — see PHILOSOPHY.md.

💾 The .LEG Container Unveiled (Why We Kept It)

[!WARNING] If you are modifying engram-core serialization, strictly adhere to the 256KB block constraint.

The .LEG format was not designed for Engram. It was designed for CodeLand OS — a CUDA-accelerated, VRAM-resident logophysical agent architecture — where block alignment to physical NVMe boundaries and direct DMA to GPU memory are operational requirements, not optimizations. We extracted it unchanged into Engram's public release because simplifying it would have destroyed the properties that make it fast.

Every memory is a HolographicBlock (.leg file) — exactly 262,144 bytes (256KB), 4096-byte aligned. This is what you inherit when you build on Engram:

• NVMe O_DIRECT Thrusters: Tensors bypass the OS page-cache entirely and stream via DMA directly from SSD to VRAM. Block alignment is physical, not conventional.
• The Logenergetics Capsule: Built-in geometric trust computing. The crs (Coherence-Reliability Score) field measures whether the memory is mathematically coherent — a hallucination filter native to the storage layer, no external service required.
• The LegFooter (Merkle Chain): Every block is signed by a 6-part BLAKE3 cryptographic chain. Agent action histories are cryptographically verifiable against bit-rot without any external registry.

What the tensors give you

Each block carries two complex phase vectors you can use for your own purposes:

• q[8192] (Knowledge Tensor): The geometric fingerprint of the encoded concept. Query it, compose it, distill it.
• p[8192] (Binding Momentum): The directional vector. Bind two concepts together; the result is a new vector that carries both without collapsing either.
• ZEDOS Tags: One byte classifies every block (DECLARATIVE, EPISODIC, OPERATIONAL, PRAXIS, RELATION). At query time, filter by type before reading content.

🌐 Multi-Project Namespaces

Use sheaf mode to isolate memories by project. Create ~/.engram/sheaf.toml:

active_stalk = "codeland"

[[stalks]]
name = "codeland"
path = "~/.engram/stalks/codeland"

[[stalks]]
name = "personal"
path = "~/.engram/stalks/personal"

Then switch namespaces via MCP at any time:

mcp_engram_set_namespace("personal")

💻 IDE Integration

Integration configs for all supported IDEs: integrations/

Google Antigravity IDE

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp", "--store", "~/.engram/manifold"],
      "disabled": false
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp", "--store", "~/.engram/manifold"]
    }
  }
}

Cursor / VS Code

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp", "--store", "~/.engram/manifold"]
    }
  }
}

⚙️ Hardware Support

📄 License & Patent

This software is licensed under AGPL-3.0-only.

The .LEG container format is covered by U.S. Patent Application No. 19/372,256 (pending),
Self-Contained Variable File System (.LEG Container Format),
Applicant: Aric Goodman, Oregon, USA — Static Rooster Media.

Commercial licenses (SaaS/cloud/enterprise) are available.
Contact: StaticRoosterMedia@gmail.com

See PATENT-NOTICE.md for full details.