Engram

Persistent geometric memory for AI agents.

Engram is a local, hardware-native memory substrate that gives AI agents coherent, long-term memory with structure-preserving compression, synthetic calculus over both words and numbers, and true continuity across cold shutdowns.

Share on X / GitHub: docs/images/engram-share-x.png (1280×720). For the repo social preview card: GitHub → Settings → General → Social preview → upload that image.

Unlike vector databases or simple logs, Engram uses fixed-size holographic blocks, VSA operations, sheaf gluing, and categorical reasoning to maintain meaning and relationships even after heavy compression and long-running sessions.

It is designed as a drop-in backend for any LLM (Grok, Claude, Llama, etc.) via the Model Context Protocol (MCP) and is fully open for anyone to build on.

New here?

Rituals = documented MCP habits (wake → trace decisions → handoff) so memory compounds across sessions — not mysticism, just the discipline that beats flat RAG.

Engram is particularly well-suited for:

• Long-running agentic systems

• Games with persistent LLM characters

• Personalized AI companions

• Any application needing coherent, evolving memory beyond simple vector stores

Human review (LEG Browser beta): ./scripts/leg (static) or ./scripts/leg --live — see docs/LEG_BROWSER.md.

Why not flat RAG?

Full comparison vs mem0/Letta/chroma: see docs/GROK_BUILD_MEMORY.md.

Related MCP server: mesh-memory

Quick start

git clone https://github.com/staticroostermedia-arch/engram.git
cd engram
cargo build -p engram-server
target/debug/engram --version   # 0.7.0-beta.5

MCP config (Grok Build / Cursor — use scripts/engram-grok):

{
  "mcpServers": {
    "engram": {
      "command": "/path/to/engram/scripts/engram-grok",
      "args": ["mcp"],
      "env": {
        "ENGRAM_STORE": "~/.engram/stalks/",
        "ENGRAM_PROFILE": "agent"
      }
    }
  }
}

Restart your IDE, then:

mcp_engram_session_start(intent="your goal")

Lean loop: session_start → context_for_edit(path) → recall(scope=anchors) → quick_trace / remember → session_end(summary).

All ecosystems: integrations/README.md. Cursor ambient wake: ./scripts/cursor-engram-preflight.sh.

LEG Browser (beta)

Local, read-only mirror of agent memory — no cloud, no npm, no account. Your manifold stays in ~/.engram/; the repo ships tools and the viewer.

./scripts/leg              # static — instant curated demo, no backend
./scripts/leg --live       # live — engram serve :3456 + viewer :8765

What you get (beta):

• Wake queue + continuity playbook (same harness agents see at session_start)

• Code atlas + evolution timeline at file loci (__arc segments, trace chain)

• Presentation stratum (~40–64 distilled nodes, not the full cold manifold)

• Activity feed, traces, goals, thought tiles, relations, geosphere view

• Hygiene controls (demote sprawl, condensation hints, wake/edit-arc debt)

Beta caveats: single-file SPA; galaxy view may be slow on 100k+ stores; agent MCP paths stay bounded. Hard-refresh after index.html updates. Static mode is a demo snapshot — --live shows real MCP work.

Full guide: docs/LEG_BROWSER.md. Safe serve restart (does not kill MCP): ./scripts/restart-leg-serve.sh.

Memory model (one paragraph)

Fixed 256KB HolographicBlocks (.leg3): 8192D phase (q), momentum (p), CRS lawfulness, BLAKE3 Merkle, spatial AABB. VSA calculus + sheaf gluing via processes/*.toml (rituals, harness, monitor). NREM / ego.leg3 for long-horizon continuity. Details: docs/GEOMETRIC_MEMORY.md, docs/RITUALS.md, docs/HARNESS_INJECTION.md.

Solid-State Tensor — NVMe as context extension

On fast NVMe (e.g. Samsung T700) with cuFile/GPUDirect and full_bvh_gpu recall, the cold manifold on disk acts as a cryptographically verified extension of the agent context window — not a separate vector DB you query occasionally.

Each concept is a persistent tensor entry: unit-hypersphere q, momentum p, dynamic bonds (relation blocks + Merkle lineage), CRS ≥ 0.74. The lean path surfaces only the relevant subgraph:

tensor_upsert → relate/bonds → promote_hot → tensor_recall (q preview + edges + lineage)

MCP tools: mcp_engram_tensor_upsert, mcp_engram_tensor_recall (plus lean default recall, query_with_momentum when trending matters). Poll mcp_engram_get_backend_readiness until nvme_recall_ready: true on large stores. Ritual: processes/ritual/solid-tensor-consolidation.toml (p-drift OP_ADD at session_end).

Thought tiles ↔ tensor (unified): mcp_engram_thought_tile_create and write_result dual-write a first-class tensor:tile__{stem} mirror with bonds to goal/trace/spatial concepts. Plain mcp_engram_update on tile:* syncs the mirror; mcp_engram_update_with_tensor_bond is the verified composite. tile_type: propose_improvement routes verified update on target_concept. Wake surfaces rituals via agent_discipline.tensor_unification_rituals. Harness: --suite tensor-thought-unification. Rituals: processes/ritual/thought_tile_to_tensor.toml, verified-update-with-consolidation.toml. See docs/skills/engram-thought-tiles.md and docs/HARNESS_INJECTION.md.

Demo: cargo test -p engram-server solid_state_tensor_verification_harness or examples/tensor_demo.py. Full tile→tensor cycle: STABLE_BIN=target/debug/engram tools/test-harness/bin/engram-harness.sh --suite tensor-thought-unification.

Linguistic calculus (words + numbers in the same sheaf): docs/CATEGORICAL_LINGUISTIC_CALCULUS.md.

flowchart LR
  W[session_start<br/>harness injection] --> E[edit + trace]
  E --> H[session_end handoff]
  H --> W

What's new (v0.7.0-beta.5+)

• Theory-informed continuity spikes: Portable rehydration_manifest at wake (no broad recall); soft sentinel nudge at ~30 turns / ~120 min; uncertainty:* receipts for thin memory claims; fork-scoped A/D/R hints; immutable receipt:session_* audit sidecar. See HARNESS_INJECTION.md.

• Tensor–thought-tile unification: Dual-write tile:* → tensor:tile__* mirrors with bonds; update_with_tensor_bond + plain update sync; propose_improvement tile type; session_end p-drift consolidation; harness suite tensor-thought-unification (2× consecutive runs + SCRATCH evidence). Rituals: thought_tile_to_tensor, verified-update-with-consolidation.

• Solid-State Tensor MVP: NVMe-backed geometric memory as context extension — tensor_upsert / tensor_recall, bond subgraph delivery, momentum consolidation ritual, hermetic verification harness.

• Goal hygiene: 72h stale autopause + session_end audit (active goal stack stays bounded).

• Code atlas continuity v2: situated edit memory at the locus — atlas v2.1, evolution_at_locus, hard wake gate, post_edit_palette, update coherence. CODE_ATLAS_CONTINUITY.md

• Large-store perf: relational lean v2, cuFile DMA readiness, bounded NREM + relation batching — wake on ~192k blocks in seconds when BVH is warm.

• 87 MCP tools registered (tool_list() in mcp.rs — 83 mcp_engram_* + 4 linguistic); lean default remains 8 essential.

• LEG evolution panel: ./scripts/leg --live + GET /api/code-atlas?evolution=1.

Full history: CHANGELOG.md.

Categorical Linguistic Calculus

Engram supports native synthetic calculus over linguistic structures — including mixed number + word operations — all inside the geometric memory manifold.

Key capabilities:

• Structure-preserving compression and decompression of language while preserving homotopy coherence (meaning up to coherent deformation).

• Synthetic operations: differentiate, integrate, and operadic composition on word bundles.

• Mixed number + word reasoning with clearly defined bridging morphisms and class-mixing guards.

• Full persistence via NREM consolidation and ego.leg3 self-modeling.

Quick Example

// Build a linguistic bundle + mixed expression
let bundle = LinguisticDiscourseBundle { ... };
let mixed = op_mixed_linguistic_number_scale(&num_phase, &word);

// Run calculus and store result
let delta = op_linguistic_differentiate(&bundle);
let result = op_linguistic_integrate(&[bundle, delta]);

// Store with full continuity
let _ = Leg3Pointer::mint_linguistic(&result, true); // promotes toward ego.leg3

All operations return CRS (Coherence-Reliability Score) and can be verified with mcp_engram_verify_manifold_integrity.

Examples

Build against target/debug/engram during development.

MCP tools

8 essential for daily work — 87 registered (83 mcp_engram_* + 4 linguistic; source: tool_list() in mcp.rs); full map: docs/TOOL_DECISION_MAP.md. Categorized reference: docs/MCP_TOOLS_REFERENCE.md. Harness matrix: tools/test-harness/python/mcp_tool_matrix.py.

Grok plugin slash commands: grok-plugin-engram/commands/.

Deep dive (linked, not repeated here)

Users

Agents

Contributors

Theory

CLI: engram remember|recall|forget|list|ingest|trace|distill|build-index

Namespaces: mcp_engram_set_namespace("project") or ~/.engram/sheaf.toml

Contributing

CONTRIBUTING.md · AGENTS.md · PR checklist in .github/PULL_REQUEST_TEMPLATE.md

Dev build: cargo build -p engram-server && target/debug/engram --version

License

AGPL-3.0-only. .leg3 format: U.S. Patent Application No. 19/372,256 (pending). Commercial licenses: StaticRoosterMedia@gmail.com — PATENT-NOTICE.md.