Feature Request
Problem
Engram tracks write-side metrics (revision_count, duplicate_count, last_seen_at) but has zero read-side instrumentation. There is no way to know which observations are frequently recalled by agents across sessions.
This means all observations are treated equally — a fact recalled 50 times has no more visibility than one never accessed.
Proposed Solution
Add recall tracking to observations and expose a /promoted endpoint (+ mem_promoted MCP tool) that surfaces frequently-recalled observations.
Store changes:
- Add
recall_count INTEGER NOT NULL DEFAULT 0 and last_recalled_at TEXT columns to observations
- Increment
recall_count on Search(), GetObservation() (fire-and-forget, never blocks reads)
- New
PromotedObservations() method: returns observations ordered by recall_count DESC with configurable threshold
HTTP API:
GET /promoted?project=X&scope=Y&min_recalls=5&limit=7 — returns observations that have proven their value through repeated access
MCP tool:
mem_promoted — agent-profile tool for surfacing high-value context at session start
Motivation
Inspired by NeoVertex1/nuggets which uses a "memory promotion" concept where frequently-accessed facts graduate to permanent system prompt context. This feature provides the data layer that clients can use to implement similar promotion strategies.
Implementation Notes
incrementRecall() is fire-and-forget (db.Exec without error propagation) — recall tracking must never break reads
- Recall data is analytics metadata, not content — no need for
enqueueSyncMutationTx
- All existing scan sites (8 total) need the new columns added to maintain consistency