diff --git a/docs/recall.md b/docs/recall.md index 434dc5bfc6..d7fb77b02e 100644 --- a/docs/recall.md +++ b/docs/recall.md @@ -26,6 +26,30 @@ Its optional lesson list accompanies mixed search only. Use `memory_lesson_recal for lessons and `memory_insight_list` for insights. Layer selection is separate from `project` and `agentId`; preserve scope filters when expanding results. +## Original memory types + +Saved memories have their own `type`, such as `fact`, `preference`, or +`architecture`. Search adapts them to the observation format, where `type` +remains `decision`. Read `memoryType` for the original saved-memory type. + +Compact search returns `memoryType` beside `type`. Expanded search and full +recall put it inside `observation`. Compact and narrative recall retain it, +including shortened previews. Ordinary observations and lessons omit it. + +For example, a saved fact appears as: + +```json +{ + "type": "decision", + "memoryType": "fact" +} +``` + +Older persisted indexes need no migration: compact smart search resolves the +type from the authorized saved record. Stored memory types and the observation +type enum do not change. The reduced local MCP fallback adds `memoryType` while +retaining its existing compact response fields. + ## Budgeted recall All three `memory_recall` formats (`full`, `compact`, `narrative`) return structured diff --git a/src/functions/recall-response.ts b/src/functions/recall-response.ts index dadd6559cd..220b470d00 100644 --- a/src/functions/recall-response.ts +++ b/src/functions/recall-response.ts @@ -54,6 +54,7 @@ function formatResult(result: SearchResult, format: RecallFormat): RecallResult sessionId: result.sessionId, title: observation.title, type: observation.type, + ...(observation.memoryType !== undefined && { memoryType: observation.memoryType }), score: result.score, timestamp: observation.timestamp, ...(result.layer !== undefined && { layer: result.layer }), @@ -76,6 +77,7 @@ function clipResult( sessionId: result.sessionId, title: "", type: observation.type, + ...(observation.memoryType !== undefined && { memoryType: observation.memoryType }), score: result.score, timestamp: observation.timestamp, ...layer, @@ -96,6 +98,7 @@ function clipResult( sessionId: result.sessionId, title, narrative, + ...(observation.memoryType !== undefined && { memoryType: observation.memoryType }), score: result.score, timestamp: observation.timestamp, ...layer, @@ -108,6 +111,7 @@ function clipResult( sessionId: observation.sessionId, timestamp: observation.timestamp, type: observation.type, + ...(observation.memoryType !== undefined && { memoryType: observation.memoryType }), title, facts: [], narrative, diff --git a/src/functions/smart-search.ts b/src/functions/smart-search.ts index 19318b0669..78caa6b3d2 100644 --- a/src/functions/smart-search.ts +++ b/src/functions/smart-search.ts @@ -227,14 +227,21 @@ export function registerSmartSearchFunction( .slice(0, limit) : projectResults.slice(0, limit); - const compact: CompactSearchResult[] = filteredHybrid.map((r) => ({ - obsId: r.observation.id, - layer: r.layer ?? getSearchIndex().layerOf(r.observation.id) ?? getSearchResultLayer(r.observation.id, r.sessionId), - sessionId: r.sessionId, - title: r.observation.title, - type: r.observation.type, - score: r.combinedScore, - timestamp: r.observation.timestamp, + const compact: CompactSearchResult[] = await Promise.all(filteredHybrid.map(async (r) => { + const layer = r.layer ?? getSearchIndex().layerOf(r.observation.id) ?? getSearchResultLayer(r.observation.id, r.sessionId); + const memoryType = layer === "memory" + ? (await kv.get(KV.memories, r.observation.id).catch(() => null))?.type ?? r.observation.memoryType + : undefined; + return { + obsId: r.observation.id, + layer, + sessionId: r.sessionId, + title: r.observation.title, + type: r.observation.type, + ...(memoryType !== undefined && { memoryType }), + score: r.combinedScore, + timestamp: r.observation.timestamp, + }; })); void recordAccessBatch( diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts index 0a5a820649..ac56053300 100644 --- a/src/mcp/standalone.ts +++ b/src/mcp/standalone.ts @@ -413,7 +413,7 @@ async function handleLocal( return textResponse(buildRecallResponse(matches, v.format ?? "full", v.tokenBudget), true); } return textResponse({ mode: "compact", results: results.map((memory) => ({ - ...memory, obsId: memory.id, sessionId: memory.sessionIds?.[0] ?? "memory", layer: "memory", + ...memory, type: "decision", memoryType: memory.type, obsId: memory.id, sessionId: memory.sessionIds?.[0] ?? "memory", layer: "memory", })) }, true); } diff --git a/src/state/memory-utils.ts b/src/state/memory-utils.ts index 9bc5b16afa..dd6ceaacfd 100644 --- a/src/state/memory-utils.ts +++ b/src/state/memory-utils.ts @@ -3,9 +3,6 @@ import type { CompressedObservation, Lesson, 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 { @@ -14,6 +11,7 @@ export function memoryToObservation(memory: Memory): CompressedObservation { sessionId: memory.sessionIds?.[0] ?? "memory", timestamp: memory.createdAt, type: "decision", + memoryType: memory.type, title: memory.title, facts: [memory.content], narrative: memory.content, diff --git a/src/types.ts b/src/types.ts index c6d6a37026..eff9b8ca86 100644 --- a/src/types.ts +++ b/src/types.ts @@ -96,6 +96,7 @@ export interface CompressedObservation { sessionId: string; timestamp: string; type: ObservationType; + memoryType?: Memory["type"]; title: string; subtitle?: string; facts: string[]; @@ -346,6 +347,7 @@ export interface CompactSearchResult { sessionId: string; title: string; type: ObservationType; + memoryType?: Memory["type"]; score: number; timestamp: string; layer?: "memory" | "observation" | "lesson" | "insight"; diff --git a/test/mcp-standalone.test.ts b/test/mcp-standalone.test.ts index 7d3edd5a0f..7b34e99f24 100644 --- a/test/mcp-standalone.test.ts +++ b/test/mcp-standalone.test.ts @@ -282,6 +282,17 @@ describe("handleToolCall", () => { expect(parsed.results[0].content).toBe("Use bcrypt for password hashing"); }); + it.each(["pattern", "preference", "architecture", "bug", "workflow", "fact"])("retains %s metadata in fallback compact and expanded search", async (type) => { + const kv = new InMemoryKV(); + await handleToolCall("memory_save", { content: "Synthetic type probe", type, project: "type-project" }, kv); + const compact = JSON.parse((await handleToolCall("memory_smart_search", { query: "Synthetic", project: "type-project" }, kv)).content[0].text); + expect(compact.results[0]).toMatchObject({ type: "decision", memoryType: type }); + const id = compact.results[0].obsId; + const expanded = JSON.parse((await handleToolCall("memory_smart_search", { expandIds: id, project: "type-project" }, kv)).content[0].text); + expect(expanded.results[0].observation).toMatchObject({ id, type: "decision", memoryType: type }); + expect((await kv.get<{ type: string }>("mem:memories", id))?.type).toBe(type); + }); + it("memory_smart_search rejects empty query to prevent match-all in forget flow", async () => { const kv = new InMemoryKV(); await handleToolCall("memory_save", { content: "anything" }, kv); diff --git a/test/memory-type-metadata.test.ts b/test/memory-type-metadata.test.ts new file mode 100644 index 0000000000..da93b3646a --- /dev/null +++ b/test/memory-type-metadata.test.ts @@ -0,0 +1,110 @@ +import { describe, expect, it, vi } from "vitest"; +import { memoryToObservation, lessonToObservation } from "../src/state/memory-utils.js"; +import { registerSmartSearchFunction } from "../src/functions/smart-search.js"; +import { buildRecallResponse } from "../src/functions/recall-response.js"; +import { CompressOutputSchema } from "../src/eval/schemas.js"; +import type { Memory, Lesson, CompressedObservation, HybridSearchResult } from "../src/types.js"; +import type { IIIClient } from "iii-sdk"; +import type { StateKV } from "../src/state/kv.js"; + +vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } })); + +const types: Memory["type"][] = ["pattern", "preference", "architecture", "bug", "workflow", "fact"]; +function memory(type: Memory["type"]): Memory { + return { + id: `mem_${type}`, type, title: "Synthetic type preservation", content: "Synthetic content. ".repeat(200), + createdAt: "2026-10-31T14:44:33.707Z", updatedAt: "2026-10-31T14:44:33.707Z", + concepts: ["synthetic"], files: [], sessionIds: [], strength: 7, version: 1, isLatest: true, + project: "project-a", agentId: "owner", + }; +} + +function fixture(saved: Memory, legacy = false, failMemoryReads = false) { + const store = new Map>([["mem:memories", new Map([[saved.id, saved]])]]); + const kv = { + get: async (scope: string, id: string) => { + if (failMemoryReads && scope === "mem:memories") throw new Error("state read failed"); + return store.get(scope)?.get(id) ?? null; + }, + set: async (scope: string, id: string, value: unknown) => { + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(id, value); + return value; + }, + list: async (scope: string) => [...(store.get(scope)?.values() ?? [])], + }; + let handler: (args: object) => Promise<{ + mode: string; + results: Array<{ obsId: string; observation?: CompressedObservation }>; + truncated?: boolean; + }>; + const sdk = { registerFunction: (_: string, fn: typeof handler) => { handler = fn; } }; + const observation = memoryToObservation(saved); + if (legacy) delete observation.memoryType; + const search = vi.fn(async (): Promise => [{ + observation, sessionId: "memory", layer: "memory", combinedScore: 1, + bm25Score: 1, vectorScore: 0, graphScore: 0, + }]); + registerSmartSearchFunction(sdk as unknown as IIIClient, kv as unknown as StateKV, search); + return { call: (args: object) => handler(args), saved }; +} + +describe("original memory type metadata", () => { + it("keeps compact search working when the stored memory read fails", async () => { + const f = fixture(memory("bug"), false, true); + const compact = await f.call({ query: "Synthetic", agentId: "*", targetLayer: "memory", includeLessons: false }); + expect(compact.results[0]).toMatchObject({ obsId: f.saved.id, type: "decision", memoryType: "bug" }); + }); + + it.each(types)("preserves %s without changing the observation type or input", (type) => { + const saved = memory(type); + const before = structuredClone(saved); + const result = memoryToObservation(Object.freeze(saved)); + expect(result).toMatchObject({ id: saved.id, type: "decision", memoryType: type, narrative: saved.content, agentId: "owner" }); + expect(saved).toEqual(before); + expect(CompressOutputSchema.safeParse(result).success).toBe(true); + expect(CompressOutputSchema.safeParse({ ...result, type }).success).toBe(false); + }); + + it.each(types)("preserves %s in compact and expanded search, including a legacy index", async (type) => { + const f = fixture(memory(type), true); + const scope = { project: "project-a", agentId: "*", targetLayer: "memory", includeLessons: false }; + const compact = await f.call({ query: "Synthetic", ...scope }); + expect(compact.results[0]).toMatchObject({ obsId: f.saved.id, type: "decision", memoryType: type }); + const expanded = await f.call({ expandIds: [f.saved.id], ...scope }); + expect(expanded.results[0].observation).toMatchObject({ type: "decision", memoryType: type, narrative: f.saved.content }); + expect(expanded.truncated).toBe(false); + expect((await f.call({ query: "Synthetic", ...scope, project: "project-b" })).results).toEqual([]); + expect((await f.call({ expandIds: [f.saved.id], ...scope, project: "project-b" })).results).toEqual([]); + expect((await f.call({ query: "Synthetic", ...scope, agentId: "other" })).results).toEqual([]); + expect((await f.call({ expandIds: [f.saved.id], ...scope, agentId: "other" })).results).toEqual([]); + expect((await f.call({ query: "Synthetic", ...scope, targetLayer: "observation" })).results).toEqual([]); + }); + + it.each(["full", "compact", "narrative"] as const)("retains memoryType in %s recall with and without clipping", (format) => { + const observation = memoryToObservation(memory("fact")); + observation.title = "Synthetic memory title ".repeat(100); + const result = { observation, sessionId: "memory", layer: "memory" as const, score: 1 }; + for (const budget of [undefined, 250]) { + const response = buildRecallResponse([result], format, budget); + const first = response.results[0]; + expect(first).toBeDefined(); + const metadata = "observation" in first ? first.observation : first; + expect(metadata).toHaveProperty("memoryType", "fact"); + if (budget) { + expect(first).toHaveProperty("content_truncated", true); + expect(response.tokens_used).toBeLessThanOrEqual(budget); + } + } + }); + + it("does not assign a memory type to lessons or ordinary observations", () => { + const lesson = { id: "lsn_test", content: "Lesson", context: "", tags: [], confidence: 7, createdAt: "2026-10-31" } as Lesson; + expect(lessonToObservation(lesson)).not.toHaveProperty("memoryType"); + const observation: CompressedObservation = { ...memoryToObservation(memory("fact")), id: "obs_test", type: "file_read" }; + delete observation.memoryType; + const result = buildRecallResponse([{ observation, sessionId: "session", layer: "observation", score: 1 }], "compact"); + expect(result.results[0]).toHaveProperty("type", "file_read"); + expect(result.results[0]).not.toHaveProperty("memoryType"); + }); +});