Skip to content

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

fix: surface saved memories in smart_search/recall (#265) (#269)

Rohit Ghumare5fc73f2eb2df
diff --git a/src/functions/remember.ts b/src/functions/remember.ts
index 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.ts
index 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 = null
export function getSearchIndex(): SearchIndex {
@@ -49,7 +29,7 @@ export async function rebuildIndex(kv: StateKV): Promise<number> {
for (const memory of memories) {
if (memory.isLatest === false) continue
if (!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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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");
+ });
});