#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(visibility): surface lessons in smart-search + tally per-store in diagnose (#473)
efenexcb2e0131dc14
diff --git a/src/functions/diagnostics.ts b/src/functions/diagnostics.tsindex 42f822cb..a63d7959 100644--- a/src/functions/diagnostics.ts+++ b/src/functions/diagnostics.ts@@ -7,8 +7,14 @@ import type {Action,ActionEdge,DiagnosticCheck,+ Insight,Lease,+ Lesson,Checkpoint,+ Crystal,+ ProceduralMemory,+ SemanticMemory,+ SessionSummary,Signal,Sentinel,Sketch,@@ -25,6 +31,12 @@ const ALL_CATEGORIES = ["signals","sessions","memories",+ "lessons",+ "summaries",+ "semantic",+ "procedural",+ "crystals",+ "insights","mesh",];@@ -354,6 +366,186 @@ export function registerDiagnosticsFunction(sdk: ISdk, kv: StateKV): void {}}+ if (categories.includes("lessons")) {+ // Counts only live lessons (deleted=true rows are tombstoned).+ // Catches bad confidence values that would silently break recall+ // scoring (memory_lesson_recall multiplies by confidence).+ const lessons = await kv.list<Lesson>(KV.lessons);+ const live = lessons.filter((l) => !l.deleted);+ let lessonIssues = 0;+ for (const l of live) {+ // Number.isFinite rejects NaN / Infinity / non-numbers; a+ // corrupted row passing those would silently survive the < / >+ // range check (e.g. NaN < 0 is false, NaN > 1 is false, so the+ // bad row would be "healthy") and skew memory_lesson_recall's+ // scoring downstream. Surface as warning.+ if (+ !Number.isFinite(l.confidence) ||+ l.confidence < 0 ||+ l.confidence > 1+ ) {+ checks.push({+ name: `lesson-bad-confidence:${l.id}`,+ category: "lessons",+ status: "warn",+ message: `Lesson ${l.id} has confidence ${l.confidence} (expected finite number in 0..1)`,+ fixable: false,+ });+ lessonIssues++;+ }+ }+ if (lessonIssues === 0) {+ checks.push({+ name: "lessons-ok",+ category: "lessons",+ status: "pass",+ message: `All ${live.length} lessons are healthy (${lessons.length - live.length} tombstoned)`,+ fixable: false,+ });+ }+ }++ if (categories.includes("summaries")) {+ const summaries = await kv.list<SessionSummary>(KV.summaries);+ let summaryIssues = 0;+ for (const s of summaries) {+ // typeof guard before .trim() — a corrupted row with title=null+ // or title=42 would otherwise throw and abort the whole diagnose+ // run before later categories get checked.+ if (typeof s.title !== "string" || s.title.trim().length === 0) {+ checks.push({+ name: `summary-missing-title:${s.sessionId}`,+ category: "summaries",+ status: "warn",+ message: `Summary for session ${s.sessionId} has no title`,+ fixable: false,+ });+ summaryIssues++;+ }+ }+ if (summaryIssues === 0) {+ checks.push({+ name: "summaries-ok",+ category: "summaries",+ status: "pass",+ message: `All ${summaries.length} session summaries are consistent`,+ fixable: false,+ });+ }+ }++ if (categories.includes("semantic")) {+ const semantic = await kv.list<SemanticMemory>(KV.semantic);+ let semanticIssues = 0;+ for (const s of semantic) {+ if (+ !Number.isFinite(s.confidence) ||+ s.confidence < 0 ||+ s.confidence > 1+ ) {+ checks.push({+ name: `semantic-bad-confidence:${s.id}`,+ category: "semantic",+ status: "warn",+ message: `Semantic fact ${s.id} has confidence ${s.confidence} (expected finite number in 0..1)`,+ fixable: false,+ });+ semanticIssues++;+ }+ }+ if (semanticIssues === 0) {+ checks.push({+ name: "semantic-ok",+ category: "semantic",+ status: "pass",+ message: `All ${semantic.length} semantic memories are consistent`,+ fixable: false,+ });+ }+ }++ if (categories.includes("procedural")) {+ const procedural = await kv.list<ProceduralMemory>(KV.procedural);+ let proceduralIssues = 0;+ for (const p of procedural) {+ if (!Array.isArray(p.steps) || p.steps.length === 0) {+ checks.push({+ name: `procedural-empty-steps:${p.id}`,+ category: "procedural",+ status: "warn",+ message: `Procedural memory "${p.name}" (${p.id}) has no steps`,+ fixable: false,+ });+ proceduralIssues++;+ }+ }+ if (proceduralIssues === 0) {+ checks.push({+ name: "procedural-ok",+ category: "procedural",+ status: "pass",+ message: `All ${procedural.length} procedural memories are consistent`,+ fixable: false,+ });+ }+ }++ if (categories.includes("crystals")) {+ const crystals = await kv.list<Crystal>(KV.crystals);+ let crystalIssues = 0;+ for (const c of crystals) {+ if (typeof c.narrative !== "string" || c.narrative.trim().length === 0) {+ checks.push({+ name: `crystal-empty-narrative:${c.id}`,+ category: "crystals",+ status: "warn",+ message: `Crystal ${c.id} has empty narrative`,+ fixable: false,+ });+ crystalIssues++;+ }+ }+ if (crystalIssues === 0) {+ checks.push({+ name: "crystals-ok",+ category: "crystals",+ status: "pass",+ message: `All ${crystals.length} crystals are consistent`,+ fixable: false,+ });+ }+ }++ if (categories.includes("insights")) {+ const insights = await kv.list<Insight>(KV.insights);+ let insightIssues = 0;+ for (const i of insights) {+ if (+ !Number.isFinite(i.confidence) ||+ i.confidence < 0 ||+ i.confidence > 1+ ) {+ checks.push({+ name: `insight-bad-confidence:${i.id}`,+ category: "insights",+ status: "warn",+ message: `Insight ${i.id} has confidence ${i.confidence} (expected finite number in 0..1)`,+ fixable: false,+ });+ insightIssues++;+ }+ }+ if (insightIssues === 0) {+ checks.push({+ name: "insights-ok",+ category: "insights",+ status: "pass",+ message: `All ${insights.length} insights are consistent`,+ fixable: false,+ });+ }+ }+if (categories.includes("mesh")) {const peers = await kv.list<MeshPeer>(KV.mesh);let meshIssues = 0;diff --git a/src/functions/smart-search.ts b/src/functions/smart-search.tsindex fdeed273..c80b1f87 100644--- a/src/functions/smart-search.ts+++ b/src/functions/smart-search.ts@@ -1,24 +1,32 @@import type { ISdk } from "iii-sdk";import type {+ CompactLessonResult,CompactSearchResult,CompressedObservation,HybridSearchResult,+ Lesson,} from "../types.js";import { KV } from "../state/schema.js";import { StateKV } from "../state/kv.js";import { recordAccessBatch } from "./access-tracker.js";import { logger } from "../logger.js";+// Compact mode trims each lesson's content for at-a-glance display. The+// full content is fetched via memory_lesson_recall when the caller needs it.+const LESSON_CONTENT_PREVIEW_CHARS = 240;+export function registerSmartSearchFunction(sdk: ISdk,kv: StateKV,searchFn: (query: string, limit: number) => Promise<HybridSearchResult[]>,): void {- sdk.registerFunction("mem::smart-search",+ sdk.registerFunction("mem::smart-search",async (data: {query?: string;expandIds?: Array<string | { obsId: string; sessionId: string }>;limit?: number;+ project?: string;+ includeLessons?: boolean;}) => {if (data.expandIds && data.expandIds.length > 0) {@@ -68,7 +76,21 @@ export function registerSmartSearchFunction(}const limit = Math.max(1, Math.min(data.limit ?? 20, 100));- const hybridResults = await searchFn(data.query, limit);+ // Cap lesson results at a smaller number than observations: lessons+ // are denser (curated insights) so 10 is usually plenty for a recall.+ const lessonLimit = Math.min(limit, 10);+ const includeLessons = data.includeLessons !== false;++ // Run observation hybrid-search and lesson recall in parallel so the+ // extra lesson lookup adds no wallclock when the underlying calls+ // can overlap. Lesson recall is best-effort: if mem::lesson-recall+ // fails or returns unexpected shape, log + fall back to empty.+ const [hybridResults, lessons] = await Promise.all([+ searchFn(data.query, limit),+ includeLessons+ ? recallLessons(sdk, data.query, lessonLimit, data.project)+ : Promise.resolve([]),+ ]);const compact: CompactSearchResult[] = hybridResults.map((r) => ({obsId: r.observation.id,@@ -87,12 +109,51 @@ export function registerSmartSearchFunction(logger.info("Smart search compact", {query: data.query,results: compact.length,+ lessons: lessons.length,});- return { mode: "compact", results: compact };+ const response: {+ mode: "compact";+ results: CompactSearchResult[];+ lessons?: CompactLessonResult[];+ } = { mode: "compact", results: compact };+ if (includeLessons) response.lessons = lessons;+ return response;},);}+async function recallLessons(+ sdk: ISdk,+ query: string,+ limit: number,+ project?: string,+): Promise<CompactLessonResult[]> {+ try {+ const result = (await sdk.trigger({+ function_id: "mem::lesson-recall",+ payload: { query, limit, project },+ })) as { success?: boolean; lessons?: Array<Lesson & { score?: number }> };+ if (!result?.success || !Array.isArray(result.lessons)) return [];+ return result.lessons.map((l) => ({+ lessonId: l.id,+ content:+ l.content.length > LESSON_CONTENT_PREVIEW_CHARS+ ? l.content.slice(0, LESSON_CONTENT_PREVIEW_CHARS) + "…"+ : l.content,+ confidence: l.confidence,+ score: l.score ?? l.confidence,+ createdAt: l.createdAt,+ project: l.project,+ tags: l.tags ?? [],+ }));+ } catch (err) {+ logger.warn("Smart search: mem::lesson-recall failed; returning empty lesson list", {+ error: err instanceof Error ? err.message : String(err),+ });+ return [];+ }+}+async function findObservation(kv: StateKV,obsId: string,diff --git a/src/types.ts b/src/types.tsindex bc38a058..87e274d1 100644--- a/src/types.ts+++ b/src/types.ts@@ -266,6 +266,16 @@ export interface CompactSearchResult {timestamp: string;}+export interface CompactLessonResult {+ lessonId: string;+ content: string;+ confidence: number;+ score: number;+ createdAt: string;+ project?: string;+ tags: string[];+}+export interface TimelineEntry {observation: CompressedObservation;sessionId: string;diff --git a/test/diagnostics.test.ts b/test/diagnostics.test.tsindex d2dc706e..053e1c40 100644--- a/test/diagnostics.test.ts+++ b/test/diagnostics.test.ts@@ -195,7 +195,10 @@ describe("Diagnostics Functions", () => {};expect(result.success).toBe(true);- expect(result.summary.pass).toBe(8);+ // 14 = 8 original (actions, leases, sentinels, sketches, signals,+ // sessions, memories, mesh) + 6 added in #lesson-visibility+ // (lessons, summaries, semantic, procedural, crystals, insights).+ expect(result.summary.pass).toBe(14);expect(result.summary.warn).toBe(0);expect(result.summary.fail).toBe(0);expect(result.summary.fixable).toBe(0);@@ -636,4 +639,229 @@ describe("Diagnostics Functions", () => {expect(unchanged!.status).toBe("blocked");});});++ describe("per-store tally categories (#lesson-visibility)", () => {+ it("lessons category: passes with valid live lessons + ignores tombstoned", async () => {+ await kv.set(KV.lessons, "lsn_live", {+ id: "lsn_live", content: "x", context: "", confidence: 0.8,+ reinforcements: 0, source: "manual", sourceIds: [], tags: [],+ createdAt: "", updatedAt: "", decayRate: 0.05,+ });+ await kv.set(KV.lessons, "lsn_tomb", {+ id: "lsn_tomb", content: "x", context: "", confidence: 0.5,+ reinforcements: 0, source: "manual", sourceIds: [], tags: [],+ createdAt: "", updatedAt: "", decayRate: 0.05, deleted: true,+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["lessons"],+ })) as { checks: DiagnosticCheck[] };++ const ok = result.checks.find((c) => c.name === "lessons-ok");+ expect(ok?.status).toBe("pass");+ expect(ok?.message).toMatch(/All 1 lessons.*1 tombstoned/);+ });++ it("lessons category: warns on out-of-range confidence", async () => {+ await kv.set(KV.lessons, "lsn_bad", {+ id: "lsn_bad", content: "x", context: "", confidence: 1.5,+ reinforcements: 0, source: "manual", sourceIds: [], tags: [],+ createdAt: "", updatedAt: "", decayRate: 0.05,+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["lessons"],+ })) as { checks: DiagnosticCheck[] };++ const warn = result.checks.find((c) => c.name.startsWith("lesson-bad-confidence:"));+ expect(warn?.status).toBe("warn");+ });++ it("summaries category: warns on missing title", async () => {+ await kv.set(KV.summaries, "ses_1", {+ sessionId: "ses_1", project: "p", createdAt: "", title: "",+ narrative: "n", keyDecisions: [], filesModified: [], concepts: [],+ observationCount: 1,+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["summaries"],+ })) as { checks: DiagnosticCheck[] };++ const warn = result.checks.find((c) => c.name.startsWith("summary-missing-title:"));+ expect(warn?.status).toBe("warn");+ });++ it("procedural category: warns on empty steps", async () => {+ await kv.set(KV.procedural, "proc_1", {+ id: "proc_1", name: "noop", steps: [], triggerCondition: "x",+ frequency: 1, sourceSessionIds: [], strength: 0.5,+ createdAt: "", updatedAt: "",+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["procedural"],+ })) as { checks: DiagnosticCheck[] };++ const warn = result.checks.find((c) => c.name.startsWith("procedural-empty-steps:"));+ expect(warn?.status).toBe("warn");+ });++ it("crystals category: warns on empty narrative", async () => {+ await kv.set(KV.crystals, "cry_1", {+ id: "cry_1", narrative: "", keyOutcomes: [], filesAffected: [],+ lessons: [], sourceActionIds: [], createdAt: "",+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["crystals"],+ })) as { checks: DiagnosticCheck[] };++ const warn = result.checks.find((c) => c.name.startsWith("crystal-empty-narrative:"));+ expect(warn?.status).toBe("warn");+ });++ it("insights category: warns on out-of-range confidence", async () => {+ await kv.set(KV.insights, "ins_bad", {+ id: "ins_bad", title: "t", content: "c", confidence: -0.1,+ reinforcements: 0, sourceConceptCluster: [], sourceMemoryIds: [],+ sourceLessonIds: [], sourceCrystalIds: [], tags: [],+ createdAt: "", updatedAt: "", decayRate: 0.05,+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["insights"],+ })) as { checks: DiagnosticCheck[] };++ const warn = result.checks.find((c) => c.name.startsWith("insight-bad-confidence:"));+ expect(warn?.status).toBe("warn");+ });++ it("semantic category: warns on out-of-range confidence", async () => {+ await kv.set(KV.semantic, "sem_bad", {+ id: "sem_bad", fact: "f", confidence: 2.0, sourceSessionIds: [],+ sourceMemoryIds: [], accessCount: 0, lastAccessedAt: "",+ strength: 0, createdAt: "", updatedAt: "",+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["semantic"],+ })) as { checks: DiagnosticCheck[] };++ const warn = result.checks.find((c) => c.name.startsWith("semantic-bad-confidence:"));+ expect(warn?.status).toBe("warn");+ });++ it("categories filter accepts new categories and skips others", async () => {+ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["lessons", "summaries"],+ })) as { checks: DiagnosticCheck[] };++ expect(result.checks.every((c) => c.category === "lessons" || c.category === "summaries")).toBe(true);+ expect(result.checks.some((c) => c.category === "lessons")).toBe(true);+ expect(result.checks.some((c) => c.category === "summaries")).toBe(true);+ });++ describe("defensive row-shape handling (CodeRabbit #473 review)", () => {+ it("NaN/Infinity confidence on a lesson is flagged as warn, not silently passed", async () => {+ await kv.set(KV.lessons, "lsn_nan", {+ id: "lsn_nan", content: "x", context: "", confidence: NaN,+ reinforcements: 0, source: "manual", sourceIds: [], tags: [],+ createdAt: "", updatedAt: "", decayRate: 0.05,+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["lessons"],+ })) as { checks: DiagnosticCheck[] };++ const warn = result.checks.find((c) => c.name.startsWith("lesson-bad-confidence:"));+ expect(warn?.status).toBe("warn");+ });++ it("non-string summary title doesn't throw — surfaces as warn", async () => {+ await kv.set(KV.summaries, "ses_bad_title", {+ sessionId: "ses_bad_title",+ project: "p",+ createdAt: "",+ title: null as unknown as string, // simulate corrupted row+ narrative: "n",+ keyDecisions: [],+ filesModified: [],+ concepts: [],+ observationCount: 1,+ });++ // The bug to guard against: the old code called .trim() unconditionally,+ // which throws on null/number, which aborts the whole diagnose run and+ // any later category check never executes. Verify diagnose completes+ // AND surfaces the bad row.+ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["summaries", "lessons"],+ })) as { checks: DiagnosticCheck[]; success?: boolean };++ expect(result.success).toBe(true);+ const warn = result.checks.find((c) => c.name.startsWith("summary-missing-title:"));+ expect(warn?.status).toBe("warn");+ // Later category still ran:+ expect(result.checks.some((c) => c.category === "lessons")).toBe(true);+ });++ it("non-string crystal narrative doesn't throw — surfaces as warn", async () => {+ await kv.set(KV.crystals, "cry_bad", {+ id: "cry_bad",+ narrative: undefined as unknown as string,+ keyOutcomes: [],+ filesAffected: [],+ lessons: [],+ sourceActionIds: [],+ createdAt: "",+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["crystals"],+ })) as { checks: DiagnosticCheck[]; success?: boolean };++ expect(result.success).toBe(true);+ const warn = result.checks.find((c) => c.name.startsWith("crystal-empty-narrative:"));+ expect(warn?.status).toBe("warn");+ });++ it("Infinity confidence on insight + semantic both flagged", async () => {+ await kv.set(KV.insights, "ins_inf", {+ id: "ins_inf",+ title: "t",+ content: "c",+ confidence: Infinity,+ reinforcements: 0,+ sourceConceptCluster: [],+ sourceMemoryIds: [],+ sourceLessonIds: [],+ sourceCrystalIds: [],+ tags: [],+ createdAt: "",+ updatedAt: "",+ decayRate: 0.05,+ });+ await kv.set(KV.semantic, "sem_nan", {+ id: "sem_nan",+ fact: "f",+ confidence: NaN,+ sourceSessionIds: [],+ sourceMemoryIds: [],+ accessCount: 0,+ lastAccessedAt: "",+ strength: 0,+ createdAt: "",+ updatedAt: "",+ });++ const result = (await sdk.trigger("mem::diagnose", {+ categories: ["insights", "semantic"],+ })) as { checks: DiagnosticCheck[] };++ expect(result.checks.find((c) => c.name === "insight-bad-confidence:ins_inf")?.status).toBe("warn");+ expect(result.checks.find((c) => c.name === "semantic-bad-confidence:sem_nan")?.status).toBe("warn");+ });+ });+ });});diff --git a/test/smart-search.test.ts b/test/smart-search.test.tsindex 4f22d1a9..9d0c94e0 100644--- a/test/smart-search.test.ts+++ b/test/smart-search.test.ts@@ -193,4 +193,102 @@ describe("Smart Search Function", () => {} | null;expect(log?.count).toBe(1);});++ describe("lesson inclusion (#lesson-visibility)", () => {+ it("compact mode returns lessons array alongside observation results", async () => {+ sdk.registerFunction("mem::lesson-recall", async (payload: any) => ({+ success: true,+ lessons: [+ { id: "lsn_a", content: "always rebase before push", confidence: 0.9, createdAt: "2026-04-01T00:00:00Z", project: "p", tags: ["git"], score: 0.81 },+ { id: "lsn_b", content: "never force-push to main", confidence: 0.95, createdAt: "2026-04-02T00:00:00Z", project: "p", tags: ["git"], score: 0.76 },+ ],+ }));++ const result = (await sdk.trigger("mem::smart-search", {+ query: "rebase",+ })) as { mode: string; results: CompactSearchResult[]; lessons?: any[] };++ expect(result.mode).toBe("compact");+ expect(result.results.length).toBe(2); // observations unchanged+ expect(result.lessons).toBeDefined();+ expect(result.lessons!.length).toBe(2);+ expect(result.lessons![0]).toMatchObject({+ lessonId: "lsn_a",+ confidence: 0.9,+ score: 0.81,+ });+ expect(result.lessons![0].tags).toEqual(["git"]);+ });++ it("compact mode truncates long lesson content for preview", async () => {+ const long = "x".repeat(500);+ sdk.registerFunction("mem::lesson-recall", async () => ({+ success: true,+ lessons: [{ id: "lsn_long", content: long, confidence: 0.5, createdAt: "", tags: [], score: 0.4 }],+ }));++ const result = (await sdk.trigger("mem::smart-search", {+ query: "x",+ })) as { lessons: any[] };++ expect(result.lessons[0].content.length).toBeLessThan(long.length);+ expect(result.lessons[0].content).toMatch(/…$/);+ });++ it("includeLessons:false omits the lessons array entirely", async () => {+ // No lesson-recall handler registered — would throw if invoked.+ const result = (await sdk.trigger("mem::smart-search", {+ query: "auth",+ includeLessons: false,+ })) as { mode: string; results: CompactSearchResult[]; lessons?: unknown };++ expect(result.results.length).toBe(2);+ expect(result.lessons).toBeUndefined();+ });++ it("forwards project filter to mem::lesson-recall", async () => {+ let receivedPayload: any = null;+ sdk.registerFunction("mem::lesson-recall", async (payload: any) => {+ receivedPayload = payload;+ return { success: true, lessons: [] };+ });++ await sdk.trigger("mem::smart-search", {+ query: "rebase",+ project: "gitops-assistant",+ });++ expect(receivedPayload).toMatchObject({+ query: "rebase",+ project: "gitops-assistant",+ });+ });++ it("tolerates mem::lesson-recall failure: returns empty lessons, observations unchanged", async () => {+ sdk.registerFunction("mem::lesson-recall", async () => {+ throw new Error("lessons store unavailable");+ });++ const result = (await sdk.trigger("mem::smart-search", {+ query: "auth",+ })) as { results: CompactSearchResult[]; lessons: any[] };++ expect(result.results.length).toBe(2);+ expect(result.lessons).toEqual([]);+ });++ it("tolerates non-success lesson-recall response shape", async () => {+ sdk.registerFunction("mem::lesson-recall", async () => ({+ success: false,+ error: "query is required",+ }));++ const result = (await sdk.trigger("mem::smart-search", {+ query: "auth",+ })) as { results: CompactSearchResult[]; lessons: any[] };++ expect(result.results.length).toBe(2);+ expect(result.lessons).toEqual([]);+ });+ });});