Engram

Hardware-native geometric memory for AI agents — 21 MCP tools.

Engram is not a vector database. It is a persistent geometric memory engine designed for AI agents. It bypasses conventional database software layers by storing information in fixed, mathematically rigorous 256KB tensors directly on NVMe drives. No cloud, no API keys, no deserialization overhead. Runs entirely on your machine via the Model Context Protocol (MCP).

🚀 Quick Start

By default, Engram uses internal geometric hashing. To enable massive-scale semantic code search, point it to any OpenAI-compatible embeddings endpoint (e.g., local llama.cpp or ONNX):

export ENGRAM_EMBED_URL="http://localhost:8080/v1/embeddings"
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.

📖 New here? Read the First Run Guide — it walks you through verifying every feature works, activating the file watcher daemon, and seeding your manifold with your codebase.

⚡ Why 256KB? The Hardware-Native Advantage

Engram maps your project's memory into strict 262,144 byte (256KB) containers called HolographicBlocks. This size is non-arbitrary.

• Native Tensor Load: 256KB perfectly aligns to 64× 4KB hardware pages. Because the .leg format is a strict C-struct, it requires zero JSON decoding or Protobuf parsing.
• O_DIRECT and GPUDirect Storage (GDS): Engram bypasses the operating system's page-cache. When your agent searches for a memory, the tensor streams via Direct Memory Access (DMA) from the physical NVMe SSD straight into CPU registers or directly into GPU VRAM using NVIDIA cuFile APIs.
• Zero-Copy Architecture: By leveraging GPUDirect Storage, Engram eliminates the CPU bounce buffer entirely. Tensors are transferred directly over the PCIe bus to the GPU for massive parallel distance calculations, enabling scan rates of gigabytes per second with near-zero CPU overhead.

Every block mathematically fuses the full original source code, 8192-dimensional semantic tensors, spatial 3D bounds (for code placement), and cryptographic BLAKE3 Merkle chain proofs.

(See docs/architecture.md for a deep dive into the container format, cuFile integration, and LBVH scaling).

🛡️ Hallucination & Loop Protection (Volatility Tracker)

Traditional vector databases are "dumb" append-logs: if an LLM hallucinates or gets stuck in a debugging loop, it will spam the database with hundreds of slightly-different, broken code snippets, destroying the context window.

Engram does not blindly accept every update as equally valid. It features a built-in mathematical volatility tracker (using Lyapunov stability equations) that monitors how much a concept "shifts" between updates:

• Low Drift: If an agent updates a memory and the semantic meaning barely changes, the system recognizes it as stable/converging. The block's Coherence-Reliability Score (CRS) goes up.
• High Drift: If an agent rapidly overwrites a memory with wildly different concepts (a hallucination loop), the system recognizes the volatility. The block's CRS is penalized.

Memories must mathematically prove their stability over time. If a block's CRS drops too low, agents know not to trust it.

🖥️ CLI Commands

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

🌳 AST-Aware Semantic Distillation

Traditional RAG chunks text arbitrarily, destroying function boundaries and context. Engram's ingest pipeline uses a universal AST-extraction layer powered natively by Tree-Sitter.

It natively parses Rust, Python, TypeScript, JavaScript, Go, Java, C, and C++.
Engram mints exactly one memory block per public semantic item (functions, structs, classes).

• The Tensor (q): Encodes the doc comment and signature.
• The Provlog: Carries the raw, full-length source code.
• Spatial Embodiment: Maps the precise 2D row/column coordinates of the AST node directly into the memory block's physical bounds, allowing the agent to know where code lives, not just what it does.

🧰 MCP Tools Reference

Engram exposes 21 tools across 5 capability groups.

Core Memory

Memory Intelligence

Workspace & Agentic

Knowledge Graph

Every mcp_engram_relate call stores a ZEDOS_RELATION block using op_bind. Edges are mathematical memory vectors, meaning no external graph database is required.

🧠 The Agentic Daemon & Autophagy

When Engram boots as an MCP server, it also launches a background Agentic Daemon that manages autonomous file system watching via inotify/fsevents kernel integration. When you save a file, the daemon re-ingests the changed AST components instantly.

[!NOTE]
Autophagy (GC) is Disabled by Default: We believe an agent's memory should outlive its sessions. If a user steps away from a project for 3 months, their contextual memory shouldn't spontaneously decay. Engram calculates Coherence-Reliability Scores (CRS) continuously, but we deliberately disabled automatic eviction. You must use the mcp_engram_forget_old tool to instruct the agent to run manual garbage collection.

🌐 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 / 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: [email protected]

See PATENT-NOTICE.md for full details.