# sdidsa/engram architecture

> Architecture diagram of the GitHub repository sdidsa/engram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sdidsa/engram
- Repository: https://github.com/sdidsa/engram

## Overview

ENGRAM is a continual-knowledge system: constrained-language input is executed as deterministic plans over a persistent bitemporal knowledge base, with retrieval and evidence-based verification producing answers. Documents can be acquired into staging, corroborated, and committed; knowledge and procedures also have separate induction and lifecycle management paths. The graph retains the major documented capabilities, but many edges rely on imports named in the SOURCE INDEX or README descriptions rather than inspected call sites; uncertain wiring is omitted.

Main entry points: [`src/engram/engine/executor.py`](https://github.com/sdidsa/engram/blob/master/src/engram/engine/executor.py) (Plan executor), [`src/engram/store/sqlite_store.py`](https://github.com/sdidsa/engram/blob/master/src/engram/store/sqlite_store.py) (Bitemporal store), [`src/engram/acquisition/pipeline.py`](https://github.com/sdidsa/engram/blob/master/src/engram/acquisition/pipeline.py) (Document acquisition), [`src/engram/procedure/service.py`](https://github.com/sdidsa/engram/blob/master/src/engram/procedure/service.py) (Procedure proposals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Language interface"]
  node_grammar["Constrained grammar<br/>[grammar.py]"]
  node_llama["Model interface<br/>[llama.py]"]
end

subgraph group_runtime["Execution and knowledge"]
  node_executor["Plan executor<br/>[executor.py]"]
  node_plans["Typed plans<br/>[plans.py]"]
  node_programs["Multi-step programs<br/>[program.py]"]
  node_inference["Datalog inference<br/>[inference.py]"]
  node_knowledge["Belief revision<br/>[revision.py]"]
  node_dependencies["Truth maintenance<br/>[dependencies.py]"]
  node_store[("Bitemporal store<br/>[sqlite_store.py]")]
  node_store_models["Version models<br/>[models.py]"]
end

subgraph group_evidence["Acquisition and evidence"]
  node_acquisition["Document acquisition<br/>[pipeline.py]"]
  node_corroboration["Fact corroboration<br/>[corroborate.py]"]
  node_retrieval["Evidence retrieval<br/>[service.py]"]
  node_verification["Answer verification<br/>[service.py]"]
  node_faithfulness["Faithfulness checks<br/>[faithfulness.py]"]
end

subgraph group_evolution["Learning and lifecycle"]
  node_induction["Knowledge induction<br/>[stage.py]"]
  node_procedure["Procedure proposals<br/>[service.py]"]
  node_procedure_runner["Procedure runner<br/>[runner.py]"]
  node_procedure_candidates["Procedure candidates<br/>[candidates.py]"]
  node_procedure_stage["Procedure staging<br/>[stage.py]"]
  node_lifecycle["Knowledge lifecycle<br/>[service.py]"]
  node_archive[("Warm archive<br/>[archive.py]")]
  node_rawstore[("Raw content store<br/>[rawstore.py]")]
end

node_user(("User"))
node_language_model(("Language model"))

node_user -->|"provides query"| node_llama
node_llama -->|"constrained decoding"| node_grammar
node_llama -.->|"submits plans"| node_executor
node_executor -->|"executes plans"| node_plans
node_executor -->|"dispatches programs"| node_programs
node_executor -->|"invokes inference"| node_inference
node_executor -->|"uses knowledge services"| node_knowledge
node_executor -->|"uses dependency graph"| node_dependencies
node_executor -->|"dispatches imports"| node_acquisition
node_executor -->|"dispatches retrieval"| node_retrieval
node_executor -->|"dispatches verification"| node_verification
node_executor -->|"dispatches proposals"| node_procedure
node_executor -->|"dispatches lifecycle"| node_lifecycle
node_inference -->|"queries recursive CTE"| node_store
node_inference -->|"compiles plan atoms"| node_plans
node_acquisition -->|"corroborates facts"| node_corroboration
node_acquisition -->|"indexes facts"| node_retrieval
node_acquisition -->|"stages and commits"| node_store
node_acquisition -->|"stores source content"| node_rawstore
node_retrieval -->|"reads facts"| node_store
node_retrieval -.->|"supplies evidence"| node_verification
node_verification -->|"checks grounding"| node_faithfulness
node_verification -->|"uses evidence access"| node_retrieval
node_verification -->|"reads fact versions"| node_store
node_inference -.->|"records support"| node_dependencies
node_procedure -->|"runs procedures"| node_procedure_runner
node_procedure -->|"generates candidates"| node_procedure_candidates
node_procedure -->|"stages proposals"| node_procedure_stage
node_procedure -->|"reads and writes"| node_store
node_procedure_runner -->|"evaluates rules"| node_inference
node_procedure_runner -->|"reads current view"| node_store
node_induction -.->|"stages knowledge"| node_store
node_lifecycle -.->|"manages persisted state"| node_store
node_lifecycle -.->|"archives history"| node_archive
node_store -->|"materializes versions"| node_store_models

click node_grammar "https://github.com/sdidsa/engram/blob/master/src/engram/interface/grammar.py"
click node_llama "https://github.com/sdidsa/engram/blob/master/src/engram/interface/llama.py"
click node_executor "https://github.com/sdidsa/engram/blob/master/src/engram/engine/executor.py"
click node_plans "https://github.com/sdidsa/engram/blob/master/src/engram/engine/plans.py"
click node_programs "https://github.com/sdidsa/engram/blob/master/src/engram/engine/program.py"
click node_inference "https://github.com/sdidsa/engram/blob/master/src/engram/engine/inference.py"
click node_knowledge "https://github.com/sdidsa/engram/blob/master/src/engram/knowledge/revision.py"
click node_dependencies "https://github.com/sdidsa/engram/blob/master/src/engram/knowledge/dependencies.py"
click node_store "https://github.com/sdidsa/engram/blob/master/src/engram/store/sqlite_store.py"
click node_store_models "https://github.com/sdidsa/engram/blob/master/src/engram/store/models.py"
click node_acquisition "https://github.com/sdidsa/engram/blob/master/src/engram/acquisition/pipeline.py"
click node_corroboration "https://github.com/sdidsa/engram/blob/master/src/engram/acquisition/corroborate.py"
click node_retrieval "https://github.com/sdidsa/engram/blob/master/src/engram/retrieval/service.py"
click node_verification "https://github.com/sdidsa/engram/blob/master/src/engram/verification/service.py"
click node_faithfulness "https://github.com/sdidsa/engram/blob/master/src/engram/verification/faithfulness.py"
click node_induction "https://github.com/sdidsa/engram/blob/master/src/engram/induction/stage.py"
click node_procedure "https://github.com/sdidsa/engram/blob/master/src/engram/procedure/service.py"
click node_procedure_runner "https://github.com/sdidsa/engram/blob/master/src/engram/procedure/runner.py"
click node_procedure_candidates "https://github.com/sdidsa/engram/blob/master/src/engram/procedure/candidates.py"
click node_procedure_stage "https://github.com/sdidsa/engram/blob/master/src/engram/procedure/stage.py"
click node_lifecycle "https://github.com/sdidsa/engram/blob/master/src/engram/lifecycle/service.py"
click node_archive "https://github.com/sdidsa/engram/blob/master/src/engram/store/archive.py"
click node_rawstore "https://github.com/sdidsa/engram/blob/master/src/engram/store/rawstore.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_grammar,node_llama,node_user toneBlue
class node_executor,node_plans,node_programs,node_inference,node_knowledge,node_dependencies,node_store,node_store_models toneAmber
class node_acquisition,node_corroboration,node_retrieval,node_verification,node_faithfulness toneMint
class node_induction,node_procedure,node_procedure_runner,node_procedure_candidates,node_procedure_stage,node_lifecycle,node_archive,node_rawstore toneRose
class node_language_model toneIndigo
```

## Components

### Language interface

- [Constrained grammar](https://github.com/sdidsa/engram/blob/master/src/engram/interface/grammar.py): `src/engram/interface/grammar.py`
- [Model interface](https://github.com/sdidsa/engram/blob/master/src/engram/interface/llama.py): `src/engram/interface/llama.py`

### Execution and knowledge

- [Plan executor](https://github.com/sdidsa/engram/blob/master/src/engram/engine/executor.py): `src/engram/engine/executor.py`
- [Typed plans](https://github.com/sdidsa/engram/blob/master/src/engram/engine/plans.py): `src/engram/engine/plans.py`
- [Multi-step programs](https://github.com/sdidsa/engram/blob/master/src/engram/engine/program.py): `src/engram/engine/program.py`
- [Datalog inference](https://github.com/sdidsa/engram/blob/master/src/engram/engine/inference.py): `src/engram/engine/inference.py`
- [Belief revision](https://github.com/sdidsa/engram/blob/master/src/engram/knowledge/revision.py): `src/engram/knowledge/revision.py`
- [Truth maintenance](https://github.com/sdidsa/engram/blob/master/src/engram/knowledge/dependencies.py): `src/engram/knowledge/dependencies.py`
- [Bitemporal store](https://github.com/sdidsa/engram/blob/master/src/engram/store/sqlite_store.py): `src/engram/store/sqlite_store.py`
- [Version models](https://github.com/sdidsa/engram/blob/master/src/engram/store/models.py): `src/engram/store/models.py`

### Acquisition and evidence

- [Document acquisition](https://github.com/sdidsa/engram/blob/master/src/engram/acquisition/pipeline.py): `src/engram/acquisition/pipeline.py`
- [Fact corroboration](https://github.com/sdidsa/engram/blob/master/src/engram/acquisition/corroborate.py): `src/engram/acquisition/corroborate.py`
- [Evidence retrieval](https://github.com/sdidsa/engram/blob/master/src/engram/retrieval/service.py): `src/engram/retrieval/service.py`
- [Answer verification](https://github.com/sdidsa/engram/blob/master/src/engram/verification/service.py): `src/engram/verification/service.py`
- [Faithfulness checks](https://github.com/sdidsa/engram/blob/master/src/engram/verification/faithfulness.py): `src/engram/verification/faithfulness.py`

### Learning and lifecycle

- [Knowledge induction](https://github.com/sdidsa/engram/blob/master/src/engram/induction/stage.py): `src/engram/induction/stage.py`
- [Procedure proposals](https://github.com/sdidsa/engram/blob/master/src/engram/procedure/service.py): `src/engram/procedure/service.py`
- [Procedure runner](https://github.com/sdidsa/engram/blob/master/src/engram/procedure/runner.py): `src/engram/procedure/runner.py`
- [Procedure candidates](https://github.com/sdidsa/engram/blob/master/src/engram/procedure/candidates.py): `src/engram/procedure/candidates.py`
- [Procedure staging](https://github.com/sdidsa/engram/blob/master/src/engram/procedure/stage.py): `src/engram/procedure/stage.py`
- [Knowledge lifecycle](https://github.com/sdidsa/engram/blob/master/src/engram/lifecycle/service.py): `src/engram/lifecycle/service.py`
- [Warm archive](https://github.com/sdidsa/engram/blob/master/src/engram/store/archive.py): `src/engram/store/archive.py`
- [Raw content store](https://github.com/sdidsa/engram/blob/master/src/engram/store/rawstore.py): `src/engram/store/rawstore.py`

### Other components

- **User**
- **Language model**

## Connections

- User → Model interface: provides query (evidence: `README.md`)
- Model interface → Constrained grammar: constrained decoding (evidence: `README.md`)
- Model interface → Plan executor: submits plans
- Plan executor → Typed plans: executes plans (evidence: `src/engram/engine/executor.py`)
- Plan executor → Multi-step programs: dispatches programs (evidence: `src/engram/engine/executor.py`)
- Plan executor → Datalog inference: invokes inference (evidence: `src/engram/engine/executor.py`)
- Plan executor → Belief revision: uses knowledge services (evidence: `src/engram/engine/executor.py`)
- Plan executor → Truth maintenance: uses dependency graph (evidence: `src/engram/engine/executor.py`)
- Plan executor → Document acquisition: dispatches imports (evidence: `src/engram/engine/executor.py`)
- Plan executor → Evidence retrieval: dispatches retrieval (evidence: `src/engram/engine/executor.py`)
- Plan executor → Answer verification: dispatches verification (evidence: `src/engram/engine/executor.py`)
- Plan executor → Procedure proposals: dispatches proposals (evidence: `src/engram/engine/executor.py`)
- Plan executor → Knowledge lifecycle: dispatches lifecycle (evidence: `src/engram/engine/executor.py`)
- Datalog inference → Bitemporal store: queries recursive CTE (evidence: `src/engram/engine/inference.py`)
- Datalog inference → Typed plans: compiles plan atoms (evidence: `src/engram/engine/inference.py`)
- Document acquisition → Fact corroboration: corroborates facts (evidence: `src/engram/acquisition/pipeline.py`)
- Document acquisition → Evidence retrieval: indexes facts (evidence: `src/engram/acquisition/pipeline.py`)
- Document acquisition → Bitemporal store: stages and commits (evidence: `src/engram/acquisition/pipeline.py`)
- Document acquisition → Raw content store: stores source content (evidence: `src/engram/acquisition/pipeline.py`)
- Evidence retrieval → Bitemporal store: reads facts (evidence: `src/engram/retrieval/service.py`)
- Evidence retrieval → Answer verification: supplies evidence
- Answer verification → Faithfulness checks: checks grounding (evidence: `src/engram/verification/service.py`)
- Answer verification → Evidence retrieval: uses evidence access (evidence: `src/engram/verification/service.py`)
- Answer verification → Bitemporal store: reads fact versions (evidence: `src/engram/verification/service.py`)
- Datalog inference → Truth maintenance: records support
- Procedure proposals → Procedure runner: runs procedures (evidence: `src/engram/procedure/service.py`)
- Procedure proposals → Procedure candidates: generates candidates (evidence: `src/engram/procedure/service.py`)
- Procedure proposals → Procedure staging: stages proposals (evidence: `src/engram/procedure/service.py`)
- Procedure proposals → Bitemporal store: reads and writes (evidence: `src/engram/procedure/service.py`)
- Procedure runner → Datalog inference: evaluates rules (evidence: `src/engram/procedure/runner.py`)
- Procedure runner → Bitemporal store: reads current view (evidence: `src/engram/procedure/runner.py`)
- Knowledge induction → Bitemporal store: stages knowledge
- Knowledge lifecycle → Bitemporal store: manages persisted state
- Knowledge lifecycle → Warm archive: archives history
- Bitemporal store → Version models: materializes versions (evidence: `src/engram/store/sqlite_store.py`)