feat(agent-memory): index bootstrap — MemoryStore.ensureIndex()

[jamby77]

Agent Memory — index bootstrap (ensureIndex)

Stacked on #259 (Phase 11).

Why

MemoryStore queries {name}:mem:idx in five paths (recall, forgetByScope, consolidate, capacity count + scan) but the package never creates that index — it was implicitly the caller's job, with the integration suite hand-rolling an FT.CREATE. This is the gap KIvanow flagged in review on #249/#250, and spec-agent-memory.md (data model + "reuse the valkey-search helper for index create/version-skew handling") calls for the package to own it. No phase had picked it up.

What's new

• buildMemoryIndex — buildMemoryIndexArgs(name, dims) / memoryIndexName(name): the FT.CREATE arg list for the memory schema — vector (HNSW, FLOAT32, COSINE), threadId/agentId/namespace/tags(comma-sep)/source as TAG, importance/created_at/last_accessed_at/access_count as NUMERIC, content as TEXT. Matches exactly the fields buildMemoryRecord writes and buildRecallQuery/buildScopeFilter query.
• MemoryStore.ensureIndex() — idempotent: FT.INFO → on isIndexNotFoundError (from @betterdb/valkey-search-kit) → FT.CREATE. Resolves the vector dimension from embedFn (probe) when no write has been observed yet, and reuses a dimension already learned from a write. Non-"not found" errors propagate. Mirrors Retriever.createIndex() in the retrieval SDK.
• AgentMemory.initialize() now calls memory.ensureIndex() first, so a freshly constructed facade is immediately usable for remember/recall without the caller hand-rolling the index. A create failure surfaces (the tier is unusable without it).

Tests

• 13 new hermetic unit tests: buildMemoryIndex arg shape + dim validation; ensureIndex create-when-missing / idempotent / dim-probe / dim-reuse / non-not-found-rethrow; AgentMemory.initialize() creates the index.
• The integration suite now dogfoods store.ensureIndex() instead of a hand-rolled FT.CREATE. (Skip-guarded; runs against a live valkey-search in CI / with the bundle up — it was not run locally here, as the bundle wasn't running. The hermetic tests verify the arg construction and idempotency.)
• tsc --noEmit + prettier clean; 115 tests pass in the package.

Notes

• The index is HNSW (per spec, production-appropriate). The integration suite previously hand-rolled a FLAT index for test simplicity; switching it to ensureIndex aligns the test on the real production path.
• Optional follow-up (spec's literal intent): lift a generic FT.CREATE builder into @betterdb/valkey-search-kit so retrieval and agent-memory share one. Not required here — the memory schema is fixed.

---

Note

Medium Risk
Index creation runs on initialize and locks vector dimension to the embedder; failures block startup, but behavior is idempotent and covered by new unit/integration tests.

Overview
agent-memory now owns creation of the {name}:mem:idx vector search index instead of leaving that to callers or integration tests.

A new buildMemoryIndex helper builds the FT.CREATE schema (HNSW cosine vector plus TAG/NUMERIC/TEXT fields aligned with writes and recall queries). MemoryStore.ensureIndex() checks FT.INFO, creates the index only when missing (using isIndexNotFoundError), and picks vector DIM from a prior write or an embedFn('probe') call. AgentMemory.initialize() awaits ensureIndex() before discovery so the facade is ready for remember/recall without manual index setup.

Hermetic tests cover index args, idempotency, dim resolution, and error propagation; the live integration suite drops its hand-rolled FT.CREATE (previously FLAT) in favor of ensureIndex() (HNSW).

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