#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(memory): index memories into BM25 + backfill on startup (closes #257) (#258)
Rohit Ghumare1a035383ded3
diff --git a/src/functions/remember.ts b/src/functions/remember.tsindex 0fb389be..9666a7df 100644--- a/src/functions/remember.ts+++ b/src/functions/remember.ts@@ -1,12 +1,33 @@import { TriggerAction, type ISdk } from "iii-sdk";-import type { Memory } from "../types.js";+import type { CompressedObservation, Memory } from "../types.js";import { KV, generateId, jaccardSimilarity } from "../state/schema.js";import { StateKV } from "../state/kv.js";import { withKeyedLock } from "../state/keyed-mutex.js";import { deleteAccessLog } from "./access-tracker.js";import { recordAudit } from "./audit.js";+import { getSearchIndex } from "./search.js";import { logger } from "../logger.js";+// SearchIndex is built around CompressedObservation. Memories carry the+// same searchable text (title + content + concepts + files) so we wrap+// them in the observation shape before indexing. Type is normalized to+// "decision" so memories are still distinguishable in result metadata+// without colliding with observation enums (file_read, command_run, etc).+function memoryAsIndexable(memory: Memory): CompressedObservation {+ return {+ id: memory.id,+ sessionId: memory.sessionIds[0] ?? "memory",+ timestamp: memory.createdAt,+ type: "decision",+ title: memory.title,+ facts: [memory.content],+ narrative: memory.content,+ concepts: memory.concepts,+ files: memory.files,+ importance: memory.strength,+ };+}+export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {sdk.registerFunction("mem::remember",async (data: {@@ -97,6 +118,20 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {}await kv.set(KV.memories, memory.id, memory);+ // Without this, mem::remember persists the row but the BM25+ // index never sees it, so memory_smart_search and memory_recall+ // return empty even seconds after save (#257). Use try/catch so+ // an indexing failure doesn't block the save itself — the+ // restart-time rebuild will pick the memory up either way.+ try {+ getSearchIndex().add(memoryAsIndexable(memory));+ } catch (err) {+ logger.warn("Failed to index saved memory into BM25", {+ memId: memory.id,+ error: err instanceof Error ? err.message : String(err),+ });+ }+if (supersededId) {await sdk.trigger({function_id: "mem::cascade-update",diff --git a/src/functions/search.ts b/src/functions/search.tsindex 62b654ab..0f662419 100644--- a/src/functions/search.ts+++ b/src/functions/search.ts@@ -1,11 +1,32 @@import type { ISdk } from 'iii-sdk'-import type { CompactSearchResult, CompressedObservation, SearchResult, Session } from '../types.js'+import type { CompactSearchResult, CompressedObservation, Memory, SearchResult, Session } from '../types.js'import { KV } from '../state/schema.js'import { StateKV } from '../state/kv.js'import { SearchIndex } from '../state/search-index.js'import { recordAccessBatch } from './access-tracker.js'import { logger } from "../logger.js";+// Memories share the same searchable fields as observations (title ++// content + concepts + files), so we wrap them in the observation shape+// before indexing. Type is normalized to "decision" to keep memories+// distinguishable in result metadata. Mirrors the helper in+// functions/remember.ts; kept inline here to avoid a circular import+// (remember.ts imports from this file).+function memoryAsIndexable(memory: Memory): CompressedObservation {+ return {+ id: memory.id,+ sessionId: memory.sessionIds[0] ?? "memory",+ timestamp: memory.createdAt,+ type: "decision",+ title: memory.title,+ facts: [memory.content],+ narrative: memory.content,+ concepts: memory.concepts,+ files: memory.files,+ importance: memory.strength,+ };+}+let index: SearchIndex | null = nullexport function getSearchIndex(): SearchIndex {@@ -17,10 +38,29 @@ export async function rebuildIndex(kv: StateKV): Promise<number> {const idx = getSearchIndex()idx.clear()+ let count = 0++ // Memories live in their own KV scope outside per-session observation+ // scopes, so they need a separate walk. Without this, mem::remember+ // entries vanish from BM25 on every restart even after the live-write+ // fix in remember.ts (#257).+ try {+ const memories = await kv.list<Memory>(KV.memories)+ for (const memory of memories) {+ if (memory.isLatest === false) continue+ if (!memory.title || !memory.content) continue+ idx.add(memoryAsIndexable(memory))+ count+++ }+ } catch (err) {+ logger.warn('rebuildIndex: failed to load memories', {+ error: err instanceof Error ? err.message : String(err),+ })+ }+const sessions = await kv.list<Session>(KV.sessions)- if (!sessions.length) return 0+ if (!sessions.length) return count- let count = 0const obsPerSession: CompressedObservation[][] = []const failedSessions: string[] = []for (let batch = 0; batch < sessions.length; batch += 10) {diff --git a/src/index.ts b/src/index.tsindex 418847b7..7a746620 100644--- a/src/index.ts+++ b/src/index.ts@@ -19,6 +19,7 @@ import {createImageEmbeddingProvider,} from "./providers/index.js";import { StateKV } from "./state/kv.js";+import { KV } from "./state/schema.js";import { VectorIndex } from "./state/vector-index.js";import { HybridSearch } from "./state/hybrid-search.js";import { IndexPersistence } from "./state/index-persistence.js";@@ -399,10 +400,51 @@ async function main() {});if (indexCount > 0) {console.log(- `[agentmemory] Search index rebuilt: ${indexCount} observations`,+ `[agentmemory] Search index rebuilt: ${indexCount} entries`,);indexPersistence.scheduleSave();}+ } else {+ // Backfill memories into BM25 for users upgrading from <0.9.5: prior+ // versions of mem::remember never indexed memories, so the persisted+ // BM25 covers observations only and `memory_smart_search` returns+ // empty for everything saved via memory_save (#257). Walk KV.memories+ // and add the ones missing from the restored index. Idempotent on+ // re-runs because SearchIndex.has() short-circuits already-indexed+ // ids.+ try {+ const memories = await kv.list<import("./types.js").Memory>(KV.memories);+ let backfilled = 0;+ for (const memory of memories) {+ if (memory.isLatest === false) continue;+ if (!memory.title || !memory.content) continue;+ if (bm25Index.has(memory.id)) continue;+ bm25Index.add({+ id: memory.id,+ sessionId: memory.sessionIds[0] ?? "memory",+ timestamp: memory.createdAt,+ type: "decision",+ title: memory.title,+ facts: [memory.content],+ narrative: memory.content,+ concepts: memory.concepts,+ files: memory.files,+ importance: memory.strength,+ });+ backfilled++;+ }+ if (backfilled > 0) {+ console.log(+ `[agentmemory] Backfilled ${backfilled} memories into BM25 (legacy gap before #257)`,+ );+ indexPersistence.scheduleSave();+ }+ } catch (err) {+ console.warn(+ `[agentmemory] Failed to backfill memories into BM25:`,+ err,+ );+ }}console.log(diff --git a/src/state/search-index.ts b/src/state/search-index.tsindex ed89a2ee..f534791d 100644--- a/src/state/search-index.ts+++ b/src/state/search-index.ts@@ -46,6 +46,10 @@ export class SearchIndex {this.sortedTerms = null;}+ has(id: string): boolean {+ return this.entries.has(id);+ }+search(query: string,limit = 20,diff --git a/test/remember-bm25-index.test.ts b/test/remember-bm25-index.test.tsnew file mode 100644index 00000000..77ee8d12--- /dev/null+++ b/test/remember-bm25-index.test.ts@@ -0,0 +1,97 @@+import { describe, it, expect } from "vitest";+import { SearchIndex } from "../src/state/search-index.js";+import type { CompressedObservation, Memory } from "../src/types.js";++// Mirrors the helper used by remember.ts and rebuildIndex(). Kept inline+// here rather than exporting from src/ so the test asserts the contract,+// not the implementation.+function memoryAsIndexable(memory: Memory): CompressedObservation {+ return {+ id: memory.id,+ sessionId: memory.sessionIds[0] ?? "memory",+ timestamp: memory.createdAt,+ type: "decision",+ title: memory.title,+ facts: [memory.content],+ narrative: memory.content,+ concepts: memory.concepts,+ files: memory.files,+ importance: memory.strength,+ };+}++function makeMemory(overrides: Partial<Memory> = {}): Memory {+ return {+ id: "mem_test_001",+ createdAt: new Date().toISOString(),+ updatedAt: new Date().toISOString(),+ type: "fact",+ title: "BM25 test memory",+ content: "BM25 search returns this memory by keyword match",+ concepts: ["bm25", "search", "test"],+ files: [],+ sessionIds: [],+ strength: 7,+ version: 1,+ isLatest: true,+ ...overrides,+ };+}++describe("SearchIndex.has()", () => {+ it("returns false for unknown ids", () => {+ expect(new SearchIndex().has("mem_unknown")).toBe(false);+ });++ it("returns true after add()", () => {+ const idx = new SearchIndex();+ idx.add(memoryAsIndexable(makeMemory()));+ expect(idx.has("mem_test_001")).toBe(true);+ });+});++describe("memory indexing into SearchIndex (closes #257)", () => {+ it("makes a saved memory findable by keyword search", () => {+ const idx = new SearchIndex();+ idx.add(memoryAsIndexable(makeMemory({+ id: "mem_user_001",+ title: "JWT middleware uses jose for Edge compatibility",+ content: "Chose jose over jsonwebtoken because Cloudflare Workers don't ship Node crypto",+ concepts: ["auth", "jose", "edge"],+ })));++ const hits = idx.search("jose middleware", 5);+ expect(hits).toHaveLength(1);+ expect(hits[0].obsId).toBe("mem_user_001");+ });++ it("returns the memory when the issue's reproduction query is run", () => {+ // From issue #257: user saved a memory containing 'BM25 test'+ // keywords and the search returned empty — recall failure.+ const idx = new SearchIndex();+ idx.add(memoryAsIndexable(makeMemory({+ id: "mem_moy3u6ua_8c6962b668e7",+ title: "BM25 test",+ content: "Confirmed BM25 indexing works for memories saved via memory_save",+ concepts: [],+ })));++ const hits = idx.search("BM25 test", 5);+ expect(hits.length).toBeGreaterThan(0);+ expect(hits[0].obsId).toBe("mem_moy3u6ua_8c6962b668e7");+ });++ it("matches concepts as well as title and content", () => {+ const idx = new SearchIndex();+ idx.add(memoryAsIndexable(makeMemory({+ id: "mem_concept_001",+ title: "Generic title",+ content: "Generic content",+ concepts: ["unique-concept-marker"],+ })));++ const hits = idx.search("unique-concept-marker", 5);+ expect(hits.length).toBeGreaterThan(0);+ expect(hits[0].obsId).toBe("mem_concept_001");+ });+});