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. When introducing or modifying an abstraction, always embed its interface contract
via --contract (callback signatures, struct shapes, error tuples). This enables zero-file-read
strategy formation for future sessions.
engrams decision log \
--summary "Provider behavior and Stripe adapter" \
--contract "fn process(amount: u64, currency: &str) -> Result<Receipt, PaymentError>" \
--rationale "Support pluggable payment gateways via unified interface" \
--details "Stripe and Mock adapters implement Provider" \
--tags payment,adapter,api \
--anchor src/adapters/stripe.rs \
--pr 42| Flag | Purpose |
|---|---|
--summary | Required. Short statement of the decision. |
--contract | Interface contract: callback signatures, struct shapes, error tuples (~15–20 lines). |
--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. |
interface, adapter, behavior, or trait, Engrams will print a
non-blocking hint if no --contract was provided.
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.