# utsapoddar/engram architecture

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

- Interactive diagram: https://gitdiagram.com/utsapoddar/engram
- Repository: https://github.com/utsapoddar/engram
- Video tour (about a minute): https://gitdiagram.com/utsapoddar/engram/video

## Overview

Engram is a local-first memory system for AI coding agents: users capture and curate durable Markdown memories, then recall them through a disposable search index. The map covers the CLI-owned workflow, note validation and safe correction, retrieval, and agent session hooks. The README also documents optional semantic ranking and read-only external corpora; those are shown as separate retrieval inputs. Some implementation details come from partial excerpts, so uncertain internal wiring is omitted.

Main entry points: [`src/engram/index.py`](https://github.com/utsapoddar/engram/blob/main/src/engram/index.py) (Memory index and search), [`src/engram/store.py`](https://github.com/utsapoddar/engram/blob/main/src/engram/store.py) (Memory store), [`src/engram/cli.py`](https://github.com/utsapoddar/engram/blob/main/src/engram/cli.py) (CLI commands), [`src/engram/maintenance.py`](https://github.com/utsapoddar/engram/blob/main/src/engram/maintenance.py) (Maintain and status)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli_entry["CLI commands<br/>[cli.py]"]
  node_config["Root and corpora config<br/>[config.py]"]
  node_maintenance["Maintain and status<br/>[maintenance.py]"]
end

subgraph group_memory["Memory lifecycle"]
  node_store["Memory store<br/>[store.py]"]
  node_sanitize["Content sanitizer<br/>[sanitize.py]"]
  node_schema["Note schema<br/>[schema.py]"]
  node_transactions["Correction recovery<br/>[transactions.py]"]
  node_io["Atomic writes and locks<br/>[io.py]"]
  node_markdown["Canonical Markdown memories"]
end

subgraph group_retrieval["Search and retrieval"]
  node_index["Memory index and search<br/>[index.py]"]
  node_sqlite[("Disposable FTS5 index")]
  node_semantic["Local semantic model"]
  node_external_corpus["External read-only corpora"]
end

subgraph group_agents["Agent integrations"]
  node_capture_hook["Session capture hook<br/>[capture_session.py]"]
  node_start_hook["Session start hook<br/>[session_start.py]"]
  node_hot_memory["Hot memory context"]
end

node_user(("User"))
node_agent(("Coding agent"))

node_user -->|"runs commands"| node_cli_entry
node_cli_entry -->|"loads settings"| node_config
node_cli_entry -->|"creates store"| node_store
node_cli_entry -->|"recalls from"| node_index
node_cli_entry -->|"runs maintenance"| node_maintenance
node_store -->|"sanitizes input"| node_sanitize
node_store -->|"creates and parses"| node_schema
node_store -->|"writes and reads"| node_markdown
node_store -->|"recovers corrections"| node_transactions
node_store -->|"locks and writes"| node_io
node_store -->|"reconciles after writes"| node_index
node_index -->|"reconciles from"| node_markdown
node_index -->|"parses notes"| node_schema
node_index -->|"recovers corrections"| node_transactions
node_index -->|"locks repository"| node_io
node_index -->|"updates and queries"| node_sqlite
node_index -.->|"fuses local rankings"| node_semantic
node_index -->|"searches configured sources"| node_external_corpus
node_maintenance -->|"reconciles and checks"| node_index
node_agent -->|"sends lifecycle event"| node_capture_hook
node_capture_hook -->|"captures transcript"| node_store
node_agent -->|"starts session"| node_start_hook
node_start_hook -->|"reads context"| node_hot_memory
node_hot_memory -->|"injects context"| node_agent

click node_cli_entry "https://github.com/utsapoddar/engram/blob/main/src/engram/cli.py"
click node_config "https://github.com/utsapoddar/engram/blob/main/src/engram/config.py"
click node_maintenance "https://github.com/utsapoddar/engram/blob/main/src/engram/maintenance.py"
click node_store "https://github.com/utsapoddar/engram/blob/main/src/engram/store.py"
click node_sanitize "https://github.com/utsapoddar/engram/blob/main/src/engram/sanitize.py"
click node_schema "https://github.com/utsapoddar/engram/blob/main/src/engram/schema.py"
click node_transactions "https://github.com/utsapoddar/engram/blob/main/src/engram/transactions.py"
click node_io "https://github.com/utsapoddar/engram/blob/main/src/engram/io.py"
click node_index "https://github.com/utsapoddar/engram/blob/main/src/engram/index.py"
click node_capture_hook "https://github.com/utsapoddar/engram/blob/main/integrations/hooks/capture_session.py"
click node_start_hook "https://github.com/utsapoddar/engram/blob/main/integrations/hooks/session_start.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_cli_entry,node_config,node_maintenance,node_user toneBlue
class node_store,node_sanitize,node_schema,node_transactions,node_io,node_markdown toneAmber
class node_index,node_sqlite,node_semantic,node_external_corpus toneMint
class node_capture_hook,node_start_hook,node_hot_memory toneRose
class node_agent toneIndigo
```

## Components

### CLI workflows

- [CLI commands](https://github.com/utsapoddar/engram/blob/main/src/engram/cli.py): `src/engram/cli.py`
- [Root and corpora config](https://github.com/utsapoddar/engram/blob/main/src/engram/config.py): `src/engram/config.py`
- [Maintain and status](https://github.com/utsapoddar/engram/blob/main/src/engram/maintenance.py): `src/engram/maintenance.py`

### Memory lifecycle

- [Memory store](https://github.com/utsapoddar/engram/blob/main/src/engram/store.py): `src/engram/store.py`
- [Content sanitizer](https://github.com/utsapoddar/engram/blob/main/src/engram/sanitize.py): `src/engram/sanitize.py`
- [Note schema](https://github.com/utsapoddar/engram/blob/main/src/engram/schema.py): `src/engram/schema.py`
- [Correction recovery](https://github.com/utsapoddar/engram/blob/main/src/engram/transactions.py): `src/engram/transactions.py`
- [Atomic writes and locks](https://github.com/utsapoddar/engram/blob/main/src/engram/io.py): `src/engram/io.py`
- **Canonical Markdown memories**

### Search and retrieval

- [Memory index and search](https://github.com/utsapoddar/engram/blob/main/src/engram/index.py): `src/engram/index.py`
- **Disposable FTS5 index**
- **Local semantic model**
- **External read-only corpora**

### Agent integrations

- [Session capture hook](https://github.com/utsapoddar/engram/blob/main/integrations/hooks/capture_session.py): `integrations/hooks/capture_session.py`
- [Session start hook](https://github.com/utsapoddar/engram/blob/main/integrations/hooks/session_start.py): `integrations/hooks/session_start.py`
- **Hot memory context**

### Other components

- **User**
- **Coding agent**

## Connections

- User → CLI commands: runs commands
- CLI commands → Root and corpora config: loads settings
- CLI commands → Memory store: creates store
- CLI commands → Memory index and search: recalls from
- CLI commands → Maintain and status: runs maintenance
- Memory store → Content sanitizer: sanitizes input
- Memory store → Note schema: creates and parses
- Memory store → Canonical Markdown memories: writes and reads
- Memory store → Correction recovery: recovers corrections
- Memory store → Atomic writes and locks: locks and writes
- Memory store → Memory index and search: reconciles after writes
- Memory index and search → Canonical Markdown memories: reconciles from
- Memory index and search → Note schema: parses notes
- Memory index and search → Correction recovery: recovers corrections
- Memory index and search → Atomic writes and locks: locks repository
- Memory index and search → Disposable FTS5 index: updates and queries
- Memory index and search → Local semantic model: fuses local rankings
- Memory index and search → External read-only corpora: searches configured sources
- Maintain and status → Memory index and search: reconciles and checks
- Coding agent → Session capture hook: sends lifecycle event
- Session capture hook → Memory store: captures transcript
- Coding agent → Session start hook: starts session
- Session start hook → Hot memory context: reads context
- Hot memory context → Coding agent: injects context