feat(agent-memory): Phase 9 — observability

[jamby77]

Stacked on #256 (Phase 8 — self-optimization config reads).

What

Phase 9 of @betterdb/agent-memory: OpenTelemetry spans + Prometheus metrics, mirroring the agent-cache/semantic-cache telemetry pattern.

createMemoryTelemetry({ tracerName?, metricsPrefix?, registry? }) builds a prom-client metric set + an OTel tracer. Metrics (prefix configurable, default agent_memory):

• agent_memory_items (gauge)
• agent_memory_recall_total / agent_memory_recall_hits_total / agent_memory_recall_empty_total
• agent_memory_recall_latency_seconds (histogram)
• agent_memory_embedding_calls_total
• agent_memory_evictions_total
• agent_memory_consolidations_total

Spans via a traced() helper (OK/ERROR status, always end()):

• agent_memory.remember — memory.importance, memory.ttl
• agent_memory.recall — recall.k, recall.candidate_count, recall.result_count
• agent_memory.consolidate — consolidate.candidates, consolidate.created, consolidate.deleted

Metrics are wired through remember/recall/consolidate/forget/forgetByScope/embed and the capacity-eviction path. All store_name-labelled.

Design / review notes

• Optional & no-op by default: the OTel tracer is a no-op until a provider is registered; metrics use prom-client's default registry unless one is passed — same as agent-cache. Telemetry creation does no I/O, so the existing .call-sequence unit tests are unaffected.
• The items gauge is an in-process net delta (documented as approximate). Eviction/forget/consolidate decrement it; remember increments it.
• A failed operation surfaces via the span's ERROR status rather than a success counter (e.g. the consolidate no-criteria guard does not count a consolidation).

Deps

Adds @opentelemetry/api, prom-client (deps, matching agent-cache) and @opentelemetry/sdk-trace-base (devDep, for the in-memory span exporter used in tests). Lockfile updated.

Tests

• MemoryStore.telemetry.test.ts (6): embedding+items on remember · recall hit (+latency count) · empty recall · evictions · consolidations · configurable prefix — all read a real prom Registry.
• MemoryStore.spans.test.ts (3): remember/recall/consolidate spans + attributes, asserted via an InMemorySpanExporter.

86/86 package tests green · tsc clean · prettier clean.

---

Note

Low Risk
Observability is additive and optional; the eviction counting fix only makes metrics/stats more accurate when the search index is stale.

Overview
Adds Phase 9 observability to @betterdb/agent-memory: optional telemetry on MemoryStore (and exported createMemoryTelemetry) following the same pattern as agent-cache—no-op OTel until a provider is registered, prom-client metrics on the default or a passed Registry.

remember, recall, and consolidate run inside a traced() helper that emits agent_memory.* spans with operation-specific attributes and OK/ERROR status. Recall also records totals, hit/empty counters, and a latency histogram; writes/deletes adjust an in-process items gauge; embed, eviction, and consolidation paths increment their counters (all labelled by store_name).

Capacity eviction now increments __mem_stats evictions and Prometheus using the DEL reply count, not the number of keys requested—so stale index entries do not inflate stats (new eviction test covers this).

^{Reviewed by Cursor Bugbot for commit 9f72079. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 41e8dfe. Configure here.}