#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix: surface saved memories in smart_search/recall (#265) (#269)
Rohit Ghumare5fc73f2eb2df
diff --git a/src/functions/remember.ts b/src/functions/remember.tsindex 9666a7df..ba9d5409 100644--- a/src/functions/remember.ts+++ b/src/functions/remember.ts@@ -1,33 +1,14 @@import { TriggerAction, type ISdk } from "iii-sdk";-import type { CompressedObservation, Memory } from "../types.js";+import type { 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 { memoryToObservation } from "../state/memory-utils.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: {@@ -124,7 +105,7 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {// 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));+ getSearchIndex().add(memoryToObservation(memory));} catch (err) {logger.warn("Failed to index saved memory into BM25", {memId: memory.id,diff --git a/src/functions/search.ts b/src/functions/search.tsindex 0f662419..edfa522b 100644--- a/src/functions/search.ts+++ b/src/functions/search.ts@@ -3,30 +3,10 @@ import type { CompactSearchResult, CompressedObservation, Memory, SearchResult,import { KV } from '../state/schema.js'import { StateKV } from '../state/kv.js'import { SearchIndex } from '../state/search-index.js'+import { memoryToObservation } from '../state/memory-utils.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 {@@ -49,7 +29,7 @@ export async function rebuildIndex(kv: StateKV): Promise<number> {for (const memory of memories) {if (memory.isLatest === false) continueif (!memory.title || !memory.content) continue- idx.add(memoryAsIndexable(memory))+ idx.add(memoryToObservation(memory))count++}} catch (err) {@@ -164,11 +144,21 @@ export function registerSearchFunction(sdk: ISdk, kv: StateKV): void {candidates.push(r)}- // Second pass: load observations in parallel.+ // Second pass: load observations in parallel. Fall back to+ // KV.memories when the observation lookup misses — entries indexed+ // via mem::remember live in the memories scope under a synthetic+ // sessionId, so the observation key never exists (#265).const obsResults = await Promise.all(- candidates.map((r) =>- kv.get<CompressedObservation>(KV.observations(r.sessionId), r.obsId)- )+ candidates.map(async (r) => {+ const obs = await kv+ .get<CompressedObservation>(KV.observations(r.sessionId), r.obsId)+ .catch(() => null)+ if (obs) return obs+ const mem = await kv+ .get<Memory>(KV.memories, r.obsId)+ .catch(() => null)+ return mem ? memoryToObservation(mem) : null+ }))const enriched: SearchResult[] = []for (let i = 0; i < candidates.length; i++) {diff --git a/src/state/hybrid-search.ts b/src/state/hybrid-search.tsindex d05fca2f..d234a3ef 100644--- a/src/state/hybrid-search.ts+++ b/src/state/hybrid-search.ts@@ -4,8 +4,10 @@ import type {EmbeddingProvider,HybridSearchResult,CompressedObservation,+ Memory,QueryExpansion,} from "../types.js";+import { memoryToObservation } from "./memory-utils.js";import type { StateKV } from "./kv.js";import { KV } from "./schema.js";import {@@ -287,11 +289,20 @@ export class HybridSearch {): Promise<HybridSearchResult[]> {const sliced = results.slice(0, limit);const observations = await Promise.all(- sliced.map((r) =>- this.kv+ sliced.map(async (r) => {+ const obs = await this.kv.get<CompressedObservation>(KV.observations(r.sessionId), r.obsId)- .catch(() => null),- ),+ .catch(() => null);+ if (obs) return obs;+ // Fallback: indexed entry may originate from mem::remember, which+ // writes to KV.memories with a synthetic sessionId ("memory" or the+ // memory's first associated session). Coerce the Memory record into+ // a CompressedObservation so search/recall surface saved memories.+ const mem = await this.kv+ .get<Memory>(KV.memories, r.obsId)+ .catch(() => null);+ return mem ? memoryToObservation(mem) : null;+ }),);const enriched: HybridSearchResult[] = [];for (let i = 0; i < sliced.length; i++) {diff --git a/src/state/memory-utils.ts b/src/state/memory-utils.tsnew file mode 100644index 00000000..a353694e--- /dev/null+++ b/src/state/memory-utils.ts@@ -0,0 +1,24 @@+import type { CompressedObservation, Memory } from "../types.js";++// Wraps a Memory record in the CompressedObservation shape that+// SearchIndex / VectorIndex / enrichment paths consume. Memories share+// the same searchable fields as observations (title + content ++// concepts + files); type is normalized to "decision" so memories stay+// distinguishable in result metadata without colliding with observation+// enums (file_read, command_run, …). The synthetic sessionId+// ("memory" or memory.sessionIds[0]) is what enrich-side fallbacks key+// off of when looking up the source record in KV.memories.+export function memoryToObservation(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,+ };+}diff --git a/test/hybrid-search.test.ts b/test/hybrid-search.test.tsindex c07df6ae..811247ac 100644--- a/test/hybrid-search.test.ts+++ b/test/hybrid-search.test.ts@@ -142,4 +142,42 @@ describe("HybridSearch", () => {const results = await hybrid.search("auth");expect(results).toEqual([]);});++ it("falls back to KV.memories when an indexed entry is a saved memory (#265)", async () => {+ // mem::remember writes to KV.memories under the synthetic sessionId+ // "memory" — the BM25 index sees that synthetic sessionId, but+ // KV.observations("memory") never has anything.+ const indexable = makeObs({+ id: "mem_abc",+ sessionId: "memory",+ title: "Test memory for search",+ narrative: "Test memory for search",+ concepts: ["test", "search"],+ });+ bm25.add(indexable);++ const memory = {+ id: "mem_abc",+ createdAt: new Date().toISOString(),+ updatedAt: new Date().toISOString(),+ type: "fact",+ title: "Test memory for search",+ content: "Test memory for search",+ concepts: ["test", "search"],+ files: [],+ sessionIds: [],+ strength: 7,+ version: 1,+ isLatest: true,+ };+ await kv.set("mem:memories", "mem_abc", memory);++ const hybrid = new HybridSearch(bm25, null, null, kv as never);+ const results = await hybrid.search("test memory search");++ expect(results.length).toBe(1);+ expect(results[0].observation.id).toBe("mem_abc");+ expect(results[0].observation.narrative).toBe("Test memory for search");+ expect(results[0].observation.concepts).toEqual(["test", "search"]);+ });});diff --git a/test/search.test.ts b/test/search.test.tsindex f7e29d0d..a7b1d954 100644--- a/test/search.test.ts+++ b/test/search.test.ts@@ -4,7 +4,7 @@ vi.mock("../src/logger.js", () => ({logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },}));-import { registerSearchFunction } from "../src/functions/search.js";+import { registerSearchFunction, getSearchIndex, rebuildIndex } from "../src/functions/search.js";import { KV } from "../src/state/schema.js";import type { CompressedObservation, Session } from "../src/types.js";@@ -97,6 +97,9 @@ describe("mem::search", () => {await kv.set(KV.observations("ses_1"), obsA.id, obsA);await kv.set(KV.observations("ses_1"), obsB.id, obsB);++ // Module-level SearchIndex singleton would leak across tests; reset.+ getSearchIndex().clear();});it("returns full format by default", async () => {@@ -147,4 +150,36 @@ describe("mem::search", () => {sdk.trigger("mem::search", { query: "auth", format: "verbose" }),).rejects.toThrow("format must be one of");});++ it("surfaces saved memories from KV.memories (#265)", async () => {+ // mem::remember persists to KV.memories under a synthetic sessionId+ // ("memory") that has no corresponding KV.observations entry. mem::search+ // must fall back to KV.memories or memory_recall returns empty.+ await kv.set(KV.memories, "mem_x1", {+ id: "mem_x1",+ createdAt: "2026-02-01T00:00:00Z",+ updatedAt: "2026-02-01T00:00:00Z",+ type: "fact",+ title: "Pineapple belongs on pizza",+ content: "Pineapple belongs on pizza for testing fallback path.",+ concepts: ["pineapple", "pizza"],+ files: [],+ sessionIds: [],+ strength: 7,+ version: 1,+ isLatest: true,+ });+ // Force the rebuild to pick up the new memory (mem::search only+ // rebuilds on first call when idx.size === 0).+ await rebuildIndex(kv as never);++ const result = (await sdk.trigger("mem::search", {+ query: "pineapple pizza",+ format: "compact",+ })) as { results: Array<{ obsId: string; title: string }> };++ const hit = result.results.find((r) => r.obsId === "mem_x1");+ expect(hit).toBeDefined();+ expect(hit?.title).toBe("Pineapple belongs on pizza");+ });});