Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

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.ts
index 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.ts
index 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 = null
export 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 = 0
const obsPerSession: CompressedObservation[][] = []
const failedSessions: string[] = []
for (let batch = 0; batch < sessions.length; batch += 10) {
diff --git a/src/index.ts b/src/index.ts
index 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.ts
index 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.ts
new file mode 100644
index 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");
+ });
+});