Release History

What was done

• Contracts on Decisions: Architectural decisions can now declare an explicit interface contract via --contract on decision log and update (and merged on consolidate). A write-time nudge reminds agents to specify contracts when introducing adapters, behaviors, or interfaces.
• Code-Node Enrichment: engrams graph rebuild now automatically scans source files to extract exported symbols, module docstrings, and line counts onto code nodes in SQLite, rendered in graph neighbors.
• One-Call Composite Brief (brief command): engrams brief <node|query> returns full decision text, contract, tags, PRs, anchors, drift status, and enriched 1-hop neighbors in a single call.
• Miss-Guidance on Empty Queries: engrams query returns structured guidance (top tags, per-token hits, recent decisions, graph hubs) instead of a bare empty array when a search yields 0 hits.
• Retrieval Economy & Filtering: engrams query --full embeds complete payloads; --fields supports canonical aliases (summary, name); cross-convention FTS matches snake_case, camelCase, and kebab-case transparently; and decision list --filter <text> provides fast server-side filtering.
• Staleness Drift Detection: Git-backed staleness scoring detects when anchored source files have been modified after a decision was logged, surfacing stale: true/false in brief, advise, and relevant.
• Usage Telemetry & Session Closure: Added automatic retrieval logging via engrams usage (with --misses and --daily), access count tracking across all paths including decision get, decision stats, engrams coverage (with --diff), engrams pr find, and engrams session close with automated PR linkage gates.
• Graph Report Polish: engrams report open now outputs HTML reports to /tmp and features wider node repulsion spacing.

Why it was done

• The File-Reading Tax: Reading source files costs 5k–15k tokens while querying the knowledge base costs tens of tokens. Making the graph self-sufficient allows agents to formulate complete strategies without opening files.
• Defensive Reads Stems from Distrust: When agents find incomplete or stale knowledge, they fall back to defensive file reading. Contracts, enriched code nodes, and staleness drift restore trust.
• Curation Requires Telemetry: Tracking zero-hit queries and access counts gives maintainers the exact vocabulary gaps that cause agent fallbacks.

Developer Benefits

• Zero-Read Strategy Formation: Formulate implementation plans purely from graph queries.
• Convention-Agnostic Search: Search without worrying about identifier casing mismatches.
• Verified PR Linkage: Enforce that PRs are linked to decisions and anchored code files at session close.

Upgrading from v0.11.x

engrams migrate

Upgrades schema to v10 with additive columns (contract on decisions, code-node metadata, usage_log, and session_closes).

What was done

• Consolidation (consolidate command): Repeated work graduates into knowledge automatically. engrams consolidate clusters Done progress entries that share file anchors and span enough distinct days into a candidate pattern — named consolidated-<path-stem>, tagged consolidated, with an initial confidence score. Propose-only by default; --apply inserts the pattern plus derived_from evidence links back to every progress entry it came from. Re-running against new evidence confirms existing consolidated patterns (bumps last_confirmed_at, attaches the new evidence) instead of duplicating them. Tunables: --min-repeats (default 3), --min-days (default 2).
• Confidence with read-time decay: Patterns carry a stored confidence in (0, 1] and a last_confirmed_at. Effective confidence is computed at read time — confidence × exp(−λ × days_since(last_confirmed_at)) reusing the same Ebbinghaus λ as retrieval scoring — so unconfirmed knowledge fades automatically, with no background jobs. pattern list/get expose both stored and effective values; pattern update --confidence 0.8 --confirm manages them. prime/relevant multiply pattern rank by effective confidence, so recently-confirmed knowledge outranks equally-important stale knowledge. Export/import round-trips both fields exactly.
• Contradiction gate on decision log: The similarity check now classifies every hit: active near-duplicates suggest conflicts_with, and shared file anchors between them upgrade the suggestion to supersedes. Superseded/archived decisions no longer gate. Resolve inline with --supersedes <id> (inserts, flips the target to superseded, writes the link, skips the gate) or --conflicts-with <id> (inserts, links, both stay active). --force still bypasses everything.
• Causal retrieval (causes/caused_by + graph why): causes joins the relationship ontology as a directed, transitive canonical rel with inverse caused_by (normalized to causes with endpoints swapped). engrams graph why --node decision:7 answers "why did this happen" by walking the causal chain upstream to its roots; --down answers "what does this affect" downstream. Each chain entry reports depth and the edge description. Node references accept the CLI's hyphenated types (system-pattern:2) as well as short aliases (pattern:2).
• Doctor advisories: engrams doctor reports unconfirmed_patterns — consolidated patterns (those with derived_from evidence) never confirmed or unconfirmed for more than 180 days — and cycles in the causes relation.
• Progress-entry anchors: engrams anchor add --type progress-entry --id <n> --path src/foo.rs — progress entries can now carry file anchors, which is what consolidation clusters on.

Why it was done

• Progress journals don't compound: Done-entries pile up describing the same recurring work without ever becoming reusable guidance. Consolidation closes that loop: repetition detected → candidate pattern with provenance → human applies → future sessions inherit the lesson.
• Unconfirmed knowledge is a liability: A pattern extracted once and never revisited silently rots. Read-time decay makes staleness a first-class, self-updating property instead of requiring maintenance jobs.
• Contradictions were cheap to log: Agents re-decided settled questions because similar decisions surfaced without classification or a one-flag resolution path. The gate now hands you the relation and the fix in the same response.
• "Why" questions had no path: The graph knew dependencies but not causality. causes + why turn hindsight queries into one command.

Developer Benefits

• Memory that compiles itself: Do the same thing three times across two weeks and engrams drafts the pattern for you — with evidence.
• Trust scores you can see: Every pattern shows stored vs. effective confidence; staleness is visible, not assumed.
• One-flag conflict resolution: --supersedes/--conflicts-with settle near-duplicates at log time.
• Causal hindsight: graph why traces any decision to its root causes or its downstream impact.

Upgrading from v0.10.x

engrams migrate

The migration to schema v7 is fully additive: two columns on system_patterns —

• confidence — REAL NOT NULL DEFAULT 1.0 (all existing patterns start at full trust)
• last_confirmed_at — TEXT (NULL; treated as the creation timestamp until first confirmation)

No existing data is modified. After migration, consolidate, the contradiction gate, graph why, and confidence-aware ranking are available immediately. To feed consolidation, attach anchors to Done progress entries as you log them.

What was done

• Retrieval Scoring: Every decision and pattern now carries a blended score combining recency-decay (Ebbinghaus exponential over age) with a user-settable importance weight (0–10, default 5). The prime, relevant, and query commands rank results by this score instead of by creation order. Scores are computed in SQL via a registered exp() function and are visible in the JSON output. Set importance with --importance on decision log, decision update, and pattern log.
• Reinforce-on-Read: Every time prime, relevant, or query surfaces a record, its access_count is incremented and last_accessed_at is updated. Frequently-consulted decisions survive longer in the active rotation — the memory self-improves with use.
• Prune-Decay: The new engrams prune command archives decisions and patterns whose Ebbinghaus retention exp(-age / strength) has decayed below a threshold (default 0.1). Strength is (importance + access_count) × 30 days, so important and frequently-read records survive longer. Use --dry-run to preview, --threshold to control aggressiveness. Archived items are excluded from retrieval by default; use --all on relevant or query to include them.
• Read Observability: engrams doctor now reports never_read (records written but never surfaced by any read path) and archived counts per table. You can audit whether logged decisions are actually influencing the agent's context.
• Pre-Edit Advisory (advise command): Purpose-built companion to relevant that returns only actionable constraints — checkable patterns and decisions anchored to the given paths — plus any current violations from engrams check. No scores, no progress, no reinforcement. Compact and fast, designed for automatic harness injection.
• Git Pre-Commit Hook (install --hooks): engrams install --harness omp --hooks now writes a git pre-commit hook that runs engrams check --staged. Error-severity violations block the commit; warn/info violations are printed but don't block. Bypass with git commit --no-verify.
• omp Edit-Time Extension: The same --hooks flag also deploys an omp extension to .omp/extensions/engrams-advisor/ that intercepts edit/write tool calls. On first edit to each file, it surfaces constraints as non-blocking guidance and blocks error-severity violations. Self-disables outside engrams workspaces.

Why it was done

• Stale ranking poisoned retrieval: Old decisions ranked identically to fresh ones, so the agent saw noise instead of signal. Scoring ensures the 5 most important recent decisions surface first.
• Unbounded accumulation: The database grew monotonically; obsolete records diluted retrieval precision. Prune-decay mirrors human memory: unused knowledge fades, important knowledge persists.
• No read-path visibility: There was no way to know whether a logged decision was ever surfaced. Observability turns "hoping the agent remembers" into "verifying it read it."
• Advisory systems are ignored under pressure: Rules and documentation proved insufficient — agents skip optional steps when working fast. The pre-commit hook and omp extension make enforcement mechanical, not voluntary.

Developer Benefits

• Signal over noise: Important, recent, frequently-consulted decisions rank first. Your agent sees what matters instead of everything equally.
• Self-cleaning memory: No manual cleanup — unused decisions fade into the archive automatically.
• Auditable advice: doctor tells you which records were never read, so you can fix retrieval gaps.
• Conventions that can't be skipped: Error-severity violations are caught at commit time and edit time, not in review.

Upgrading from v0.9.x

engrams migrate

The migration to schema v6 is fully additive. It adds four columns to the decisions and system_patterns tables:

• importance — INTEGER NOT NULL DEFAULT 5 (all existing records get importance 5)
• access_count — INTEGER NOT NULL DEFAULT 0 (all existing records start unread)
• last_accessed_at — TEXT (NULL until first surfaced by a read path)
• archived — INTEGER NOT NULL DEFAULT 0 (no existing records are archived)

All existing decisions, patterns, links, and exports continue to work unchanged. No data is modified, no breaking changes. After migration, the new prime/query/relevant ranking takes effect immediately.

Optional: Enable enforcement with engrams install --harness omp --hooks to install both the git pre-commit hook and the omp edit-time extension.

What was done

• The Policy Engine — Checkable Patterns: Patterns graduated from prose to policy. engrams pattern log now accepts a machine-checkable expression (--check-kind regex|ast with --check) and an enforcement --severity of info, warn, or error. The new engrams check command runs every stored check against your files — scoped with --staged or --paths — so conventions are verified in CI and at session end, not just recalled.
• In-Session Enforcement: engrams install --harness omp writes harness rule files into the workspace so checkable patterns are enforced while the agent works, not only after the fact.
• Workspace Isolation Hardening: Workspace-root and database-path resolution was hardened for git worktrees and nested agent sessions, so concurrent agents stay pinned to the intended project database instead of leaking writes across workspace boundaries.
• Docs Site Revamp — "The Active Advisor": The documentation site was restructured and redesigned around the advisor narrative — Engrams as an advisor that compounds — with the real knowledge graph from this repository rendered interactively on the landing page.

Why it was done

• Memory that can't act is trivia: A recalled pattern only helps if the agent honors it. The policy engine closes the loop between remembering a convention and enforcing it — the step that turns storage into advice.
• Isolated agents became the default: With worktree- and harness-based isolation now the standard way of running parallel agents, database resolution had to be airtight before it could be load-bearing.

Developer Benefits

• Conventions with teeth: A regex or AST check turns "we don't do that here" from a hope into a gate — engrams check --staged drops into any pre-commit hook or CI pipeline.
• Enforcement inside the session: Installed harness rules catch violations as the code is being written, when fixing them is cheapest.
• Safe parallelism: Run multiple isolated agent sessions against the same repository without cross-contaminating project memory.
• Zero-friction upgrade: Schema v5 is additive — one engrams migrate and existing patterns default to warn severity with no check attached.

Upgrading from v0.8.x

engrams migrate

The migration is additive: it adds check-expression columns to the patterns table. Existing patterns are untouched — they default to warn severity with no check and behave exactly as before until you attach one.

What was done

• Onboarding Instructions Synced to the Installed CLI: The output of engrams instructions was rewritten to track the current operating loop: a command quick-reference table, the closed status vocabularies, the Store/Link/Retrieve model, the six-step session-end protocol, doctor/migrate/export, and the global --compact and --fields flags. It had drifted from AGENTS.md and still mirrored the legacy seven-step text loop.
• Canonical Relationship Examples: The session-end protocol's example relationship names were corrected from the non-canonical extends/uses to implements/depends_on/supersedes, both in the instructions output and in AGENTS.md. Non-canonical names would be flagged by engrams doctor for anyone who followed them.

Why it was done

• Drifted Onboarding: Newly onboarded agents received stale operating guidance that no longer matched the installed CLI's commands or vocabularies, referencing pre-v0.8.0 behavior and wasting tokens.
• Eroding Ontology Trust: Example relationships that aren't canonical would produce doctor warnings, undercutting the shared-semantics guarantees the v0.8.0 relationship ontology introduced.

Developer Benefits

• Accurate Self-Service Onboarding: engrams instructions now matches the installed CLI surface and the current AGENTS.md, so copy-paste onboarding guidance is correct out of the box.
• Doctor-Clean Defaults: The documented session-end protocol uses canonical relationships by default, so agents following it won't seed the graph with non-canonical edges.

What was done

• Relationship Ontology with Domain/Range Constraints: Canonical relationship types (supersedes, depends_on, refines, conflicts_with, implemented_in, anchored_to, …) now declare algebraic properties: allowed source/target item types (domain/range), same-type requirements, functional constraints, and disjointness rules. link add validates every canonical relationship against its spec and rejects violations by default; pass --force to record an intentional override. Free-form relationship names still pass through untouched.
• Controlled Status Vocabularies: Decision and progress statuses are validated at write time against closed sets. Decisions: active, superseded, rejected, revisited. Progress: Todo, InProgress, InReview, Blocked, Done, Dropped. --force escapes the check on any write, and decision supersede now auto-flips the retired decision's status to superseded.
• Named Workstream Contexts (Schema v4): Active context is no longer a single document. Maintain multiple named tracks — one per workstream, branch, or focus area — with the new active-context get / update / list subcommands and a --name flag. The existing singleton migrates transparently to the default track, and prime lists every track while expanding the one matching your current scope.
• Transitive Graph Traversal: The new graph chain command walks transitive closures over supersedes, depends_on, part_of, and refines — answering "what transitively breaks if I revisit this decision?". prime demotes superseded decisions into a compact annotated section (visible, never hidden), and doctor warns on cycles in any transitive relation.
• Materialized Inverse Edges: graph rebuild now materializes declared inverse relationships (e.g. superseded_by, depended_on_by) as derived edges, so consumers never need to know which direction a link was originally asserted in.
• Smarter Doctor: New audits surface orphan graph nodes and stale-graph rebuild recommendations, detect cycles in canonical transitive relations (supersedes/depends_on/part_of/refines), and lint non-canonical relationship vocabulary (frequency counts for review).
• Interoperable Exports: Exported markdown now carries YAML frontmatter with structured metadata fields (including schema.org actionStatus for progress entries), making engrams output directly parseable by Astro, static-site generators, and agent tooling alongside the existing JSON content blocks.
• Release Hardening: A type-safe Direction enum replaces stringly-typed link direction (JSON output unchanged), error context is now evaluated lazily via with_context closures, and prime --budget token estimation serializes each section once without an intermediate Value round-trip.

Why it was done

• Relationships Without Meaning: v0.7.0 added a real topology, but relationships were still free-form strings with no shared semantics — agents couldn't trust that supersedes meant the same thing across projects, and nothing prevented contradictory links (a decision both depends_on and conflicts_with the same target).
• Status Free-For-All: Any string was accepted as a status, so done, Done, and d could all coexist, fragmenting progress tracking and breaking filters.
• One Document, Many Workstreams: A single active-context document forced teams working on parallel workstreams to overwrite each other's focus. Named tracks give each workstream its own context without clobbering.

Developer Benefits

• Trustworthy Relationships: Validation catches contradictory and ill-typed links at write time instead of letting them surface as silent graph corruption later. Every override is explicit.
• Consistent Status: A shared, closed vocabulary means progress and decision status reads the same way for agents, humans, and dashboards.
• Multi-Workstream Context: Carry separate active-context tracks per branch or focus area; prime auto-selects the relevant one from your working scope.
• Reachability & Health: graph chain answers transitive impact questions, while cycle detection and vocabulary linting keep the graph coherent as it grows.
• Ecosystem-Ready Exports: Structured frontmatter lets you feed engrams knowledge into docs sites and agent pipelines without custom parsers.

Upgrading

Existing databases migrate to schema v4 and rebuild derived edges in two steps:

engrams migrate
engrams graph rebuild

The migration copies the current active-context singleton into a new default track (the old table is dropped), and normalizes legacy status values to the canonical vocabulary via a case-insensitive match. Any status that doesn't match a known value is preserved as-is and flagged by engrams doctor for review.

What was done

• Knowledge Graph → Codebase Topology: Files are now first-class graph nodes. A new code_nodes table represents every source file engrams knows about, and edges are derived automatically from three sources: file anchors on decisions/patterns (anchored_to), items sharing an anchor (co_anchor), and Git commit co-change history (co_changes, weighted by commit count).
• Canonical Relationship Algebra: Relationship types (extends, uses, supersedes, depends_on, …) now have defined symmetry and inverses. link add normalizes them automatically (e.g. depended_on_by is stored as depends_on with source/target swapped); unknown relationship names still pass through untouched.
• Manual vs. Derived Edges: Links carry an origin (manual/derived) and a weight. graph rebuild re-derives all automatic edges idempotently without ever touching hand-authored links, and graph ingest incrementally folds in new commits. Exports preserve manual links only.
• Graph Analytics CLI: New graph command family: rebuild, ingest, stats (counts, density, degree, components, orphans), central (PageRank), clusters, orphans, path, and neighbors — all computed in memory over the whole knowledge base.
• Graph-Aware Briefings & Audits: prime now includes a compact graph summary (node/edge counts, density, top-central nodes) in its payload, and doctor reports orphan nodes and a rebuild_recommended advisory.
• Noise-Free Ingest: Vendored and generated paths (node_modules, dist, lockfiles, minified assets, …) are excluded from co-change ingest, and graph rebuild prunes code nodes no edge references — keeping the topology limited to real source files.

Why it was done

• Sparse, Hand-Maintained Graph: Previously the graph consisted of only four knowledge node types joined by free-form, hand-authored relationship strings. Files existed only as anchor text, never as nodes, and nothing derived edges — so the graph stayed a sparse scatter that never mirrored the codebase and required manual upkeep to be useful.
• No Structural Insight: Without a real topology there was no way to answer "which files and decisions are central", "what clusters exist", or "how are these two items connected" — the questions a knowledge graph exists to answer.

Developer Benefits

• Self-Maintaining Topology: The graph now grows automatically with every anchored decision and every commit — no manual linking required to keep it useful.
• Actionable Centrality: PageRank over the combined knowledge + code graph surfaces the true hubs of a project (files and decisions everything routes through), guiding refactoring attention and agent context selection.
• Focused Agent Briefings: Graph summaries in prime give LLM agents structural awareness of the project at negligible token cost, and orphan/rebuild advisories in doctor keep the knowledge base healthy.

Upgrading

Existing databases must be migrated to schema v3 before the new commands work, then the derived links are built with a single rebuild:

engrams migrate
engrams graph rebuild

After that, engrams graph ingest folds in new commits incrementally — run it any time, e.g. after pulling or committing. All derived edges are rebuilt idempotently and hand-authored links are never touched.

What was done

• Git Worktree Workspace Resolution: Enhanced the database workspace auto-detection system to identify and resolve Git worktrees (where .git is a file referencing a parent .git/worktrees/<name> directory) back to their primary checkout root.
• Filter Context Briefs by Path or Tag: Added optional --paths and --tags flags to the prime command. A context brief is the core package of decisions and rules that an AI agent reads when it starts working on your project. This change allows you to limit that package to only the files, folders, or topics (tags) you are currently working on. It also hides the project's daily progress logs to keep the package small. As a result, the AI agent gets a highly focused set of guidelines, which prevents it from getting distracted, speeds up its responses, and saves money on AI costs.

Why it was done

• Seamless Worktree Support: Developers frequently checkout concurrent branches using Git worktrees. Previously, running engrams inside a worktree checkout directory would fail to automatically discover the primary workspace repository database, leading to disconnected context databases.
• Token & Cost Efficiency: Generative AI models operate with limited context windows and charge by token counts. Scoping the context brief to specific folders or tags prevents unnecessary decisions, patterns, and progress logs from bloating the prompt, drastically reducing LLM token consumption.

Developer Benefits

• Unified Context Database: Engrams works natively out-of-the-box across all active Git worktrees without requiring manual overrides (like --db or --workspace).
• Targeted Context Injection: Keep LLM agents focused strictly on the files they are editing, ensuring cleaner agent execution, less distraction, and faster agent completion times.

What was done

• Agent Onboarding: Added initial support for onboard instructions specifically formatted for consumption by LLM agents.
• PR Linking & Anchoring: Added features to associate pull request URLs with logged decisions and system patterns, and query relevance matching against specific codebase file paths.

Why it was done

• Traceability: To establish a robust, queryable link between engineering decisions, pull requests, and the specific files they affect.

Developer Benefits

• Deep Context Preservation: Developers and AI agents can query any file and immediately understand the architectural decisions and patterns that govern it.

What was done

• Interactive HTML Dashboard: Created the report command, compiling project memory into an interactive web interface complete with search and cytoscape-based knowledge graph visualization.

Why it was done

• Better Visual Auditing: As project databases grow, console lists become harder to parse. A visual dashboard helps humans easily spot gaps, dependencies, and orphaned records.

Developer Benefits

• Graphical Knowledge Mapping: An intuitive way to explore how codebase decisions, patterns, and files interrelate.

What was done

• Deduplication & Consolidation: Introduced the supersede command to mark old decisions as obsolete and point directly to new, active decisions.
• CLI Release Checking: Added automated checks to notify users when a newer CLI version is available.

Why it was done

• Evolving Architectural Context: Code bases evolve and old decisions become outdated. Keeping outdated decisions active confuses agents; superseding them cleanly preserves history while pointing to current guidelines.

Developer Benefits

• Single Source of Truth: Ensures agents only consume active, relevant context while maintaining a complete, historical audit trail of how decisions changed.

What was done

• Markdown Reports: Added the initial CLI reporting command to output workspace metrics and records as clean, readable Markdown tables in the terminal.

Why it was done

• Console Readability: Provided developers with a structured, tabular summary of decisions, patterns, and progress from the shell without needing external tools.

Developer Benefits

• Fast Inspections: Instant visibility into the repository's context database directly inside the developer's CLI flow.

What was done

• Database Foundation: Configured the SQLite embedded database, designed the initial tables (decisions, system patterns, progress), and implemented schema migrations.
• Full-Text Search (FTS5): Configured sqlite FTS5 indexing triggers to allow sub-millisecond keyword search across summary, description, and rationale fields.

Why it was done

• Initial Architecture: Laid down the zero-dependency, local-first data store required for reliable context tracking.

Developer Benefits

• Speed & Reliability: Sub-millisecond queries backed by the robustness of an embedded SQLite database.