feat(agent-memory): Phase 0 — scaffold @betterdb/agent-memory

[jamby77]

Agent Memory — Phase 0: Scaffold

First phase of the Agent Memory pillar (second of the three context-layer pillars; Retrieval is the first). Branches off master — Agent Memory depends only on the already-merged @betterdb/valkey-search-kit (#234), not on the open retrieval stack.

What's new

• New @betterdb/agent-memory package that re-exports @betterdb/agent-cache (AgentCache + all short-term tiers/types) and adds two new exports:
  • MemoryStore — the long-term semantic tier (stub for now)
  • AgentMemory — convenience facade = AgentCache + MemoryStore (stub for now)
• Test helpers: deterministic dimension-configurable fakeEmbed (sha256→vector) and a mockClient (FT.* call spy), mirroring the semantic-cache/retrieval test conventions.

Dependency decision (spec §253)

@betterdb/agent-memory depends on the shared low-level @betterdb/valkey-search-kit helper, not @betterdb/semantic-cache — avoids a heavy/circular dependency. The caller supplies embedFn (as in the spec example).

Tests

3 unit tests asserting the package re-exports AgentCache and exports MemoryStore/AgentMemory. tsc --noEmit + prettier clean; build green; frozen-lockfile valid.

Next

Phase 1 (remember() write path) stacks on this branch, then recall() ranking, etc. — 12 core phases per plan-agent-memory.md.

---

Note

Low Risk
Scaffold-only: no runtime behavior, stubs, and export tests; no auth, data paths, or production logic yet.

Overview
Introduces @betterdb/agent-memory as the Agent Memory pillar package: it re-exports everything from @betterdb/agent-cache and adds MemoryStore (long-term semantic tier) and AgentMemory (facade) as empty class stubs for upcoming phases.

The package wires @betterdb/agent-cache and @betterdb/valkey-search-kit (not semantic-cache), with standard build/typecheck/vitest tooling. Test-only helpers fakeEmbed (deterministic sha256-based vectors) and mockClient (iovalkey-style call spy) mirror patterns from semantic-cache tests. Three export smoke tests cover the public API surface.

pnpm-lock.yaml registers the new workspace package; unrelated lockfile key formatting for retry-axios also shifts.

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

[KIvanow]

Scaffold looks clean overall — package layout, the export * re-export of agent-cache, and the tsconfig all match the retrieval package conventions, and the valkey-search-kit (not semantic-cache) dependency call is the right one per the spec. Just one thing I'd fix before merging.

Unrelated lockfile drift. The pnpm-lock.yaml diff has a change that has nothing to do with this package: it drops cpu: [x64, arm64] from @lancedb/lancedb@0.23.0. That looks like it snuck in from regenerating the lock on a different pnpm/platform rather than an intentional edit. Since that field constrains which CPU archs lancedb's native binary installs on, I'd revert it so this PR only adds the new packages/agent-memory importer entry and leaves everything else untouched — keeps the scaffold PR clean and avoids a surprise install-resolution change for other folks.

One small non-blocker: fakeEmbed and mockClient aren't referenced by any test in this PR yet. Totally fine as forward-scaffold for the Phase 1 write-path tests — just flagging that they'll sit as unused until then in case lint/coverage complains.

Nothing else from me — happy to re-approve once the lockfile is back to just the new entry.

Dismissing — moved this feedback off the PR per request.