feat(agent-memory): Phase 10 — AgentMemory facade

[jamby77]

Stacked on #257 (Phase 9 — observability).

What

Phase 10 of @betterdb/agent-memory: the AgentMemory convenience facade so a caller gets all four tiers from one construct.

const mem = new AgentMemory({
  client, embedFn,
  tierDefaults: { session: { ttl: 1800 } },
  memory: { defaultThreshold: 0.25, recall: { weights, halfLifeSeconds }, maxItemsPerScope: 5000 },
});
await mem.initialize();
mem.llm / mem.tool / mem.session   // short-term, delegated to AgentCache (unchanged)
mem.memory                         // long-term MemoryStore

• Wraps AgentCache (exposing .llm/.tool/.session) + a MemoryStore (.memory), sharing the client, the resolved name prefix, and the telemetry registry.
• Requires embedFn — throws a clear error if missing (checked before any resource is constructed).
• Maps the memory sub-config onto MemoryStore (verified end-to-end via currentConfig()).
• initialize() awaits discovery readiness for both tiers; close() tears down both (memory first, cache.shutdown() in a finally).

Design / review notes (fixes applied)

• Single resolved name: the name is resolved once (options.name ?? 'betterdb_ac') and passed explicitly to both AgentCache and MemoryStore, so their key prefixes / discovery markers / stats keys can never drift even if AgentCache's internal default changes.
• Symmetric discovery: AgentCache discovers by default, so the facade now discovers the memory tier by default too (opt-out via memory.discovery: false). Standalone MemoryStore stays opt-in. Added MemoryStore.ensureDiscoveryReady() so initialize() can await it.
• Leak-safe close: close() runs cache.shutdown() in a finally, so a failing memory.close() can't leave cache timers/heartbeats running.
• Distinct metric namespaces (agent_cache_* vs agent_memory_*) are intentional; only the prom registry is shared.

Tests (AgentMemory.test.ts, 9)

exposes 4 tiers · embedFn-missing throws · memory wired to shared client+prefix · custom name prefix · sub-config mapping via currentConfig() · initialize()/close() drive both (spy) · memory marker registered by default · memory discovery opt-out · one shared prom registry (agent_cache_* + agent_memory_*).

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

---

Note

Low Risk
New facade and lifecycle wiring with no changes to core recall/storage algorithms; risk is mainly integration (shared client/name, dual teardown) covered by tests.

Overview
Introduces AgentMemory, a single entry point that exposes short-term llm / tool / session tiers (via AgentCache) and long-term memory (MemoryStore) from one constructor.

Construction requires embedFn, resolves name once for both tiers (default betterdb_ac), maps the memory sub-config (threshold, recall weights/half-life, caps, discovery, config refresh), and optionally shares one Prometheus registry across cache and memory metrics.

initialize() awaits discovery readiness for cache and memory; close() shuts down memory first and always runs cache.shutdown() in a finally to avoid timer/heartbeat leaks. Memory discovery defaults on in the facade (opt out with memory.discovery: false); MemoryStore.ensureDiscoveryReady() is added so initialization can await registration.

Package exports and a new AgentMemory.test.ts suite cover wiring, prefixes, config mapping, discovery markers ({name}:mem), and shared telemetry.

^{Reviewed by Cursor Bugbot for commit a0accf8. 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 268b946. Configure here.}