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: mnemos

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

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)

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

Beta caveats: single-file SPA; large stores may be slow on some panels; hard-refresh after 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.

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 in v0.7.0-beta.2

• Cold-start onboarding: README human→agent fork, FIRST_RUN role split, contract bootstrap checklist — install path works without insider context.

• Public docs polish: personal knowledge wiki, docs/internal/ maintainer journals, external-reader tone pass.

• JIT deformation: task-type playbooks + verified_processes at wake (DEFORMATION_PLAYBOOKS.md).

• 70 MCP tools smoke-tested (67 pass in harness); lean default remains 8 essential.

• LEG Browser beta (from beta.1): ./scripts/leg --live — memory review UI, wake queue, presentation stratum.

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 — 70 registered (66 mcp_engram_* + 4 linguistic); 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.