@ai2070/memex 0.9.0 → 0.10.0

package/API.md

@@ -21,6 +21,9 @@ interface MemoryItem {
   conviction?: number;           // 0..1 -- how sure was the author?
   importance?: number;           // 0..1 -- how much attention does this need right now? (salience)
 
+  intent_id?: string;            // intent that produced this item
+  task_id?: string;              // task that produced this item
+
   meta?: {
     agent_id?: string;
     session_id?: string;
@@ -221,6 +224,11 @@ interface MemoryFilter {
   kind?: MemoryKind;
   source_kind?: SourceKind;
 
+  intent_id?: string;            // exact match on intent_id
+  intent_ids?: string[];         // match any of these intent_ids
+  task_id?: string;              // exact match on task_id
+  task_ids?: string[];           // match any of these task_ids
+
   range?: {
     authority?: { min?: number; max?: number };
     conviction?: { min?: number; max?: number };
@@ -757,6 +765,7 @@ type IntentStatus = "active" | "paused" | "completed" | "cancelled";
 
 interface Intent {
   id: string;
+  parent_id?: string;            // parent intent for sub-intent hierarchies
   label: string;
   description?: string;
   priority: number;              // 0..1
@@ -808,10 +817,13 @@ interface IntentFilter {
   statuses?: IntentStatus[];
   min_priority?: number;
   has_memory_id?: string;        // intent references this memory item
+  parent_id?: string;            // filter by parent intent
+  is_root?: boolean;             // true = no parent, false = has parent
 }
 
 getIntents(state, { owner: "user:laz", statuses: ["active", "paused"] });
 getIntentById(state, "i1");
+getChildIntents(state, "i1");    // all intents with parent_id = "i1"
 ```
 
 ---
@@ -828,6 +840,7 @@ type TaskStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
 interface Task {
   id: string;
   intent_id: string;             // parent intent
+  parent_id?: string;            // parent task for subtask hierarchies
   action: string;                // "search_linkedin", "summarize_case"
   label?: string;
   status: TaskStatus;
@@ -886,10 +899,13 @@ interface TaskFilter {
   min_priority?: number;
   has_input_memory_id?: string;
   has_output_memory_id?: string;
+  parent_id?: string;            // filter by parent task
+  is_root?: boolean;             // true = no parent, false = has parent
 }
 
 getTasks(state, { intent_id: "i1", statuses: ["pending", "running"] });
 getTaskById(state, "t1");
+getChildTasks(state, "t1");      // all tasks with parent_id = "t1"
 getTasksByIntent(state, "i1");
 ```
 
@@ -902,11 +918,13 @@ The three graphs (memory, intent, task) reference each other by ID:
 | From | To | Field |
 |------|----|-------|
 | Intent | Memory | `Intent.root_memory_ids` |
+| Intent | Intent (parent) | `Intent.parent_id` |
 | Task | Intent | `Task.intent_id` |
+| Task | Task (parent) | `Task.parent_id` |
 | Task | Memory (input) | `Task.input_memory_ids` |
 | Task | Memory (output) | `Task.output_memory_ids` |
-| Memory | Intent | `MemoryItem.meta.creation_intent_id` |
-| Memory | Task | `MemoryItem.meta.creation_task_id` |
+| Memory | Intent | `MemoryItem.intent_id` |
+| Memory | Task | `MemoryItem.task_id` |
 
 No unified query across graphs — each graph has its own getters. The app layer composes them.
 

package/README.md

@@ -14,7 +14,7 @@ Every chat session starts from scratch. Memory systems try to fix this by append
 - **Whether** it's still relevant (decay)
 - **Where** it came from (source attribution)
 
-The result: agents that can retrieve old text but can't reason about what they know.
+Most systems conflate "I can retrieve it" with "I know it." Retrieval is not memory. MemEX separates recall (a tool problem) from belief state (a knowledge problem).
 
 ## What MemEX Does
 
@@ -77,7 +77,7 @@ MemEX is the structured memory layer in a larger stack. It doesn't replace your
 
 **Event store** -- the append-only command log. MemEX emits lifecycle events that get persisted. On restart, `replayFromEnvelopes` rebuilds the graph from the log.
 
-MemEX is the system of record. The library itself is pure TypeScript with a single runtime dependency (`uuidv7`). Storage, search, and bus integration belong in the service layer above.
+MemEX is the system of record. It does not replace retrieval systems -- it governs them. Vector search and keyword search are recall tools; MemEX is the epistemic coordination layer that decides what matters, what conflicts, and what to include in context. The library itself is pure TypeScript with a single runtime dependency (`uuidv7`). Storage, search, and bus integration belong in the service layer above.
 
 ### What changes in agent behavior
 
@@ -257,6 +257,24 @@ Commands go in, lifecycle events come out of the reducer, state events are full
 
 `applyCommand` never mutates input state. It returns a new `GraphState` and an array of lifecycle events. History is in the append-only event log; `GraphState` is always the latest snapshot.
 
+## Design Philosophy
+
+Every system encodes assumptions about truth, knowledge, and time -- whether it acknowledges them or not. MemEX makes those assumptions explicit.
+
+| Question | Typical system | MemEX |
+|----------|---------------|-------|
+| What is knowledge? | Similar text (vectors) or structured facts (SQL) | Beliefs with provenance, confidence, and conflict |
+| What exists? | Documents, rows | Observations, hypotheses, derivations, policies, traits |
+| Is truth binary? | Yes (stored or not) | No -- graded by authority, conviction, and importance |
+| Does knowledge decay? | No (or manually pruned) | Yes -- query-time decay, configurable per retrieval |
+| What about contradictions? | Overwrite or ignore | Represent, carry, and optionally resolve |
+
+Most memory systems compress and resolve -- they produce a single clean narrative. MemEX preserves and represents -- it maintains a field of competing claims that a reasoning layer can interpret. The graph is the pre-answer belief state, not the final answer.
+
+This is a deliberate architectural choice. MemEX is not a thinking system. It is a substrate that makes thinking systems possible. Storage, search, and cognition belong above the library. MemEX provides the structured epistemic state they operate on.
+
+Vector search tells you what is similar. MemEX tells you what you believe.
+
 ## Three Graphs
 
 MemEX contains three logical graphs in one package. Use what you need:
@@ -273,11 +291,17 @@ All three follow the same pattern: commands → reducer → lifecycle events. Th
 // intent links to memory items that motivated it
 const intent = createIntent({ label: "find_kati", root_memory_ids: [obs.id], ... });
 
+// sub-intent decomposes a parent goal
+const sub = createIntent({ label: "check_financials", parent_id: intent.id, ... });
+
 // task links to its parent intent and memory items it consumes/produces
 const task = createTask({ intent_id: intent.id, input_memory_ids: [obs.id], ... });
 
+// subtask breaks a task into steps
+const step = createTask({ intent_id: intent.id, parent_id: task.id, action: "parse_profile", ... });
+
 // after task completes, memory items link back
-createMemoryItem({ ..., meta: { creation_intent_id: intent.id, creation_task_id: task.id } });
+createMemoryItem({ ..., intent_id: intent.id, task_id: task.id });
 ```
 
 ## The Loop
@@ -352,10 +376,21 @@ Transferring cognition between agents is transferring this vector. The receiving
 
 This is what `exportSlice` / `importSlice` enables at the library level. The transport layer (network, bus, file) is outside the library; MemEX provides the serializable structure.
 
+### What transplant enables
+
+| Pattern | How it works |
+|---------|-------------|
+| **Safe delegation** | Export a slice to a sub-agent. It operates on its own copy. Merge results back append-only -- no risk of corrupting the main graph. |
+| **Parallel reasoning** | Fork belief state into multiple slices. Run different reasoning paths independently. Compare outcomes before merging. |
+| **Reproducibility** | Event logs + deterministic slices mean any state can be replayed, audited, or debugged after the fact. |
+| **State mobility** | Memory is not tied to one runtime. Export, serialize, move between agents or machines, rehydrate anywhere. |
+
+Memory is no longer a local resource. It is portable belief.
+
 ## Features
 
 **Memory graph:**
-- Full query algebra: `and`, `or`, `not`, `range`, `ids`, `scope_prefix`, `parents` (includes/count), `meta` (dot-path), `meta_has`, `created` (time range), `decay` (freshness filter)
+- Full query algebra: `and`, `or`, `not`, `range`, `ids`, `scope_prefix`, `parents` (includes/count), `intent_id`, `task_id`, `meta` (dot-path), `meta_has`, `created` (time range), `decay` (freshness filter)
 - Multi-sort with tiebreakers (authority, conviction, importance, recency)
 - Configurable time decay: exponential, linear, or step -- applied at query time, not stored
 - Scored retrieval with pre/post filters, min_score threshold, and decay
@@ -374,13 +409,15 @@ This is what `exportSlice` / `importSlice` enables at the library level. The tra
 
 **Intent graph:**
 - Status machine: active ↔ paused → completed / cancelled
-- Query by owner, status, priority, linked memory items
+- Sub-intent hierarchies via `parent_id`
+- Query by owner, status, priority, parent, linked memory items
 - Invalid transitions throw typed errors
 
 **Task graph:**
 - Status machine: pending → running → completed / failed, with retry support (failed → running)
+- Subtask hierarchies via `parent_id`
 - Links to parent intent, input/output memory items, agent assignment
-- Query by intent, action, status, agent, linked memory items
+- Query by intent, action, status, agent, parent, linked memory items
 
 **Transplant (export / import):**
 - Export a self-contained slice by walking provenance chains, aliases, related intents/tasks
@@ -464,7 +501,10 @@ item.meta.session_id            // "session-abc"
 item.meta.crew_id               // "crew:investigation-42"
 
 // which intent spawned this?
-item.meta.creation_intent_id    // "i1"
+item.intent_id                  // "i1"
+
+// which task produced this?
+item.task_id                    // "t1"
 ```
 
 All of these are queryable via `meta` and `meta_has` filters. The graph is one shared structure; segmentation is just queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai2070/memex",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "MemEX memory layer — graph of memories and edges over an append-only event log",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -98,6 +98,7 @@ export {
   applyIntentCommand,
   getIntents,
   getIntentById,
+  getChildIntents,
   IntentNotFoundError,
   DuplicateIntentError,
   InvalidIntentTransitionError,
@@ -119,6 +120,7 @@ export {
   getTasks,
   getTaskById,
   getTasksByIntent,
+  getChildTasks,
   TaskNotFoundError,
   DuplicateTaskError,
   InvalidTaskTransitionError,

package/src/intent.ts

@@ -8,6 +8,7 @@ export type IntentStatus = "active" | "paused" | "completed" | "cancelled";
 
 export interface Intent {
   id: string;
+  parent_id?: string; // parent intent for sub-intent hierarchies
   label: string;
   description?: string;
 
@@ -268,6 +269,8 @@ export interface IntentFilter {
   statuses?: IntentStatus[];
   min_priority?: number;
   has_memory_id?: string;
+  parent_id?: string;
+  is_root?: boolean; // true = no parent, false = has parent
 }
 
 export function getIntents(
@@ -298,6 +301,13 @@ export function getIntents(
       )
         continue;
     }
+    if (filter.parent_id !== undefined && intent.parent_id !== filter.parent_id)
+      continue;
+    if (filter.is_root !== undefined) {
+      const hasParent = intent.parent_id !== undefined;
+      if (filter.is_root && hasParent) continue;
+      if (!filter.is_root && !hasParent) continue;
+    }
     results.push(intent);
   }
   return results;
@@ -309,3 +319,10 @@ export function getIntentById(
 ): Intent | undefined {
   return state.intents.get(id);
 }
+
+export function getChildIntents(
+  state: IntentState,
+  parentId: string,
+): Intent[] {
+  return getIntents(state, { parent_id: parentId });
+}

package/src/query.ts

@@ -60,6 +60,16 @@ function matchesFilter(item: MemoryItem, filter: MemoryFilter): boolean {
   )
     return false;
 
+  // cross-graph links
+  if (filter.intent_id !== undefined && item.intent_id !== filter.intent_id)
+    return false;
+  if (filter.intent_ids !== undefined && (!item.intent_id || !filter.intent_ids.includes(item.intent_id)))
+    return false;
+  if (filter.task_id !== undefined && item.task_id !== filter.task_id)
+    return false;
+  if (filter.task_ids !== undefined && (!item.task_id || !filter.task_ids.includes(item.task_id)))
+    return false;
+
   // score ranges
   if (filter.range) {
     if (!matchesRange(item.authority, filter.range.authority)) return false;

package/src/task.ts

@@ -14,6 +14,7 @@ export type TaskStatus =
 export interface Task {
   id: string;
   intent_id: string;
+  parent_id?: string; // parent task for subtask hierarchies
 
   action: string; // "search_linkedin", "summarize_case"
   label?: string;
@@ -325,6 +326,8 @@ export interface TaskFilter {
   min_priority?: number;
   has_input_memory_id?: string;
   has_output_memory_id?: string;
+  parent_id?: string;
+  is_root?: boolean; // true = no parent, false = has parent
 }
 
 export function getTasks(state: TaskState, filter?: TaskFilter): Task[] {
@@ -359,6 +362,13 @@ export function getTasks(state: TaskState, filter?: TaskFilter): Task[] {
       )
         continue;
     }
+    if (filter.parent_id !== undefined && task.parent_id !== filter.parent_id)
+      continue;
+    if (filter.is_root !== undefined) {
+      const hasParent = task.parent_id !== undefined;
+      if (filter.is_root && hasParent) continue;
+      if (!filter.is_root && !hasParent) continue;
+    }
     results.push(task);
   }
   return results;
@@ -371,3 +381,10 @@ export function getTaskById(state: TaskState, id: string): Task | undefined {
 export function getTasksByIntent(state: TaskState, intentId: string): Task[] {
   return getTasks(state, { intent_id: intentId });
 }
+
+export function getChildTasks(
+  state: TaskState,
+  parentId: string,
+): Task[] {
+  return getTasks(state, { parent_id: parentId });
+}

package/src/transplant.ts

@@ -148,12 +148,10 @@ export function exportSlice(
         }
       }
     }
-    // also check memory meta for creation_intent_id
+    // also check memory items for linked intent
     for (const mid of memoryIds) {
       const item = memState.items.get(mid);
-      if (item?.meta?.creation_intent_id) {
-        intentIds.add(item.meta.creation_intent_id as string);
-      }
+      if (item?.intent_id) intentIds.add(item.intent_id);
     }
   }
 
@@ -172,12 +170,10 @@ export function exportSlice(
         taskIds.add(task.id);
       }
     }
-    // also check memory meta for creation_task_id
+    // also check memory items for linked task
     for (const mid of memoryIds) {
       const item = memState.items.get(mid);
-      if (item?.meta?.creation_task_id) {
-        taskIds.add(item.meta.creation_task_id as string);
-      }
+      if (item?.task_id) taskIds.add(item.task_id);
     }
   }
 
@@ -404,6 +400,9 @@ export function importSlice(
             const remapped: Intent = {
               ...intent,
               id: newId,
+              parent_id: intent.parent_id
+                ? rewriteId(intent.parent_id, intentIdMap)
+                : undefined,
               root_memory_ids: rewriteIds(intent.root_memory_ids, memIdMap),
             };
             const result = applyIntentCommand(currentIntent, {
@@ -423,6 +422,9 @@ export function importSlice(
     }
     const remapped: Intent = {
       ...intent,
+      parent_id: intent.parent_id
+        ? rewriteId(intent.parent_id, intentIdMap)
+        : undefined,
       root_memory_ids: rewriteIds(intent.root_memory_ids, memIdMap),
     };
     const result = applyIntentCommand(currentIntent, {
@@ -447,6 +449,9 @@ export function importSlice(
               ...task,
               id: newId,
               intent_id: rewriteId(task.intent_id, intentIdMap),
+              parent_id: task.parent_id
+                ? rewriteId(task.parent_id, taskIdMap)
+                : undefined,
               input_memory_ids: rewriteIds(task.input_memory_ids, memIdMap),
               output_memory_ids: rewriteIds(task.output_memory_ids, memIdMap),
             };
@@ -468,6 +473,9 @@ export function importSlice(
     const remapped: Task = {
       ...task,
       intent_id: rewriteId(task.intent_id, intentIdMap),
+      parent_id: task.parent_id
+        ? rewriteId(task.parent_id, taskIdMap)
+        : undefined,
       input_memory_ids: rewriteIds(task.input_memory_ids, memIdMap),
       output_memory_ids: rewriteIds(task.output_memory_ids, memIdMap),
     };

package/src/types.ts

@@ -46,6 +46,9 @@ export interface MemoryItem {
   conviction?: number; // 0..1 -- how sure was the author?
   importance?: number; // 0..1 -- how much attention does this need right now? (salience)
 
+  intent_id?: string; // intent that produced this item
+  task_id?: string; // task that produced this item
+
   meta?: {
     agent_id?: string;
     session_id?: string;
@@ -181,6 +184,11 @@ export interface MemoryFilter {
     importance?: { min?: number; max?: number };
   };
 
+  intent_id?: string; // exact match on intent_id
+  intent_ids?: string[]; // match any of these intent_ids
+  task_id?: string; // exact match on task_id
+  task_ids?: string[]; // match any of these task_ids
+
   has_parent?: string; // sugar for parents.includes
   is_root?: boolean; // sugar for parents.count.max = 0
   parents?: {

package/tests/bugfix-holes.test.ts

@@ -621,13 +621,13 @@ describe("resolveContradiction with multiple CONTRADICTS edges", () => {
 });
 
 // =========================================================================
-// 10. exportSlice with include_related_intents via meta.creation_intent_id
+// 10. exportSlice with include_related_intents via intent_id
 // =========================================================================
 
-describe("exportSlice walks meta.creation_intent_id", () => {
-  it("includes intents referenced by memory meta", () => {
+describe("exportSlice walks intent_id", () => {
+  it("includes intents referenced by memory intent_id", () => {
     const memState = stateWith([
-      makeItem("m1", { meta: { creation_intent_id: "i1" } }),
+      makeItem("m1", { intent_id: "i1" }),
     ]);
     let intentState = createIntentState();
     const intent = createIntent({
@@ -653,13 +653,13 @@ describe("exportSlice walks meta.creation_intent_id", () => {
 });
 
 // =========================================================================
-// 11. exportSlice with include_related_tasks via meta.creation_task_id
+// 11. exportSlice with include_related_tasks via task_id
 // =========================================================================
 
-describe("exportSlice walks meta.creation_task_id", () => {
-  it("includes tasks referenced by memory meta", () => {
+describe("exportSlice walks task_id", () => {
+  it("includes tasks referenced by memory task_id", () => {
     const memState = stateWith([
-      makeItem("m1", { meta: { creation_task_id: "t1" } }),
+      makeItem("m1", { task_id: "t1" }),
     ]);
     const intentState = createIntentState();
     let taskState = createTaskState();

package/tests/cross-graph-fields.test.ts

@@ -0,0 +1,378 @@
+import { describe, it, expect } from "vitest";
+import { createGraphState } from "../src/graph.js";
+import { applyCommand } from "../src/reducer.js";
+import { getItems } from "../src/query.js";
+import {
+  createIntentState,
+  createIntent,
+  applyIntentCommand,
+  getIntents,
+  getIntentById,
+  getChildIntents,
+} from "../src/intent.js";
+import {
+  createTaskState,
+  createTask,
+  applyTaskCommand,
+  getTasks,
+  getTaskById,
+  getChildTasks,
+} from "../src/task.js";
+import { exportSlice, importSlice } from "../src/transplant.js";
+import type { MemoryItem, GraphState } from "../src/types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeItem(
+  id: string,
+  overrides: Partial<MemoryItem> = {},
+): MemoryItem {
+  return {
+    id,
+    scope: "test",
+    kind: "observation",
+    content: { text: `item ${id}` },
+    author: "agent:test",
+    source_kind: "observed",
+    authority: 0.8,
+    ...overrides,
+  };
+}
+
+function stateWith(items: MemoryItem[]): GraphState {
+  let state = createGraphState();
+  for (const item of items) {
+    state = applyCommand(state, { type: "memory.create", item }).state;
+  }
+  return state;
+}
+
+// =========================================================================
+// MemoryFilter: intent_id / task_id exact match
+// =========================================================================
+
+describe("MemoryFilter intent_id and task_id", () => {
+  it("filters by exact intent_id", () => {
+    const state = stateWith([
+      makeItem("m1", { intent_id: "i1" }),
+      makeItem("m2", { intent_id: "i2" }),
+      makeItem("m3"),
+    ]);
+
+    const results = getItems(state, { intent_id: "i1" });
+    expect(results.map((i) => i.id)).toEqual(["m1"]);
+  });
+
+  it("filters by exact task_id", () => {
+    const state = stateWith([
+      makeItem("m1", { task_id: "t1" }),
+      makeItem("m2", { task_id: "t2" }),
+      makeItem("m3"),
+    ]);
+
+    const results = getItems(state, { task_id: "t1" });
+    expect(results.map((i) => i.id)).toEqual(["m1"]);
+  });
+
+  it("excludes items without intent_id when filtering", () => {
+    const state = stateWith([
+      makeItem("m1"),
+      makeItem("m2", { intent_id: "i1" }),
+    ]);
+
+    const results = getItems(state, { intent_id: "i1" });
+    expect(results.length).toBe(1);
+    expect(results[0].id).toBe("m2");
+  });
+});
+
+// =========================================================================
+// MemoryFilter: intent_ids / task_ids (any-of)
+// =========================================================================
+
+describe("MemoryFilter intent_ids and task_ids", () => {
+  it("filters by any of intent_ids", () => {
+    const state = stateWith([
+      makeItem("m1", { intent_id: "i1" }),
+      makeItem("m2", { intent_id: "i2" }),
+      makeItem("m3", { intent_id: "i3" }),
+      makeItem("m4"),
+    ]);
+
+    const results = getItems(state, { intent_ids: ["i1", "i3"] });
+    expect(results.map((i) => i.id).sort()).toEqual(["m1", "m3"]);
+  });
+
+  it("filters by any of task_ids", () => {
+    const state = stateWith([
+      makeItem("m1", { task_id: "t1" }),
+      makeItem("m2", { task_id: "t2" }),
+      makeItem("m3", { task_id: "t3" }),
+    ]);
+
+    const results = getItems(state, { task_ids: ["t2", "t3"] });
+    expect(results.map((i) => i.id).sort()).toEqual(["m2", "m3"]);
+  });
+
+  it("excludes items without task_id when using task_ids filter", () => {
+    const state = stateWith([
+      makeItem("m1"),
+      makeItem("m2", { task_id: "t1" }),
+    ]);
+
+    const results = getItems(state, { task_ids: ["t1"] });
+    expect(results.length).toBe(1);
+    expect(results[0].id).toBe("m2");
+  });
+
+  it("combines intent_id and task_id filters (AND)", () => {
+    const state = stateWith([
+      makeItem("m1", { intent_id: "i1", task_id: "t1" }),
+      makeItem("m2", { intent_id: "i1", task_id: "t2" }),
+      makeItem("m3", { intent_id: "i2", task_id: "t1" }),
+    ]);
+
+    const results = getItems(state, { intent_id: "i1", task_id: "t1" });
+    expect(results.map((i) => i.id)).toEqual(["m1"]);
+  });
+});
+
+// =========================================================================
+// IntentFilter: parent_id / is_root
+// =========================================================================
+
+describe("IntentFilter parent_id and is_root", () => {
+  function setupIntents() {
+    let state = createIntentState();
+    const root = createIntent({
+      id: "i1",
+      label: "investigate",
+      priority: 0.9,
+      owner: "user:laz",
+    });
+    const child1 = createIntent({
+      id: "i2",
+      parent_id: "i1",
+      label: "find associates",
+      priority: 0.7,
+      owner: "user:laz",
+    });
+    const child2 = createIntent({
+      id: "i3",
+      parent_id: "i1",
+      label: "map finances",
+      priority: 0.8,
+      owner: "user:laz",
+    });
+    state = applyIntentCommand(state, { type: "intent.create", intent: root }).state;
+    state = applyIntentCommand(state, { type: "intent.create", intent: child1 }).state;
+    state = applyIntentCommand(state, { type: "intent.create", intent: child2 }).state;
+    return state;
+  }
+
+  it("filters by parent_id", () => {
+    const state = setupIntents();
+    const children = getIntents(state, { parent_id: "i1" });
+    expect(children.map((i) => i.id).sort()).toEqual(["i2", "i3"]);
+  });
+
+  it("is_root: true returns only root intents", () => {
+    const state = setupIntents();
+    const roots = getIntents(state, { is_root: true });
+    expect(roots.map((i) => i.id)).toEqual(["i1"]);
+  });
+
+  it("is_root: false returns only child intents", () => {
+    const state = setupIntents();
+    const children = getIntents(state, { is_root: false });
+    expect(children.map((i) => i.id).sort()).toEqual(["i2", "i3"]);
+  });
+
+  it("getChildIntents returns children of a parent", () => {
+    const state = setupIntents();
+    const children = getChildIntents(state, "i1");
+    expect(children.map((i) => i.id).sort()).toEqual(["i2", "i3"]);
+  });
+
+  it("getChildIntents returns empty for leaf intents", () => {
+    const state = setupIntents();
+    const children = getChildIntents(state, "i2");
+    expect(children).toEqual([]);
+  });
+});
+
+// =========================================================================
+// TaskFilter: parent_id / is_root
+// =========================================================================
+
+describe("TaskFilter parent_id and is_root", () => {
+  function setupTasks() {
+    let state = createTaskState();
+    const root = createTask({
+      id: "t1",
+      intent_id: "i1",
+      action: "search",
+      priority: 0.9,
+    });
+    const sub1 = createTask({
+      id: "t2",
+      intent_id: "i1",
+      parent_id: "t1",
+      action: "parse_profile",
+      priority: 0.7,
+    });
+    const sub2 = createTask({
+      id: "t3",
+      intent_id: "i1",
+      parent_id: "t1",
+      action: "extract_contacts",
+      priority: 0.6,
+    });
+    state = applyTaskCommand(state, { type: "task.create", task: root }).state;
+    state = applyTaskCommand(state, { type: "task.create", task: sub1 }).state;
+    state = applyTaskCommand(state, { type: "task.create", task: sub2 }).state;
+    return state;
+  }
+
+  it("filters by parent_id", () => {
+    const state = setupTasks();
+    const subs = getTasks(state, { parent_id: "t1" });
+    expect(subs.map((t) => t.id).sort()).toEqual(["t2", "t3"]);
+  });
+
+  it("is_root: true returns only root tasks", () => {
+    const state = setupTasks();
+    const roots = getTasks(state, { is_root: true });
+    expect(roots.map((t) => t.id)).toEqual(["t1"]);
+  });
+
+  it("is_root: false returns only subtasks", () => {
+    const state = setupTasks();
+    const subs = getTasks(state, { is_root: false });
+    expect(subs.map((t) => t.id).sort()).toEqual(["t2", "t3"]);
+  });
+
+  it("getChildTasks returns children of a parent", () => {
+    const state = setupTasks();
+    const subs = getChildTasks(state, "t1");
+    expect(subs.map((t) => t.id).sort()).toEqual(["t2", "t3"]);
+  });
+
+  it("getChildTasks returns empty for leaf tasks", () => {
+    const state = setupTasks();
+    const subs = getChildTasks(state, "t3");
+    expect(subs).toEqual([]);
+  });
+});
+
+// =========================================================================
+// Transplant: parent_id rewriting
+// =========================================================================
+
+describe("transplant rewrites parent_id", () => {
+  it("rewrites intent parent_id on re-id", () => {
+    const memState = createGraphState();
+    let intentState = createIntentState();
+    const taskState = createTaskState();
+
+    // create parent intent in destination
+    const existing = createIntent({
+      id: "i1",
+      label: "existing",
+      priority: 0.5,
+      owner: "user:laz",
+    });
+    intentState = applyIntentCommand(intentState, {
+      type: "intent.create",
+      intent: existing,
+    }).state;
+
+    // slice has same id but different data, plus a child
+    const sliceParent = createIntent({
+      id: "i1",
+      label: "different",
+      priority: 0.9,
+      owner: "user:laz",
+    });
+    const sliceChild = createIntent({
+      id: "i2",
+      parent_id: "i1",
+      label: "child",
+      priority: 0.7,
+      owner: "user:laz",
+    });
+
+    const result = importSlice(memState, intentState, taskState, {
+      memories: [],
+      edges: [],
+      intents: [sliceParent, sliceChild],
+      tasks: [],
+    }, {
+      skipExistingIds: true,
+      shallowCompareExisting: true,
+      reIdOnDifference: true,
+    });
+
+    // parent got re-id'd
+    const newParentId = result.report.created.intents[0];
+    expect(newParentId).not.toBe("i1");
+
+    // child should reference the new parent id
+    const child = result.intentState.intents.get("i2")!;
+    expect(child.parent_id).toBe(newParentId);
+  });
+
+  it("rewrites task parent_id on re-id", () => {
+    const memState = createGraphState();
+    const intentState = createIntentState();
+    let taskState = createTaskState();
+
+    // create parent task in destination
+    const existing = createTask({
+      id: "t1",
+      intent_id: "i1",
+      action: "search",
+      priority: 0.5,
+    });
+    taskState = applyTaskCommand(taskState, {
+      type: "task.create",
+      task: existing,
+    }).state;
+
+    // slice has same id but different data, plus a child
+    const sliceParent = createTask({
+      id: "t1",
+      intent_id: "i1",
+      action: "different_search",
+      priority: 0.9,
+    });
+    const sliceChild = createTask({
+      id: "t2",
+      intent_id: "i1",
+      parent_id: "t1",
+      action: "parse",
+      priority: 0.7,
+    });
+
+    const result = importSlice(memState, intentState, taskState, {
+      memories: [],
+      edges: [],
+      intents: [],
+      tasks: [sliceParent, sliceChild],
+    }, {
+      skipExistingIds: true,
+      shallowCompareExisting: true,
+      reIdOnDifference: true,
+    });
+
+    // parent got re-id'd
+    const newParentId = result.report.created.tasks[0];
+    expect(newParentId).not.toBe("t1");
+
+    // child should reference the new parent id
+    const child = result.taskState.tasks.get("t2")!;
+    expect(child.parent_id).toBe(newParentId);
+  });
+});