Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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) |