Engram

Hardware-native geometric memory for AI agents — 31 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 — with a background daemon that autonomously consolidates memory, monitors your system's health, and proposes fixes.

No cloud. No API keys. No deserialization overhead. Runs entirely on your machine via the Model Context Protocol (MCP).

🚀 Quick Start

# Clone and install from source
git clone https://github.com/staticroostermedia-arch/engram.git
cd engram
cargo install --path crates/engram-server

# Verify install
engram --version
# engram-server 0.4.x

Add to your MCP config and restart your IDE:

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

Your agent immediately has access to all 31 tools. See integrations/ for IDE-specific configs (Antigravity, Claude Desktop, Cursor, VS Code).

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

🔌 Optional — enable neural semantic search: set ENGRAM_EMBED_URL=http://localhost:8086/v1/embeddings to point at any OpenAI-compatible local embedding server (llama.cpp, ONNX, nomic-embed). Without it, Engram falls back to BLAKE3 spiral-phase encoding — everything still works.

⚡ 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 aligns perfectly to 64× 4KB hardware pages. The .leg3 format is a strict C-struct — zero JSON decoding, zero Protobuf parsing.

• O_DIRECT and GPUDirect Storage (GDS): Engram bypasses the OS page-cache. When your agent searches for a memory, the tensor streams via DMA from NVMe directly into CPU registers or GPU VRAM via NVIDIA cuFile APIs.

• Zero-Copy Architecture: GPUDirect Storage eliminates the CPU bounce buffer. Tensors transfer directly over PCIe to the GPU for parallel distance calculations — scan rates in the GB/s range with near-zero CPU overhead.

Every block fuses the full source text, an 8192-dimensional semantic tensor, spatial 3D bounds (for code placement), a BLAKE3 Merkle chain proof, and a thermodynamic confidence score (CRS).

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

🛡️ Hallucination & Loop Protection

Traditional vector databases are append-logs: if an LLM hallucinates or loops, it spams the database with broken snippets, destroying context quality.

Engram uses a built-in Lyapunov stability tracker (the Coherence-Reliability Score, CRS) that monitors how much a concept drifts between updates:

• Low Drift → CRS rises: The system recognizes convergence and increases trust.

• High Drift → CRS penalized: Rapid contradictory overwrites are flagged as hallucination. Agents learn not to trust low-CRS blocks.

Memories must mathematically prove their stability. High-CRS blocks are automatically promoted to permanent ZEDOS_PRAXIS status during NREM consolidation. Low-CRS blocks decay and are swept by autophagy.

🧠 The Agentic Daemon

When Engram boots as an MCP server, it launches a background daemon that runs three autonomous loops:

1. File Watcher

Auto-ingests saved files via inotify/fsevents kernel hooks. Every time you save a .rs, .py, .ts, or any other supported file, the AST pipeline extracts new semantic blocks and updates the manifold without any agent intervention.

2. NREM Consolidation (Phase 3)

On a periodic cycle (~every 10 minutes), the daemon performs a sleep-cycle memory consolidation pass:

• Harvests all memories above CRS ≥ 0.74 (grounded fact tier)

• Superimposes them via OP_ADD into a unified ego narrative tensor

• Writes the result to ego.leg3 — the agent's persistent self-model

• Mints a ZEDOS_EPISODIC block summarizing the consolidation

This is the equivalent of REM sleep for the agent's memory. Knowledge crystallized in one session is absorbed into the ego tensor and becomes available as prior context in all future sessions.

3. System Health Watchdog

The daemon continuously monitors critical background processes (e.g., the Circadian daemon that drives nightly consolidation). If a watched process dies, it automatically mints an Agency Proposal in the agency_proposals.json queue — a human-readable explanation of what failed and exactly what command it wants to run to fix it. The operator can approve or reject the proposal via the Cockpit UI or API.

Autophagy is disabled by default. An agent's memory should outlive sessions. Use mcp_engram_forget_old to trigger manual GC when needed.

🌳 AST-Aware Semantic Distillation

Traditional RAG chunks text arbitrarily, destroying function boundaries. Engram's ingest pipeline uses a universal AST-extraction layer powered by Tree-Sitter, parsing Rust, Python, TypeScript, JavaScript, Go, Java, C, and C++.

It mints exactly one memory block per public semantic item (functions, structs, classes, traits):

• The Tensor (q): Encodes the doc comment and signature — what it is and what it does.

• The Provlog: Carries the raw, full-length source code — verbatim retrieval at any time.

• Spatial Embodiment: Maps the precise 2D row/column coordinates (AABB) of each AST node into the block's physical bounds. Agents know where code lives, not just what it does.

🧰 MCP Tools Reference (31 Tools)

Core Memory (4)

Memory Management (9)

Workspace & Agentic (8)

Knowledge Graph (3)

Every mcp_engram_relate call stores a ZEDOS_RELATION block via OP_BIND. Edges are mathematical memory vectors — no external graph database required.

Physics & Alignment (5)

Autonomy & Orchestration (2)

These tools expose Engram's deeper integration with the Monad OS oracle layer, enabling agent self-reflection and multi-step workflow orchestration.

🖥️ CLI Commands

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

🌐 Multi-Project Namespaces

Engram isolates memories by project via namespaced stalks. No config file required — just call:

mcp_engram_set_namespace("my_project")   # creates + switches to this namespace
mcp_engram_set_namespace("work_project") # switch to another project
mcp_engram_list_namespaces()             # see all namespaces

Or configure via ~/.engram/sheaf.toml:

active_stalk = "codeland"

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

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

⚙️ Hardware Support

💻 IDE Integration

Integration configs for all supported IDEs: integrations/

Google Antigravity IDE

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

Claude Desktop / Cursor / VS Code

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

📄 License & Patent

This software is licensed under AGPL-3.0-only.

The .LEG3 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.