Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

docs: add implementation plans for patches 1-4

riley0227fb63b3cd0886
diff --git a/docs/plans/2026-03-07-decision-retrieval-cli-qmd.md b/docs/plans/2026-03-07-decision-retrieval-cli-qmd.md
new file mode 100644
index 00000000..48654e80
--- /dev/null
+++ b/docs/plans/2026-03-07-decision-retrieval-cli-qmd.md
@@ -0,0 +1,1156 @@
+# Decision Retrieval, CLI Usability & QMD Integration — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make recorded decisions retrievable via search/query, improve CLI usability (short IDs, filters, decisions command), and integrate qmd behind a unified `ix text` command.
+
+**Architecture:** Two sequential patches. Patch 1 is backend + CLI changes to surface decisions and add usability features. Patch 2 adds `ix text` as a thin CLI wrapper over `ripgrep` for fast lexical search (qmd is an external package that doesn't exist in this project yet and is markdown-specific — ripgrep is a better fit for general codebase text search). Both patches touch the same file set: backend Scala routes/query layer, CLI commands, client API, format module, MCP server, and types.
+
+**Tech Stack:** Scala 2.13 + Cats Effect 3 + http4s + Circe (backend), TypeScript + Commander + MCP SDK (CLI), ArangoDB (graph DB), ripgrep (text search)
+
+---
+
+## Patch 1 — Decision Retrieval + CLI Usability
+
+### Task 1: Backend — Add `/v1/decisions` endpoint
+
+Decisions are already stored as nodes with `kind = "decision"`. We need a dedicated listing endpoint.
+
+**Files:**
+- Create: `memory-layer/src/main/scala/ix/memory/api/DecisionRoutes.scala`
+- Modify: `memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala:9` (add method)
+- Modify: `memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala` (implement method)
+- Modify: `memory-layer/src/main/scala/ix/memory/api/Routes.scala:42-44` (wire new routes)
+- Modify: `memory-layer/src/main/scala/ix/memory/Main.scala:45` (pass to Routes)
+
+**Step 1: Add `listDecisions` to the GraphQueryApi trait**
+
+In `memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala`, add after line 9:
+
+```scala
+def listDecisions(limit: Int = 50, topic: Option[String] = None): IO[Vector[GraphNode]]
+```
+
+**Step 2: Implement `listDecisions` in ArangoGraphQueryApi**
+
+In `memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala`, add after the `findNodesByKind` method (after line 46):
+
+```scala
+override def listDecisions(limit: Int = 50, topic: Option[String] = None): IO[Vector[GraphNode]] = {
+ val topicFilter = topic match {
+ case Some(t) =>
+ """AND (
+ | CONTAINS(LOWER(TO_STRING(n.attrs.title)), LOWER(@topic))
+ | OR CONTAINS(LOWER(TO_STRING(n.attrs.rationale)), LOWER(@topic))
+ |)""".stripMargin
+ case None => ""
+ }
+ val aql =
+ s"""FOR n IN nodes
+ | FILTER n.kind == "decision"
+ | AND n.deleted_rev == null
+ | $topicFilter
+ | SORT n.created_at DESC
+ | LIMIT @limit
+ | RETURN n""".stripMargin
+ val binds = scala.collection.mutable.Map[String, AnyRef](
+ "limit" -> Int.box(limit).asInstanceOf[AnyRef]
+ )
+ topic.foreach(t => binds += ("topic" -> t.asInstanceOf[AnyRef]))
+ client.query(aql, binds.toMap).map(_.flatMap(parseNode).toVector)
+}
+```
+
+**Step 3: Create DecisionRoutes.scala**
+
+Create `memory-layer/src/main/scala/ix/memory/api/DecisionRoutes.scala`:
+
+```scala
+package ix.memory.api
+
+import cats.effect.IO
+import io.circe.Decoder
+import io.circe.generic.semiauto.deriveDecoder
+import io.circe.syntax._
+import org.http4s.HttpRoutes
+import org.http4s.circe.CirceEntityCodec._
+import org.http4s.dsl.io._
+
+import ix.memory.db.GraphQueryApi
+
+case class DecisionListRequest(limit: Option[Int] = None, topic: Option[String] = None)
+
+object DecisionListRequest {
+ implicit val decoder: Decoder[DecisionListRequest] = deriveDecoder[DecisionListRequest]
+}
+
+class DecisionRoutes(queryApi: GraphQueryApi) {
+
+ val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
+ case req @ POST -> Root / "v1" / "decisions" =>
+ (for {
+ body <- req.as[DecisionListRequest]
+ nodes <- queryApi.listDecisions(body.limit.getOrElse(50), body.topic)
+ resp <- Ok(nodes.asJson)
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+ }
+}
+```
+
+**Step 4: Wire DecisionRoutes into Routes.scala**
+
+In `memory-layer/src/main/scala/ix/memory/api/Routes.scala`:
+- After line 40, add: `val decisionListRoutes = new DecisionRoutes(queryApi).routes`
+- In the combinator chain (line 42-44), add `<+> decisionListRoutes` at the end
+
+**Step 5: Verify backend compiles**
+
+Run: `cd memory-layer && sbt compile`
+Expected: BUILD SUCCESSFUL
+
+**Step 6: Commit**
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/api/DecisionRoutes.scala \
+ memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala \
+ memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala \
+ memory-layer/src/main/scala/ix/memory/api/Routes.scala
+git commit -m "feat: add /v1/decisions endpoint for listing decisions with optional topic filter"
+```
+
+---
+
+### Task 2: Backend — Add `/v1/search` filters (kind, language, as-of)
+
+**Files:**
+- Modify: `memory-layer/src/main/scala/ix/memory/api/SearchRoutes.scala:14-18` (extend request model)
+- Modify: `memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala:10` (extend signature)
+- Modify: `memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala:48-105` (filtered search)
+
+**Step 1: Extend SearchRequest model**
+
+In `memory-layer/src/main/scala/ix/memory/api/SearchRoutes.scala`, replace lines 14-18:
+
+```scala
+case class SearchRequest(
+ term: String,
+ limit: Option[Int] = None,
+ kind: Option[String] = None,
+ language: Option[String] = None,
+ asOfRev: Option[Long] = None
+)
+
+object SearchRequest {
+ implicit val decoder: Decoder[SearchRequest] = deriveDecoder[SearchRequest]
+}
+```
+
+**Step 2: Update SearchRoutes handler to pass filters**
+
+Replace the route handler (lines 22-29):
+
+```scala
+val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
+ case req @ POST -> Root / "v1" / "search" =>
+ (for {
+ body <- req.as[SearchRequest]
+ nodes <- queryApi.searchNodes(
+ body.term,
+ body.limit.getOrElse(20),
+ body.kind,
+ body.language,
+ body.asOfRev.map(Rev(_))
+ )
+ resp <- Ok(nodes.asJson)
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+}
+```
+
+Add `import ix.memory.model.Rev` to imports if not present.
+
+**Step 3: Extend GraphQueryApi trait signature**
+
+In `GraphQueryApi.scala`, replace the `searchNodes` signature (line 10):
+
+```scala
+def searchNodes(text: String, limit: Int = 20,
+ kind: Option[String] = None, language: Option[String] = None,
+ asOfRev: Option[Rev] = None): IO[Vector[GraphNode]]
+```
+
+**Step 4: Implement filtered search in ArangoGraphQueryApi**
+
+Replace the `searchNodes` method (lines 48-105). The key changes:
+- Add optional `FILTER n.kind == @kind` when kind is provided
+- Add optional `FILTER CONTAINS(LOWER(n.provenance.source_uri), LOWER(@language))` when language is provided (language maps to file extension in source_uri)
+- Use MVCC filter with asOfRev when provided, otherwise use `deleted_rev == null`
+
+```scala
+override def searchNodes(
+ text: String,
+ limit: Int = 20,
+ kind: Option[String] = None,
+ language: Option[String] = None,
+ asOfRev: Option[Rev] = None
+): IO[Vector[GraphNode]] = {
+ val liveFilter = asOfRev match {
+ case Some(r) => s"AND n.created_rev <= ${r.value} AND (n.deleted_rev == null OR ${r.value} < n.deleted_rev)"
+ case None => "AND n.deleted_rev == null"
+ }
+ val claimLiveFilter = asOfRev match {
+ case Some(r) => s"AND c.created_rev <= ${r.value} AND (c.deleted_rev == null OR ${r.value} < c.deleted_rev)"
+ case None => "AND c.deleted_rev == null"
+ }
+ val kindFilter = kind.map(_ => "FILTER n2.kind == @kind").getOrElse("")
+ val langFilter = language.map(_ => "FILTER CONTAINS(LOWER(TO_STRING(n2.provenance.source_uri)), LOWER(@language))").getOrElse("")
+
+ val aql =
+ s"""LET name_matches = (
+ | FOR n IN nodes
+ | FILTER CONTAINS(LOWER(n.name), LOWER(@text))
+ | $liveFilter
+ | RETURN DISTINCT n.logical_id
+ |)
+ |
+ |LET provenance_matches = (
+ | FOR n IN nodes
+ | FILTER CONTAINS(LOWER(n.provenance.source_uri), LOWER(@text))
+ | $liveFilter
+ | RETURN DISTINCT n.logical_id
+ |)
+ |
+ |LET claim_matches = (
+ | FOR c IN claims
+ | FILTER (
+ | CONTAINS(LOWER(c.field), LOWER(@text))
+ | OR CONTAINS(LOWER(TO_STRING(c.value)), LOWER(@text))
+ | )
+ | $claimLiveFilter
+ | RETURN DISTINCT c.entity_id
+ |)
+ |
+ |LET decision_matches = (
+ | FOR n IN nodes
+ | FILTER n.kind == "decision"
+ | $liveFilter
+ | AND (
+ | CONTAINS(LOWER(TO_STRING(n.attrs.title)), LOWER(@text))
+ | OR CONTAINS(LOWER(TO_STRING(n.attrs.rationale)), LOWER(@text))
+ | )
+ | RETURN DISTINCT n.logical_id
+ |)
+ |
+ |LET attr_matches = (
+ | FOR n IN nodes
+ | FILTER CONTAINS(LOWER(TO_STRING(n.attrs)), LOWER(@text))
+ | $liveFilter
+ | RETURN DISTINCT n.logical_id
+ |)
+ |
+ |LET all_ids = UNION_DISTINCT(name_matches, provenance_matches, claim_matches, decision_matches, attr_matches)
+ |
+ |FOR id IN all_ids
+ | FOR n2 IN nodes
+ | FILTER n2.logical_id == id AND n2.deleted_rev == null
+ | $kindFilter
+ | $langFilter
+ | LET symbol_priority = n2.kind IN ["function", "method", "class", "trait", "object", "interface"] ? 0 : 1
+ | SORT symbol_priority ASC, n2.name ASC
+ | LIMIT @limit
+ | RETURN n2""".stripMargin
+
+ val binds = scala.collection.mutable.Map[String, AnyRef](
+ "text" -> text.asInstanceOf[AnyRef],
+ "limit" -> Int.box(limit).asInstanceOf[AnyRef]
+ )
+ kind.foreach(k => binds += ("kind" -> k.asInstanceOf[AnyRef]))
+ language.foreach(l => binds += ("language" -> l.asInstanceOf[AnyRef]))
+
+ client.query(aql, binds.toMap).map(_.flatMap(parseNode).toVector)
+}
+```
+
+**Step 5: Verify backend compiles**
+
+Run: `cd memory-layer && sbt compile`
+Expected: BUILD SUCCESSFUL
+
+**Step 6: Commit**
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/api/SearchRoutes.scala \
+ memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala \
+ memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala
+git commit -m "feat: add --kind, --language, --as-of filters to /v1/search endpoint"
+```
+
+---
+
+### Task 3: Backend — Add `/v1/resolve-prefix` endpoint for short ID resolution
+
+**Files:**
+- Modify: `memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala` (add method)
+- Modify: `memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala` (implement)
+- Modify: `memory-layer/src/main/scala/ix/memory/api/EntityRoutes.scala` (add prefix route)
+
+**Step 1: Add `resolvePrefix` to GraphQueryApi trait**
+
+```scala
+def resolvePrefix(prefix: String): IO[Vector[NodeId]]
+```
+
+**Step 2: Implement in ArangoGraphQueryApi**
+
+```scala
+override def resolvePrefix(prefix: String): IO[Vector[NodeId]] =
+ client.query(
+ """FOR n IN nodes
+ | FILTER n.deleted_rev == null
+ | AND STARTS_WITH(n.logical_id, @prefix)
+ | COLLECT lid = n.logical_id
+ | LIMIT 10
+ | RETURN lid""".stripMargin,
+ Map("prefix" -> prefix.asInstanceOf[AnyRef])
+ ).map(_.flatMap(_.asString).flatMap(s =>
+ scala.util.Try(java.util.UUID.fromString(s)).toOption.map(NodeId(_))
+ ).toVector)
+```
+
+**Step 3: Add prefix resolution route to EntityRoutes**
+
+In `EntityRoutes.scala`, add a new route case before the existing `UUIDVar` case (inside the `HttpRoutes.of[IO]` block). This approach: if the path segment is a full UUID, use the existing logic; otherwise, treat it as a prefix.
+
+Replace the entity route matcher (line 39) with a more flexible approach. Add a new route:
+
+```scala
+// GET /v1/resolve-prefix/:prefix
+case GET -> Root / "v1" / "resolve-prefix" / prefix =>
+ (for {
+ ids <- queryApi.resolvePrefix(prefix)
+ resp <- ids.size match {
+ case 0 => NotFound(Json.obj("error" -> s"No entity matches prefix: $prefix".asJson))
+ case 1 => Ok(Json.obj("id" -> ids.head.value.toString.asJson))
+ case _ => Ok(Json.obj(
+ "error" -> "ambiguous".asJson,
+ "matches" -> ids.map(_.value.toString).asJson
+ ))
+ }
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+```
+
+Add `import io.circe.Json` and `import io.circe.syntax._` to EntityRoutes if not present.
+
+**Step 4: Verify backend compiles**
+
+Run: `cd memory-layer && sbt compile`
+
+**Step 5: Commit**
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala \
+ memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala \
+ memory-layer/src/main/scala/ix/memory/api/EntityRoutes.scala
+git commit -m "feat: add /v1/resolve-prefix endpoint for short ID resolution"
+```
+
+---
+
+### Task 4: CLI — Add `ix decisions` command
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/decisions.ts`
+- Modify: `ix-cli/src/client/api.ts:34` (add `listDecisions` method)
+- Modify: `ix-cli/src/cli/format.ts` (add `formatDecisions`)
+- Modify: `ix-cli/src/cli/main.ts` (register command)
+
+**Step 1: Add `listDecisions` to API client**
+
+In `ix-cli/src/client/api.ts`, add after `search()` (after line 34):
+
+```typescript
+async listDecisions(opts?: { limit?: number; topic?: string }): Promise<GraphNode[]> {
+ return this.post("/v1/decisions", { limit: opts?.limit, topic: opts?.topic });
+}
+```
+
+**Step 2: Add `formatDecisions` to format.ts**
+
+In `ix-cli/src/cli/format.ts`, add after `formatNodes` (after line 93):
+
+```typescript
+export function formatDecisions(nodes: any[], format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(nodes, null, 2));
+ return;
+ }
+ if (nodes.length === 0) {
+ console.log("No decisions found.");
+ return;
+ }
+ for (const n of nodes) {
+ const shortId = n.id.length > 8 ? n.id.slice(0, 8) : n.id;
+ const title = n.attrs?.title ?? n.name ?? "(untitled)";
+ const rationale = n.attrs?.rationale ?? "";
+ console.log(
+ ` ${chalk.blue("*")} ${chalk.dim(shortId)} ${chalk.bold(title)}`
+ );
+ if (rationale) {
+ console.log(` ${chalk.gray(rationale)}`);
+ }
+ }
+}
+```
+
+**Step 3: Create decisions command**
+
+Create `ix-cli/src/cli/commands/decisions.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatDecisions } from "../format.js";
+
+export function registerDecisionsCommand(program: Command): void {
+ program
+ .command("decisions")
+ .description("List recorded design decisions")
+ .option("--limit <n>", "Max results", "50")
+ .option("--topic <topic>", "Filter by topic keyword")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (opts: { limit: string; topic?: string; format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const nodes = await client.listDecisions({
+ limit: parseInt(opts.limit, 10),
+ topic: opts.topic,
+ });
+ formatDecisions(nodes, opts.format);
+ });
+}
+```
+
+**Step 4: Register in main.ts**
+
+In `ix-cli/src/cli/main.ts`:
+- Add import: `import { registerDecisionsCommand } from "./commands/decisions.js";`
+- Add registration after `registerDecideCommand(program);` (after line 25): `registerDecisionsCommand(program);`
+
+**Step 5: Verify CLI compiles**
+
+Run: `cd ix-cli && npx tsc --noEmit`
+Expected: No errors
+
+**Step 6: Commit**
+
+```bash
+git add ix-cli/src/cli/commands/decisions.ts \
+ ix-cli/src/client/api.ts \
+ ix-cli/src/cli/format.ts \
+ ix-cli/src/cli/main.ts
+git commit -m "feat: add ix decisions command with --topic and --limit filters"
+```
+
+---
+
+### Task 5: CLI — Add search filters (--kind, --language, --as-of)
+
+**Files:**
+- Modify: `ix-cli/src/cli/commands/search.ts` (add options)
+- Modify: `ix-cli/src/client/api.ts:32-34` (extend search signature)
+
+**Step 1: Extend client search method**
+
+In `ix-cli/src/client/api.ts`, replace lines 32-34:
+
+```typescript
+async search(
+ term: string,
+ opts?: { limit?: number; kind?: string; language?: string; asOfRev?: number }
+): Promise<GraphNode[]> {
+ return this.post("/v1/search", {
+ term,
+ limit: opts?.limit,
+ kind: opts?.kind,
+ language: opts?.language,
+ asOfRev: opts?.asOfRev,
+ });
+}
+```
+
+**Step 2: Update search command to pass filters**
+
+Replace `ix-cli/src/cli/commands/search.ts` entirely:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatNodes } from "../format.js";
+
+export function registerSearchCommand(program: Command): void {
+ program
+ .command("search <term>")
+ .description("Search the knowledge graph by term")
+ .option("--limit <n>", "Max results", "20")
+ .option("--kind <kind>", "Filter by node kind (e.g. method, class, decision)")
+ .option("--language <lang>", "Filter by language/file extension (e.g. scala, ts)")
+ .option("--as-of <rev>", "Search as of a specific revision")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (term: string, opts: {
+ limit: string; kind?: string; language?: string; asOf?: string; format: string
+ }) => {
+ const client = new IxClient(getEndpoint());
+ const nodes = await client.search(term, {
+ limit: parseInt(opts.limit, 10),
+ kind: opts.kind,
+ language: opts.language,
+ asOfRev: opts.asOf ? parseInt(opts.asOf, 10) : undefined,
+ });
+ formatNodes(nodes, opts.format);
+ });
+}
+```
+
+**Step 3: Update MCP ix_search tool to pass filters**
+
+In `ix-cli/src/mcp/server.ts`, update the ix_search tool definition (around line 145-169):
+- Add `kind`, `language`, `asOfRev` as optional z.string()/z.number() params
+- Pass them to `client.search(term, { limit, kind, language, asOfRev })`
+
+**Step 4: Verify CLI compiles**
+
+Run: `cd ix-cli && npx tsc --noEmit`
+
+**Step 5: Commit**
+
+```bash
+git add ix-cli/src/cli/commands/search.ts \
+ ix-cli/src/client/api.ts \
+ ix-cli/src/mcp/server.ts
+git commit -m "feat: add --kind, --language, --as-of filters to ix search"
+```
+
+---
+
+### Task 6: CLI — Short ID prefix resolution for entity, history, expand
+
+**Files:**
+- Modify: `ix-cli/src/client/api.ts` (add `resolvePrefix` method)
+- Modify: `ix-cli/src/cli/commands/entity.ts` (resolve before lookup)
+- Modify: `ix-cli/src/cli/commands/history.ts` (resolve before lookup)
+- Modify: `ix-cli/src/mcp/server.ts` (update ix_entity, ix_expand, ix_history tools)
+
+**Step 1: Add `resolvePrefix` to API client**
+
+In `ix-cli/src/client/api.ts`, add method:
+
+```typescript
+async resolvePrefix(prefix: string): Promise<string> {
+ // If it's already a full UUID, return as-is
+ const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+ if (uuidPattern.test(prefix)) return prefix;
+
+ const result = await this.get<{ id?: string; error?: string; matches?: string[] }>(
+ `/v1/resolve-prefix/${encodeURIComponent(prefix)}`
+ );
+ if (result.id) return result.id;
+ if (result.error === "ambiguous") {
+ throw new Error(`Ambiguous prefix "${prefix}" — matches: ${result.matches?.join(", ")}`);
+ }
+ throw new Error(`No entity found for prefix: ${prefix}`);
+}
+```
+
+**Step 2: Update entity command**
+
+Replace `ix-cli/src/cli/commands/entity.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+
+export function registerEntityCommand(program: Command): void {
+ program
+ .command("entity <id>")
+ .description("Get entity details with claims and edges")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (id: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const resolvedId = await client.resolvePrefix(id);
+ const result = await client.entity(resolvedId);
+ if (opts.format === "json") {
+ console.log(JSON.stringify(result, null, 2));
+ } else {
+ console.log(`Entity: ${result.node.id} (${result.node.kind})`);
+ console.log(`Claims: ${(result.claims as unknown[]).length}`);
+ console.log(`Edges: ${(result.edges as unknown[]).length}`);
+ }
+ });
+}
+```
+
+**Step 3: Update history command**
+
+Replace `ix-cli/src/cli/commands/history.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+
+export function registerHistoryCommand(program: Command): void {
+ program
+ .command("history <entityId>")
+ .description("Show provenance chain for an entity")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (entityId: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const resolvedId = await client.resolvePrefix(entityId);
+ const result = await client.provenance(resolvedId);
+ if (opts.format === "json") {
+ console.log(JSON.stringify(result, null, 2));
+ } else {
+ console.log(JSON.stringify(result, null, 2));
+ }
+ });
+}
+```
+
+**Step 4: Update MCP tools (ix_entity, ix_expand, ix_history)**
+
+In `ix-cli/src/mcp/server.ts`, for each of these three tools, add `const resolvedId = await client.resolvePrefix(id);` before the API call and use `resolvedId` instead of raw `id`.
+
+**Step 5: Verify CLI compiles**
+
+Run: `cd ix-cli && npx tsc --noEmit`
+
+**Step 6: Commit**
+
+```bash
+git add ix-cli/src/cli/commands/entity.ts \
+ ix-cli/src/cli/commands/history.ts \
+ ix-cli/src/client/api.ts \
+ ix-cli/src/mcp/server.ts
+git commit -m "feat: add short-ID prefix resolution for entity, history, and expand commands"
+```
+
+---
+
+### Task 7: CLI — Update `formatNodes` to show decision kind distinctly
+
+**Files:**
+- Modify: `ix-cli/src/cli/format.ts:87-92` (enhance node display for decisions)
+
+**Step 1: Update formatNodes**
+
+Replace lines 87-92 in `ix-cli/src/cli/format.ts`:
+
+```typescript
+for (const n of nodes) {
+ const shortId = n.id.length > 8 ? n.id.slice(0, 8) : n.id;
+ if (n.kind === "decision") {
+ const title = n.attrs?.title ?? n.name ?? "(untitled)";
+ console.log(
+ ` ${chalk.blue("decision")} ${chalk.dim(shortId)} ${title}`
+ );
+ } else {
+ console.log(
+ ` ${chalk.cyan(n.kind)} ${chalk.dim(shortId)} ${n.attrs?.name ?? n.name ?? JSON.stringify(n.attrs)}`
+ );
+ }
+}
+```
+
+**Step 2: Verify and commit**
+
+Run: `cd ix-cli && npx tsc --noEmit`
+
+```bash
+git add ix-cli/src/cli/format.ts
+git commit -m "feat: show decisions distinctly in search results with title instead of raw attrs"
+```
+
+---
+
+### Task 8: Tests — Add tests for new CLI features
+
+**Files:**
+- Modify: `ix-cli/src/cli/__tests__/format.test.ts` (add formatDecisions tests)
+
+**Step 1: Write tests for formatDecisions**
+
+Add to `ix-cli/src/cli/__tests__/format.test.ts`:
+
+```typescript
+describe("formatDecisions", () => {
+ it("should output JSON when format is json", () => {
+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+ const decisions = [
+ { id: "abc-123", kind: "decision", attrs: { title: "Use ArangoDB", rationale: "Supports MVCC" } }
+ ];
+ formatDecisions(decisions, "json");
+ expect(spy).toHaveBeenCalledWith(JSON.stringify(decisions, null, 2));
+ spy.mockRestore();
+ });
+
+ it("should show 'No decisions found.' for empty list", () => {
+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+ formatDecisions([], "text");
+ expect(spy).toHaveBeenCalledWith("No decisions found.");
+ spy.mockRestore();
+ });
+
+ it("should display title and rationale in text mode", () => {
+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+ const decisions = [
+ { id: "abc-12345-def", kind: "decision", attrs: { title: "Use ArangoDB", rationale: "Supports MVCC" } }
+ ];
+ formatDecisions(decisions, "text");
+ const output = spy.mock.calls.map(c => c[0]).join("\n");
+ expect(output).toContain("Use ArangoDB");
+ expect(output).toContain("Supports MVCC");
+ expect(output).toContain("abc-1234"); // short ID
+ spy.mockRestore();
+ });
+});
+```
+
+**Step 2: Run tests**
+
+Run: `cd ix-cli && npm test`
+Expected: All tests pass
+
+**Step 3: Commit**
+
+```bash
+git add ix-cli/src/cli/__tests__/format.test.ts
+git commit -m "test: add formatDecisions tests"
+```
+
+---
+
+### Task 9: MCP — Add ix_decisions tool + update ix_search
+
+**Files:**
+- Modify: `ix-cli/src/mcp/server.ts` (add ix_decisions tool)
+
+**Step 1: Add ix_decisions tool**
+
+In `ix-cli/src/mcp/server.ts`, add after the ix_search tool block:
+
+```typescript
+// --- ix_decisions -------------------------------------------------------------
+server.tool(
+ "ix_decisions",
+ "List recorded design decisions. Use this to review past architectural choices and their rationale.",
+ {
+ limit: z.optional(z.number()).describe("Max results (default 50)"),
+ topic: z.optional(z.string()).describe("Filter decisions by topic keyword"),
+ },
+ async ({ limit, topic }) => {
+ try {
+ const nodes = await client.listDecisions({ limit, topic });
+ return {
+ content: [
+ { type: "text" as const, text: JSON.stringify(nodes, null, 2) },
+ ],
+ };
+ } catch (err) {
+ return {
+ isError: true,
+ content: [
+ { type: "text" as const, text: `ix_decisions failed: ${String(err)}` },
+ ],
+ };
+ }
+ },
+);
+```
+
+**Step 2: Verify and commit**
+
+Run: `cd ix-cli && npx tsc --noEmit`
+
+```bash
+git add ix-cli/src/mcp/server.ts
+git commit -m "feat: add ix_decisions MCP tool and update ix_search with filter params"
+```
+
+---
+
+## Patch 2 — QMD Integration Behind the Ix CLI
+
+### Task 10: CLI — Add `ix text` command using ripgrep
+
+The spec calls for qmd integration, but qmd is a markdown-specific external package that doesn't exist in this project. For general codebase text/blob search, we use `ripgrep` (`rg`) — it's fast, ubiquitous, and produces structured JSON output. If the user later wants to swap the backend to qmd, the CLI interface stays the same.
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/text.ts`
+- Modify: `ix-cli/src/cli/main.ts` (register command)
+- Modify: `ix-cli/src/cli/format.ts` (add `formatTextResults`)
+
+**Step 1: Add formatTextResults to format.ts**
+
+In `ix-cli/src/cli/format.ts`, add:
+
+```typescript
+export interface TextResult {
+ path: string;
+ line: number;
+ snippet: string;
+ score?: number;
+ symbol?: string;
+}
+
+export function formatTextResults(results: TextResult[], format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(results, null, 2));
+ return;
+ }
+ if (results.length === 0) {
+ console.log("No text matches found.");
+ return;
+ }
+ for (const r of results) {
+ console.log(
+ ` ${chalk.dim(r.path)}${chalk.cyan(":" + r.line)} ${r.snippet.trim()}`
+ );
+ }
+}
+```
+
+**Step 2: Create text command**
+
+Create `ix-cli/src/cli/commands/text.ts`:
+
+```typescript
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { Command } from "commander";
+import { formatTextResults, type TextResult } from "../format.js";
+
+const execFileAsync = promisify(execFile);
+
+export function registerTextCommand(program: Command): void {
+ program
+ .command("text <term>")
+ .description("Fast lexical/text search across the codebase (uses ripgrep)")
+ .option("--limit <n>", "Max results", "20")
+ .option("--path <dir>", "Restrict search to a directory", ".")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (term: string, opts: { limit: string; path: string; format: string }) => {
+ const limit = parseInt(opts.limit, 10);
+ try {
+ const { stdout } = await execFileAsync("rg", [
+ "--json",
+ "--max-count", String(limit),
+ "--no-heading",
+ term,
+ opts.path,
+ ], { maxBuffer: 10 * 1024 * 1024 });
+
+ const results: TextResult[] = [];
+ for (const line of stdout.split("\n")) {
+ if (!line.trim()) continue;
+ try {
+ const parsed = JSON.parse(line);
+ if (parsed.type === "match") {
+ const data = parsed.data;
+ results.push({
+ path: data.path?.text ?? "",
+ line: data.line_number ?? 0,
+ snippet: data.lines?.text ?? "",
+ });
+ }
+ } catch {
+ // skip non-JSON lines
+ }
+ }
+
+ formatTextResults(results.slice(0, limit), opts.format);
+ } catch (err: any) {
+ if (err.code === "ENOENT") {
+ console.error("Error: ripgrep (rg) is not installed. Install it: https://github.com/BurntSushi/ripgrep#installation");
+ process.exit(1);
+ }
+ // rg exits with code 1 when no matches found
+ if (err.code === 1 || err.status === 1) {
+ formatTextResults([], opts.format);
+ } else {
+ throw err;
+ }
+ }
+ });
+}
+```
+
+**Step 3: Register in main.ts**
+
+In `ix-cli/src/cli/main.ts`:
+- Add import: `import { registerTextCommand } from "./commands/text.js";`
+- Add registration: `registerTextCommand(program);`
+
+**Step 4: Verify CLI compiles**
+
+Run: `cd ix-cli && npx tsc --noEmit`
+
+**Step 5: Smoke test**
+
+Run: `cd /path/to/project && npx tsx /path/to/ix-cli/src/cli/main.ts text parseClaim --format json`
+Expected: JSON array of `{ path, line, snippet }` objects
+
+**Step 6: Commit**
+
+```bash
+git add ix-cli/src/cli/commands/text.ts \
+ ix-cli/src/cli/main.ts \
+ ix-cli/src/cli/format.ts
+git commit -m "feat: add ix text command for fast lexical search via ripgrep"
+```
+
+---
+
+### Task 11: MCP — Add ix_text tool
+
+**Files:**
+- Modify: `ix-cli/src/mcp/server.ts` (add ix_text tool)
+
+**Step 1: Add ix_text tool**
+
+In `ix-cli/src/mcp/server.ts`, add a new tool:
+
+```typescript
+// --- ix_text -----------------------------------------------------------------
+server.tool(
+ "ix_text",
+ "Fast lexical/text search across the codebase. Use for exact string matches, symbol lookups, and filename searches. For semantic questions use ix_query instead.",
+ {
+ term: z.string().describe("Text/pattern to search for"),
+ limit: z.optional(z.number()).describe("Max results (default 20)"),
+ path: z.optional(z.string()).describe("Restrict search to a directory path"),
+ },
+ async ({ term, limit, path }) => {
+ try {
+ const { execFile } = await import("node:child_process");
+ const { promisify } = await import("node:util");
+ const execFileAsync = promisify(execFile);
+
+ const maxResults = limit ?? 20;
+ const searchPath = path ?? ".";
+ const { stdout } = await execFileAsync("rg", [
+ "--json",
+ "--max-count", String(maxResults),
+ "--no-heading",
+ term,
+ searchPath,
+ ], { maxBuffer: 10 * 1024 * 1024 });
+
+ const results: Array<{ path: string; line: number; snippet: string }> = [];
+ for (const line of stdout.split("\n")) {
+ if (!line.trim()) continue;
+ try {
+ const parsed = JSON.parse(line);
+ if (parsed.type === "match") {
+ const data = parsed.data;
+ results.push({
+ path: data.path?.text ?? "",
+ line: data.line_number ?? 0,
+ snippet: (data.lines?.text ?? "").trim(),
+ });
+ }
+ } catch { /* skip */ }
+ }
+
+ return {
+ content: [
+ { type: "text" as const, text: JSON.stringify(results.slice(0, maxResults), null, 2) },
+ ],
+ };
+ } catch (err: any) {
+ if (err.code === 1 || err.status === 1) {
+ return {
+ content: [{ type: "text" as const, text: "No matches found." }],
+ };
+ }
+ return {
+ isError: true,
+ content: [
+ { type: "text" as const, text: `ix_text failed: ${String(err)}` },
+ ],
+ };
+ }
+ },
+);
+```
+
+**Step 2: Verify and commit**
+
+Run: `cd ix-cli && npx tsc --noEmit`
+
+```bash
+git add ix-cli/src/mcp/server.ts
+git commit -m "feat: add ix_text MCP tool for fast lexical search"
+```
+
+---
+
+### Task 12: Update CLAUDE.md routing guidance
+
+**Files:**
+- Modify: `ix-cli/src/cli/commands/init.ts` (update IX_CLAUDE_MD_BLOCK template)
+
+**Step 1: Read current init.ts**
+
+Read the file to get exact content of the template block.
+
+**Step 2: Add routing guidance to the CLAUDE.md template**
+
+Add a new section to `IX_CLAUDE_MD_BLOCK` (the template injected by `ix init`):
+
+```markdown
+## Command Routing
+- `ix text` — exact lexical / snippet / filename lookup (fast, uses ripgrep)
+- `ix search` — graph entity search by name, kind, or attribute
+- `ix query` — semantic questions about the codebase (assembles context with confidence)
+- `ix decisions` — list and inspect recorded design decisions
+- `ix history` / `ix diff` — temporal questions about entity changes
+```
+
+**Step 3: Update CLI help descriptions**
+
+Verify that `ix text`, `ix search`, and `ix query` have clear, non-overlapping `.description()` strings.
+
+**Step 4: Commit**
+
+```bash
+git add ix-cli/src/cli/commands/init.ts
+git commit -m "docs: add command routing guidance to CLAUDE.md template"
+```
+
+---
+
+### Task 13: Tests — Add tests for text command and format
+
+**Files:**
+- Modify: `ix-cli/src/cli/__tests__/format.test.ts`
+
+**Step 1: Write tests for formatTextResults**
+
+```typescript
+describe("formatTextResults", () => {
+ it("should output JSON when format is json", () => {
+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+ const results = [{ path: "src/foo.ts", line: 42, snippet: "const foo = bar;" }];
+ formatTextResults(results, "json");
+ expect(spy).toHaveBeenCalledWith(JSON.stringify(results, null, 2));
+ spy.mockRestore();
+ });
+
+ it("should show 'No text matches found.' for empty results", () => {
+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+ formatTextResults([], "text");
+ expect(spy).toHaveBeenCalledWith("No text matches found.");
+ spy.mockRestore();
+ });
+
+ it("should display path:line and snippet in text mode", () => {
+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+ const results = [{ path: "src/foo.ts", line: 42, snippet: "const foo = bar;" }];
+ formatTextResults(results, "text");
+ const output = spy.mock.calls.map(c => c[0]).join("\n");
+ expect(output).toContain("src/foo.ts");
+ expect(output).toContain(":42");
+ expect(output).toContain("const foo = bar;");
+ spy.mockRestore();
+ });
+});
+```
+
+**Step 2: Run tests**
+
+Run: `cd ix-cli && npm test`
+Expected: All tests pass
+
+**Step 3: Commit**
+
+```bash
+git add ix-cli/src/cli/__tests__/format.test.ts
+git commit -m "test: add formatTextResults tests"
+```
+
+---
+
+### Task 14: Final verification — Run full acceptance checklist
+
+**Step 1: Verify backend compiles**
+
+Run: `cd memory-layer && sbt compile`
+
+**Step 2: Verify CLI compiles and tests pass**
+
+Run: `cd ix-cli && npx tsc --noEmit && npm test`
+
+**Step 3: Run acceptance checks (requires running backend)**
+
+```bash
+# A. Decision written becomes searchable
+ix decide "Symbol-level extraction is the right granularity for Ix" \
+ --rationale "Method/class nodes enable CALLS and IMPORTS edges."
+ix search "Symbol-level extraction"
+# Expected: at least one result of kind decision
+
+# B. Decision appears in query
+ix query "design decisions"
+# Expected: decisions section populated
+
+# C. Decisions listing
+ix decisions
+ix decisions --topic extraction
+# Expected: lists decisions, topic filter narrows
+
+# D. Short ID works
+ix entity 11d0f399
+# Expected: resolves entity or "no match" error
+
+# E. Search filters
+ix search parse --kind method
+ix search parse --kind class
+# Expected: different result sets
+
+# F. Text search
+ix text timeout_ms
+ix text parseClaim --format json
+# Expected: file hits with snippets
+```
+
+**Step 4: Final commit (if any fixups needed)**
+
+```bash
+git add -A
+git commit -m "fix: acceptance test fixups"
+```
+
+---
+
+## File Change Summary
+
+| File | Action | Patch |
+|------|--------|-------|
+| `memory-layer/.../api/DecisionRoutes.scala` | Create | 1 |
+| `memory-layer/.../api/SearchRoutes.scala` | Modify | 1 |
+| `memory-layer/.../api/EntityRoutes.scala` | Modify | 1 |
+| `memory-layer/.../api/Routes.scala` | Modify | 1 |
+| `memory-layer/.../db/GraphQueryApi.scala` | Modify | 1 |
+| `memory-layer/.../db/ArangoGraphQueryApi.scala` | Modify | 1 |
+| `ix-cli/src/cli/commands/decisions.ts` | Create | 1 |
+| `ix-cli/src/cli/commands/search.ts` | Modify | 1 |
+| `ix-cli/src/cli/commands/entity.ts` | Modify | 1 |
+| `ix-cli/src/cli/commands/history.ts` | Modify | 1 |
+| `ix-cli/src/cli/commands/text.ts` | Create | 2 |
+| `ix-cli/src/cli/commands/init.ts` | Modify | 2 |
+| `ix-cli/src/cli/main.ts` | Modify | 1+2 |
+| `ix-cli/src/cli/format.ts` | Modify | 1+2 |
+| `ix-cli/src/client/api.ts` | Modify | 1 |
+| `ix-cli/src/mcp/server.ts` | Modify | 1+2 |
+| `ix-cli/src/cli/__tests__/format.test.ts` | Modify | 1+2 |
diff --git a/docs/plans/2026-03-07-ingestion-pipeline-rewrite.md b/docs/plans/2026-03-07-ingestion-pipeline-rewrite.md
new file mode 100644
index 00000000..c277bc68
--- /dev/null
+++ b/docs/plans/2026-03-07-ingestion-pipeline-rewrite.md
@@ -0,0 +1,883 @@
+# Ingestion Pipeline Rewrite — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Rewrite the ingestion pipeline to be 100-500x faster by replacing per-op AQL with ArangoDB Document API batch inserts, parallelizing file parsing, and adding git-based incremental ingestion.
+
+**Architecture:** The current pipeline processes files sequentially, running ~150 individual AQL queries per file inside a stream transaction. The new pipeline uses an FS2 streaming architecture: discover files → parallel parse (bounded by CPU cores) → batch accumulate → bulk Document API insert. Idempotency shifts from per-file DB queries to local content-hash comparison. Versioning is preserved via deterministic `_key` generation.
+
+**Tech Stack:** Scala 2.13, Cats Effect 3, FS2, ArangoDB Java Driver 7.12.0 (Document API), existing parsers unchanged
+
+---
+
+## Task 1: Add bulk insert methods to ArangoClient
+
+The ArangoDB Java Driver's `ArangoCollection.insertDocuments()` method accepts a list of documents and returns results in one HTTP call. This is 22-1000x faster than individual AQL INSERTs.
+
+**Files:**
+- Modify: `memory-layer/src/main/scala/ix/memory/db/ArangoClient.scala`
+
+**Step 1: Read the current file**
+
+Read `memory-layer/src/main/scala/ix/memory/db/ArangoClient.scala` to confirm current state.
+
+**Step 2: Add bulk insert methods**
+
+Add these methods to the `ArangoClient` class (after the `execute` method, before the transaction methods):
+
+```scala
+import com.arangodb.entity.DocumentCreateEntity
+import com.arangodb.model.DocumentCreateOptions
+
+/** Bulk insert/replace documents into a collection. Uses Document API (not AQL). */
+def bulkInsert(
+ collection: String,
+ documents: Seq[java.util.Map[String, AnyRef]],
+ overwriteMode: String = "replace"
+): IO[Int] =
+ if (documents.isEmpty) IO.pure(0)
+ else IO.blocking {
+ val opts = new DocumentCreateOptions()
+ .overwriteMode(com.arangodb.model.OverwriteMode.valueOf(overwriteMode))
+ .waitForSync(false)
+ val docs = new java.util.ArrayList[java.util.Map[String, AnyRef]](documents.size)
+ documents.foreach(docs.add)
+ val result = db.collection(collection).insertDocuments(docs, opts)
+ documents.size - result.getErrors.size
+ }
+
+/** Bulk insert edge documents. Same as bulkInsert but validates _from/_to format. */
+def bulkInsertEdges(
+ collection: String,
+ documents: Seq[java.util.Map[String, AnyRef]],
+ overwriteMode: String = "replace"
+): IO[Int] = bulkInsert(collection, documents, overwriteMode)
+```
+
+Also add import at top of file:
+```scala
+import com.arangodb.model.{AqlQueryOptions, DocumentCreateOptions, OverwriteMode, StreamTransactionOptions}
+```
+
+**Step 3: Verify it compiles**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+
+**Step 4: Commit**
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/db/ArangoClient.scala
+git commit -m "feat: add bulkInsert methods to ArangoClient for Document API batch writes"
+```
+
+---
+
+## Task 2: Create BulkWriteApi — batch write service
+
+This replaces the per-op AQL approach with batched Document API calls. Instead of 150 AQL queries per file, we accumulate documents and flush in 3 calls (nodes, edges, claims).
+
+**Files:**
+- Create: `memory-layer/src/main/scala/ix/memory/db/BulkWriteApi.scala`
+
+**Step 1: Create the BulkWriteApi**
+
+```scala
+package ix.memory.db
+
+import java.time.Instant
+import java.util.UUID
+
+import cats.effect.IO
+import cats.syntax.traverse._
+import io.circe.Json
+import io.circe.syntax._
+
+import ix.memory.model._
+
+/**
+ * High-performance batch writer that uses ArangoDB Document API
+ * instead of individual AQL queries. Accumulates documents from
+ * multiple files and flushes them in bulk.
+ */
+class BulkWriteApi(client: ArangoClient) {
+
+ private val mapper = new com.fasterxml.jackson.databind.ObjectMapper()
+
+ /**
+ * Commit a batch of parsed files in bulk.
+ * Returns the new revision number.
+ */
+ def commitBatch(
+ fileBatches: Vector[FileBatch],
+ baseRev: Long
+ ): IO[CommitResult] = {
+ val newRev = baseRev + 1L
+
+ val allNodes = fileBatches.flatMap(_.nodeDocuments(newRev))
+ val allEdges = fileBatches.flatMap(_.edgeDocuments(newRev))
+ val allClaims = fileBatches.flatMap(_.claimDocuments(newRev))
+ val allPatches = fileBatches.map(_.patchDocument(newRev))
+
+ for {
+ _ <- client.bulkInsert("nodes", allNodes)
+ _ <- client.bulkInsertEdges("edges", allEdges)
+ _ <- client.bulkInsert("claims", allClaims)
+ _ <- client.bulkInsert("patches", allPatches)
+ _ <- updateRevision(newRev)
+ } yield CommitResult(Rev(newRev), CommitStatus.Ok)
+ }
+
+ private def updateRevision(newRev: Long): IO[Unit] =
+ client.execute(
+ """UPSERT { _key: @key }
+ | INSERT { _key: @key, rev: @rev }
+ | UPDATE { rev: @rev }
+ | IN revisions""".stripMargin,
+ Map(
+ "key" -> "current".asInstanceOf[AnyRef],
+ "rev" -> Long.box(newRev).asInstanceOf[AnyRef]
+ )
+ )
+}
+
+/**
+ * Pre-computed batch of documents for a single file,
+ * ready to be merged with other files and bulk-inserted.
+ */
+case class FileBatch(
+ filePath: String,
+ sourceHash: Option[String],
+ patch: GraphPatch,
+ provenance: java.util.Map[String, AnyRef]
+) {
+ private val mapper = new com.fasterxml.jackson.databind.ObjectMapper()
+
+ private def parseToJavaMap(jsonStr: String): java.util.Map[String, AnyRef] =
+ mapper.readValue(jsonStr, classOf[java.util.Map[String, AnyRef]])
+
+ private def jsonToJava(json: Json): AnyRef =
+ mapper.readValue(json.noSpaces, classOf[AnyRef])
+
+ private def nodeKindToString(nk: NodeKind): String =
+ nk.asJson.asString.getOrElse(nk.toString)
+
+ def nodeDocuments(rev: Long): Vector[java.util.Map[String, AnyRef]] = {
+ val now = Instant.now().toString
+ patch.ops.collect { case PatchOp.UpsertNode(id, kind, name, attrs) =>
+ val logicalId = id.value.toString
+ val attrsJson = Json.obj(attrs.toSeq.map { case (k, v) => k -> v }: _*).noSpaces
+ val doc = new java.util.HashMap[String, AnyRef]()
+ doc.put("_key", s"${logicalId}_${rev}")
+ doc.put("logical_id", logicalId)
+ doc.put("id", logicalId)
+ doc.put("kind", nodeKindToString(kind))
+ doc.put("name", name)
+ doc.put("attrs", parseToJavaMap(attrsJson))
+ doc.put("provenance", provenance)
+ doc.put("created_rev", Long.box(rev))
+ doc.put("deleted_rev", null)
+ doc.put("created_at", now)
+ doc.put("updated_at", now)
+ doc: java.util.Map[String, AnyRef]
+ }
+ }
+
+ def edgeDocuments(rev: Long): Vector[java.util.Map[String, AnyRef]] = {
+ val now = Instant.now().toString
+ patch.ops.collect { case PatchOp.UpsertEdge(id, src, dst, predicate, attrs) =>
+ val attrsJson = Json.obj(attrs.toSeq.map { case (k, v) => k -> v }: _*).noSpaces
+ val doc = new java.util.HashMap[String, AnyRef]()
+ doc.put("_key", id.value.toString)
+ doc.put("_from", s"nodes/${src.value}")
+ doc.put("_to", s"nodes/${dst.value}")
+ doc.put("id", id.value.toString)
+ doc.put("src", src.value.toString)
+ doc.put("dst", dst.value.toString)
+ doc.put("predicate", predicate.value)
+ doc.put("attrs", parseToJavaMap(attrsJson))
+ doc.put("created_rev", Long.box(rev))
+ doc.put("deleted_rev", null)
+ doc.put("provenance", provenance)
+ doc.put("created_at", now)
+ doc.put("updated_at", now)
+ doc: java.util.Map[String, AnyRef]
+ }
+ }
+
+ def claimDocuments(rev: Long): Vector[java.util.Map[String, AnyRef]] =
+ patch.ops.collect { case PatchOp.AssertClaim(entityId, field, value, confidence) =>
+ val doc = new java.util.HashMap[String, AnyRef]()
+ doc.put("_key", java.util.UUID.randomUUID().toString)
+ doc.put("entity_id", entityId.value.toString)
+ doc.put("field", field)
+ doc.put("value", jsonToJava(value))
+ doc.put("confidence", confidence.map(Double.box).orNull)
+ doc.put("status", "active")
+ doc.put("created_rev", Long.box(rev))
+ doc.put("deleted_rev", null)
+ doc.put("provenance", provenance)
+ doc: java.util.Map[String, AnyRef]
+ }
+
+ def patchDocument(rev: Long): java.util.Map[String, AnyRef] = {
+ val patchJson = patch.asJson.noSpaces
+ val doc = new java.util.HashMap[String, AnyRef]()
+ doc.put("_key", patch.patchId.value.toString)
+ doc.put("patch_id", patch.patchId.value.toString)
+ doc.put("rev", Long.box(rev))
+ doc.put("data", mapper.readValue(patchJson, classOf[java.util.Map[String, AnyRef]]))
+ doc: java.util.Map[String, AnyRef]
+ }
+}
+```
+
+**Step 2: Verify it compiles**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+
+**Step 3: Commit**
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/db/BulkWriteApi.scala
+git commit -m "feat: add BulkWriteApi for batch Document API writes"
+```
+
+---
+
+## Task 3: Create BulkIngestionService — parallel pipeline
+
+This is the new ingestion orchestrator that replaces the sequential `files.traverse()` with parallel parsing and batched writes.
+
+**Files:**
+- Create: `memory-layer/src/main/scala/ix/memory/ingestion/BulkIngestionService.scala`
+
+**Step 1: Create the service**
+
+```scala
+package ix.memory.ingestion
+
+import java.nio.file.{Files, Path}
+import java.time.Instant
+import java.util.UUID
+
+import cats.effect.IO
+import cats.syntax.all._
+import io.circe.Json
+import io.circe.syntax._
+
+import ix.memory.db.{BulkWriteApi, CommitResult, FileBatch, GraphQueryApi}
+import ix.memory.model._
+
+/**
+ * High-performance ingestion service that:
+ * 1. Discovers files (with optional git-diff incremental mode)
+ * 2. Parses files in parallel (bounded by CPU cores)
+ * 3. Batches parsed results
+ * 4. Bulk-inserts via Document API
+ */
+class BulkIngestionService(
+ parserRouter: ParserRouter,
+ bulkWriteApi: BulkWriteApi,
+ queryApi: GraphQueryApi
+) {
+
+ private val parallelism = Runtime.getRuntime.availableProcessors.max(2)
+
+ /**
+ * Ingest files under a path using parallel parsing and bulk writes.
+ */
+ def ingestPath(
+ path: Path,
+ language: Option[String],
+ recursive: Boolean
+ ): IO[IngestionResult] = {
+ for {
+ files <- discoverFiles(path, language, recursive)
+ // Load existing hashes to skip unchanged files
+ hashMap <- loadExistingHashes(files)
+ // Parse files in parallel, skipping unchanged
+ batches <- files.parTraverseN(parallelism) { f =>
+ parseFile(f, hashMap).attempt
+ }
+ validBatches = batches.collect { case Right(Some(b)) => b }
+ skippedCount = batches.count {
+ case Right(None) => true // unchanged file
+ case _ => false
+ }
+ // Get current rev and bulk commit
+ latestRev <- queryApi.getLatestRev
+ result <- if (validBatches.isEmpty) IO.pure(CommitResult(latestRev, ix.memory.db.CommitStatus.Ok))
+ else bulkWriteApi.commitBatch(validBatches.toVector, latestRev.value)
+ } yield IngestionResult(
+ filesProcessed = files.size,
+ patchesApplied = validBatches.size,
+ filesSkipped = skippedCount,
+ entitiesCreated = validBatches.flatMap(_.patch.ops.collect { case _: PatchOp.UpsertNode => 1 }).size,
+ latestRev = result.newRev
+ )
+ }
+
+ /**
+ * Parse a single file into a FileBatch (or None if unchanged).
+ * This is the CPU-bound work that runs in parallel.
+ */
+ private def parseFile(filePath: Path, hashMap: Map[String, String]): IO[Option[FileBatch]] = {
+ for {
+ bytes <- IO.blocking(Files.readAllBytes(filePath))
+ _ <- if (bytes.isEmpty) IO.pure(None) else IO.unit
+ hash = sha256Bytes(bytes)
+ // Skip if hash unchanged
+ result <- hashMap.get(filePath.toString) match {
+ case Some(existingHash) if existingHash == hash =>
+ IO.pure(None) // unchanged
+ case _ =>
+ for {
+ source <- IO.blocking {
+ try new String(bytes, java.nio.charset.StandardCharsets.UTF_8)
+ catch { case _: Throwable => new String(bytes, java.nio.charset.StandardCharsets.ISO_8859_1) }
+ }
+ parserOpt = parserRouter.parserFor(filePath.toString)
+ parseResult = parserOpt match {
+ case Some(p) => p.parse(filePath.getFileName.toString, source)
+ case None => genericTextParse(filePath.getFileName.toString, source)
+ }
+ patch = GraphPatchBuilder.build(filePath.toString, Some(hash), parseResult)
+ provenance = buildProvenanceMap(patch)
+ } yield Some(FileBatch(filePath.toString, Some(hash), patch, provenance))
+ }
+ } yield result
+ }
+
+ /**
+ * Load existing source hashes from the database for quick local comparison.
+ * Returns Map[filePath -> hash].
+ */
+ private def loadExistingHashes(files: List[Path]): IO[Map[String, String]] = {
+ // Query all patches to get stored hashes — single DB round trip
+ val paths = files.map(_.toString)
+ if (paths.isEmpty) IO.pure(Map.empty)
+ else {
+ // Use a single AQL query to get all known hashes at once
+ queryApi.getLatestRev.flatMap { _ =>
+ IO.pure(Map.empty[String, String]) // Simplified: will be populated from patches collection
+ // TODO: Add a queryApi method to batch-fetch hashes by source URIs
+ // For now, every file is treated as changed on first bulk run.
+ // On subsequent runs, the hash check prevents duplicate inserts via overwriteMode=replace.
+ }
+ }
+ }
+
+ private def buildProvenanceMap(patch: GraphPatch): java.util.Map[String, AnyRef] = {
+ val mapper = new com.fasterxml.jackson.databind.ObjectMapper()
+ val json = Json.obj(
+ "source_uri" -> Json.fromString(patch.source.uri),
+ "source_hash" -> patch.source.sourceHash.fold(Json.Null)(Json.fromString),
+ "extractor" -> Json.fromString(patch.source.extractor),
+ "source_type" -> Json.fromString(patch.source.sourceType.asJson.asString.getOrElse("code")),
+ "observed_at" -> Json.fromString(patch.timestamp.toString)
+ )
+ mapper.readValue(json.noSpaces, classOf[java.util.Map[String, AnyRef]])
+ }
+
+ private def discoverFiles(
+ path: Path,
+ language: Option[String],
+ recursive: Boolean
+ ): IO[List[Path]] = IO.blocking {
+ import scala.jdk.CollectionConverters._
+
+ val extensions = language match {
+ case Some("python") => Set(".py")
+ case Some("typescript") => Set(".ts", ".tsx")
+ case Some("scala") => Set(".scala", ".sc")
+ case Some("config") => Set(".json", ".yaml", ".yml", ".toml")
+ case Some("markdown") => Set(".md")
+ case _ => Set(
+ ".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+ ".java", ".scala", ".sc", ".go", ".rs", ".c", ".h", ".cc", ".cpp", ".hpp",
+ ".kt", ".kts", ".swift", ".rb", ".php",
+ ".json", ".yaml", ".yml", ".toml", ".ini", ".conf", ".env", ".properties",
+ ".md", ".mdx", ".rst", ".txt"
+ )
+ }
+
+ val specialFiles = Set("Dockerfile", "Makefile", "README", "LICENSE", "NOTICE", "build.sbt")
+
+ if (Files.isRegularFile(path)) {
+ val base = path.getFileName.toString
+ if (specialFiles.contains(base) || extensions.exists(base.endsWith)) List(path)
+ else List.empty
+ } else if (Files.isDirectory(path)) {
+ val stream = if (recursive) Files.walk(path) else Files.list(path)
+ try {
+ stream.iterator().asScala
+ .filter(Files.isRegularFile(_))
+ .filter { p =>
+ val base = p.getFileName.toString
+ specialFiles.contains(base) || extensions.exists(base.endsWith)
+ }
+ .toList
+ } finally stream.close()
+ } else List.empty
+ }
+
+ private def sha256Bytes(bytes: Array[Byte]): String = {
+ val md = java.security.MessageDigest.getInstance("SHA-256")
+ md.digest(bytes).map("%02x".format(_)).mkString
+ }
+
+ private def genericTextParse(fileName: String, source: String): ParseResult = {
+ val lines = if (source.isEmpty) 1 else source.count(_ == '\n') + 1
+ ParseResult(
+ entities = Vector(ParsedEntity(
+ name = fileName, kind = NodeKind.File,
+ attrs = Map("content" -> Json.fromString(source)),
+ lineStart = 1, lineEnd = lines
+ )),
+ relationships = Vector.empty
+ )
+ }
+}
+```
+
+**Step 2: Verify it compiles**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+
+**Step 3: Commit**
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/ingestion/BulkIngestionService.scala
+git commit -m "feat: add BulkIngestionService with parallel parsing and batch writes"
+```
+
+---
+
+## Task 4: Wire BulkIngestionService into the application
+
+Connect the new service to the HTTP routes and Main entry point. The old `IngestionService` stays for backward compatibility (single-file `ingestFile` used by MCP `ix_ingest`), but the `/v1/ingest` endpoint now uses the bulk path.
+
+**Files:**
+- Modify: `memory-layer/src/main/scala/ix/memory/Main.scala:29-34`
+- Modify: `memory-layer/src/main/scala/ix/memory/api/IngestionRoutes.scala`
+- Modify: `memory-layer/src/main/scala/ix/memory/api/Routes.scala`
+
+**Step 1: Update Main.scala**
+
+Read the file first. After `writeApi` and `queryApi` creation (around line 30), add:
+
+```scala
+bulkWriteApi = new BulkWriteApi(client)
+```
+
+After `ingestionService` creation (around line 34), add:
+
+```scala
+bulkIngestionService = new BulkIngestionService(parserRouter, bulkWriteApi, queryApi)
+```
+
+Update the `Routes.all(...)` call to pass `bulkIngestionService` as well. This requires updating the `Routes.all` signature.
+
+Add import: `import ix.memory.db.BulkWriteApi`
+
+**Step 2: Update IngestionRoutes to accept both services**
+
+Read the file first. Change the constructor to accept the bulk service:
+
+```scala
+class IngestionRoutes(ingestionService: IngestionService, bulkIngestionService: BulkIngestionService) {
+```
+
+Update the route handler to use `bulkIngestionService` for the path-based ingest:
+
+```scala
+val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
+ case req @ POST -> Root / "v1" / "ingest" =>
+ (for {
+ body <- req.as[IngestRequest]
+ _ <- IO.raiseWhen(body.path.contains(".."))(
+ new IllegalArgumentException("Path traversal not allowed")
+ )
+ path = Paths.get(body.path)
+ result <- bulkIngestionService.ingestPath(path, body.language, body.recursive.getOrElse(false))
+ resp <- Ok(IngestResponse(
+ filesProcessed = result.filesProcessed,
+ patchesApplied = result.patchesApplied,
+ entitiesCreated = result.entitiesCreated,
+ latestRev = result.latestRev.value
+ ))
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+}
+```
+
+Add import: `import ix.memory.ingestion.BulkIngestionService`
+
+**Step 3: Update Routes.scala**
+
+Read the file. Update `Routes.all` to accept and pass `bulkIngestionService`:
+
+```scala
+def all(
+ contextService: ContextService,
+ ingestionService: IngestionService,
+ bulkIngestionService: BulkIngestionService,
+ queryApi: GraphQueryApi,
+ writeApi: GraphWriteApi,
+ conflictService: ConflictService,
+ client: ArangoClient
+): HttpRoutes[IO] = {
+```
+
+Update the `ingestionRoutes` creation:
+```scala
+val ingestionRoutes = new IngestionRoutes(ingestionService, bulkIngestionService).routes
+```
+
+Add import: `import ix.memory.ingestion.BulkIngestionService`
+
+Update the call site in Main.scala to pass the new parameter.
+
+**Step 4: Verify it compiles**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+
+**Step 5: Commit**
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/Main.scala \
+ memory-layer/src/main/scala/ix/memory/api/IngestionRoutes.scala \
+ memory-layer/src/main/scala/ix/memory/api/Routes.scala
+git commit -m "feat: wire BulkIngestionService into HTTP routes and Main"
+```
+
+---
+
+## Task 5: Add batch hash lookup to GraphQueryApi
+
+Enable the `BulkIngestionService` to load all existing file hashes in a single query, so it can skip unchanged files without N+1 queries.
+
+**Files:**
+- Modify: `memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala`
+- Modify: `memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala`
+- Modify: `memory-layer/src/main/scala/ix/memory/ingestion/BulkIngestionService.scala`
+
+**Step 1: Add trait method**
+
+In `GraphQueryApi.scala`, add:
+
+```scala
+def getSourceHashes(sourceUris: Seq[String]): IO[Map[String, String]]
+```
+
+**Step 2: Implement in ArangoGraphQueryApi**
+
+Read the file. Add implementation:
+
+```scala
+override def getSourceHashes(sourceUris: Seq[String]): IO[Map[String, String]] = {
+ if (sourceUris.isEmpty) IO.pure(Map.empty)
+ else {
+ val uriList = new java.util.ArrayList[String](sourceUris.size)
+ sourceUris.foreach(uriList.add)
+ client.query(
+ """FOR p IN patches
+ | FILTER p.data.source.uri IN @uris
+ | SORT p.rev DESC
+ | COLLECT uri = p.data.source.uri INTO groups
+ | LET latest = FIRST(groups)
+ | RETURN { uri: uri, hash: latest.p.data.source.sourceHash }""".stripMargin,
+ Map("uris" -> uriList.asInstanceOf[AnyRef])
+ ).map { results =>
+ results.flatMap { json =>
+ for {
+ uri <- json.hcursor.get[String]("uri").toOption
+ hash <- json.hcursor.get[String]("hash").toOption
+ } yield uri -> hash
+ }.toMap
+ }
+ }
+}
+```
+
+**Step 3: Update BulkIngestionService.loadExistingHashes**
+
+Replace the `loadExistingHashes` method in `BulkIngestionService.scala`:
+
+```scala
+private def loadExistingHashes(files: List[Path]): IO[Map[String, String]] = {
+ val paths = files.map(_.toString)
+ queryApi.getSourceHashes(paths)
+}
+```
+
+**Step 4: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala \
+ memory-layer/src/main/scala/ix/memory/db/ArangoGraphQueryApi.scala \
+ memory-layer/src/main/scala/ix/memory/ingestion/BulkIngestionService.scala
+git commit -m "feat: add batch source hash lookup for incremental ingestion skip"
+```
+
+---
+
+## Task 6: Handle node versioning in bulk mode
+
+The old `UpsertNode` does SELECT + conditional tombstone + INSERT. In bulk mode, we use `overwriteMode=replace` which handles this at the Document API level. However, we need to tombstone old versioned rows. Add a pre-flush tombstone step.
+
+**Files:**
+- Modify: `memory-layer/src/main/scala/ix/memory/db/BulkWriteApi.scala`
+
+**Step 1: Add tombstone step before bulk insert**
+
+Read the file. Update the `commitBatch` method to first tombstone any existing live rows for the logical IDs being upserted:
+
+```scala
+def commitBatch(
+ fileBatches: Vector[FileBatch],
+ baseRev: Long
+): IO[CommitResult] = {
+ val newRev = baseRev + 1L
+
+ val allNodes = fileBatches.flatMap(_.nodeDocuments(newRev))
+ val allEdges = fileBatches.flatMap(_.edgeDocuments(newRev))
+ val allClaims = fileBatches.flatMap(_.claimDocuments(newRev))
+ val allPatches = fileBatches.map(_.patchDocument(newRev))
+
+ // Collect all logical_ids being upserted
+ val logicalIds = allNodes.flatMap { doc =>
+ Option(doc.get("logical_id")).map(_.toString)
+ }
+
+ for {
+ // Step 1: Tombstone existing live rows for these logical_ids
+ _ <- tombstoneExistingNodes(logicalIds, newRev)
+ // Step 2: Retire old claims for entities being re-ingested
+ _ <- retireOldClaims(fileBatches, newRev)
+ // Step 3: Bulk insert new rows
+ _ <- client.bulkInsert("nodes", allNodes)
+ _ <- client.bulkInsertEdges("edges", allEdges)
+ _ <- client.bulkInsert("claims", allClaims)
+ _ <- client.bulkInsert("patches", allPatches)
+ // Step 4: Update revision
+ _ <- updateRevision(newRev)
+ } yield CommitResult(Rev(newRev), CommitStatus.Ok)
+}
+
+/**
+ * Tombstone existing live node rows for the given logical IDs.
+ * Uses a single AQL query (not per-node).
+ */
+private def tombstoneExistingNodes(logicalIds: Vector[String], newRev: Long): IO[Unit] = {
+ if (logicalIds.isEmpty) IO.unit
+ else {
+ val idList = new java.util.ArrayList[String](logicalIds.size)
+ logicalIds.distinct.foreach(idList.add)
+ client.execute(
+ """FOR n IN nodes
+ | FILTER n.logical_id IN @ids
+ | AND n.deleted_rev == null
+ | UPDATE n WITH { deleted_rev: @rev, updated_at: @now } IN nodes""".stripMargin,
+ Map(
+ "ids" -> idList.asInstanceOf[AnyRef],
+ "rev" -> Long.box(newRev).asInstanceOf[AnyRef],
+ "now" -> Instant.now().toString.asInstanceOf[AnyRef]
+ )
+ )
+ }
+}
+
+/**
+ * Retire old claims for entities being re-ingested.
+ * Single AQL query per batch.
+ */
+private def retireOldClaims(fileBatches: Vector[FileBatch], newRev: Long): IO[Unit] = {
+ val entityIds = fileBatches.flatMap(_.patch.ops.collect {
+ case PatchOp.UpsertNode(id, _, _, _) => id.value.toString
+ }).distinct
+ if (entityIds.isEmpty) IO.unit
+ else {
+ val idList = new java.util.ArrayList[String](entityIds.size)
+ entityIds.foreach(idList.add)
+ client.execute(
+ """FOR c IN claims
+ | FILTER c.entity_id IN @ids
+ | AND c.deleted_rev == null
+ | UPDATE c WITH { status: "retracted", deleted_rev: @rev } IN claims""".stripMargin,
+ Map(
+ "ids" -> idList.asInstanceOf[AnyRef],
+ "rev" -> Long.box(newRev).asInstanceOf[AnyRef]
+ )
+ )
+ }
+}
+```
+
+**Step 2: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/db/BulkWriteApi.scala
+git commit -m "feat: add tombstone + claim retirement steps to bulk commit"
+```
+
+---
+
+## Task 7: Update CLI/MCP ingest to report performance
+
+Show timing information so users can see the speedup.
+
+**Files:**
+- Modify: `ix-cli/src/cli/commands/ingest.ts`
+- Modify: `ix-cli/src/client/types.ts`
+
+**Step 1: Add timing to CLI ingest output**
+
+Read and update `ix-cli/src/cli/commands/ingest.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+
+export function registerIngestCommand(program: Command): void {
+ program
+ .command("ingest <path>")
+ .description("Ingest source files into the knowledge graph")
+ .option("--recursive", "Recursively ingest directory")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (path: string, opts: { recursive?: boolean; format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const start = performance.now();
+ const result = await client.ingest(path, opts.recursive);
+ const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+ if (opts.format === "json") {
+ console.log(JSON.stringify({ ...result, elapsedSeconds: parseFloat(elapsed) }, null, 2));
+ } else {
+ console.log(`Ingested: ${result.filesProcessed} files, ${result.patchesApplied} patches applied (${elapsed}s)`);
+ if (result.filesSkipped) {
+ console.log(`Skipped: ${result.filesSkipped} unchanged files`);
+ }
+ console.log(`Rev: ${result.latestRev}`);
+ }
+ });
+}
+```
+
+**Step 2: Add filesSkipped to CommitResult type**
+
+Read `ix-cli/src/client/types.ts`. Update the IngestResult or CommitResult to include:
+
+```typescript
+export interface IngestResult {
+ filesProcessed: number;
+ patchesApplied: number;
+ filesSkipped?: number;
+ entitiesCreated: number;
+ latestRev: number;
+}
+```
+
+Also update `api.ts` to use `IngestResult` as the return type of `ingest()`.
+
+**Step 3: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit`
+
+```bash
+git add ix-cli/src/cli/commands/ingest.ts ix-cli/src/client/types.ts ix-cli/src/client/api.ts
+git commit -m "feat: add timing and skip count to ingest CLI output"
+```
+
+---
+
+## Task 8: Add IngestionRoutes response for filesSkipped
+
+The backend `IngestionResult` already has `filesSkipped`, but the HTTP response model `IngestResponse` doesn't expose it.
+
+**Files:**
+- Modify: `memory-layer/src/main/scala/ix/memory/api/IngestionRoutes.scala`
+
+**Step 1: Add filesSkipped to IngestResponse**
+
+Read the file. Update `IngestResponse`:
+
+```scala
+case class IngestResponse(
+ filesProcessed: Int,
+ patchesApplied: Int,
+ filesSkipped: Int,
+ entitiesCreated: Int,
+ latestRev: Long
+)
+```
+
+Update the route handler to include `filesSkipped = result.filesSkipped`.
+
+**Step 2: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/api/IngestionRoutes.scala
+git commit -m "feat: expose filesSkipped in IngestResponse"
+```
+
+---
+
+## Task 9: Final verification — compile + test full stack
+
+**Files:** None (verification only)
+
+**Step 1: Backend compilation**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+Expected: `[success]`
+
+**Step 2: CLI type check and tests**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit && npm test`
+Expected: All tests pass
+
+**Step 3: Review git log**
+
+Run: `git log --oneline -10`
+Expected: Clean commit history with feat: prefixes
+
+---
+
+## Architecture Summary
+
+### Before (per file):
+```
+File → Read → Hash → DB query (idempotency check) → Parse → Build patch
+ → BEGIN TX → 150 AQL queries → COMMIT TX
+ = ~157 HTTP round-trips to ArangoDB per file
+```
+
+### After (batch):
+```
+Discover files → Load all hashes (1 query) → Filter unchanged
+ → Parse N files in parallel (N = CPU cores)
+ → Tombstone existing nodes (1 AQL query)
+ → Retire old claims (1 AQL query)
+ → Bulk insert nodes (1 Document API call)
+ → Bulk insert edges (1 Document API call)
+ → Bulk insert claims (1 Document API call)
+ → Bulk insert patches (1 Document API call)
+ → Update revision (1 AQL query)
+ = 7 HTTP round-trips total for entire batch
+```
+
+### Expected Performance
+
+| Metric | Before | After |
+|--------|--------|-------|
+| DB round-trips per file | ~157 | ~0.07 (7 / 100 files) |
+| Parsing | Sequential | Parallel (N cores) |
+| 100 files | ~15 seconds | ~0.3 seconds |
+| 500 files | ~75 seconds | ~1.5 seconds |
+| Re-ingest (no changes) | ~50 seconds | ~0.5 seconds (hash check only) |
diff --git a/docs/plans/2026-03-07-retrieval-navigation.md b/docs/plans/2026-03-07-retrieval-navigation.md
new file mode 100644
index 00000000..cd305d66
--- /dev/null
+++ b/docs/plans/2026-03-07-retrieval-navigation.md
@@ -0,0 +1,1382 @@
+# Retrieval Unification & Graph Navigation — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Link text search, graph search, and semantic query into a unified retrieval layer, and add first-class graph navigation commands (callers, imports, contains, stats, doctor).
+
+**Architecture:** Patch 3 standardizes `ix text` output, adds `ix locate` (text→graph bridge), `ix explain` (entity summary), and text search filters. Patch 4 adds graph traversal commands that use the existing `expand` API with predicate filters. All new CLI commands are client-side — no new backend routes needed except `GET /v1/stats` for node/edge counts.
+
+**Tech Stack:** TypeScript (Commander, chalk), Scala (http4s, AQL), ripgrep
+
+---
+
+## Patch 3 — Retrieval Unification
+
+---
+
+### Task 1: Standardize `ix text` result schema
+
+Update the `TextResult` interface and ripgrep parser to produce the stable JSON fields required for future engine swaps.
+
+**Files:**
+- Modify: `ix-cli/src/cli/format.ts`
+- Modify: `ix-cli/src/cli/commands/text.ts`
+- Modify: `ix-cli/src/mcp/server.ts`
+
+**Step 1: Update TextResult interface**
+
+In `ix-cli/src/cli/format.ts`, replace the existing `TextResult` interface:
+
+```typescript
+export interface TextResult {
+ path: string;
+ line_start: number;
+ line_end: number;
+ snippet: string;
+ engine: string;
+ score: number;
+ language?: string;
+ symbol_hint?: string;
+}
+```
+
+Update `formatTextResults` to use the new fields:
+
+```typescript
+export function formatTextResults(results: TextResult[], format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(results, null, 2));
+ return;
+ }
+ if (results.length === 0) {
+ console.log("No text matches found.");
+ return;
+ }
+ for (const r of results) {
+ const lang = r.language ? chalk.magenta(`[${r.language}]`) + " " : "";
+ const sym = r.symbol_hint ? chalk.yellow(`(${r.symbol_hint})`) + " " : "";
+ console.log(
+ ` ${lang}${chalk.dim(r.path)}${chalk.cyan(":" + r.line_start)} ${sym}${r.snippet.trim()}`
+ );
+ }
+}
+```
+
+**Step 2: Update text.ts parser**
+
+In `ix-cli/src/cli/commands/text.ts`, update the ripgrep parser to produce the new schema. Replace the result-building block inside the match handler:
+
+```typescript
+const results: TextResult[] = [];
+for (const line of stdout.split("\n")) {
+ if (!line.trim()) continue;
+ try {
+ const parsed = JSON.parse(line);
+ if (parsed.type === "match") {
+ const data = parsed.data;
+ const filePath = data.path?.text ?? "";
+ const lineNum = data.line_number ?? 0;
+ results.push({
+ path: filePath,
+ line_start: lineNum,
+ line_end: lineNum,
+ snippet: data.lines?.text ?? "",
+ engine: "ripgrep",
+ score: 1.0,
+ language: inferLanguage(filePath),
+ });
+ }
+ } catch {
+ // skip non-JSON lines
+ }
+}
+```
+
+Add the `inferLanguage` helper at the bottom of `text.ts`:
+
+```typescript
+function inferLanguage(filePath: string): string | undefined {
+ if (filePath.endsWith(".py")) return "python";
+ if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) return "typescript";
+ if (filePath.endsWith(".js") || filePath.endsWith(".jsx")) return "javascript";
+ if (filePath.endsWith(".scala") || filePath.endsWith(".sc")) return "scala";
+ if (filePath.endsWith(".java")) return "java";
+ if (filePath.endsWith(".go")) return "go";
+ if (filePath.endsWith(".rs")) return "rust";
+ if (filePath.endsWith(".rb")) return "ruby";
+ if (filePath.endsWith(".md")) return "markdown";
+ if (filePath.endsWith(".json")) return "json";
+ if (filePath.endsWith(".yaml") || filePath.endsWith(".yml")) return "yaml";
+ return undefined;
+}
+```
+
+**Step 3: Update MCP server ix_text tool**
+
+In `ix-cli/src/mcp/server.ts`, update the ix_text tool result builder to produce the new schema. Find the results.push block inside the ix_text handler and update to match:
+
+```typescript
+results.push({
+ path: data.path?.text ?? "",
+ line_start: data.line_number ?? 0,
+ line_end: data.line_number ?? 0,
+ snippet: (data.lines?.text ?? "").trim(),
+ engine: "ripgrep",
+ score: 1.0,
+});
+```
+
+**Step 4: Update tests**
+
+In `ix-cli/src/cli/__tests__/format.test.ts`, update the `formatTextResults` test to use the new field names (`line_start` instead of `line`, add `engine`, `score`, `line_end`).
+
+**Step 5: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit && npm test`
+
+```bash
+git add ix-cli/src/cli/format.ts ix-cli/src/cli/commands/text.ts ix-cli/src/mcp/server.ts ix-cli/src/cli/__tests__/format.test.ts
+git commit -m "feat: standardize ix text result schema with engine, score, language fields"
+```
+
+---
+
+### Task 2: Add text search filters (`--path`, `--limit`, `--language`)
+
+Extend `ix text` with `--language` filter and ensure `--path` and `--limit` work properly. The `--language` filter restricts ripgrep to files with matching extensions.
+
+**Files:**
+- Modify: `ix-cli/src/cli/commands/text.ts`
+- Modify: `ix-cli/src/mcp/server.ts`
+
+**Step 1: Add --language option to CLI**
+
+In `ix-cli/src/cli/commands/text.ts`, add the option after the existing options:
+
+```typescript
+.option("--language <lang>", "Filter by language (python, typescript, scala, etc.)")
+```
+
+Update the action signature:
+
+```typescript
+.action(async (term: string, opts: { limit: string; path: string; format: string; language?: string }) => {
+```
+
+Update the ripgrep args to include language-specific glob filters:
+
+```typescript
+const rgArgs = [
+ "--json",
+ "--max-count", String(limit),
+ "--no-heading",
+];
+
+if (opts.language) {
+ const globs = languageGlobs(opts.language);
+ for (const g of globs) {
+ rgArgs.push("--glob", g);
+ }
+}
+
+rgArgs.push(term, opts.path);
+
+const { stdout } = await execFileAsync("rg", rgArgs, { maxBuffer: 10 * 1024 * 1024 });
+```
+
+Add the `languageGlobs` helper:
+
+```typescript
+function languageGlobs(lang: string): string[] {
+ switch (lang) {
+ case "python": return ["*.py"];
+ case "typescript": return ["*.ts", "*.tsx"];
+ case "javascript": return ["*.js", "*.jsx", "*.mjs", "*.cjs"];
+ case "scala": return ["*.scala", "*.sc"];
+ case "java": return ["*.java"];
+ case "go": return ["*.go"];
+ case "rust": return ["*.rs"];
+ case "ruby": return ["*.rb"];
+ case "markdown": return ["*.md", "*.mdx"];
+ case "config": return ["*.json", "*.yaml", "*.yml", "*.toml"];
+ default: return [`*.${lang}`];
+ }
+}
+```
+
+**Step 2: Update MCP server ix_text tool**
+
+Add `language` parameter to the ix_text tool schema:
+
+```typescript
+language: z.optional(z.string()).describe("Filter by language (python, typescript, scala, etc.)"),
+```
+
+And apply the same glob logic in the handler before calling rg.
+
+**Step 3: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit`
+
+```bash
+git add ix-cli/src/cli/commands/text.ts ix-cli/src/mcp/server.ts
+git commit -m "feat: add --language filter to ix text command"
+```
+
+---
+
+### Task 3: Add `ix locate` command — bridge text hits to graph entities
+
+`ix locate <symbol>` runs `ix text` to find occurrences, then resolves each hit to a graph entity if one exists.
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/locate.ts`
+- Modify: `ix-cli/src/cli/format.ts`
+- Modify: `ix-cli/src/cli/main.ts`
+- Modify: `ix-cli/src/mcp/server.ts`
+
+**Step 1: Create the locate command**
+
+Create `ix-cli/src/cli/commands/locate.ts`:
+
+```typescript
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatLocateResults, type LocateResult } from "../format.js";
+
+const execFileAsync = promisify(execFile);
+
+export function registerLocateCommand(program: Command): void {
+ program
+ .command("locate <symbol>")
+ .description("Find a symbol in code and resolve to graph entities")
+ .option("--limit <n>", "Max text hits to check", "10")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { limit: string; format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const limit = parseInt(opts.limit, 10);
+
+ // Step 1: Search the graph for matching entities
+ const graphNodes = await client.search(symbol, { limit: 5 });
+
+ // Step 2: Run ripgrep for text hits
+ let textHits: Array<{ path: string; line: number }> = [];
+ try {
+ const { stdout } = await execFileAsync("rg", [
+ "--json", "--max-count", String(limit),
+ "--no-heading", "--word-regexp",
+ symbol, ".",
+ ], { maxBuffer: 10 * 1024 * 1024 });
+
+ for (const line of stdout.split("\n")) {
+ if (!line.trim()) continue;
+ try {
+ const parsed = JSON.parse(line);
+ if (parsed.type === "match") {
+ textHits.push({
+ path: parsed.data.path?.text ?? "",
+ line: parsed.data.line_number ?? 0,
+ });
+ }
+ } catch { /* skip */ }
+ }
+ } catch (err: any) {
+ if (err.code !== 1 && err.status !== 1 && err.code !== "ENOENT") throw err;
+ }
+
+ // Step 3: Build results — graph entities first, then unmatched text hits
+ const results: LocateResult[] = [];
+ for (const node of graphNodes) {
+ const name = node.attrs?.name as string ?? node.kind;
+ const sourceUri = node.provenance?.sourceUri;
+ results.push({
+ kind: node.kind,
+ id: node.id,
+ name,
+ file: sourceUri,
+ source: "graph",
+ });
+ }
+
+ // Add text-only hits that didn't match any graph entity
+ const graphFiles = new Set(results.map(r => r.file).filter(Boolean));
+ const seenPaths = new Set<string>();
+ for (const hit of textHits) {
+ if (!seenPaths.has(hit.path) && !graphFiles.has(hit.path)) {
+ seenPaths.add(hit.path);
+ results.push({
+ kind: "text-match",
+ name: symbol,
+ file: hit.path,
+ line: hit.line,
+ source: "ripgrep",
+ });
+ }
+ }
+
+ formatLocateResults(results, opts.format);
+ });
+}
+```
+
+**Step 2: Add LocateResult and formatLocateResults to format.ts**
+
+In `ix-cli/src/cli/format.ts`, add:
+
+```typescript
+export interface LocateResult {
+ kind: string;
+ id?: string;
+ name: string;
+ file?: string;
+ line?: number;
+ source: "graph" | "ripgrep";
+}
+
+export function formatLocateResults(results: LocateResult[], format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(results, null, 2));
+ return;
+ }
+ if (results.length === 0) {
+ console.log("No matches found.");
+ return;
+ }
+ for (const r of results) {
+ const shortId = r.id ? chalk.dim(r.id.slice(0, 8)) + " " : "";
+ const filePart = r.file ? chalk.dim(r.file) + (r.line ? chalk.cyan(`:${r.line}`) : "") : "";
+ console.log(` ${chalk.cyan(r.kind)} ${shortId}${chalk.bold(r.name)}`);
+ if (filePart) {
+ console.log(` ${filePart}`);
+ }
+ }
+}
+```
+
+**Step 3: Register in main.ts**
+
+Add import and registration:
+
+```typescript
+import { registerLocateCommand } from "./commands/locate.js";
+// ...
+registerLocateCommand(program);
+```
+
+**Step 4: Add ix_locate MCP tool**
+
+In `ix-cli/src/mcp/server.ts`, add a new tool that does the same logic:
+
+```typescript
+// --- ix_locate ---------------------------------------------------------------
+server.tool(
+ "ix_locate",
+ "Locate a symbol — finds it in code via ripgrep and resolves to graph entities. Use when you need to find where something is defined and get its entity ID.",
+ {
+ symbol: z.string().describe("Symbol/identifier to locate"),
+ limit: z.optional(z.number()).describe("Max results (default 10)"),
+ },
+ async ({ symbol, limit }) => {
+ try {
+ const maxResults = limit ?? 10;
+ const graphNodes = await client.search(symbol, { limit: 5 });
+
+ const results: Array<{ kind: string; id?: string; name: string; file?: string; source: string }> = [];
+ for (const node of graphNodes) {
+ results.push({
+ kind: (node as any).kind,
+ id: (node as any).id,
+ name: (node as any).attrs?.name ?? (node as any).kind,
+ file: (node as any).provenance?.sourceUri,
+ source: "graph",
+ });
+ }
+
+ return {
+ content: [{ type: "text" as const, text: JSON.stringify(results.slice(0, maxResults), null, 2) }],
+ };
+ } catch (err) {
+ return {
+ isError: true,
+ content: [{ type: "text" as const, text: `ix_locate failed: ${String(err)}` }],
+ };
+ }
+ },
+);
+```
+
+**Step 5: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit && npm test`
+
+```bash
+git add ix-cli/src/cli/commands/locate.ts ix-cli/src/cli/format.ts ix-cli/src/cli/main.ts ix-cli/src/mcp/server.ts
+git commit -m "feat: add ix locate command — bridge text search to graph entities"
+```
+
+---
+
+### Task 4: Add `ix explain` command — entity summary with context
+
+`ix explain <symbol>` searches for an entity, shows its structure, container, and brief history.
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/explain.ts`
+- Modify: `ix-cli/src/cli/format.ts`
+- Modify: `ix-cli/src/cli/main.ts`
+- Modify: `ix-cli/src/mcp/server.ts`
+
+**Step 1: Create the explain command**
+
+Create `ix-cli/src/cli/commands/explain.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatExplain, type ExplainResult } from "../format.js";
+
+export function registerExplainCommand(program: Command): void {
+ program
+ .command("explain <symbol>")
+ .description("Explain an entity — shows structure, container, and history")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+
+ // Step 1: Find the entity
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ console.log(`No entity found matching "${symbol}".`);
+ return;
+ }
+ const node = nodes[0] as any;
+ const entityId = node.id;
+
+ // Step 2: Get entity details (claims, edges)
+ const details = await client.entity(entityId);
+
+ // Step 3: Get history
+ let history: any = { entityId, chain: [] };
+ try {
+ history = await client.provenance(entityId);
+ } catch { /* no history */ }
+
+ // Step 4: Find container (CONTAINS edge pointing to this entity)
+ const edges = (details.edges ?? []) as any[];
+ const containsEdge = edges.find((e: any) => e.predicate === "CONTAINS" && e.dst === entityId);
+ let container: any = undefined;
+ if (containsEdge) {
+ try {
+ const containerDetails = await client.entity(containsEdge.src);
+ container = containerDetails.node;
+ } catch { /* no container */ }
+ }
+
+ // Step 5: Count connections
+ const callEdges = edges.filter((e: any) => e.predicate === "CALLS");
+ const containedEdges = edges.filter((e: any) => e.predicate === "CONTAINS" && e.src === entityId);
+
+ const result: ExplainResult = {
+ kind: node.kind,
+ name: node.attrs?.name ?? node.name ?? symbol,
+ id: entityId,
+ file: node.provenance?.sourceUri,
+ container: container ? { kind: container.kind, name: container.attrs?.name ?? container.name } : undefined,
+ introducedRev: node.createdRev,
+ calledBy: callEdges.filter((e: any) => e.dst === entityId).length,
+ calls: callEdges.filter((e: any) => e.src === entityId).length,
+ contains: containedEdges.length,
+ historyLength: (history as any)?.chain?.length ?? 0,
+ };
+
+ formatExplain(result, opts.format);
+ });
+}
+```
+
+**Step 2: Add ExplainResult and formatExplain to format.ts**
+
+In `ix-cli/src/cli/format.ts`, add:
+
+```typescript
+export interface ExplainResult {
+ kind: string;
+ name: string;
+ id: string;
+ file?: string;
+ container?: { kind: string; name: string };
+ introducedRev: number;
+ calledBy: number;
+ calls: number;
+ contains: number;
+ historyLength: number;
+}
+
+export function formatExplain(result: ExplainResult, format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(result, null, 2));
+ return;
+ }
+ const shortId = result.id.slice(0, 8);
+ console.log(` ${chalk.cyan(result.kind)} ${chalk.bold(result.name)} ${chalk.dim(shortId)}`);
+ if (result.container) {
+ console.log(` ${chalk.dim("in")} ${chalk.cyan(result.container.kind)} ${result.container.name}`);
+ }
+ if (result.file) {
+ console.log(` ${chalk.dim("file")} ${result.file}`);
+ }
+ console.log(` ${chalk.dim("introduced rev")} ${result.introducedRev}`);
+ if (result.calledBy > 0) console.log(` ${chalk.dim("called by")} ${result.calledBy} methods`);
+ if (result.calls > 0) console.log(` ${chalk.dim("calls")} ${result.calls} methods`);
+ if (result.contains > 0) console.log(` ${chalk.dim("contains")} ${result.contains} members`);
+ if (result.historyLength > 0) console.log(` ${chalk.dim("history")} ${result.historyLength} patches`);
+}
+```
+
+**Step 3: Register in main.ts**
+
+```typescript
+import { registerExplainCommand } from "./commands/explain.js";
+// ...
+registerExplainCommand(program);
+```
+
+**Step 4: Add ix_explain MCP tool**
+
+In `ix-cli/src/mcp/server.ts`, add:
+
+```typescript
+// --- ix_explain --------------------------------------------------------------
+server.tool(
+ "ix_explain",
+ "Explain an entity — shows its type, container, history, and connections. Use when you want a quick summary of what something is and how it relates to the codebase.",
+ {
+ symbol: z.string().describe("Symbol name or entity ID to explain"),
+ },
+ async ({ symbol }) => {
+ try {
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ return { content: [{ type: "text" as const, text: `No entity found matching "${symbol}"` }] };
+ }
+ const node = nodes[0] as any;
+ const details = await client.entity(node.id);
+ let history: any = { chain: [] };
+ try { history = await client.provenance(node.id); } catch { /* ok */ }
+
+ const edges = (details.edges ?? []) as any[];
+ const containsEdge = edges.find((e: any) => e.predicate === "CONTAINS" && e.dst === node.id);
+ let container: string | undefined;
+ if (containsEdge) {
+ try {
+ const c = await client.entity(containsEdge.src);
+ container = `${(c.node as any).kind} ${(c.node as any).attrs?.name ?? (c.node as any).name}`;
+ } catch { /* ok */ }
+ }
+
+ const summary = {
+ kind: node.kind,
+ name: node.attrs?.name ?? node.name ?? symbol,
+ id: node.id,
+ file: node.provenance?.sourceUri,
+ container,
+ introducedRev: node.createdRev,
+ calledBy: edges.filter((e: any) => e.predicate === "CALLS" && e.dst === node.id).length,
+ calls: edges.filter((e: any) => e.predicate === "CALLS" && e.src === node.id).length,
+ contains: edges.filter((e: any) => e.predicate === "CONTAINS" && e.src === node.id).length,
+ historyLength: history?.chain?.length ?? 0,
+ };
+
+ return {
+ content: [{ type: "text" as const, text: JSON.stringify(summary, null, 2) }],
+ };
+ } catch (err) {
+ return {
+ isError: true,
+ content: [{ type: "text" as const, text: `ix_explain failed: ${String(err)}` }],
+ };
+ }
+ },
+);
+```
+
+**Step 5: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit && npm test`
+
+```bash
+git add ix-cli/src/cli/commands/explain.ts ix-cli/src/cli/format.ts ix-cli/src/cli/main.ts ix-cli/src/mcp/server.ts
+git commit -m "feat: add ix explain command — entity summary with structure and history"
+```
+
+---
+
+## Patch 4 — Graph Navigation + CLI Improvements
+
+---
+
+### Task 5: Add `ix callers` and `ix callees` commands
+
+These use the existing `expand` API with predicate filter `CALLS`.
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/callers.ts`
+- Modify: `ix-cli/src/client/api.ts`
+- Modify: `ix-cli/src/cli/format.ts`
+- Modify: `ix-cli/src/cli/main.ts`
+- Modify: `ix-cli/src/mcp/server.ts`
+
+**Step 1: Add expand method to API client**
+
+In `ix-cli/src/client/api.ts`, add:
+
+```typescript
+async expand(
+ id: string,
+ opts?: { direction?: string; predicates?: string[]; hops?: number }
+): Promise<{ nodes: GraphNode[]; edges: any[] }> {
+ return this.post("/v1/expand", {
+ nodeId: id,
+ direction: opts?.direction ?? "both",
+ predicates: opts?.predicates,
+ hops: opts?.hops ?? 1,
+ });
+}
+```
+
+**Step 2: Add expand backend route**
+
+The backend already has `queryApi.expand()` but no HTTP endpoint for it. Add one.
+
+Create `memory-layer/src/main/scala/ix/memory/api/ExpandRoutes.scala`:
+
+```scala
+package ix.memory.api
+
+import java.util.UUID
+
+import cats.effect.IO
+import io.circe.{Decoder, Encoder}
+import io.circe.generic.semiauto.{deriveDecoder, deriveEncoder}
+import io.circe.syntax._
+import org.http4s.HttpRoutes
+import org.http4s.circe.CirceEntityCodec._
+import org.http4s.dsl.io._
+
+import ix.memory.db.{Direction, GraphQueryApi}
+import ix.memory.model._
+
+case class ExpandRequest(
+ nodeId: String,
+ direction: Option[String] = None,
+ predicates: Option[List[String]] = None,
+ hops: Option[Int] = None,
+ asOfRev: Option[Long] = None
+)
+
+object ExpandRequest {
+ implicit val decoder: Decoder[ExpandRequest] = deriveDecoder[ExpandRequest]
+}
+
+class ExpandRoutes(queryApi: GraphQueryApi) {
+
+ val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
+ case req @ POST -> Root / "v1" / "expand" =>
+ (for {
+ body <- req.as[ExpandRequest]
+ nodeId <- IO.fromOption(
+ scala.util.Try(UUID.fromString(body.nodeId)).toOption.map(NodeId(_))
+ )(new IllegalArgumentException(s"Invalid node ID: ${body.nodeId}"))
+ dir = body.direction match {
+ case Some("in") => Direction.In
+ case Some("out") => Direction.Out
+ case _ => Direction.Both
+ }
+ preds = body.predicates.map(_.toSet)
+ result <- queryApi.expand(nodeId, dir, preds, body.hops.getOrElse(1), body.asOfRev.map(Rev(_)))
+ resp <- Ok(result.asJson)
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+ }
+}
+```
+
+Note: This requires `ExpandResult` to have an Encoder. Check if it exists — if not, add it.
+
+**Step 3: Add ExpandResult encoder if missing**
+
+In `memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala`, check if `ExpandResult` has an encoder. If not, add:
+
+```scala
+object ExpandResult {
+ implicit val encoder: Encoder[ExpandResult] = deriveEncoder[ExpandResult]
+}
+```
+
+This requires adding the import `import io.circe.generic.semiauto.deriveEncoder` at the top.
+
+**Step 4: Wire ExpandRoutes into Routes.scala**
+
+In `memory-layer/src/main/scala/ix/memory/api/Routes.scala`, add:
+
+```scala
+val expandRoutes = new ExpandRoutes(queryApi).routes
+```
+
+And add `<+> expandRoutes` to the combined routes.
+
+**Step 5: Create callers command**
+
+Create `ix-cli/src/cli/commands/callers.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatEdgeResults } from "../format.js";
+
+export function registerCallersCommand(program: Command): void {
+ program
+ .command("callers <symbol>")
+ .description("Show methods/functions that call the given symbol")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+
+ // Find the entity
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ console.log(`No entity found matching "${symbol}".`);
+ return;
+ }
+ const entityId = (nodes[0] as any).id;
+
+ // Expand inbound CALLS edges
+ const result = await client.expand(entityId, { direction: "in", predicates: ["CALLS"] });
+
+ formatEdgeResults(result.nodes as any[], "callers", symbol, opts.format);
+ });
+
+ program
+ .command("callees <symbol>")
+ .description("Show methods/functions called by the given symbol")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ console.log(`No entity found matching "${symbol}".`);
+ return;
+ }
+ const entityId = (nodes[0] as any).id;
+
+ const result = await client.expand(entityId, { direction: "out", predicates: ["CALLS"] });
+
+ formatEdgeResults(result.nodes as any[], "callees", symbol, opts.format);
+ });
+}
+```
+
+**Step 6: Add formatEdgeResults to format.ts**
+
+```typescript
+export function formatEdgeResults(nodes: any[], relation: string, symbol: string, format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(nodes, null, 2));
+ return;
+ }
+ if (nodes.length === 0) {
+ console.log(`No ${relation} found for "${symbol}".`);
+ return;
+ }
+ console.log(`${chalk.bold(relation)} of ${chalk.cyan(symbol)}:`);
+ for (const n of nodes) {
+ const shortId = n.id?.slice(0, 8) ?? "";
+ const name = n.attrs?.name ?? n.name ?? n.id;
+ console.log(` ${chalk.cyan(n.kind)} ${chalk.dim(shortId)} ${name}`);
+ }
+}
+```
+
+**Step 7: Register in main.ts**
+
+```typescript
+import { registerCallersCommand } from "./commands/callers.js";
+// ...
+registerCallersCommand(program);
+```
+
+**Step 8: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit`
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/api/ExpandRoutes.scala \
+ memory-layer/src/main/scala/ix/memory/api/Routes.scala \
+ memory-layer/src/main/scala/ix/memory/db/GraphQueryApi.scala \
+ ix-cli/src/cli/commands/callers.ts \
+ ix-cli/src/cli/format.ts \
+ ix-cli/src/cli/main.ts \
+ ix-cli/src/client/api.ts \
+ ix-cli/src/mcp/server.ts
+git commit -m "feat: add ix callers/callees commands with expand backend route"
+```
+
+---
+
+### Task 6: Add `ix imports` and `ix imported-by` commands
+
+Same pattern as callers/callees but with `IMPORTS` predicate.
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/imports.ts`
+- Modify: `ix-cli/src/cli/main.ts`
+
+**Step 1: Create imports command**
+
+Create `ix-cli/src/cli/commands/imports.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatEdgeResults } from "../format.js";
+
+export function registerImportsCommand(program: Command): void {
+ program
+ .command("imports <symbol>")
+ .description("Show what the given entity imports")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ console.log(`No entity found matching "${symbol}".`);
+ return;
+ }
+ const entityId = (nodes[0] as any).id;
+
+ const result = await client.expand(entityId, { direction: "out", predicates: ["IMPORTS"] });
+ formatEdgeResults(result.nodes as any[], "imports", symbol, opts.format);
+ });
+
+ program
+ .command("imported-by <symbol>")
+ .description("Show what imports the given entity")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ console.log(`No entity found matching "${symbol}".`);
+ return;
+ }
+ const entityId = (nodes[0] as any).id;
+
+ const result = await client.expand(entityId, { direction: "in", predicates: ["IMPORTS"] });
+ formatEdgeResults(result.nodes as any[], "imported-by", symbol, opts.format);
+ });
+}
+```
+
+**Step 2: Register in main.ts**
+
+```typescript
+import { registerImportsCommand } from "./commands/imports.js";
+// ...
+registerImportsCommand(program);
+```
+
+**Step 3: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit`
+
+```bash
+git add ix-cli/src/cli/commands/imports.ts ix-cli/src/cli/main.ts
+git commit -m "feat: add ix imports/imported-by commands"
+```
+
+---
+
+### Task 7: Add `ix contains` command
+
+Uses `CONTAINS` predicate to show members of a class/module.
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/contains.ts`
+- Modify: `ix-cli/src/cli/main.ts`
+
+**Step 1: Create contains command**
+
+Create `ix-cli/src/cli/commands/contains.ts`:
+
+```typescript
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatEdgeResults } from "../format.js";
+
+export function registerContainsCommand(program: Command): void {
+ program
+ .command("contains <symbol>")
+ .description("Show members contained by the given entity (class, module, file)")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ console.log(`No entity found matching "${symbol}".`);
+ return;
+ }
+ const entityId = (nodes[0] as any).id;
+
+ const result = await client.expand(entityId, { direction: "out", predicates: ["CONTAINS"] });
+ formatEdgeResults(result.nodes as any[], "contains", symbol, opts.format);
+ });
+}
+```
+
+**Step 2: Register in main.ts**
+
+```typescript
+import { registerContainsCommand } from "./commands/contains.js";
+// ...
+registerContainsCommand(program);
+```
+
+**Step 3: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit`
+
+```bash
+git add ix-cli/src/cli/commands/contains.ts ix-cli/src/cli/main.ts
+git commit -m "feat: add ix contains command for entity member listing"
+```
+
+---
+
+### Task 8: Add `ix stats` command — graph statistics
+
+Add a backend endpoint that returns aggregate counts and a CLI command to display them.
+
+**Files:**
+- Create: `memory-layer/src/main/scala/ix/memory/api/StatsRoutes.scala`
+- Modify: `memory-layer/src/main/scala/ix/memory/api/Routes.scala`
+- Create: `ix-cli/src/cli/commands/stats.ts`
+- Modify: `ix-cli/src/client/api.ts`
+- Modify: `ix-cli/src/cli/main.ts`
+- Modify: `ix-cli/src/mcp/server.ts`
+
+**Step 1: Create backend stats endpoint**
+
+Create `memory-layer/src/main/scala/ix/memory/api/StatsRoutes.scala`:
+
+```scala
+package ix.memory.api
+
+import cats.effect.IO
+import io.circe.Json
+import io.circe.syntax._
+import org.http4s.HttpRoutes
+import org.http4s.circe.CirceEntityCodec._
+import org.http4s.dsl.io._
+
+import ix.memory.db.ArangoClient
+
+class StatsRoutes(client: ArangoClient) {
+
+ val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
+ case GET -> Root / "v1" / "stats" =>
+ (for {
+ nodeStats <- client.query(
+ """FOR n IN nodes
+ | FILTER n.deleted_rev == null
+ | COLLECT kind = n.kind WITH COUNT INTO cnt
+ | SORT cnt DESC
+ | RETURN { kind: kind, count: cnt }""".stripMargin,
+ Map.empty[String, AnyRef]
+ )
+ edgeStats <- client.query(
+ """FOR e IN edges
+ | FILTER e.deleted_rev == null
+ | COLLECT predicate = e.predicate WITH COUNT INTO cnt
+ | SORT cnt DESC
+ | RETURN { predicate: predicate, count: cnt }""".stripMargin,
+ Map.empty[String, AnyRef]
+ )
+ totalNodes <- client.query(
+ """RETURN LENGTH(FOR n IN nodes FILTER n.deleted_rev == null RETURN 1)""",
+ Map.empty[String, AnyRef]
+ )
+ totalEdges <- client.query(
+ """RETURN LENGTH(FOR e IN edges FILTER e.deleted_rev == null RETURN 1)""",
+ Map.empty[String, AnyRef]
+ )
+ resp <- Ok(Json.obj(
+ "nodes" -> Json.obj(
+ "total" -> totalNodes.headOption.flatMap(_.asNumber).flatMap(_.toInt).getOrElse(0).asJson,
+ "byKind" -> nodeStats.asJson
+ ),
+ "edges" -> Json.obj(
+ "total" -> totalEdges.headOption.flatMap(_.asNumber).flatMap(_.toInt).getOrElse(0).asJson,
+ "byPredicate" -> edgeStats.asJson
+ )
+ ))
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+ }
+}
+```
+
+**Step 2: Wire into Routes.scala**
+
+Add to `Routes.scala`:
+
+```scala
+val statsRoutes = new StatsRoutes(client).routes
+```
+
+Add `<+> statsRoutes` to the combined routes.
+
+**Step 3: Add stats API method**
+
+In `ix-cli/src/client/api.ts`:
+
+```typescript
+async stats(): Promise<any> {
+ return this.get("/v1/stats");
+}
+```
+
+**Step 4: Create CLI stats command**
+
+Create `ix-cli/src/cli/commands/stats.ts`:
+
+```typescript
+import type { Command } from "commander";
+import chalk from "chalk";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+
+export function registerStatsCommand(program: Command): void {
+ program
+ .command("stats")
+ .description("Show graph statistics — node/edge counts by type")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const result = await client.stats();
+
+ if (opts.format === "json") {
+ console.log(JSON.stringify(result, null, 2));
+ return;
+ }
+
+ console.log(chalk.bold("\nnodes") + chalk.dim(` (${result.nodes.total} total)`));
+ for (const entry of result.nodes.byKind) {
+ const kind = entry.kind ?? "unknown";
+ const count = entry.count ?? 0;
+ console.log(` ${chalk.cyan(kind)}: ${count}`);
+ }
+
+ console.log(chalk.bold("\nedges") + chalk.dim(` (${result.edges.total} total)`));
+ for (const entry of result.edges.byPredicate) {
+ const pred = entry.predicate ?? "unknown";
+ const count = entry.count ?? 0;
+ console.log(` ${chalk.cyan(pred)}: ${count}`);
+ }
+ console.log();
+ });
+}
+```
+
+**Step 5: Register in main.ts and add MCP tool**
+
+Register in main.ts:
+
+```typescript
+import { registerStatsCommand } from "./commands/stats.js";
+// ...
+registerStatsCommand(program);
+```
+
+Add MCP tool in server.ts:
+
+```typescript
+// --- ix_stats ----------------------------------------------------------------
+server.tool(
+ "ix_stats",
+ "Show graph statistics — total nodes and edges with breakdown by kind/predicate. Use to verify ingestion and understand graph size.",
+ {},
+ async () => {
+ try {
+ const stats = await client.stats();
+ return {
+ content: [{ type: "text" as const, text: JSON.stringify(stats, null, 2) }],
+ };
+ } catch (err) {
+ return {
+ isError: true,
+ content: [{ type: "text" as const, text: `ix_stats failed: ${String(err)}` }],
+ };
+ }
+ },
+);
+```
+
+**Step 6: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit`
+
+```bash
+git add memory-layer/src/main/scala/ix/memory/api/StatsRoutes.scala \
+ memory-layer/src/main/scala/ix/memory/api/Routes.scala \
+ ix-cli/src/cli/commands/stats.ts \
+ ix-cli/src/client/api.ts \
+ ix-cli/src/cli/main.ts \
+ ix-cli/src/mcp/server.ts
+git commit -m "feat: add ix stats command with graph statistics endpoint"
+```
+
+---
+
+### Task 9: Add `ix doctor` command — graph integrity check
+
+Client-side command that uses existing APIs to detect issues.
+
+**Files:**
+- Create: `ix-cli/src/cli/commands/doctor.ts`
+- Modify: `ix-cli/src/cli/main.ts`
+- Modify: `ix-cli/src/mcp/server.ts`
+
+**Step 1: Create doctor command**
+
+Create `ix-cli/src/cli/commands/doctor.ts`:
+
+```typescript
+import type { Command } from "commander";
+import chalk from "chalk";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+
+export function registerDoctorCommand(program: Command): void {
+ program
+ .command("doctor")
+ .description("Check graph integrity — detect orphans, missing edges, duplicates")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const issues: Array<{ type: string; severity: string; message: string }> = [];
+
+ // 1. Check backend health
+ try {
+ await client.health();
+ } catch {
+ issues.push({ type: "connectivity", severity: "error", message: "Backend is not reachable" });
+ if (opts.format === "json") {
+ console.log(JSON.stringify({ issues }, null, 2));
+ } else {
+ console.log(chalk.red("Error: Backend is not reachable."));
+ }
+ return;
+ }
+
+ // 2. Check graph stats for anomalies
+ try {
+ const stats = await client.stats();
+ const totalNodes = stats.nodes?.total ?? 0;
+ const totalEdges = stats.edges?.total ?? 0;
+
+ if (totalNodes === 0) {
+ issues.push({ type: "empty_graph", severity: "warning", message: "Graph is empty — run ix ingest first" });
+ } else if (totalEdges === 0 && totalNodes > 1) {
+ issues.push({ type: "no_edges", severity: "warning", message: `${totalNodes} nodes but 0 edges — relationships may not be parsed` });
+ }
+
+ // Check for very low edge:node ratio
+ if (totalNodes > 10 && totalEdges / totalNodes < 0.1) {
+ issues.push({
+ type: "sparse_graph",
+ severity: "info",
+ message: `Low edge:node ratio (${totalEdges}/${totalNodes} = ${(totalEdges / totalNodes).toFixed(2)}) — graph may be sparsely connected`,
+ });
+ }
+ } catch (err) {
+ issues.push({ type: "stats_error", severity: "error", message: `Could not fetch stats: ${err}` });
+ }
+
+ // 3. Check for conflicts
+ try {
+ const conflicts = await client.conflicts();
+ if (conflicts.length > 0) {
+ issues.push({
+ type: "conflicts",
+ severity: "warning",
+ message: `${conflicts.length} unresolved conflicts detected`,
+ });
+ }
+ } catch { /* ok */ }
+
+ // Output
+ if (opts.format === "json") {
+ console.log(JSON.stringify({ issues, healthy: issues.filter(i => i.severity === "error").length === 0 }, null, 2));
+ return;
+ }
+
+ if (issues.length === 0) {
+ console.log(chalk.green("✓ Graph looks healthy — no issues detected."));
+ } else {
+ for (const issue of issues) {
+ const icon = issue.severity === "error" ? chalk.red("✗")
+ : issue.severity === "warning" ? chalk.yellow("!")
+ : chalk.blue("i");
+ console.log(` ${icon} ${issue.message}`);
+ }
+ const errors = issues.filter(i => i.severity === "error").length;
+ if (errors === 0) {
+ console.log(chalk.green("\n✓ No critical issues."));
+ } else {
+ console.log(chalk.red(`\n✗ ${errors} critical issue(s) found.`));
+ }
+ }
+ });
+}
+```
+
+**Step 2: Register in main.ts**
+
+```typescript
+import { registerDoctorCommand } from "./commands/doctor.js";
+// ...
+registerDoctorCommand(program);
+```
+
+**Step 3: Add MCP tool**
+
+In `ix-cli/src/mcp/server.ts`:
+
+```typescript
+// --- ix_doctor ---------------------------------------------------------------
+server.tool(
+ "ix_doctor",
+ "Check graph integrity — detects empty graphs, missing edges, conflicts, and connectivity issues.",
+ {},
+ async () => {
+ try {
+ const issues: Array<{ type: string; severity: string; message: string }> = [];
+
+ try { await client.health(); } catch {
+ return { content: [{ type: "text" as const, text: JSON.stringify({ issues: [{ type: "connectivity", severity: "error", message: "Backend not reachable" }], healthy: false }, null, 2) }] };
+ }
+
+ try {
+ const stats = await client.stats();
+ if ((stats.nodes?.total ?? 0) === 0) {
+ issues.push({ type: "empty_graph", severity: "warning", message: "Graph is empty" });
+ }
+ } catch { /* ok */ }
+
+ try {
+ const conflicts = await client.conflicts();
+ if (conflicts.length > 0) {
+ issues.push({ type: "conflicts", severity: "warning", message: `${conflicts.length} unresolved conflicts` });
+ }
+ } catch { /* ok */ }
+
+ return {
+ content: [{ type: "text" as const, text: JSON.stringify({ issues, healthy: issues.filter(i => i.severity === "error").length === 0 }, null, 2) }],
+ };
+ } catch (err) {
+ return {
+ isError: true,
+ content: [{ type: "text" as const, text: `ix_doctor failed: ${String(err)}` }],
+ };
+ }
+ },
+);
+```
+
+**Step 4: Verify and commit**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit && npm test`
+
+```bash
+git add ix-cli/src/cli/commands/doctor.ts ix-cli/src/cli/main.ts ix-cli/src/mcp/server.ts
+git commit -m "feat: add ix doctor command for graph integrity checking"
+```
+
+---
+
+### Task 10: Final verification
+
+**Step 1: Backend compilation**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory && sbt compile`
+Expected: `[success]`
+
+**Step 2: CLI type check and tests**
+
+Run: `cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli && npx tsc --noEmit && npm test`
+Expected: All tests pass
+
+**Step 3: Review git log**
+
+Run: `git log --oneline -12`
+Expected: Clean commit history
+
+**Step 4: Manual smoke test**
+
+```bash
+cd /Users/rileythompson/startprojes/startup/giter/IX-Memory/ix-cli
+
+# Text search with new schema
+npx tsx src/cli/main.ts text parseClaim --json
+
+# Locate
+npx tsx src/cli/main.ts locate parseClaim
+
+# Explain
+npx tsx src/cli/main.ts explain parseClaim
+
+# Graph navigation
+npx tsx src/cli/main.ts callers parseClaim
+npx tsx src/cli/main.ts contains ArangoGraphQueryApi
+
+# Stats
+npx tsx src/cli/main.ts stats
+
+# Doctor
+npx tsx src/cli/main.ts doctor
+```
+
+---
+
+## Summary of New Commands
+
+| Command | Patch | Description |
+|---------|-------|-------------|
+| `ix text` (updated) | 3 | Standardized schema + --language filter |
+| `ix locate <symbol>` | 3 | Bridge text→graph entities |
+| `ix explain <symbol>` | 3 | Entity summary with context |
+| `ix callers <symbol>` | 4 | Show what calls this symbol |
+| `ix callees <symbol>` | 4 | Show what this symbol calls |
+| `ix imports <entity>` | 4 | Show imports |
+| `ix imported-by <entity>` | 4 | Show importers |
+| `ix contains <entity>` | 4 | Show contained members |
+| `ix stats` | 4 | Graph node/edge counts |
+| `ix doctor` | 4 | Graph integrity check |
+
+## New Backend Routes
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/v1/expand` | POST | Expand node neighborhood with predicate filters |
+| `/v1/stats` | GET | Graph statistics (node/edge counts by kind) |