Engrams are defined as the physical changes in brain state induced by an event, serving as the memory trace.
Jump to: What it is · Use cases · How it learns · Quick start · Prior art
Engram is a deterministic reasoning kernel — deterministic semantic reasoning system built on symbolic structure, a finite state machine, with configurable boundaries and self-improving weights. The nodes and actions are fixed by design; what learns over time are the connections between them. Given a context, Engram navigates a directed graph of concepts, asks targeted breaking questions to resolve ambiguity, and emits typed action contracts that a separate execution layer runs. Every path is auditable, the reasoning kernel cannot execute side effects, and the execution layer validates every contract against policy before running it. every weight is named, and the system improves without retraining — not by inventing new knowledge, but by finding more reliable routes through what it already knows.
The design makes specific trade-offs that most AI tooling deliberately avoids:
| Requirement | Small LLM / fine-tuned model | Engram |
|---|---|---|
| Same input + same graph state → guaranteed same output | No — stochastic by design | Yes — deterministic graph traversal |
| Full reasoning trace, auditable to each step | No | Yes — every node and edge is named |
| Runs fully offline, no runtime dependency | Needs runtime / server | Yes — single binary, no network |
| Improves from session feedback without retraining | No — requires new fine-tune | Yes — learns from every confirmed session. Can be frozen for compliance deployments |
| Stores patterns, never raw content | Depends on deployment | Structural — raw data never exists in transmittable form |
| Domain knowledge independently ownable per team | No — entangled in weights | Yes — separate graph files, swappable |
A 100–500 MB Engram graph in a single language covers the majority of queries in bounded domains where vocabulary is finite and resolution patterns repeat: CI/CD triage, structured log analysis, payment dispute routing, frontend error classification. The same 200–2000 problem signatures that account for 80–95% of real-world queries resolve in microseconds on a single CPU core — no GPU, no API key, no network.
LLMs (50–100 GB of weights) are better at novel cross-domain reasoning, source code analysis, deep unstructured conversation, and multilingual abstraction — capabilities Engram deliberately does not attempt. Engram handles the well-trodden paths cheaply and deterministically; the LLM handles novel cases and teaches the graph what to encode next. Each LLM resolution becomes a new graph path — that query never costs tokens again.
See future.md §19.1 for the full resource boundary analysis.
LLM agent mesh — the highest-value deployment is Engram as the deterministic first pass in front of an LLM:
Query arrives
│
▼
Engram graph activation
│
├── High confidence ──► Answer directly (no API call, microseconds)
│
└── Confidence below threshold ──► Bounded graph loop
│
├── Fetch actions + breaking questions + re-propagation
│
├── If confidence rises ──► Answer directly
│
└── If still unresolved ──► Structured handoff to LLM
│
▼
LLM response → reinforces the graph for next time
In a well-trained bounded domain, Engram handles the majority of queries without any model call. The LLM only sees cases that remain unresolved after the bounded loop — typically genuinely novel cases — and each one it resolves teaches the graph, making the next similar query cheaper. A fleet of specialist graphs coordinated by a router is a deterministic sparse Mixture of Experts: large total knowledge, small per-query compute, every routing decision auditable.
LLM tool gateway — structural security boundary — current LLM tool
security relies on system prompts and scattered runtime checks: fuzzy fuses
that a sufficiently persuasive input can blow. When an LLM calls Engram via
MCP, the only operations available are those explicitly enumerated in the
action contract. Permissions, rate limits, and confirmation requirements are
declared in a policy file and enforced by the PolicyEngine before any
execution layer call. The LLM cannot trigger an action outside the contract —
not because a prompt says so, but because the execution pathway does not exist.
Every action surface is enumerable before deployment; every blocked call is
logged; the policy file is the complete audit record.
MCP server — knowledge database for LLM agents — today's LLMs carry
memory in context windows (resets every conversation) or flat files (static,
unstructured). Engram exposed as an MCP tool gives any LLM agent access to
persistent, confidence-weighted, self-improving knowledge accumulated across
thousands of sessions. The LLM calls engram.query() mid-reasoning and
receives a typed reasoning path — confidence score, ruled-out candidates,
resolved dimensions — not a text chunk. Multiple agents sharing one Engram
instance share the graph (compressed patterns), never raw conversations.
The graph learns from every LLM-confirmed answer, so queries that initially
required model reasoning eventually resolve from Engram alone.
Team knowledge distillation — every resolved session compresses into the graph as edge weight updates, never as stored conversation or attributed records. Teams accumulate knowledge structurally: incident runbooks distilled from resolutions, onboarding paths that outlast any wiki, CI/CD triage patterns learned from real failures. Attribution is structurally absent — not scrubbed, never recorded. Privacy is a structural property of the design, not a policy enforced on top of it.
Industrial domain agent — bounded, high-stakes domains where determinism and auditability are regulatory requirements: medical triage routing, financial compliance screening, infrastructure fault isolation. The graph stores the domain; the policy engine enforces who can trigger which actions; the execution layer is completely separate. Also the right choice wherever an LLM of any size is not permitted: air-gapped, safety-critical, or regulated environments.
Distributed analytics without telemetry — local Engram instances (including browser-embedded WASM) emit compact graph deltas — not raw events, not identifying data — to server instances that merge them upward. What travels between nodes is edge weight adjustments, never raw user actions. The signal is the graph change, not the event: product analytics without telemetry pipelines, local-first apps contributing to a global knowledge pool without central data collection.
docs/use_cases.md documents all 10 deployment contexts.
User input text is discarded at the tokeniser boundary — it never enters any storage layer. This is a structural guarantee, not a sanitisation policy.
After each session, edge weights on the confirmed path increase; weights on rejected paths decay. What the graph stores is a node activation pattern and an outcome — not words, not who was involved, not what was typed. After 30 engineers hit the same error and confirm the same fix:
error=timeout + service=auth
→ CheckConnectionPool [weight: 0.91, n=34]
The 34 people who contributed that weight are structurally absent — not scrubbed, never recorded. Conflicting resolutions stay provisional until independently confirmed. Hidden relationships between concepts surface automatically as the session population grows.
Latent nodes are Engram's representation learning layer: repeated co-activation compresses recurring multi-signal patterns into reusable concepts.
Example: timeout + p95_latency_spike + retry_burst can converge into a latent node like upstream_saturation, which then routes future incidents faster.
- Deterministic — same input always produces the same reasoning path
- Explainable — every answer shows exactly which nodes and edges led to it
- Incremental learning — session feedback updates edge weights in real time, no retraining
- Offline — no network, no API key, no model server
- Composable — domain knowledge in separate graph files, loadable and swappable independently
- Action-first — reasoning proposes typed contracts only; execution layer validates and runs them
- Goal-aware — multi-step goals span multiple exchanges with mid-conversation revision support
- Escalation-ready — structured context exported for handoff when confidence falls below threshold
- Configurable learning — each graph deployment chooses whether to learn from live traffic or stay frozen
The graph is a file on disk today. Write-back is a deliberate per-deployment choice, not a system default. This gives two distinct operating modes:
Continuous learning — sessions write back to the graph in real time. Edge weights shift with every confirmed or rejected outcome. The right choice for collective memory, LLM agent mesh, and MCP deployments where improving from live traffic is the point.
Frozen / versioned — the engine reasons against a static graph and never mutates it. Learning happens offline: session outcomes accumulate in a staging environment, a new graph version is validated and promoted deliberately. The right choice for industrial agents, compliance routing, and business logic runners where stability and auditability matter more than continuous improvement — the graph behaves like versioned application code.
The same engine supports both. Which mode a deployment uses is a configuration decision, not an architectural one.
Phase 15 introduces a GraphStore trait that decouples the engine from the
filesystem entirely — the same reasoning engine will read and write graphs from
JSON files, an in-memory store, a REST API, a database, or a socket stream
without changing any traversal code. See roadmap.md for details.
More precisely, there are four independently lockable axes — context nodes, actions, graph learning, and input mode — giving 16 deployment configurations from fully frozen to fully adaptive. See architecture.md §3.7 for the full matrix and the provisional node mechanism that makes open axes safe.
Inspecting the graph: the graph files are plain JSON — readable with any tool today. The planned Phase 14 milestone adds a visual connectome inspector: load a knowledge directory, watch activation propagate from a query to a solution node, click any edge to inspect its weight and session history. See roadmap.md for details.
Several existing systems overlap with parts of Engram:
| System | What it shares | What it lacks |
|---|---|---|
| Drools / RETE rule engines | Deterministic, auditable, fires typed actions | No dialogue layer, no graph traversal, salience is hand-tuned not learned |
| Rasa | Task-oriented dialogue, story graphs, slot-filling (breaking question analog) | Stores utterances, requires full retraining, not offline-first |
| AIML / Pandorabots | Deterministic pattern-match dialogue | No weight learning, no graph navigation |
| Bayesian belief networks | Weighted directed graph, deterministic inference | No dialogue layer, no action contracts |
| OpenCyc / ResearchCyc | Closed-world knowledge graph, hard factual boundary, offline | No learning, no dialogue |
| LLM Wiki (Karpathy, 2026) | Knowledge compiled at ingest time, persistent cross-references, accumulates across sessions, local ownership | Requires an LLM at query time, stores raw text, non-deterministic answers, no typed action contracts |
The combination that does not exist elsewhere: a dialogue layer with structural privacy (no text stored at any layer), incremental weight learning without retraining, breaking questions as a first-class graph traversal primitive, and a hard knowledge boundary as an architectural guarantee rather than policy. Engram sits at the intersection of expert system, task-oriented dialogue, and reinforcement-learned policy graph — a combination shaped by constraints that existing tools treat as optional.
LLM Wiki as a companion pattern — the LLM Wiki pattern (compiling knowledge into a maintained Markdown vault rather than retrieving raw documents at query time) is a natural complement, not a competitor. An LLM Wiki accumulates human-readable prose understanding; Engram accumulates executable reasoning paths from confirmed sessions. A domain expert could maintain both in parallel: the wiki as the inspectable narrative layer, the Engram graph as the deterministic query engine. As the graph matures and handles the well-trodden queries directly, the LLM that maintains the wiki increasingly focuses on novel edges — the two systems feed each other.
| Document | What it covers |
|---|---|
| use_cases.md | 10 deployment contexts with strategic priority — start here for the "why" |
| proposal.md | Design overview, motivation, core concept, and index to all spec files |
| architecture.md | Data structures, query pipeline, activation-as-attention |
| disambiguation.md | Breaking questions, path labeling, goal tracking |
| learning.md | Reinforcement learning, latent discovery, weak memory, user profiles |
| roadmap.md | All 15 development phases (Phase 0–14) with checkpoints and deliverables |
| future.md | System comparison vs LLMs, future directions, sparse MoE framing |
| storage.md | CLI behavior and knowledge file layout |
| metrics.md | Sizing budget and production outcome metrics |
Phase 1 complete. The binary compiles, loads a real knowledge graph, and answers HTTP/API queries by keyword lookup with an optional reasoning trace.
Next: Phase 2 (graph activation and propagation) — the system navigates the graph by spreading activation through edges, producing ranked candidates with confidence scores rather than direct keyword matches.
The Rust binary is the reference implementation. The knowledge file format (JSON) and the reasoning spec are language-agnostic — implementations in any language are welcome. See CONTRIBUTING.md for details.
See docs/roadmap.md for all 15 phases (Phase 0–14) and checkpoints.
Requirements: Rust 1.85+ (rustup recommended)
git clone https://github.com/dominikj111/Engram.git
cd Engram/app
cargo build
cargo runengram v0.1.0 — knowledge loaded: 19 nodes, 17 edges
engram> 401 unauthorized
401 Unauthorized — the request lacks valid authentication. Check that your
token or API key is present, not expired, and sent in the correct header
(usually Authorization: Bearer <token>).
engram> cors blocked
CORS error — the browser blocked the request because the server did not
include the required Access-Control-Allow-Origin header. Add CORS middleware
on the server, or configure it to allow your origin explicitly.
engram> my api keeps getting 429
429 Too Many Requests — the rate limit has been exceeded. Back off and retry
after the duration in the Retry-After header.
engram> exit
Goodbye.
A seed HTTP/API knowledge graph ships with the repo — 19 nodes, 17 edges,
covering the most common status codes, CORS, timeouts, rate limits, and SSL
errors. Pass --explain at startup to see the reasoning trace on every answer:
$ cargo run -- --explain
engram> cors blocked
CORS error — ...
path: fix_cors
score: 3.76
via: fix_cors → cors
The subcommands reflect the full architecture:
$ cargo run -- --help
Usage: engram [OPTIONS] [QUERY] [COMMAND]
Commands:
history Show the last N sessions from history
weak List all unresolved weak memory entries
latent List all discovered latent nodes
provisional List all provisional (unconfirmed) nodes
audit Show bias audit: dominant edges and staleness report
Options:
--explain Print the full reasoning trace for each answer
--knowledge-dir Path to the knowledge directory (default: ./knowledge)
weak, latent, provisional, and audit are stubs today — each one
maps to a phase in docs/roadmap.md. The architecture is
built to be filled in, not redesigned.
- Spreading activation — Collins & Loftus (1975) — the activation propagation formula is a direct implementation
- Rescorla-Wagner learning rule — Rescorla & Wagner (1972) — the edge weight update formula
w' = w + α(1-w)is a direct implementation - ACT-R cognitive architecture — Anderson (1983) — activation thresholds, declarative memory chunks, learned associations across sessions
- Case-Based Reasoning — Aamodt & Plaza (1994) — the path cache is CBR
- ConceptNet — graph-based knowledge representation
- Task-oriented dialogue systems — breaking questions, goal tracking, action contracts, escalation payloads
- Sparse Mixture of Experts — the specialist swarm architecture is formally equivalent to sparse MoE
Not a clone of any of them — a deliberate combination shaped by the hard constraints: deterministic output, full auditability, offline operation, no retraining cycle.