Storing
Put facts in. Four item types cover everything the agent learns: architectural decisions, recurring patterns, task progress, and arbitrary custom data. Everything stored here is what the advisor later reasons over.
Decisions — engrams decision log
A decision is an ADR: what was chosen, why, and how it's implemented. Log it the moment the
choice is made. By default the CLI checks for similar existing decisions first; pass
--force to skip the similarity check and insert unconditionally.
engrams decision log \
--summary "Use SQLite for context database" \
--rationale "Embedded, zero-config, FTS5 built in" \
--details "rusqlite with the bundled feature" \
--tags database,sqlite,storage \
--anchor src/db.rs \
--pr 42| Flag | Purpose |
|---|---|
--summary | Required. Short statement of the decision. |
--rationale | The reasoning — the part future sessions actually need. |
--details | Implementation specifics. |
--tags | Comma-separated tags for filtering. |
--status | Initial status; defaults to active. |
--anchor | File path anchor; repeatable. |
--pr | PR number or URL; repeatable. |
--force | Skip the similar-decision check. |
Patterns — engrams pattern log
A pattern is a recurring convention the codebase must keep following. Patterns can carry a
machine-checkable expression — that turns engrams into a policy engine: the pattern becomes an
exportable harness rule and a local engrams check gate.
engrams pattern log \
--name "No throwaway collections" \
--description "Never materialize a collection only to consume it immediately" \
--tags rust,perf \
--anchor src/ops \
--check-kind regex \
--check '\.collect::<Vec<_>>\(\)\.join\(' \
--severity error| Flag | Purpose |
|---|---|
--name | Required. Unique pattern name. |
--description | What the convention is and why it exists. |
--tags / --anchor / --pr | Same as decision log. |
--check-kind | regex or ast (ast-grep). Omit for a prose-only pattern. |
--check | The check expression source; pairs with --check-kind. |
--severity | info, warn, or error (default warn). |
Regexes are compiled at write time — an invalid regex is rejected before any row is inserted.
Prose-only patterns (no --check-kind) never produce violations.
Progress — engrams progress log
Progress entries track task state so any future session can reconstruct where the work stands.
Entries form hierarchies via --parent-id.
engrams progress log --status InProgress \
--description "Implementing link constraint validation" \
--parent-id 12 --check-similar| Flag | Purpose |
|---|---|
--status | Required. One of the progress status values below. |
--description | Required. What was done or is happening now. |
--parent-id | ID of the parent progress entry, for subtasks. |
--check-similar | Check for recent similar entries before inserting. |
--force | Bypass status-vocabulary validation. |
Custom data — engrams custom set
Arbitrary key-value pairs grouped by category — configuration, environment facts, anything that doesn't fit the three typed stores.
engrams custom set --category api --key endpoint \
--value '<string-or-json>' --json --category, --key, and --value are required;
--json marks the value as JSON.
Status vocabularies
| Item | Valid status |
|---|---|
| Decision | active, superseded, rejected, revisited |
| Progress | Todo, InProgress, InReview, Blocked, Done, Dropped |
Legacy or misspelled values are normalized case-insensitively during
engrams migrate; unrecognized values are preserved as-is and flagged by
engrams doctor. See Maintaining.