feat(agent-memory): Phase 6 — consolidate()

[jamby77]

Stacked on #253 (Phase 5 — eviction & TTL).

What

Phase 6 of @betterdb/agent-memory: consolidation — summarize many old/low-value memories into fewer durable ones. Callable, not scheduled (per spec).

consolidate(options):

• Selects candidates in scope (threadId/agentId/namespace + tags) filtered by olderThanSeconds and maxImportance.
• Calls the caller-supplied summarize(items) => Promise<string> (the library never hard-codes an LLM — mirrors the judge-injection pattern).
• Writes the result as a normal memory with source: 'summary' at summaryImportance (default 0.7), scoped/tagged to the request.
• With deleteSources (default true) removes the originals; returns { consolidated, created, deleted }.

Design / review notes

• Write-before-delete: the summary is written before sources are deleted, so a failure can never destroy memories without leaving their consolidated replacement.
• Mass-delete guard: requires at least one selection criterion (scope, tags, olderThanSeconds, or maxImportance) — a criteria-less consolidate({summarize}) would otherwise summarize+delete the entire store. Mirrors forgetByScope's guard.
• Efficiency: the candidate scan uses an explicit RETURN of only the fields parseMemoryItem needs, so it never transfers vector blobs.
• Bounded scan (CONSOLIDATE_SCAN_LIMIT); a single summarize() over a whole huge scope is impractical anyway, and the remainder consolidates on subsequent calls.

Tests (MemoryStore.consolidate.test.ts, 8)

candidate summarize+write+delete+counts · olderThanSeconds filter · maxImportance filter · summary scope+summaryImportance · deleteSources:false keeps sources · nothing-matches → zeros & no summarize/write · no-criteria guard throws · defaults (0.7 / delete).

55/55 package tests green · tsc --noEmit clean · prettier clean.

---

Note

Medium Risk
The operation can bulk-delete stored memories if criteria match; guards and write-before-delete reduce accidental loss, but misconfigured scope or summarize failures still need careful caller handling.

Overview
Adds MemoryStore.consolidate() so callers can merge many scoped memories into one durable summary memory, with optional removal of the originals.

Candidates are found via scoped FT.SEARCH, then filtered by olderThanSeconds and maxImportance. The caller supplies summarize(items) (no built-in LLM). The summary is stored through remember() with source: 'summary', default summaryImportance 0.7, and the same scope/tags. deleteSources defaults to true; the API returns { consolidated, created, deleted }.

Safety: consolidation requires at least one selection criterion (scope, tags, age, or importance cap) to block whole-store runs. The summary is written before source deletes. Scans are capped at CONSOLIDATE_SCAN_LIMIT and use a narrow RETURN list (no vector payloads). New ConsolidateOptions / ConsolidateResult types are exported; behavior is covered by MemoryStore.consolidate.test.ts.

^{Reviewed by Cursor Bugbot for commit e27477f. 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.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

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