Maintaining: Telemetry, Coverage & Curation

Maintenance in Engrams is continuous and measurable. Instead of passive knowledge decay, Engrams uses retrieval telemetry to identify vocabulary gaps, coverage audits to prevent unanchored code, and enforced PR gates at session close.

1. Usage Telemetry & Curation — engrams usage

Engrams automatically logs every retrieval command (query, relevant, advise, brief). The usage command exposes call counts and trends:

engrams usage
engrams usage --since 2w --daily

Example response:

{
  "total_calls": 73,
  "commands": {
    "advise": { "calls": 34, "constraints_fired": 89, "distinct_targets": 3 },
    "relevant": { "calls": 21, "decisions_surfaced": 67 },
    "query": { "calls": 18, "zero_hit": 4 },
    "brief": { "calls": 5, "hits": 5 }
  }
}

The Zero-Hit Curation Loop

Zero-hit queries are the single most valuable telemetry signal — each miss represents a vocabulary gap that likely caused an agent to fall back to an expensive file dump. engrams usage --misses ranks these gaps so maintainers can add missing tags or anchors:

engrams usage --misses

{
  "hint": "each miss is a search that found nothing — a vocabulary gap that likely triggered a file-dump fallback",
  "misses": [
    { "query": "outlook", "count": 2 },
    { "query": "system_user_id", "count": 1 }
  ]
}

2. Knowledge Health & Access Stats — decision stats

Verify which architectural decisions are actively earning their keep vs. candidates for consolidation:

engrams decision stats --most-accessed --limit 5
engrams decision stats --never-accessed

3. Knowledge Coverage Audits — engrams coverage

Before shipping feature work or refactors, verify what fraction of files have live anchored decisions and how close the nearest guidance is:

# Check a directory
engrams coverage src/

# Audit changed files on a PR branch
engrams coverage --diff main...HEAD

Example response:

{
  "files": 14,
  "anchored": 10,
  "anchored_pct": 0.714,
  "dead_anchors": [],
  "median_hops": 1.0
}

4. Session Closure & PR Gates — engrams session close

At the end of a session, record the reads your knowledge graph prevented and validate that PRs are properly connected to decisions and source files:

engrams session close \
  --reads-skipped 14 \
  --reads-required 2 \
  --tokens-saved 70000 \
  --pr 42 \
  --note "Designed Stripe adapter using Provider contract"

To inspect cumulative token ROI and past sessions:

engrams session history

5. PR Reverse Lookup — engrams pr find

Find which decisions, patterns, or progress entries reference a specific PR number or URL:

engrams pr find 42

6. Structural Health — engrams doctor

Run project-wide integrity checks across all records:

engrams doctor

• Dead file anchors (anchors pointing to deleted or moved files).
• Dangling manual links.
• Decisions with Git staleness drift.
• Unconfirmed consolidation patterns (>180 days old).
• Cycles in transitive relationships (causes, supersedes, depends_on).

Session End Protocol (PR Close-Back)

1. 1

   Enumerate

   git diff --name-only <base>...HEAD to list changed paths.

2. 2

   Decide

   Log decisions for all durable design choices with --contract.

3. 3

   Anchor & Link

   Attach file anchors (anchor add) and PR references (pr add).

4. 4

   Rebuild

   engrams graph rebuild turns anchors into code-node edges.

5. 5

   Close & Export

   engrams session close --pr <n> validates the PR gate and engrams export commits markdown.