Skip to content

feat(store): add recall tracking and promoted observations endpoint #95

@sergiomarquezdev

Description

@sergiomarquezdev

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions