@agentmemory/agentmemory 0.7.0

package/test/export-import.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+  getContext: () => ({
+    logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+  }),
+}));
+
+import { registerExportImportFunction } from "../src/functions/export-import.js";
+import type {
+  Session,
+  CompressedObservation,
+  Memory,
+  SessionSummary,
+  ExportData,
+} 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);
+    },
+  };
+}
+
+const testSession: Session = {
+  id: "ses_1",
+  project: "my-project",
+  cwd: "/tmp",
+  startedAt: "2026-02-01T00:00:00Z",
+  status: "completed",
+  observationCount: 1,
+};
+
+const testObs: CompressedObservation = {
+  id: "obs_1",
+  sessionId: "ses_1",
+  timestamp: "2026-02-01T10:00:00Z",
+  type: "file_edit",
+  title: "Edit auth",
+  facts: ["Added check"],
+  narrative: "Auth changes",
+  concepts: ["auth"],
+  files: ["src/auth.ts"],
+  importance: 7,
+};
+
+const testMemory: Memory = {
+  id: "mem_1",
+  createdAt: "2026-02-01T00:00:00Z",
+  updatedAt: "2026-02-01T00:00:00Z",
+  type: "pattern",
+  title: "Auth pattern",
+  content: "Always validate tokens",
+  concepts: ["auth"],
+  files: [],
+  sessionIds: ["ses_1"],
+  strength: 5,
+  version: 1,
+  isLatest: true,
+};
+
+const testSummary: SessionSummary = {
+  sessionId: "ses_1",
+  project: "my-project",
+  createdAt: "2026-02-01T00:00:00Z",
+  title: "Auth work",
+  narrative: "Worked on auth",
+  keyDecisions: ["Use JWT"],
+  filesModified: ["src/auth.ts"],
+  concepts: ["auth"],
+  observationCount: 1,
+};
+
+describe("Export/Import Functions", () => {
+  let sdk: ReturnType<typeof mockSdk>;
+  let kv: ReturnType<typeof mockKV>;
+
+  beforeEach(async () => {
+    sdk = mockSdk();
+    kv = mockKV();
+    registerExportImportFunction(sdk as never, kv as never);
+
+    await kv.set("mem:sessions", "ses_1", testSession);
+    await kv.set("mem:obs:ses_1", "obs_1", testObs);
+    await kv.set("mem:memories", "mem_1", testMemory);
+    await kv.set("mem:summaries", "ses_1", testSummary);
+  });
+
+  it("export produces valid ExportData structure", async () => {
+    const result = (await sdk.trigger("mem::export", {})) as ExportData;
+
+    expect(result.version).toBe("0.7.0");
+    expect(result.exportedAt).toBeDefined();
+    expect(result.sessions.length).toBe(1);
+    expect(result.sessions[0].id).toBe("ses_1");
+    expect(result.observations["ses_1"].length).toBe(1);
+    expect(result.memories.length).toBe(1);
+    expect(result.summaries.length).toBe(1);
+  });
+
+  it("import with merge strategy adds data", async () => {
+    const exportData: ExportData = {
+      version: "0.3.0",
+      exportedAt: new Date().toISOString(),
+      sessions: [{ ...testSession, id: "ses_2", observationCount: 0 }],
+      observations: {},
+      memories: [{ ...testMemory, id: "mem_2", title: "New pattern" }],
+      summaries: [],
+    };
+
+    const result = (await sdk.trigger("mem::import", {
+      exportData,
+      strategy: "merge",
+    })) as { success: boolean; sessions: number; memories: number };
+
+    expect(result.success).toBe(true);
+    expect(result.sessions).toBe(1);
+    expect(result.memories).toBe(1);
+
+    const allSessions = await kv.list("mem:sessions");
+    expect(allSessions.length).toBe(2);
+  });
+
+  it("import with skip strategy does not overwrite existing", async () => {
+    const exportData: ExportData = {
+      version: "0.3.0",
+      exportedAt: new Date().toISOString(),
+      sessions: [testSession],
+      observations: { ses_1: [testObs] },
+      memories: [testMemory],
+      summaries: [testSummary],
+    };
+
+    const result = (await sdk.trigger("mem::import", {
+      exportData,
+      strategy: "skip",
+    })) as { success: boolean; skipped: number; sessions: number };
+
+    expect(result.success).toBe(true);
+    expect(result.skipped).toBeGreaterThan(0);
+    expect(result.sessions).toBe(0);
+  });
+
+  it("import with replace strategy clears existing data first", async () => {
+    const newSession: Session = {
+      id: "ses_new",
+      project: "new-project",
+      cwd: "/tmp/new",
+      startedAt: "2026-03-01T00:00:00Z",
+      status: "active",
+      observationCount: 0,
+    };
+    const exportData: ExportData = {
+      version: "0.3.0",
+      exportedAt: new Date().toISOString(),
+      sessions: [newSession],
+      observations: {},
+      memories: [],
+      summaries: [],
+    };
+
+    const result = (await sdk.trigger("mem::import", {
+      exportData,
+      strategy: "replace",
+    })) as { success: boolean; sessions: number };
+
+    expect(result.success).toBe(true);
+    expect(result.sessions).toBe(1);
+
+    const oldSession = await kv.get("mem:sessions", "ses_1");
+    expect(oldSession).toBeNull();
+  });
+
+  it("export then import round-trip preserves data", async () => {
+    const exported = (await sdk.trigger("mem::export", {})) as ExportData;
+
+    const freshKv = mockKV();
+    const freshSdk = mockSdk();
+    registerExportImportFunction(freshSdk as never, freshKv as never);
+
+    const importResult = (await freshSdk.trigger("mem::import", {
+      exportData: exported,
+      strategy: "merge",
+    })) as {
+      success: boolean;
+      sessions: number;
+      observations: number;
+      memories: number;
+    };
+
+    expect(importResult.success).toBe(true);
+    expect(importResult.sessions).toBe(1);
+    expect(importResult.observations).toBe(1);
+    expect(importResult.memories).toBe(1);
+
+    const reExported = (await freshSdk.trigger(
+      "mem::export",
+      {},
+    )) as ExportData;
+    expect(reExported.sessions.length).toBe(exported.sessions.length);
+    expect(reExported.memories.length).toBe(exported.memories.length);
+  });
+
+  it("import rejects unsupported version", async () => {
+    const exportData = {
+      version: "1.0.0",
+      exportedAt: new Date().toISOString(),
+      sessions: [],
+      observations: {},
+      memories: [],
+      summaries: [],
+    } as unknown as ExportData;
+
+    const result = (await sdk.trigger("mem::import", {
+      exportData,
+      strategy: "merge",
+    })) as { success: boolean; error: string };
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("Unsupported export version");
+  });
+});

package/test/facets.test.ts

@@ -0,0 +1,448 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+  getContext: () => ({
+    logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+  }),
+}));
+
+import { registerFacetsFunction } from "../src/functions/facets.js";
+import type { Facet } 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("Facets Functions", () => {
+  let sdk: ReturnType<typeof mockSdk>;
+  let kv: ReturnType<typeof mockKV>;
+
+  beforeEach(() => {
+    sdk = mockSdk();
+    kv = mockKV();
+    registerFacetsFunction(sdk as never, kv as never);
+  });
+
+  describe("mem::facet-tag", () => {
+    it("tags a target with a facet", async () => {
+      const result = (await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      })) as { success: boolean; facet: Facet };
+
+      expect(result.success).toBe(true);
+      expect(result.facet.id).toMatch(/^fct_/);
+      expect(result.facet.targetId).toBe("act_123");
+      expect(result.facet.targetType).toBe("action");
+      expect(result.facet.dimension).toBe("priority");
+      expect(result.facet.value).toBe("high");
+      expect(result.facet.createdAt).toBeDefined();
+    });
+
+    it("returns error when dimension is empty", async () => {
+      const result = (await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "  ",
+        value: "high",
+      })) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("dimension is required");
+    });
+
+    it("returns error when value is empty", async () => {
+      const result = (await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "",
+      })) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("value is required");
+    });
+
+    it("returns error for invalid targetType", async () => {
+      const result = (await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "invalid",
+        dimension: "priority",
+        value: "high",
+      })) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("targetType must be one of");
+    });
+
+    it("skips duplicate tag", async () => {
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+
+      const result = (await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      })) as { success: boolean; facet: Facet; skipped: boolean };
+
+      expect(result.success).toBe(true);
+      expect(result.skipped).toBe(true);
+    });
+  });
+
+  describe("mem::facet-untag", () => {
+    it("removes a specific value from a dimension", async () => {
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "urgent",
+      });
+
+      const result = (await sdk.trigger("mem::facet-untag", {
+        targetId: "act_123",
+        dimension: "priority",
+        value: "high",
+      })) as { success: boolean; removed: number };
+
+      expect(result.success).toBe(true);
+      expect(result.removed).toBe(1);
+
+      const remaining = (await sdk.trigger("mem::facet-get", {
+        targetId: "act_123",
+      })) as { success: boolean; dimensions: Array<{ dimension: string; values: string[] }> };
+
+      expect(remaining.dimensions[0].values).toEqual(["urgent"]);
+    });
+
+    it("removes all values in a dimension when value is omitted", async () => {
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_123",
+        targetType: "action",
+        dimension: "priority",
+        value: "urgent",
+      });
+
+      const result = (await sdk.trigger("mem::facet-untag", {
+        targetId: "act_123",
+        dimension: "priority",
+      })) as { success: boolean; removed: number };
+
+      expect(result.success).toBe(true);
+      expect(result.removed).toBe(2);
+
+      const remaining = (await sdk.trigger("mem::facet-get", {
+        targetId: "act_123",
+      })) as { success: boolean; dimensions: Array<{ dimension: string; values: string[] }> };
+
+      expect(remaining.dimensions).toEqual([]);
+    });
+  });
+
+  describe("mem::facet-query", () => {
+    beforeEach(async () => {
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "status",
+        value: "active",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_2",
+        targetType: "action",
+        dimension: "priority",
+        value: "low",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_2",
+        targetType: "action",
+        dimension: "status",
+        value: "active",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "mem_1",
+        targetType: "memory",
+        dimension: "priority",
+        value: "high",
+      });
+    });
+
+    it("queries with matchAll (AND logic)", async () => {
+      const result = (await sdk.trigger("mem::facet-query", {
+        matchAll: ["priority:high", "status:active"],
+      })) as { success: boolean; results: Array<{ targetId: string }> };
+
+      expect(result.success).toBe(true);
+      expect(result.results.length).toBe(1);
+      expect(result.results[0].targetId).toBe("act_1");
+    });
+
+    it("queries with matchAny (OR logic)", async () => {
+      const result = (await sdk.trigger("mem::facet-query", {
+        matchAny: ["priority:high", "priority:low"],
+      })) as { success: boolean; results: Array<{ targetId: string }> };
+
+      expect(result.success).toBe(true);
+      expect(result.results.length).toBe(3);
+    });
+
+    it("queries with both matchAll and matchAny", async () => {
+      const result = (await sdk.trigger("mem::facet-query", {
+        matchAll: ["status:active"],
+        matchAny: ["priority:high"],
+      })) as { success: boolean; results: Array<{ targetId: string; matchedFacets: string[] }> };
+
+      expect(result.success).toBe(true);
+      expect(result.results.length).toBe(1);
+      expect(result.results[0].targetId).toBe("act_1");
+      expect(result.results[0].matchedFacets).toContain("status:active");
+      expect(result.results[0].matchedFacets).toContain("priority:high");
+    });
+
+    it("returns error when neither matchAll nor matchAny provided", async () => {
+      const result = (await sdk.trigger("mem::facet-query", {})) as {
+        success: boolean;
+        error: string;
+      };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("at least one of matchAll or matchAny is required");
+    });
+
+    it("filters by targetType", async () => {
+      const result = (await sdk.trigger("mem::facet-query", {
+        matchAny: ["priority:high"],
+        targetType: "memory",
+      })) as { success: boolean; results: Array<{ targetId: string; targetType: string }> };
+
+      expect(result.success).toBe(true);
+      expect(result.results.length).toBe(1);
+      expect(result.results[0].targetId).toBe("mem_1");
+      expect(result.results[0].targetType).toBe("memory");
+    });
+
+    it("respects limit", async () => {
+      const result = (await sdk.trigger("mem::facet-query", {
+        matchAny: ["priority:high", "priority:low"],
+        limit: 1,
+      })) as { success: boolean; results: Array<{ targetId: string }> };
+
+      expect(result.success).toBe(true);
+      expect(result.results.length).toBe(1);
+    });
+  });
+
+  describe("mem::facet-get", () => {
+    it("returns facets grouped by dimension", async () => {
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "priority",
+        value: "urgent",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "status",
+        value: "active",
+      });
+
+      const result = (await sdk.trigger("mem::facet-get", {
+        targetId: "act_1",
+      })) as { success: boolean; dimensions: Array<{ dimension: string; values: string[] }> };
+
+      expect(result.success).toBe(true);
+      expect(result.dimensions.length).toBe(2);
+
+      const priorityDim = result.dimensions.find((d) => d.dimension === "priority");
+      expect(priorityDim).toBeDefined();
+      expect(priorityDim!.values).toEqual(["high", "urgent"]);
+
+      const statusDim = result.dimensions.find((d) => d.dimension === "status");
+      expect(statusDim).toBeDefined();
+      expect(statusDim!.values).toEqual(["active"]);
+    });
+
+    it("returns empty dimensions for target with no facets", async () => {
+      const result = (await sdk.trigger("mem::facet-get", {
+        targetId: "nonexistent",
+      })) as { success: boolean; dimensions: Array<{ dimension: string; values: string[] }> };
+
+      expect(result.success).toBe(true);
+      expect(result.dimensions).toEqual([]);
+    });
+  });
+
+  describe("mem::facet-stats", () => {
+    beforeEach(async () => {
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_2",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_3",
+        targetType: "action",
+        dimension: "priority",
+        value: "low",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "mem_1",
+        targetType: "memory",
+        dimension: "category",
+        value: "bugfix",
+      });
+    });
+
+    it("returns dimensions with value counts", async () => {
+      const result = (await sdk.trigger("mem::facet-stats", {})) as {
+        success: boolean;
+        dimensions: Array<{
+          dimension: string;
+          values: Array<{ value: string; count: number }>;
+        }>;
+        totalFacets: number;
+      };
+
+      expect(result.success).toBe(true);
+      expect(result.totalFacets).toBe(4);
+      expect(result.dimensions.length).toBe(2);
+
+      const priorityDim = result.dimensions.find((d) => d.dimension === "priority");
+      expect(priorityDim).toBeDefined();
+      const highVal = priorityDim!.values.find((v) => v.value === "high");
+      expect(highVal!.count).toBe(2);
+      const lowVal = priorityDim!.values.find((v) => v.value === "low");
+      expect(lowVal!.count).toBe(1);
+    });
+
+    it("filters by targetType", async () => {
+      const result = (await sdk.trigger("mem::facet-stats", {
+        targetType: "memory",
+      })) as {
+        success: boolean;
+        dimensions: Array<{
+          dimension: string;
+          values: Array<{ value: string; count: number }>;
+        }>;
+        totalFacets: number;
+      };
+
+      expect(result.success).toBe(true);
+      expect(result.totalFacets).toBe(1);
+      expect(result.dimensions.length).toBe(1);
+      expect(result.dimensions[0].dimension).toBe("category");
+      expect(result.dimensions[0].values[0].value).toBe("bugfix");
+      expect(result.dimensions[0].values[0].count).toBe(1);
+    });
+  });
+
+  describe("mem::facet-dimensions", () => {
+    it("returns unique dimension names with counts", async () => {
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "priority",
+        value: "high",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_2",
+        targetType: "action",
+        dimension: "priority",
+        value: "low",
+      });
+      await sdk.trigger("mem::facet-tag", {
+        targetId: "act_1",
+        targetType: "action",
+        dimension: "status",
+        value: "active",
+      });
+
+      const result = (await sdk.trigger("mem::facet-dimensions", {})) as {
+        success: boolean;
+        dimensions: Array<{ dimension: string; count: number }>;
+      };
+
+      expect(result.success).toBe(true);
+      expect(result.dimensions.length).toBe(2);
+
+      const priorityDim = result.dimensions.find((d) => d.dimension === "priority");
+      expect(priorityDim).toBeDefined();
+      expect(priorityDim!.count).toBe(2);
+
+      const statusDim = result.dimensions.find((d) => d.dimension === "status");
+      expect(statusDim).toBeDefined();
+      expect(statusDim!.count).toBe(1);
+    });
+  });
+});