Maintaining

A knowledge graph decays unless someone maintains it. That someone is the agent: superseding decisions that no longer hold, patching the active-context track, exporting for git sync, migrating schema, and running the doctor to catch drift before it misleads.

Superseding decisions — engrams decision supersede

When a decision is replaced, don't delete it — supersede it. The old decision keeps its rationale (which is often exactly what a future session needs to avoid repeating a dead end), and the supersedes link preserves the reasoning trail.

engrams decision supersede 7 --by 11
engrams link add --source-type decision --source-id 7 \
  --target-type decision --target-id 11 --rel supersedes

supersedes is functional — a decision has at most one successor — and transitive, so engrams graph chain --rel supersedes walks the full history. Valid decision statuses: active, superseded, rejected, revisited. Reopening a settled choice means changing its status to revisited, not silently editing it.

Active context — engrams active-context update

Active-context tracks are named workstream documents — goals, open questions, next steps — that survive session boundaries. prime always includes them, no matter how tight the token budget. Update the track at session end so the next session starts where this one stopped.

engrams active-context update --name default \
  --patch '{"goals": ["ship 0.9.0"], "next_steps": ["verify docs build"]}'

# replace the whole document instead of merging
engrams active-context update --content '{"goals": [...]}'

Audits — engrams doctor

Run periodically. The doctor scans for eight problems; the first four set the ok flag, the rest are advisories about graph and vocabulary health:

1. Missing file anchors — anchored files that were renamed, moved, or deleted.
2. Dangling links — relationships whose source or target no longer exists.
3. Stale decisions — anchored files modified since the decision's commit.
4. Unlinked decisions — active decisions carrying a commit but no PR link.
5. Orphan nodes — graph nodes with degree ≤ 1: link them or prune them.
6. Graph rebuild recommendation — writes landed after the last graph rebuild; derived edges are stale.
7. Transitive-relation cycles — loops in supersedes, depends_on, part_of, or refines that break reachability queries.
8. Non-canonical relationship vocabulary — free-form rel labels, tallied for review (normalize or keep intentionally).

The agent should treat doctor output as a work queue: clean up obsolete anchors, attach missing PR links, and alert when code drifts from documented decisions.

Export — engrams export

engrams export            # writes ./engrams_export/
engrams export --path ./docs/memory

Dumps the database to Markdown for git sync and human browsing. Commit engrams_export/ alongside the code so the team's knowledge travels with the repository. Agents must not read engrams_export/ files — they are verbose and token-expensive; the CLI (prime, relevant, query, graph) is the source of truth.

Schema — engrams migrate

Brings the database schema to the latest version. Run it after upgrading the CLI binary. Migration also normalizes legacy status values case-insensitively toward the canonical vocabularies; values it doesn't recognize are preserved as-is and flagged by doctor for review.

The session-end protocol

Maintenance is a loop, not a chore list. Every session ends the same way:

1. engrams decision log — record what was decided, with rationale and anchors.
2. engrams link add — wire it to what it implements, depends on, or supersedes.
3. engrams progress log — mark the task state.
4. engrams active-context update --patch — merge outcome and next steps into the track.
5. engrams export — then commit engrams_export/ with the code.