engram CLAUDE.md

Engram

Persistent memory for LLM agents, backed by an agent-memory zettelkasten vault. Two skills — recall and learn — read from and write to the vault on demand; at their write sites they hand off to a fifth skill, write-memory, which composes and executes the vault-write commands (parents judge, the worker writes). A third skill, please, orchestrates end-to-end work by sequencing recall, learn, and other available skills around a user's <ask>, with adversarial review gates over the plan, refactors, docs, and outward prose. A fourth skill, route, encodes the delegate-everything doctrine: it guides subagent selection (agent type, model, effort) rather than doing object-level work itself. please consults it when assigning gate reviewers. A sixth skill, curate, judges engram serve's pending-offer notes against the host vault using the same covered/near/absent reasoning recall's Step 2.5 documents, and is self-contained — it composes and executes engram amend directly rather than handing off to write-memory, since an offer's content already exists as a note file with nothing left to compose from scratch.

Core Principles

• Verify, don't guess. Always read source code and documentation before guessing at formats, paths, or API contracts. Never assume directory structures or payload fields — verify first.

Directory Structure

engram/
├── cmd/engram/        # CLI binary entry point — single-statement main() + checker-thin per-group functions supplying raw I/O primitives (targ check-thin-api-enforced)
├── internal/          # Non-public implementation
│   ├── chunk/         # Splits memory sources (stripped transcripts, markdown) into embedding-sized chunks for the auto-ingested vector space (pure string logic, no I/O)
│   ├── cli/           # CLI command wiring (targ targets) + composition root: cli.NewDeps builds every production adapter from injected cli.Primitives
│   ├── cluster/       # k-means clustering with silhouette-based auto-K, for recall clustering
│   ├── context/       # Transcript processing for LLM agents
│   ├── debuglog/      # Tail-friendly debug logger
│   ├── embed/         # Embedder interface + Hugot/GoMLX backend, sidecar I/O, state classification
│   ├── luhmann/       # Luhmann zettelkasten ID parsing/sorting
│   ├── transcript/    # Claude Code session transcript reading
│   ├── update/        # `engram update` subcommand
│   └── vaultgraph/    # Wikilink graph analysis of the vault
├── agent-instructions/
│   ├── skills/        # Source for the recall, learn, write-memory, please, and route skills
│   └── guidance/      # Source for the deployable ambient guidance docs — recall-firing (`recall.md`), delegation-firing (`delegate.md`), and learn-firing (`learn.md`) — synced by `engram update --with-guidance` to canonical paths in `~/.claude/engram/guidance/` (Claude Code) and `~/.pi/agent/engram/guidance/` (Pi); compat symlinks at old flat paths keep existing `@import` lines in CLAUDE.md / AGENTS.md resolving (ADR-0022 D9); activated via `@import`
├── openspec/          # Primary behavior specs — one per shipped capability; backfilled 2026-07-27 from docs/FEATURES.md surface
├── dev/               # Build tooling (targ definitions, linter configs)
└── docs/              # Organized by charter — see docs/README.md