Skip to content

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

fix: CrystallizableAction type, npm package size, add lesson + obsidian tests

Rohit Ghumare45eb99d656f4
diff --git a/package.json b/package.json
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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|");
+ });
+});