#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix: CrystallizableAction type, npm package size, add lesson + obsidian tests
Rohit Ghumare45eb99d656f4
diff --git a/package.json b/package.jsonindex fe87f57f..c9ca3780 100644--- a/package.json+++ b/package.json@@ -30,6 +30,15 @@"context","observation"],+ "files": [+ "dist/",+ "plugin/",+ "iii-config.yaml",+ "docker-compose.yml",+ "LICENSE",+ "README.md",+ "AGENTS.md"+ ],"author": "Rohit Ghumare <[email protected]>","license": "Apache-2.0","repository": {diff --git a/src/functions/crystallize.ts b/src/functions/crystallize.tsindex 2ec6ce3f..e44e2662 100644--- a/src/functions/crystallize.ts+++ b/src/functions/crystallize.ts@@ -154,7 +154,7 @@ export function registerCrystallizeFunction(const dryRun = data.dryRun ?? false;const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;- let allActions = await kv.list<CrystallizableAction>(KV.actions);+ let allActions = await kv.list<Action>(KV.actions);allActions = allActions.filter((a) =>diff --git a/test/lessons.test.ts b/test/lessons.test.tsnew file mode 100644index 00000000..9cf673b4--- /dev/null+++ b/test/lessons.test.ts@@ -0,0 +1,351 @@+import { describe, it, expect, beforeEach, vi } from "vitest";++vi.mock("iii-sdk", () => ({+ getContext: () => ({+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },+ }),+}));++import { registerLessonsFunctions } from "../src/functions/lessons.js";+import type { Lesson } from "../src/types.js";++function mockKV() {+ const store = new Map<string, Map<string, unknown>>();+ return {+ get: async <T>(scope: string, key: string): Promise<T | null> => {+ return (store.get(scope)?.get(key) as T) ?? null;+ },+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, data);+ return data;+ },+ delete: async (scope: string, key: string): Promise<void> => {+ store.get(scope)?.delete(key);+ },+ list: async <T>(scope: string): Promise<T[]> => {+ const entries = store.get(scope);+ return entries ? (Array.from(entries.values()) as T[]) : [];+ },+ };+}++function mockSdk() {+ const functions = new Map<string, Function>();+ return {+ registerFunction: (opts: { id: string }, handler: Function) => {+ functions.set(opts.id, handler);+ },+ registerTrigger: () => {},+ trigger: async (id: string, data: unknown) => {+ const fn = functions.get(id);+ if (!fn) throw new Error(`No function: ${id}`);+ return fn(data);+ },+ };+}++describe("Lessons", () => {+ let sdk: ReturnType<typeof mockSdk>;+ let kv: ReturnType<typeof mockKV>;++ beforeEach(() => {+ sdk = mockSdk();+ kv = mockKV();+ registerLessonsFunctions(sdk as never, kv as never);+ });++ describe("mem::lesson-save", () => {+ it("creates a lesson with default confidence 0.5", async () => {+ const result = (await sdk.trigger("mem::lesson-save", {+ content: "Always use execFile instead of exec",+ context: "Security best practice",+ project: "/test",+ tags: ["security"],+ })) as { success: boolean; action: string; lesson: Lesson };++ expect(result.success).toBe(true);+ expect(result.action).toBe("created");+ expect(result.lesson.confidence).toBe(0.5);+ expect(result.lesson.content).toBe("Always use execFile instead of exec");+ expect(result.lesson.source).toBe("manual");+ expect(result.lesson.reinforcements).toBe(0);+ });++ it("accepts custom confidence", async () => {+ const result = (await sdk.trigger("mem::lesson-save", {+ content: "Test lesson",+ confidence: 0.8,+ })) as { lesson: Lesson };++ expect(result.lesson.confidence).toBe(0.8);+ });++ it("clamps invalid confidence to default", async () => {+ const result = (await sdk.trigger("mem::lesson-save", {+ content: "Bad confidence",+ confidence: 5.0,+ })) as { lesson: Lesson };++ expect(result.lesson.confidence).toBe(0.5);+ });++ it("strengthens existing lesson on duplicate content", async () => {+ const first = (await sdk.trigger("mem::lesson-save", {+ content: "Duplicate lesson",+ })) as { action: string; lesson: Lesson };++ expect(first.action).toBe("created");+ const originalId = first.lesson.id;++ const second = (await sdk.trigger("mem::lesson-save", {+ content: "Duplicate lesson",+ })) as { action: string; lesson: Lesson };++ expect(second.action).toBe("strengthened");+ expect(second.lesson.id).toBe(originalId);+ expect(second.lesson.reinforcements).toBe(1);+ expect(second.lesson.confidence).toBeGreaterThan(0.5);+ });++ it("rejects empty content", async () => {+ const result = (await sdk.trigger("mem::lesson-save", {+ content: "",+ })) as { success: boolean };++ expect(result.success).toBe(false);+ });++ it("sets crystal source and sourceIds when provided", async () => {+ const result = (await sdk.trigger("mem::lesson-save", {+ content: "Crystal-derived lesson",+ source: "crystal",+ sourceIds: ["crys_123"],+ confidence: 0.6,+ })) as { lesson: Lesson };++ expect(result.lesson.source).toBe("crystal");+ expect(result.lesson.sourceIds).toEqual(["crys_123"]);+ expect(result.lesson.confidence).toBe(0.6);+ });+ });++ describe("mem::lesson-recall", () => {+ beforeEach(async () => {+ await sdk.trigger("mem::lesson-save", {+ content: "Database indexing improves query performance",+ project: "/app",+ tags: ["database"],+ confidence: 0.9,+ });+ await sdk.trigger("mem::lesson-save", {+ content: "Always validate user input at boundaries",+ project: "/app",+ tags: ["security"],+ confidence: 0.3,+ });+ await sdk.trigger("mem::lesson-save", {+ content: "Use TypeScript strict mode for type safety",+ project: "/other",+ tags: ["typescript"],+ });+ });++ it("finds lessons matching query", async () => {+ const result = (await sdk.trigger("mem::lesson-recall", {+ query: "database performance",+ })) as { success: boolean; lessons: Array<Lesson & { score: number }> };++ expect(result.success).toBe(true);+ expect(result.lessons.length).toBeGreaterThan(0);+ expect(result.lessons[0].content).toContain("Database indexing");+ });++ it("filters by project", async () => {+ const result = (await sdk.trigger("mem::lesson-recall", {+ query: "type safety typescript",+ project: "/other",+ })) as { lessons: Lesson[] };++ expect(result.lessons.length).toBe(1);+ expect(result.lessons[0].project).toBe("/other");+ });++ it("filters by minConfidence", async () => {+ const result = (await sdk.trigger("mem::lesson-recall", {+ query: "validate input",+ minConfidence: 0.5,+ })) as { lessons: Lesson[] };++ expect(result.lessons.length).toBe(0);+ });++ it("returns empty for no matches", async () => {+ const result = (await sdk.trigger("mem::lesson-recall", {+ query: "xyznonexistent",+ })) as { lessons: Lesson[] };++ expect(result.lessons.length).toBe(0);+ });++ it("rejects empty query", async () => {+ const result = (await sdk.trigger("mem::lesson-recall", {+ query: "",+ })) as { success: boolean };++ expect(result.success).toBe(false);+ });+ });++ describe("mem::lesson-list", () => {+ beforeEach(async () => {+ await sdk.trigger("mem::lesson-save", { content: "Lesson A", confidence: 0.9, project: "/app" });+ await sdk.trigger("mem::lesson-save", { content: "Lesson B", confidence: 0.3, project: "/app" });+ await sdk.trigger("mem::lesson-save", { content: "Lesson C", confidence: 0.7, source: "crystal" });+ });++ it("lists all lessons sorted by confidence", async () => {+ const result = (await sdk.trigger("mem::lesson-list", {})) as { lessons: Lesson[] };++ expect(result.lessons.length).toBe(3);+ expect(result.lessons[0].confidence).toBe(0.9);+ expect(result.lessons[2].confidence).toBe(0.3);+ });++ it("filters by project", async () => {+ const result = (await sdk.trigger("mem::lesson-list", { project: "/app" })) as { lessons: Lesson[] };+ expect(result.lessons.length).toBe(2);+ });++ it("filters by source", async () => {+ const result = (await sdk.trigger("mem::lesson-list", { source: "crystal" })) as { lessons: Lesson[] };+ expect(result.lessons.length).toBe(1);+ });++ it("filters by minConfidence", async () => {+ const result = (await sdk.trigger("mem::lesson-list", { minConfidence: 0.5 })) as { lessons: Lesson[] };+ expect(result.lessons.length).toBe(2);+ });++ it("respects limit", async () => {+ const result = (await sdk.trigger("mem::lesson-list", { limit: 1 })) as { lessons: Lesson[] };+ expect(result.lessons.length).toBe(1);+ });+ });++ describe("mem::lesson-strengthen", () => {+ it("increases confidence with diminishing returns", async () => {+ const saved = (await sdk.trigger("mem::lesson-save", {+ content: "Strengthen me",+ confidence: 0.5,+ })) as { lesson: Lesson };++ const result = (await sdk.trigger("mem::lesson-strengthen", {+ lessonId: saved.lesson.id,+ })) as { success: boolean; lesson: Lesson };++ expect(result.success).toBe(true);+ expect(result.lesson.reinforcements).toBe(1);+ expect(result.lesson.confidence).toBeCloseTo(0.55, 1);+ expect(result.lesson.lastReinforcedAt).toBeDefined();+ });++ it("caps confidence at 1.0", async () => {+ const saved = (await sdk.trigger("mem::lesson-save", {+ content: "High confidence",+ confidence: 0.95,+ })) as { lesson: Lesson };++ const result = (await sdk.trigger("mem::lesson-strengthen", {+ lessonId: saved.lesson.id,+ })) as { lesson: Lesson };++ expect(result.lesson.confidence).toBeLessThanOrEqual(1.0);+ });++ it("fails for missing lessonId", async () => {+ const result = (await sdk.trigger("mem::lesson-strengthen", {+ lessonId: "nonexistent",+ })) as { success: boolean };++ expect(result.success).toBe(false);+ });+ });++ describe("mem::lesson-decay-sweep", () => {+ it("decays old lessons incrementally", async () => {+ const saved = (await sdk.trigger("mem::lesson-save", {+ content: "Old lesson",+ confidence: 0.8,+ })) as { lesson: Lesson };++ const lessons = await kv.list<Lesson>("mem:lessons");+ const lesson = lessons[0];+ lesson.createdAt = new Date(Date.now() - 14 * 24 * 60 * 60 * 1000).toISOString();+ await kv.set("mem:lessons", lesson.id, lesson);++ const result = (await sdk.trigger("mem::lesson-decay-sweep", {})) as {+ decayed: number;+ softDeleted: number;+ };++ expect(result.decayed).toBe(1);++ const after = await kv.get<Lesson>("mem:lessons", lesson.id);+ expect(after!.confidence).toBeLessThan(0.8);+ expect(after!.lastDecayedAt).toBeDefined();+ });++ it("does not decay lessons less than 1 week old", async () => {+ await sdk.trigger("mem::lesson-save", {+ content: "Recent lesson",+ confidence: 0.5,+ });++ const result = (await sdk.trigger("mem::lesson-decay-sweep", {})) as {+ decayed: number;+ };++ expect(result.decayed).toBe(0);+ });++ it("soft-deletes low-confidence unreinforced lessons", async () => {+ const saved = (await sdk.trigger("mem::lesson-save", {+ content: "Weak lesson",+ confidence: 0.12,+ })) as { lesson: Lesson };++ const lesson = await kv.get<Lesson>("mem:lessons", saved.lesson.id);+ lesson!.createdAt = new Date(Date.now() - 21 * 24 * 60 * 60 * 1000).toISOString();+ await kv.set("mem:lessons", lesson!.id, lesson!);++ const result = (await sdk.trigger("mem::lesson-decay-sweep", {})) as {+ softDeleted: number;+ };++ expect(result.softDeleted).toBe(1);++ const after = await kv.get<Lesson>("mem:lessons", saved.lesson.id);+ expect(after!.deleted).toBe(true);+ });++ it("uses lastDecayedAt for incremental delta (not full age)", async () => {+ const saved = (await sdk.trigger("mem::lesson-save", {+ content: "Incremental decay",+ confidence: 0.8,+ })) as { lesson: Lesson };++ const lesson = await kv.get<Lesson>("mem:lessons", saved.lesson.id);+ lesson!.createdAt = new Date(Date.now() - 28 * 24 * 60 * 60 * 1000).toISOString();+ lesson!.lastDecayedAt = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();+ lesson!.confidence = 0.6;+ await kv.set("mem:lessons", lesson!.id, lesson!);++ await sdk.trigger("mem::lesson-decay-sweep", {});++ const after = await kv.get<Lesson>("mem:lessons", saved.lesson.id);+ expect(after!.confidence).toBeCloseTo(0.55, 1);+ expect(after!.confidence).toBeGreaterThan(0.4);+ });+ });+});diff --git a/test/obsidian-export.test.ts b/test/obsidian-export.test.tsnew file mode 100644index 00000000..a7ce709f--- /dev/null+++ b/test/obsidian-export.test.ts@@ -0,0 +1,276 @@+import { describe, it, expect, beforeEach, vi } from "vitest";++vi.mock("iii-sdk", () => ({+ getContext: () => ({+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },+ }),+}));++const writtenFiles = new Map<string, string>();+const createdDirs = new Set<string>();++vi.mock("node:fs/promises", () => ({+ mkdir: vi.fn(async (dir: string) => {+ createdDirs.add(dir);+ }),+ writeFile: vi.fn(async (path: string, content: string) => {+ writtenFiles.set(path, content);+ }),+}));++import { registerObsidianExportFunction } from "../src/functions/obsidian-export.js";+import type { Memory, Lesson, Crystal, Session } from "../src/types.js";++function mockKV() {+ const store = new Map<string, Map<string, unknown>>();+ return {+ get: async <T>(scope: string, key: string): Promise<T | null> => {+ return (store.get(scope)?.get(key) as T) ?? null;+ },+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, data);+ return data;+ },+ delete: async (scope: string, key: string): Promise<void> => {+ store.get(scope)?.delete(key);+ },+ list: async <T>(scope: string): Promise<T[]> => {+ const entries = store.get(scope);+ return entries ? (Array.from(entries.values()) as T[]) : [];+ },+ };+}++function mockSdk() {+ const functions = new Map<string, Function>();+ return {+ registerFunction: (opts: { id: string }, handler: Function) => {+ functions.set(opts.id, handler);+ },+ registerTrigger: () => {},+ trigger: async (id: string, data: unknown) => {+ const fn = functions.get(id);+ if (!fn) throw new Error(`No function: ${id}`);+ return fn(data);+ },+ };+}++function makeMemory(id: string): Memory {+ return {+ id,+ createdAt: "2026-04-01T00:00:00Z",+ updatedAt: "2026-04-01T00:00:00Z",+ type: "pattern",+ title: `Memory ${id}`,+ content: `Content for ${id}`,+ concepts: ["testing"],+ files: ["src/test.ts"],+ sessionIds: ["ses_1"],+ strength: 7,+ version: 1,+ isLatest: true,+ };+}++function makeLesson(id: string): Lesson {+ return {+ id,+ content: `Lesson ${id}`,+ context: "Test context",+ confidence: 0.8,+ reinforcements: 2,+ source: "manual",+ sourceIds: [],+ project: "/test",+ tags: ["testing"],+ createdAt: "2026-04-01T00:00:00Z",+ updatedAt: "2026-04-01T00:00:00Z",+ decayRate: 0.05,+ };+}++function makeCrystal(id: string): Crystal {+ return {+ id,+ narrative: `Crystal narrative ${id}`,+ keyOutcomes: ["Outcome 1"],+ filesAffected: ["src/test.ts"],+ lessons: ["Learned something"],+ sourceActionIds: ["act_1"],+ sessionId: "ses_1",+ project: "/test",+ createdAt: "2026-04-01T00:00:00Z",+ };+}++function makeSession(id: string): Session {+ return {+ id,+ project: "/test",+ cwd: "/Users/test/project",+ startedAt: "2026-04-01T00:00:00Z",+ endedAt: "2026-04-01T01:00:00Z",+ status: "completed",+ observationCount: 15,+ };+}++describe("Obsidian Export", () => {+ let sdk: ReturnType<typeof mockSdk>;+ let kv: ReturnType<typeof mockKV>;++ beforeEach(() => {+ sdk = mockSdk();+ kv = mockKV();+ writtenFiles.clear();+ createdDirs.clear();+ registerObsidianExportFunction(sdk as never, kv as never);+ });++ it("creates directories and MOC.md with empty data", async () => {+ const result = (await sdk.trigger("mem::obsidian-export", {})) as {+ success: boolean;+ exported: Record<string, number>;+ vaultDir: string;+ };++ expect(result.success).toBe(true);+ expect(result.exported.memories).toBe(0);+ expect(result.exported.lessons).toBe(0);+ expect(result.exported.crystals).toBe(0);+ expect(result.exported.sessions).toBe(0);+ expect(createdDirs.size).toBe(4);++ const mocPath = [...writtenFiles.keys()].find((k) => k.endsWith("MOC.md"));+ expect(mocPath).toBeDefined();+ const moc = writtenFiles.get(mocPath!);+ expect(moc).toContain("# agentmemory vault");+ expect(moc).toContain("## Memories (0)");+ });++ it("exports memories with YAML frontmatter", async () => {+ const mem = makeMemory("mem_001");+ await kv.set("mem:memories", mem.id, mem);++ const result = (await sdk.trigger("mem::obsidian-export", {})) as {+ exported: Record<string, number>;+ };++ expect(result.exported.memories).toBe(1);++ const memFile = [...writtenFiles.entries()].find(([k]) =>+ k.includes("memories/mem_001.md"),+ );+ expect(memFile).toBeDefined();+ const content = memFile![1];+ expect(content).toContain("---");+ expect(content).toContain('id: "mem_001"');+ expect(content).toContain('type: "pattern"');+ expect(content).toContain("# Memory mem_001");+ expect(content).toContain("#testing");+ });++ it("exports lessons with confidence and source", async () => {+ const lesson = makeLesson("lsn_001");+ await kv.set("mem:lessons", lesson.id, lesson);++ const result = (await sdk.trigger("mem::obsidian-export", {})) as {+ exported: Record<string, number>;+ };++ expect(result.exported.lessons).toBe(1);++ const lsnFile = [...writtenFiles.entries()].find(([k]) =>+ k.includes("lessons/lsn_001.md"),+ );+ expect(lsnFile).toBeDefined();+ const content = lsnFile![1];+ expect(content).toContain("confidence: 0.8");+ expect(content).toContain("reinforcements: 2");+ expect(content).toContain('source: "manual"');+ });++ it("exports crystals with wikilinks to source actions", async () => {+ const crystal = makeCrystal("crys_001");+ await kv.set("mem:crystals", crystal.id, crystal);++ await sdk.trigger("mem::obsidian-export", {});++ const crysFile = [...writtenFiles.entries()].find(([k]) =>+ k.includes("crystals/crys_001.md"),+ );+ expect(crysFile).toBeDefined();+ expect(crysFile![1]).toContain("[[act_1]]");+ expect(crysFile![1]).toContain("Outcome 1");+ });++ it("respects types filter", async () => {+ await kv.set("mem:memories", "mem_001", makeMemory("mem_001"));+ await kv.set("mem:lessons", "lsn_001", makeLesson("lsn_001"));++ const result = (await sdk.trigger("mem::obsidian-export", {+ types: ["lessons"],+ })) as { exported: Record<string, number> };++ expect(result.exported.lessons).toBe(1);+ expect(result.exported.memories).toBe(0);+ });++ it("respects custom vaultDir", async () => {+ await sdk.trigger("mem::obsidian-export", {+ vaultDir: "/tmp/test-vault",+ });++ const hasCustomPath = [...createdDirs].some((d) =>+ d.startsWith("/tmp/test-vault"),+ );+ expect(hasCustomPath).toBe(true);+ });++ it("skips deleted lessons", async () => {+ const lesson = makeLesson("lsn_deleted");+ (lesson as any).deleted = true;+ await kv.set("mem:lessons", lesson.id, lesson);++ const result = (await sdk.trigger("mem::obsidian-export", {})) as {+ exported: Record<string, number>;+ };++ expect(result.exported.lessons).toBe(0);+ });++ it("skips non-latest memories", async () => {+ const mem = makeMemory("mem_old");+ mem.isLatest = false;+ await kv.set("mem:memories", mem.id, mem);++ const result = (await sdk.trigger("mem::obsidian-export", {})) as {+ exported: Record<string, number>;+ };++ expect(result.exported.memories).toBe(0);+ });++ it("MOC groups entries by type", async () => {+ await kv.set("mem:memories", "mem_001", makeMemory("mem_001"));+ await kv.set("mem:lessons", "lsn_001", makeLesson("lsn_001"));+ await kv.set("mem:crystals", "crys_001", makeCrystal("crys_001"));+ await kv.set("mem:sessions", "ses_001", makeSession("ses_001"));++ await sdk.trigger("mem::obsidian-export", {});++ const mocPath = [...writtenFiles.keys()].find((k) => k.endsWith("MOC.md"));+ const moc = writtenFiles.get(mocPath!)!;++ expect(moc).toContain("## Memories (1)");+ expect(moc).toContain("## Lessons (1)");+ expect(moc).toContain("## Crystals (1)");+ expect(moc).toContain("## Sessions (1)");+ expect(moc).toContain("[[memories/mem_001|");+ expect(moc).toContain("[[lessons/lsn_001|");+ expect(moc).toContain("[[crystals/crys_001|");+ expect(moc).toContain("[[sessions/ses_001|");+ });+});