@ai2070/memex 0.9.0

package/tests/transplant.test.ts

@@ -0,0 +1,385 @@
+import { describe, it, expect } from "vitest";
+import { exportSlice, importSlice } from "../src/transplant.js";
+import { createGraphState } from "../src/graph.js";
+import { applyCommand } from "../src/reducer.js";
+import {
+  createIntentState,
+  applyIntentCommand,
+  createIntent,
+} from "../src/intent.js";
+import { createTaskState, applyTaskCommand, createTask } from "../src/task.js";
+import type { MemoryItem, Edge, GraphState } from "../src/types.js";
+import type { IntentState } from "../src/intent.js";
+import type { TaskState } from "../src/task.js";
+
+// -- helpers --
+
+const makeItem = (
+  id: string,
+  overrides: Partial<MemoryItem> = {},
+): MemoryItem => ({
+  id,
+  scope: "test",
+  kind: "observation",
+  content: {},
+  author: "agent:a",
+  source_kind: "observed",
+  authority: 0.5,
+  ...overrides,
+});
+
+const makeEdge = (
+  id: string,
+  from: string,
+  to: string,
+  kind: string = "SUPPORTS",
+): Edge => ({
+  edge_id: id,
+  from,
+  to,
+  kind,
+  author: "system:rule",
+  source_kind: "derived_deterministic",
+  authority: 0.8,
+  active: true,
+});
+
+function buildState(): {
+  mem: GraphState;
+  intents: IntentState;
+  tasks: TaskState;
+} {
+  let mem = createGraphState();
+  mem = applyCommand(mem, {
+    type: "memory.create",
+    item: makeItem("m1"),
+  }).state;
+  mem = applyCommand(mem, {
+    type: "memory.create",
+    item: makeItem("m2", { parents: ["m1"] }),
+  }).state;
+  mem = applyCommand(mem, {
+    type: "memory.create",
+    item: makeItem("m3", { parents: ["m2"] }),
+  }).state;
+  mem = applyCommand(mem, {
+    type: "memory.create",
+    item: makeItem("m4"),
+  }).state;
+  mem = applyCommand(mem, {
+    type: "edge.create",
+    edge: makeEdge("e1", "m1", "m2"),
+  }).state;
+  mem = applyCommand(mem, {
+    type: "edge.create",
+    edge: makeEdge("e2", "m2", "m3"),
+  }).state;
+
+  let intents = createIntentState();
+  intents = applyIntentCommand(intents, {
+    type: "intent.create",
+    intent: createIntent({
+      id: "i1",
+      label: "find_kati",
+      priority: 0.9,
+      owner: "user:laz",
+      root_memory_ids: ["m1"],
+    }),
+  }).state;
+
+  let tasks = createTaskState();
+  tasks = applyTaskCommand(tasks, {
+    type: "task.create",
+    task: createTask({
+      id: "t1",
+      intent_id: "i1",
+      action: "search",
+      priority: 0.8,
+      input_memory_ids: ["m1"],
+      output_memory_ids: ["m2"],
+    }),
+  }).state;
+
+  return { mem, intents, tasks };
+}
+
+// ============================================================
+// Export
+// ============================================================
+
+describe("exportSlice", () => {
+  it("exports specific memory ids", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m1"],
+    });
+    expect(slice.memories).toHaveLength(1);
+    expect(slice.memories[0].id).toBe("m1");
+    expect(slice.edges).toHaveLength(0); // no edges with both ends in slice
+    expect(slice.intents).toHaveLength(0);
+    expect(slice.tasks).toHaveLength(0);
+  });
+
+  it("exports with parents", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m3"],
+      include_parents: true,
+    });
+    expect(slice.memories.map((m) => m.id).sort()).toEqual(["m1", "m2", "m3"]);
+    // edges between included items
+    expect(slice.edges.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("exports with children", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m1"],
+      include_children: true,
+    });
+    expect(slice.memories.map((m) => m.id).sort()).toEqual(["m1", "m2", "m3"]);
+  });
+
+  it("exports related intents and tasks", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m1"],
+      include_related_intents: true,
+      include_related_tasks: true,
+    });
+    expect(slice.intents).toHaveLength(1);
+    expect(slice.intents[0].id).toBe("i1");
+    expect(slice.tasks).toHaveLength(1);
+    expect(slice.tasks[0].id).toBe("t1");
+  });
+
+  it("exports by intent id with related tasks", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      intent_ids: ["i1"],
+      include_related_tasks: true,
+    });
+    expect(slice.intents).toHaveLength(1);
+    expect(slice.tasks).toHaveLength(1);
+  });
+
+  it("empty export returns empty slice", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {});
+    expect(slice.memories).toHaveLength(0);
+    expect(slice.edges).toHaveLength(0);
+    expect(slice.intents).toHaveLength(0);
+    expect(slice.tasks).toHaveLength(0);
+  });
+});
+
+// ============================================================
+// Import — default (skip existing ids)
+// ============================================================
+
+describe("importSlice (default: skip existing)", () => {
+  it("imports into empty state", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m1", "m2"],
+      include_related_intents: true,
+      include_related_tasks: true,
+    });
+
+    const result = importSlice(
+      createGraphState(),
+      createIntentState(),
+      createTaskState(),
+      slice,
+    );
+
+    expect(result.memState.items.size).toBe(2);
+    expect(result.intentState.intents.size).toBe(1);
+    expect(result.taskState.tasks.size).toBe(1);
+    expect(result.report.created.memories).toHaveLength(2);
+    expect(result.report.skipped.memories).toHaveLength(0);
+  });
+
+  it("skips existing ids without overwriting", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m1", "m2"],
+    });
+
+    // import into state that already has m1
+    let targetMem = createGraphState();
+    targetMem = applyCommand(targetMem, {
+      type: "memory.create",
+      item: makeItem("m1", { authority: 0.99 }),
+    }).state;
+
+    const result = importSlice(
+      targetMem,
+      createIntentState(),
+      createTaskState(),
+      slice,
+    );
+
+    expect(result.memState.items.size).toBe(2);
+    expect(result.memState.items.get("m1")!.authority).toBe(0.99); // not overwritten
+    expect(result.report.created.memories).toEqual(["m2"]);
+    expect(result.report.skipped.memories).toEqual(["m1"]);
+  });
+
+  it("does not mutate original states", () => {
+    const empty = createGraphState();
+    const emptyIntents = createIntentState();
+    const emptyTasks = createTaskState();
+    const slice = {
+      memories: [makeItem("m1")],
+      edges: [],
+      intents: [],
+      tasks: [],
+    };
+
+    importSlice(empty, emptyIntents, emptyTasks, slice);
+
+    expect(empty.items.size).toBe(0);
+  });
+});
+
+// ============================================================
+// Import — shallow compare + re-id
+// ============================================================
+
+describe("importSlice (shallow compare + re-id)", () => {
+  it("detects conflicts without re-id", () => {
+    let targetMem = createGraphState();
+    targetMem = applyCommand(targetMem, {
+      type: "memory.create",
+      item: makeItem("m1", { authority: 0.99 }),
+    }).state;
+
+    const slice = {
+      memories: [makeItem("m1", { authority: 0.1 })], // different
+      edges: [],
+      intents: [],
+      tasks: [],
+    };
+
+    const result = importSlice(
+      targetMem,
+      createIntentState(),
+      createTaskState(),
+      slice,
+      { shallowCompareExisting: true },
+    );
+
+    expect(result.report.conflicts.memories).toEqual(["m1"]);
+    expect(result.report.created.memories).toHaveLength(0);
+    expect(result.memState.items.get("m1")!.authority).toBe(0.99); // unchanged
+  });
+
+  it("skips silently when shallow-equal", () => {
+    const item = makeItem("m1");
+    let targetMem = createGraphState();
+    targetMem = applyCommand(targetMem, {
+      type: "memory.create",
+      item,
+    }).state;
+
+    const slice = {
+      memories: [item], // identical
+      edges: [],
+      intents: [],
+      tasks: [],
+    };
+
+    const result = importSlice(
+      targetMem,
+      createIntentState(),
+      createTaskState(),
+      slice,
+      { shallowCompareExisting: true },
+    );
+
+    expect(result.report.skipped.memories).toEqual(["m1"]);
+    expect(result.report.conflicts.memories).toHaveLength(0);
+  });
+
+  it("re-ids on difference when enabled", () => {
+    let targetMem = createGraphState();
+    targetMem = applyCommand(targetMem, {
+      type: "memory.create",
+      item: makeItem("m1", { authority: 0.99 }),
+    }).state;
+
+    const slice = {
+      memories: [makeItem("m1", { authority: 0.1 })],
+      edges: [],
+      intents: [],
+      tasks: [],
+    };
+
+    const result = importSlice(
+      targetMem,
+      createIntentState(),
+      createTaskState(),
+      slice,
+      { shallowCompareExisting: true, reIdOnDifference: true },
+    );
+
+    expect(result.memState.items.size).toBe(2); // original + re-id'd
+    expect(result.memState.items.get("m1")!.authority).toBe(0.99); // original untouched
+    expect(result.report.created.memories).toHaveLength(1);
+    const newId = result.report.created.memories[0];
+    expect(newId).not.toBe("m1");
+    expect(result.memState.items.get(newId)!.authority).toBe(0.1);
+  });
+});
+
+// ============================================================
+// Round-trip
+// ============================================================
+
+describe("export + import round-trip", () => {
+  it("round-trips a full chain into empty state", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m1"],
+      include_children: true,
+      include_related_intents: true,
+      include_related_tasks: true,
+    });
+
+    const result = importSlice(
+      createGraphState(),
+      createIntentState(),
+      createTaskState(),
+      slice,
+    );
+
+    expect(result.memState.items.size).toBe(3); // m1, m2, m3
+    expect(result.memState.edges.size).toBe(2); // e1, e2
+    expect(result.intentState.intents.size).toBe(1);
+    expect(result.taskState.tasks.size).toBe(1);
+    expect(result.report.created.memories.sort()).toEqual(["m1", "m2", "m3"]);
+  });
+
+  it("JSON serializable round-trip", () => {
+    const { mem, intents, tasks } = buildState();
+    const slice = exportSlice(mem, intents, tasks, {
+      memory_ids: ["m1", "m2"],
+      include_related_intents: true,
+      include_related_tasks: true,
+    });
+
+    const json = JSON.stringify(slice);
+    const parsed = JSON.parse(json);
+
+    const result = importSlice(
+      createGraphState(),
+      createIntentState(),
+      createTaskState(),
+      parsed,
+    );
+
+    expect(result.memState.items.size).toBe(2);
+    expect(result.intentState.intents.size).toBe(1);
+  });
+});

package/tests/types.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect, expectTypeOf } from "vitest";
+import type {
+  MemoryItem,
+  Edge,
+  EventEnvelope,
+  GraphState,
+  MemoryCommand,
+  MemoryLifecycleEvent,
+  MemoryFilter,
+} from "../src/types.js";
+
+describe("MemoryItem", () => {
+  it("accepts a valid literal", () => {
+    const item: MemoryItem = {
+      id: "01HV5W1YF3F8R9H1M6V3X6X8A0",
+      scope: "user:laz/general",
+      kind: "assertion",
+      content: { key: "theme", value: "dark" },
+      author: "user:laz",
+      source_kind: "user_explicit",
+      authority: 0.99,
+    };
+    expect(item.id).toBe("01HV5W1YF3F8R9H1M6V3X6X8A0");
+  });
+
+  it("accepts optional fields", () => {
+    const item: MemoryItem = {
+      id: "m1",
+      scope: "test",
+      kind: "observation",
+      content: {},
+      author: "test",
+      source_kind: "observed",
+      authority: 0.5,
+      conviction: 0.8,
+      importance: 0.3,
+      meta: { agent_id: "agent:x", session_id: "s1", custom: true },
+    };
+    expect(item.conviction).toBe(0.8);
+    expect(item.meta?.custom).toBe(true);
+  });
+
+  it("accepts arbitrary kind and source_kind strings", () => {
+    const item: MemoryItem = {
+      id: "m2",
+      scope: "test",
+      kind: "custom_kind",
+      content: {},
+      author: "test",
+      source_kind: "custom_source",
+      authority: 0.5,
+    };
+    expect(item.kind).toBe("custom_kind");
+    expect(item.source_kind).toBe("custom_source");
+  });
+});
+
+describe("Edge", () => {
+  it("accepts a valid literal", () => {
+    const edge: Edge = {
+      edge_id: "e1",
+      from: "m1",
+      to: "m2",
+      kind: "DERIVED_FROM",
+      author: "system:rule_x",
+      source_kind: "derived_deterministic",
+      authority: 0.9,
+      active: true,
+    };
+    expect(edge.kind).toBe("DERIVED_FROM");
+  });
+
+  it("accepts optional weight and meta", () => {
+    const edge: Edge = {
+      edge_id: "e2",
+      from: "m1",
+      to: "m3",
+      kind: "SUPPORTS",
+      weight: 0.7,
+      author: "agent:reasoner",
+      source_kind: "agent_inferred",
+      authority: 0.6,
+      active: true,
+      meta: { reason: "correlation" },
+    };
+    expect(edge.weight).toBe(0.7);
+  });
+});
+
+describe("MemoryCommand discriminated union", () => {
+  it("narrows memory.create to access cmd.item", () => {
+    const cmd: MemoryCommand = {
+      type: "memory.create",
+      item: {
+        id: "m1",
+        scope: "test",
+        kind: "observation",
+        content: {},
+        author: "test",
+        source_kind: "observed",
+        authority: 1,
+      },
+    };
+    if (cmd.type === "memory.create") {
+      expectTypeOf(cmd.item).toEqualTypeOf<MemoryItem>();
+      expect(cmd.item.id).toBe("m1");
+    }
+  });
+
+  it("narrows memory.update to access cmd.partial and cmd.item_id", () => {
+    const cmd: MemoryCommand = {
+      type: "memory.update",
+      item_id: "m1",
+      partial: { authority: 0.5 },
+      author: "system:tuner",
+    };
+    if (cmd.type === "memory.update") {
+      expectTypeOf(cmd.item_id).toBeString();
+      expectTypeOf(cmd.partial).toEqualTypeOf<Partial<MemoryItem>>();
+    }
+  });
+
+  it("narrows edge.create to access cmd.edge", () => {
+    const cmd: MemoryCommand = {
+      type: "edge.create",
+      edge: {
+        edge_id: "e1",
+        from: "m1",
+        to: "m2",
+        kind: "SUPPORTS",
+        author: "test",
+        source_kind: "observed",
+        authority: 1,
+        active: true,
+      },
+    };
+    if (cmd.type === "edge.create") {
+      expectTypeOf(cmd.edge).toEqualTypeOf<Edge>();
+    }
+  });
+});
+
+describe("EventEnvelope", () => {
+  it("types payload generically", () => {
+    const env: EventEnvelope<{ item: MemoryItem }> = {
+      id: "ev1",
+      namespace: "memory",
+      type: "state.memory",
+      ts: "2026-04-10T19:30:00.010Z",
+      payload: {
+        item: {
+          id: "m1",
+          scope: "test",
+          kind: "observation",
+          content: {},
+          author: "test",
+          source_kind: "observed",
+          authority: 1,
+        },
+      },
+    };
+    expectTypeOf(env.payload.item).toEqualTypeOf<MemoryItem>();
+    expect(env.namespace).toBe("memory");
+  });
+
+  it("accepts optional trace_id", () => {
+    const env: EventEnvelope<null> = {
+      id: "ev2",
+      namespace: "memory",
+      type: "test",
+      ts: "2026-01-01T00:00:00Z",
+      trace_id: "trace-123",
+      payload: null,
+    };
+    expect(env.trace_id).toBe("trace-123");
+  });
+});
+
+describe("GraphState", () => {
+  it("constructs with empty Maps", () => {
+    const state: GraphState = { items: new Map(), edges: new Map() };
+    expect(state.items.size).toBe(0);
+    expect(state.edges.size).toBe(0);
+  });
+});
+
+describe("MemoryLifecycleEvent", () => {
+  it("has namespace memory and dot-notation type", () => {
+    const event: MemoryLifecycleEvent = {
+      namespace: "memory",
+      type: "memory.created",
+      item: {
+        id: "m1",
+        scope: "test",
+        kind: "observation",
+        content: {},
+        author: "test",
+        source_kind: "observed",
+        authority: 1,
+      },
+      cause_type: "memory.create",
+    };
+    expect(event.namespace).toBe("memory");
+    expect(event.type).toBe("memory.created");
+  });
+});
+
+describe("MemoryFilter", () => {
+  it("accepts an empty object (all fields optional)", () => {
+    const filter: MemoryFilter = {};
+    expect(filter).toEqual({});
+  });
+
+  it("accepts all fields including range", () => {
+    const filter: MemoryFilter = {
+      scope: "user:laz/general",
+      author: "user:laz",
+      kind: "observation",
+      source_kind: "observed",
+      range: {
+        authority: { min: 0.3, max: 0.9 },
+        conviction: { min: 0.2 },
+        importance: { max: 0.7 },
+      },
+      not: { or: [{ kind: "simulation" }, { kind: "hypothesis" }] },
+      meta: { agent_id: "agent:foo" },
+      or: [{ kind: "trait" }],
+    };
+    expect(filter.scope).toBe("user:laz/general");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+  },
+});