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 no-op until a tracer provider or custom registry is configured; core memory logic behavior is unchanged aside from metric side effects.

Overview
Adds Phase 9 observability to @betterdb/agent-memory: a new telemetry.ts with createMemoryTelemetry() (configurable tracer name, metrics prefix, and prom Registry), exported from the package public API.

MemoryStore accepts optional telemetry options and wires OpenTelemetry spans around remember, recall, and consolidate via a traced() helper (OK/ERROR status, operation-specific attributes). Prometheus metrics are updated on the main paths: recall totals/hits/empty/latency, embedding calls, an in-process items gauge (inc/dec on remember, forget, eviction, consolidate), plus evictions and consolidation counters—all labeled by store_name.

Dependencies add @opentelemetry/api and prom-client; tests cover metrics against a real Registry and spans via an in-memory OTel exporter.

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