How utsapoddar/engram works
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: index.py Memory index and search · store.py Memory store · cli.py CLI commands · maintenance.py Maintain and status
Components 18
CLI workflows
- CLI commands
src/engram/cli.py - Root and corpora config
src/engram/config.py - Maintain and status
src/engram/maintenance.py
Memory lifecycle
- Memory store
src/engram/store.py - Content sanitizer
src/engram/sanitize.py - Note schema
src/engram/schema.py - Correction recovery
src/engram/transactions.py - Atomic writes and locks
src/engram/io.py - Canonical Markdown memories
Search and retrieval
- Memory index and search
src/engram/index.py - Disposable FTS5 index
- Local semantic model
- External read-only corpora
Agent integrations
- Session capture hook
integrations/hooks/capture_session.py - Session start hook
integrations/hooks/session_start.py - Hot memory context
Other components
- User
- Coding agent
Connections 24
- 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