Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/recall.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/functions/recall-response.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }),
Expand All @@ -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,
Expand All @@ -96,6 +98,7 @@ function clipResult(
sessionId: result.sessionId,
title,
narrative,
...(observation.memoryType !== undefined && { memoryType: observation.memoryType }),
score: result.score,
timestamp: observation.timestamp,
...layer,
Expand All @@ -108,6 +111,7 @@ function clipResult(
sessionId: observation.sessionId,
timestamp: observation.timestamp,
type: observation.type,
...(observation.memoryType !== undefined && { memoryType: observation.memoryType }),
title,
facts: [],
narrative,
Expand Down
23 changes: 15 additions & 8 deletions src/functions/smart-search.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Memory>(KV.memories, r.observation.id).catch(() => null))?.type ?? r.observation.memoryType
: undefined;
Comment thread
rohitg00 marked this conversation as resolved.
Resolved
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(
Expand Down
2 changes: 1 addition & 1 deletion src/mcp/standalone.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}

Expand Down
4 changes: 1 addition & 3 deletions src/state/memory-utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ export interface CompressedObservation {
sessionId: string;
timestamp: string;
type: ObservationType;
memoryType?: Memory["type"];
title: string;
subtitle?: string;
facts: string[];
Expand Down Expand Up @@ -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";
Expand Down
11 changes: 11 additions & 0 deletions test/mcp-standalone.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
110 changes: 110 additions & 0 deletions test/memory-type-metadata.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, Map<string, unknown>>([["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<HybridSearchResult[]> => [{
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");
});
});