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
feat: make CLI the canonical agent interface, deprecate MCP
riley02273e343567965f
diff --git a/CLAUDE.md b/CLAUDE.mdindex e4564889..e18d6972 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -3,85 +3,103 @@This project uses Ix Memory — persistent, time-aware context for LLM assistants.+## Interface++Use the `ix` CLI exclusively. Do NOT use MCP tools — the CLI is the canonical agent interface.++All commands support `--format json` for machine-readable output. Use JSON when chaining command results.+## MANDATORY RULES-1. BEFORE answering codebase questions → use targeted Ix tools (see Command Routing below). Do NOT answer from training data alone.-2. AFTER every design or architecture decision → call `ix_decide` with both the conclusion AND the reasoning.-3. When you notice contradictory information → call `ix_conflicts` and present conflicts to the user before continuing.-4. NEVER guess about codebase facts — if Ix has structured data, use it. Say "according to Ix" when citing results.-5. IMMEDIATELY after modifying code → call `ix_ingest` on changed files. Do not batch this to the end of the session.-6. At start of each session → review `ix://session/context` to load prior work and decisions.-7. When the user states a goal → call `ix_truth` to record the intent so all decisions can trace back to it.+1. BEFORE answering codebase questions → use targeted `ix` CLI commands (see routing below). Do NOT answer from training data alone.+2. AFTER every design or architecture decision → run `ix decide <title> --rationale <text>`.+3. When you notice contradictory information → run `ix conflicts` and present results to the user.+4. NEVER guess about codebase facts — if Ix has structured data, use it.+5. IMMEDIATELY after modifying code → run `ix ingest <path>` on changed files.+6. When the user states a goal → run `ix truth add "<statement>"`.-## Preferred Ix Command Routing+## Ix CLI Command Routing-Use bounded, composable primitives — never broad NLP-style queries.+Use bounded, composable CLI commands — never broad queries.-| Question type | Command | Example |+### Finding & Understanding Code+| Goal | Command | Example |+|---|---|---|+| Find entity by name | `ix search` | `ix search IngestionService --kind class --limit 10` |+| Understand a symbol | `ix explain` | `ix explain IngestionService` |+| Read source code | `ix read` | `ix read src/auth.py:10-50` or `ix read verify_token` |+| Full entity details | `ix entity` | `ix entity <id> --format json` |+| Fast text search | `ix text` | `ix text "verify_token" --language python --limit 20` |+| Find symbol (graph+text) | `ix locate` | `ix locate AuthProvider --limit 10` |++### Navigating Relationships+| Goal | Command | Example |+|---|---|---|+| What calls a function | `ix callers` | `ix callers verify_token --format json` |+| What a function calls | `ix callees` | `ix callees processPayment` |+| Members of a class | `ix contains` | `ix contains IngestionService` |+| What an entity imports | `ix imports` | `ix imports auth_provider.py` |+| What imports an entity | `ix imported-by` | `ix imported-by AuthProvider` |+| Dependency impact | `ix depends` | `ix depends verify_token --depth 2` |++### History & Decisions+| Goal | Command | Example ||---|---|---|-| Find an entity by name | `ix_search` | `ix_search "IngestionService" --kind class` |-| Understand a symbol | `ix_entity` | `ix_entity <id>` |-| What calls a function | `ix_expand` | `ix_expand <id> direction=in predicates=["CALLS"]` |-| What a function calls | `ix_expand` | `ix_expand <id> direction=out predicates=["CALLS"]` |-| Members of a class/module | `ix_expand` | `ix_expand <id> direction=out predicates=["CONTAINS"]` |-| What imports something | `ix_expand` | `ix_expand <id> direction=in predicates=["IMPORTS"]` |-| Exact text/snippet search | `ix_text` | `ix_text "verify_token" --language python` |-| Past design decisions | `ix_decisions` | `ix_decisions --topic "ingestion"` |-| Entity change history | `ix_history` | `ix_history <entityId>` |-| What changed between revisions | `ix_diff` | `ix_diff 1 5` |-| Detect contradictions | `ix_conflicts` | `ix_conflicts` |-| Record a goal | `ix_truth` | `ix_truth add "Support 100k file repos"` |+| Design decisions | `ix decisions` | `ix decisions --topic ingestion --limit 10` |+| Entity history | `ix history` | `ix history <entityId>` |+| Changes between revisions | `ix diff` | `ix diff 1 5 --format json` |+| Detect contradictions | `ix conflicts` | `ix conflicts --format json` |+| Record a decision | `ix decide` | `ix decide "Use CONTAINS" --rationale "Normalize edges"` |+| Record a goal | `ix truth add` | `ix truth add "Support 100k file repos"` |+| List goals | `ix truth list` | `ix truth list --format json` |++### Ingestion & Health+| Goal | Command | Example |+|---|---|---|+| Ingest files | `ix ingest` | `ix ingest ./src --recursive` |+| Backend health | `ix status` | `ix status` |+| Graph statistics | `ix stats` | `ix stats --format json` |### Decomposition Examples-**"List all files and what they import"**-1. `ix_search "" --kind file --limit 50`-2. For each file: `ix_expand <id> direction=out predicates=["IMPORTS"]`-**"How does ingestion work?"**-1. `ix_search "IngestionService" --kind class`-2. `ix_entity <id>` — get details-3. `ix_expand <id> direction=out predicates=["CONTAINS"]` — see methods-4. `ix_expand <methodId> direction=out predicates=["CALLS"]` — see what each method calls+```bash+ix search IngestionService --kind class --format json+ix explain IngestionService --format json+ix contains IngestionService --format json+ix callees parseFile --format json+```**"What depends on verify_token?"**-1. `ix_search "verify_token" --kind function`-2. `ix_expand <id> direction=in predicates=["CALLS"]` — callers-3. `ix_expand <id> direction=in predicates=["IMPORTS"]` — importers--### Bounded-Result Best Practices+```bash+ix depends verify_token --format json+# or manually:+ix callers verify_token --format json+ix imported-by verify_token --format json+```++**"List all files and their imports"**+```bash+ix search "" --kind file --limit 50 --format json+ix imports <filename> --format json # for each file+```++### Best Practices- Always use `--kind` to filter entity type when searching- Always use `--limit` to cap result sets-- Use `--path` to restrict text searches to specific directories-- Use exact entity IDs from previous results, not broad queries-- Decompose large questions into multiple targeted tool calls--## Avoid ix_query--`ix_query` is **deprecated**. Do NOT use it for:-- Broad repo-wide inventory ("list all classes")-- NLP-style QA ("how does X work?")-- Exploratory graph sweeps--These produce oversized, low-signal responses that waste tokens and return noisy data. Always decompose into the targeted commands above.--## Workflow-A typical session follows this flow:-1. **Start** — Read `ix://session/context` and `ix://project/intent` to understand prior state.-2. **Explore** — Use `ix_search` + `ix_entity` + `ix_expand` to understand relevant code.-3. **Work** — Implement changes, making decisions as needed.-4. **Ingest** — After each file change, call `ix_ingest` immediately to keep the graph current.-5. **Decide** — Record any design decisions with `ix_decide` so future sessions can understand why.--## What NOT to Do-- Do NOT use `ix_query` for broad exploration — decompose into targeted commands instead.-- Do NOT answer architecture questions from training data alone — always check Ix first.-- Do NOT skip `ix_ingest` after modifying files — stale memory leads to wrong answers next session.-- Do NOT record a decision without rationale — "we chose X" is useless without "because Y".-- Do NOT ignore conflicts — if `ix_conflicts` returns results, surface them to the user before proceeding.+- Use `--format json` when chaining results between commands+- Use `--path` or `--language` to restrict text searches+- Use exact entity IDs from previous JSON results+- Decompose large questions into multiple targeted calls++## Do NOT Use+- `ix query` — deprecated, produces oversized low-signal responses+- MCP tools (`ix_query`, `ix_search`, etc.) — deprecated, use CLI instead+- Broad repo-wide inventory queries+- NLP-style QA in a single command## Confidence Scores-Ix returns confidence scores with query results. When data has low confidence:-- Mention the uncertainty to the user (e.g., "Ix has low confidence on this — it may be outdated").-- Suggest re-ingesting the relevant files to improve confidence.-- Never present low-confidence data as established fact.+Ix returns confidence scores with results. When data has low confidence:+- Mention the uncertainty to the user+- Suggest re-ingesting the relevant files+- Never present low-confidence data as established fact<!-- IX-MEMORY END -->diff --git a/README.md b/README.mdindex 396360e8..29c92b10 100644--- a/README.md+++ b/README.md@@ -115,66 +115,31 @@ All commands accept `--format json` for machine-readable output.| `ix mcp-install` | `ix mcp-install [--cursor\|--claude-code]` | Install MCP server config || `ix mcp-start` | `ix mcp-start` | Start the MCP server (stdio) |-## MCP Integration+## MCP Integration (Compatibility Only)-Ix exposes 13 tools and 2 resources over the [Model Context Protocol](https://modelcontextprotocol.io/), so LLMs can query, ingest, and record decisions automatically.+> **Note:** The CLI is now the canonical agent interface. MCP is retained for backward compatibility but is no longer the recommended integration path. Use `ix` CLI commands with `--format json` instead.-### Claude Code+MCP server installation is still available if needed:```bash-ix mcp-install --claude-code+ix mcp-install --claude-code # Claude Code+ix mcp-install --cursor # Cursor+ix mcp-install # Claude Desktop```-### Cursor--```bash-ix mcp-install --cursor-```--### Claude Desktop--```bash-ix mcp-install-```--### MCP Tools--| Tool | Description |-|------|-------------|-| `ix_query` | [DEPRECATED] Broad graph query — use ix_search + ix_entity + ix_expand instead |-| `ix_ingest` | Ingest files into the graph (call IMMEDIATELY after file changes) |-| `ix_decide` | Record a design decision with rationale |-| `ix_search` | Search nodes by term |-| `ix_entity` | Get full entity details |-| `ix_expand` | Expand a node's neighborhood |-| `ix_history` | Get provenance chain |-| `ix_truth` | Manage project intents |-| `ix_diff` | Diff between revisions |-| `ix_conflicts` | List conflicts |-| `ix_resolve` | Resolve a conflict |-| `ix_assert` | Assert a claim about an entity |-| `ix_patches` | List or get patches |--### MCP Resources--| URI | Description |-|-----|-------------|-| `ix://session/context` | Current session working set (entities queried, decisions made) |-| `ix://project/intent` | Project intent tree |-## Architecture```-┌─────────────┐ ┌──────────────────┐ ┌───────────┐-│ ix CLI │────>│ Memory Layer │────>│ ArangoDB │-│ (TypeScript)│ │ (Scala/http4s) │ │ (Graph) │-└─────────────┘ └──────────────────┘ └───────────┘- │-┌──────┴──────┐-│ MCP Server │ (stdio transport, same TypeScript codebase)-│ 13 tools │-│ 2 resources│-└─────────────┘+ ┌──────────────────┐ ┌───────────┐+┌─────────────┐ │ Memory Layer │────>│ ArangoDB │+│ ix CLI │───>│ (Scala/http4s) │ │ (Graph) │+│ (canonical)│ └──────────────────┘ └───────────┘+└─────────────┘ ▲+ ┌────────┘+ │+ ┌─────┴───────┐+ │ MCP Server │ (compatibility only)+ └─────────────┘```- **Memory Layer** — Scala 2.13, Cats Effect 3, http4s 0.23, Circe. Handles ingestion, parsing, graph operations, context assembly with 6-factor confidence scoring.diff --git a/ix-cli/src/cli/__tests__/init.test.ts b/ix-cli/src/cli/__tests__/init.test.tsindex 0748a0eb..c5b374fa 100644--- a/ix-cli/src/cli/__tests__/init.test.ts+++ b/ix-cli/src/cli/__tests__/init.test.ts@@ -19,24 +19,24 @@ beforeAll(async () => {});describe("CLAUDE_MD template", () => {- it("contains all 7 mandatory rules and command routing", () => {- expect(CLAUDE_MD).toContain("ix_decide");- expect(CLAUDE_MD).toContain("ix_conflicts");+ it("contains mandatory rules and CLI command routing", () => {+ expect(CLAUDE_MD).toContain("ix decide");+ expect(CLAUDE_MD).toContain("ix conflicts");expect(CLAUDE_MD).toContain("NEVER guess");- expect(CLAUDE_MD).toContain("ix_ingest");- expect(CLAUDE_MD).toContain("ix://session/context");- expect(CLAUDE_MD).toContain("ix_truth");- expect(CLAUDE_MD).toContain("ix_search");- expect(CLAUDE_MD).toContain("ix_entity");- expect(CLAUDE_MD).toContain("ix_expand");+ expect(CLAUDE_MD).toContain("ix ingest");+ expect(CLAUDE_MD).toContain("ix truth");+ expect(CLAUDE_MD).toContain("ix search");+ expect(CLAUDE_MD).toContain("ix explain");+ expect(CLAUDE_MD).toContain("ix callers");});- it("contains a Workflow section", () => {- expect(CLAUDE_MD).toContain("## Workflow");+ it("routes through CLI exclusively, not MCP", () => {+ expect(CLAUDE_MD).toContain("ix` CLI exclusively");+ expect(CLAUDE_MD).toContain("Do NOT use MCP");});- it("contains a What NOT to Do section", () => {- expect(CLAUDE_MD).toContain("## What NOT to Do");+ it("contains a Do NOT Use section", () => {+ expect(CLAUDE_MD).toContain("## Do NOT Use");});it("contains a Confidence Scores section", () => {@@ -48,8 +48,8 @@ describe("CLAUDE_MD template", () => {expect(lines.length).toBeLessThan(80);});- it("has numbered rules 1-7 in the MANDATORY RULES section", () => {- for (let i = 1; i <= 7; i++) {+ it("has numbered rules 1-6 in the MANDATORY RULES section", () => {+ for (let i = 1; i <= 6; i++) {expect(CLAUDE_MD).toContain(`${i}.`);}});diff --git a/ix-cli/src/cli/commands/callers.ts b/ix-cli/src/cli/commands/callers.tsindex 5a3d539a..d155ec29 100644--- a/ix-cli/src/cli/commands/callers.ts+++ b/ix-cli/src/cli/commands/callers.ts@@ -14,9 +14,12 @@ export function registerCallersCommand(program: Command): void {.command("callers <symbol>").description("Show methods/functions that call the given symbol (cross-file)").option("--kind <kind>", "Filter target entity by kind")+ .option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json)", "text")- .action(async (symbol: string, opts: { kind?: string; format: string }) => {+ .addHelpText("after", "\nExamples:\n ix callers verify_token\n ix callers processPayment --format json\n ix callers parse --kind method --limit 20")+ .action(async (symbol: string, opts: { kind?: string; limit: string; format: string }) => {const client = new IxClient(getEndpoint());+ const limit = parseInt(opts.limit, 10);const target = await resolveEntity(client, symbol, ["method", "function"], opts);if (!target) return;printResolved(target);@@ -74,7 +77,7 @@ export function registerCallersCommand(program: Command): void {// Both graph and text emptyformatEdgeResults([], "callers", target.name, opts.format, target, "graph");} else {- formatEdgeResults(result.nodes, "callers", target.name, opts.format, target, "graph");+ formatEdgeResults(result.nodes.slice(0, limit), "callers", target.name, opts.format, target, "graph");}});@@ -82,9 +85,12 @@ export function registerCallersCommand(program: Command): void {.command("callees <symbol>").description("Show methods/functions called by the given symbol (cross-file)").option("--kind <kind>", "Filter target entity by kind")+ .option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json)", "text")- .action(async (symbol: string, opts: { kind?: string; format: string }) => {+ .addHelpText("after", "\nExamples:\n ix callees processPayment\n ix callees parse --format json")+ .action(async (symbol: string, opts: { kind?: string; limit: string; format: string }) => {const client = new IxClient(getEndpoint());+ const calleeLimit = parseInt(opts.limit, 10);const target = await resolveEntity(client, symbol, ["method", "function"], opts);if (!target) return;printResolved(target);@@ -94,6 +100,6 @@ export function registerCallersCommand(program: Command): void {predicates: ["CALLS"],kinds: ["function", "method"],});- formatEdgeResults(result.nodes, "callees", target.name, opts.format, target, "graph");+ formatEdgeResults(result.nodes.slice(0, calleeLimit), "callees", target.name, opts.format, target, "graph");});}diff --git a/ix-cli/src/cli/commands/contains.ts b/ix-cli/src/cli/commands/contains.tsindex 6b8767ea..7a351873 100644--- a/ix-cli/src/cli/commands/contains.ts+++ b/ix-cli/src/cli/commands/contains.ts@@ -9,13 +9,17 @@ export function registerContainsCommand(program: Command): void {.command("contains <symbol>").description("Show members contained by the given entity (class, module, file)").option("--kind <kind>", "Filter target entity by kind")+ .option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json)", "text")- .action(async (symbol: string, opts: { kind?: string; format: string }) => {+ .addHelpText("after", "\nExamples:\n ix contains IngestionService\n ix contains auth.py --kind file --format json\n ix contains MyClass --limit 20")+ .action(async (symbol: string, opts: { kind?: string; limit: string; format: string }) => {const client = new IxClient(getEndpoint());+ const limit = parseInt(opts.limit, 10);const target = await resolveEntity(client, symbol, ["class", "object", "trait", "interface", "module", "file"], opts);if (!target) return;printResolved(target);const result = await client.expand(target.id, { direction: "out", predicates: ["CONTAINS"] });- formatEdgeResults(result.nodes, "contains", target.name, opts.format, target, "graph");+ const limited = result.nodes.slice(0, limit);+ formatEdgeResults(limited, "contains", target.name, opts.format, target, "graph");});}diff --git a/ix-cli/src/cli/commands/depends.ts b/ix-cli/src/cli/commands/depends.tsindex 4f7a2a3e..7b9e8a66 100644--- a/ix-cli/src/cli/commands/depends.ts+++ b/ix-cli/src/cli/commands/depends.ts@@ -10,9 +10,12 @@ export function registerDependsCommand(program: Command): void {.description("Show what depends on the given entity (reverse CALLS + IMPORTS)").option("--kind <kind>", "Filter target entity by kind").option("--depth <n>", "Traversal depth (default 1)", "1")+ .option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json)", "text")- .action(async (symbol: string, opts: { kind?: string; depth: string; format: string }) => {+ .addHelpText("after", "\nExamples:\n ix depends verify_token\n ix depends AuthProvider --depth 2 --format json\n ix depends parser.py --kind file --limit 20")+ .action(async (symbol: string, opts: { kind?: string; depth: string; limit: string; format: string }) => {const client = new IxClient(getEndpoint());+ const limit = parseInt(opts.limit, 10);const target = await resolveEntity(client, symbol,["method", "function", "class", "object", "trait", "interface", "module", "file"],@@ -44,7 +47,7 @@ export function registerDependsCommand(program: Command): void {}}- const allDependents = [...callers, ...importers];+ const allDependents = [...callers, ...importers].slice(0, limit);if (opts.format === "json") {console.log(JSON.stringify({diff --git a/ix-cli/src/cli/commands/explain.ts b/ix-cli/src/cli/commands/explain.tsindex 173f85d6..d9658681 100644--- a/ix-cli/src/cli/commands/explain.ts+++ b/ix-cli/src/cli/commands/explain.ts@@ -10,6 +10,7 @@ export function registerExplainCommand(program: Command): void {.description("Explain an entity — shows structure, container, and history").option("--kind <kind>", "Filter target entity by kind").option("--format <fmt>", "Output format (text|json)", "text")+ .addHelpText("after", "\nExamples:\n ix explain IngestionService\n ix explain verify_token --kind function --format json").action(async (symbol: string, opts: { kind?: string; format: string }) => {const client = new IxClient(getEndpoint());const target = await resolveEntity(client, symbol, ["class", "function", "method", "trait", "object", "interface", "module", "file"], opts);diff --git a/ix-cli/src/cli/commands/imports.ts b/ix-cli/src/cli/commands/imports.tsindex 85ec8d05..0fd32e1b 100644--- a/ix-cli/src/cli/commands/imports.ts+++ b/ix-cli/src/cli/commands/imports.ts@@ -9,27 +9,33 @@ export function registerImportsCommand(program: Command): void {.command("imports <symbol>").description("Show what the given entity imports").option("--kind <kind>", "Filter target entity by kind")+ .option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json)", "text")- .action(async (symbol: string, opts: { kind?: string; format: string }) => {+ .addHelpText("after", "\nExamples:\n ix imports auth.py\n ix imports IngestionService --format json")+ .action(async (symbol: string, opts: { kind?: string; limit: string; format: string }) => {const client = new IxClient(getEndpoint());+ const limit = parseInt(opts.limit, 10);const target = await resolveEntity(client, symbol, ["file", "module", "class"], opts);if (!target) return;printResolved(target);const result = await client.expand(target.id, { direction: "out", predicates: ["IMPORTS"] });- formatEdgeResults(result.nodes, "imports", target.name, opts.format, target, "graph");+ formatEdgeResults(result.nodes.slice(0, limit), "imports", target.name, opts.format, target, "graph");});program.command("imported-by <symbol>").description("Show what imports the given entity").option("--kind <kind>", "Filter target entity by kind")+ .option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json)", "text")- .action(async (symbol: string, opts: { kind?: string; format: string }) => {+ .addHelpText("after", "\nExamples:\n ix imported-by AuthProvider\n ix imported-by io.circe.Json --format json")+ .action(async (symbol: string, opts: { kind?: string; limit: string; format: string }) => {const client = new IxClient(getEndpoint());+ const limit = parseInt(opts.limit, 10);const target = await resolveEntity(client, symbol, ["file", "module", "class"], opts);if (!target) return;printResolved(target);const result = await client.expand(target.id, { direction: "in", predicates: ["IMPORTS"] });- formatEdgeResults(result.nodes, "imported-by", target.name, opts.format, target, "graph");+ formatEdgeResults(result.nodes.slice(0, limit), "imported-by", target.name, opts.format, target, "graph");});}diff --git a/ix-cli/src/cli/commands/init.ts b/ix-cli/src/cli/commands/init.tsindex ae099ba8..276603a2 100644--- a/ix-cli/src/cli/commands/init.ts+++ b/ix-cli/src/cli/commands/init.ts@@ -15,62 +15,62 @@ export const IX_CLAUDE_MD_BLOCK = `${IX_MARKER_START}This project uses Ix Memory — persistent, time-aware context for LLM assistants.+## Interface++Use the \`ix\` CLI exclusively. Do NOT use MCP tools — the CLI is the canonical agent interface.+All commands support \`--format json\` for machine-readable output.+## MANDATORY RULES-1. BEFORE answering codebase questions → use targeted Ix tools (see Command Routing below). Do NOT answer from training data alone.-2. AFTER every design or architecture decision → call \`ix_decide\` with both the conclusion AND the reasoning.-3. When you notice contradictory information → call \`ix_conflicts\` and present conflicts to the user before continuing.-4. NEVER guess about codebase facts — if Ix has structured data, use it. Say "according to Ix" when citing results.-5. IMMEDIATELY after modifying code → call \`ix_ingest\` on changed files. Do not batch this to the end of the session.-6. At start of each session → review \`ix://session/context\` to load prior work and decisions.-7. When the user states a goal → call \`ix_truth\` to record the intent so all decisions can trace back to it.--## Preferred Ix Command Routing--Use bounded, composable primitives — never broad NLP-style queries.--- \`ix_search\` — find entities by name, kind, or language (\`--kind class --limit 10\`)-- \`ix_entity\` — get full entity details (node, claims, edges) by ID-- \`ix_expand\` — traverse edges: CALLS, IMPORTS, CONTAINS (use direction + predicates)-- \`ix_text\` — fast lexical search via ripgrep (\`--language python --path src/\`)-- \`ix_decisions\` — list past design decisions (\`--topic "ingestion"\`)-- \`ix_history\` — entity provenance chain-- \`ix_diff\` — what changed between revisions-- \`ix_conflicts\` — detect contradictions-- \`ix_truth\` — manage project intents/goals--### Decompose broad questions into targeted calls:-- "How does X work?" → \`ix_search "X"\` → \`ix_entity <id>\` → \`ix_expand <id>\`-- "What depends on Y?" → \`ix_search "Y"\` → \`ix_expand <id> direction=in predicates=["CALLS"]\`-- "List all imports" → \`ix_search "" --kind file\` → \`ix_expand <id> predicates=["IMPORTS"]\`--### Best practices:-- Always use \`--kind\` and \`--limit\` to constrain search results-- Use \`--path\` to restrict text searches to specific directories-- Use exact entity IDs from previous results, not broad queries--## Avoid ix_query--\`ix_query\` is **deprecated**. It produces broad, oversized, low-signal responses. Do NOT use it for repo-wide inventory, NLP-style QA, or exploratory graph sweeps. Decompose into the targeted commands above.--## Workflow-1. **Start** — Read \`ix://session/context\` and \`ix://project/intent\` to understand prior state.-2. **Explore** — Use \`ix_search\` + \`ix_entity\` + \`ix_expand\` to understand relevant code.-3. **Work** — Implement changes, making decisions as needed.-4. **Ingest** — After each file change, call \`ix_ingest\` immediately to keep the graph current.-5. **Decide** — Record any design decisions with \`ix_decide\` so future sessions can understand why.--## What NOT to Do-- Do NOT use \`ix_query\` for broad exploration — decompose into targeted commands instead.-- Do NOT answer architecture questions from training data alone — always check Ix first.-- Do NOT skip \`ix_ingest\` after modifying files — stale memory leads to wrong answers next session.-- Do NOT record a decision without rationale — "we chose X" is useless without "because Y".-- Do NOT ignore conflicts — if \`ix_conflicts\` returns results, surface them to the user before proceeding.+1. BEFORE answering codebase questions → use targeted \`ix\` CLI commands (see routing below). Do NOT answer from training data alone.+2. AFTER every design or architecture decision → run \`ix decide <title> --rationale <text>\`.+3. When you notice contradictory information → run \`ix conflicts\` and present results to the user.+4. NEVER guess about codebase facts — if Ix has structured data, use it.+5. IMMEDIATELY after modifying code → run \`ix ingest <path>\` on changed files.+6. When the user states a goal → run \`ix truth add "<statement>"\`.++## Ix CLI Command Routing++Use bounded, composable CLI commands — never broad queries.++### Finding & Understanding Code+- \`ix search <term>\` — find entities by name (\`--kind class --limit 10\`)+- \`ix explain <symbol>\` — structure, container, history, calls+- \`ix read <target>\` — read source (\`file.py:10-50\` or symbol name)+- \`ix entity <id>\` — full entity details by ID+- \`ix text <term>\` — fast text search (\`--language python --limit 20\`)+- \`ix locate <symbol>\` — find symbol via graph + text++### Navigating Relationships+- \`ix callers <symbol>\` — what calls a function (cross-file)+- \`ix callees <symbol>\` — what a function calls+- \`ix contains <symbol>\` — members of a class/module+- \`ix imports <symbol>\` — what an entity imports+- \`ix imported-by <symbol>\` — what imports an entity+- \`ix depends <symbol>\` — dependency impact analysis++### History & Decisions+- \`ix decisions\` — list design decisions (\`--topic ingestion\`)+- \`ix history <entityId>\` — entity provenance chain+- \`ix diff <from> <to>\` — changes between revisions+- \`ix conflicts\` — detect contradictions++### Best practices+- Use \`--kind\` and \`--limit\` to constrain results+- Use \`--format json\` when chaining command results+- Use \`--path\` or \`--language\` to restrict text searches+- Use exact entity IDs from previous JSON results+- Decompose large questions into multiple targeted calls++## Do NOT Use+- \`ix query\` — deprecated, oversized low-signal responses+- MCP tools — deprecated, use CLI instead+- Broad repo-wide inventory queries## Confidence Scores-Ix returns confidence scores with query results. When data has low confidence:-- Mention the uncertainty to the user (e.g., "Ix has low confidence on this — it may be outdated").-- Suggest re-ingesting the relevant files to improve confidence.-- Never present low-confidence data as established fact.+Ix returns confidence scores with results. When data has low confidence:+- Mention the uncertainty to the user+- Suggest re-ingesting the relevant files+- Never present low-confidence data as established fact${IX_MARKER_END}`;export function registerInitCommand(program: Command): void {diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.tsindex dd385a0f..e89b50a1 100644--- a/ix-cli/src/cli/commands/search.ts+++ b/ix-cli/src/cli/commands/search.ts@@ -12,6 +12,7 @@ export function registerSearchCommand(program: Command): void {.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")+ .addHelpText("after", "\nExamples:\n ix search IngestionService --kind class\n ix search auth --language python --limit 10\n ix search \"\" --kind file --limit 50 --format json").action(async (term: string, opts: {limit: string; kind?: string; language?: string; asOf?: string; format: string}) => {diff --git a/ix-cli/src/cli/commands/text.ts b/ix-cli/src/cli/commands/text.tsindex c8ed9e36..5d4c4236 100644--- a/ix-cli/src/cli/commands/text.ts+++ b/ix-cli/src/cli/commands/text.ts@@ -15,6 +15,7 @@ export function registerTextCommand(program: Command): void {.option("--language <lang>", "Filter by language (python, typescript, scala, etc.)").option("--format <fmt>", "Output format (text|json)", "text").option("--root <dir>", "Workspace root directory")+ .addHelpText("after", "\nExamples:\n ix text verify_token --language python\n ix text \"class.*Service\" --limit 10 --format json\n ix text TODO --path src/").action(async (term: string, opts: { limit: string; path: string; format: string; language?: string; root?: string }) => {const limit = parseInt(opts.limit, 10);const searchPath = opts.path !== "." ? opts.path : resolveWorkspaceRoot(opts.root);diff --git a/ix-cli/src/mcp/__tests__/server.test.ts b/ix-cli/src/mcp/__tests__/server.test.tsindex c797c328..58b79f45 100644--- a/ix-cli/src/mcp/__tests__/server.test.ts+++ b/ix-cli/src/mcp/__tests__/server.test.ts@@ -25,13 +25,12 @@ beforeAll(async () => {});describe("MCP server INSTRUCTIONS", () => {- it("contains all 7 mandatory rules", () => {+ it("contains mandatory rules and key tool references", () => {expect(INSTRUCTIONS).toContain("ix_query");expect(INSTRUCTIONS).toContain("ix_decide");expect(INSTRUCTIONS).toContain("ix_conflicts");expect(INSTRUCTIONS).toContain("NEVER answer from training data alone");expect(INSTRUCTIONS).toContain("ix_ingest");- expect(INSTRUCTIONS).toContain("ix://session/context");expect(INSTRUCTIONS).toContain("ix_truth");});@@ -44,10 +43,8 @@ describe("MCP server INSTRUCTIONS", () => {expect(INSTRUCTIONS).toContain("BEHAVIORAL CHECKS");});- it("contains routing guidance for codebase questions", () => {- expect(INSTRUCTIONS).toContain("ix_search");- expect(INSTRUCTIONS).toContain("ix_entity");- expect(INSTRUCTIONS).toContain("ix_expand");+ it("notes CLI is canonical interface", () => {+ expect(INSTRUCTIONS).toContain("ix CLI is now the canonical agent interface");});it("describes what Ix returns", () => {diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.tsindex d6f17df3..4b85eac5 100644--- a/ix-cli/src/mcp/server.ts+++ b/ix-cli/src/mcp/server.ts@@ -1,8 +1,9 @@/**- * Ix Memory MCP Server+ * Ix Memory MCP Server (Compatibility Only)*- * Exposes 14 tools and 2 resources over the Model Context Protocol,- * providing persistent, time-aware memory to LLM coding assistants.+ * The CLI (`ix` commands) is now the canonical agent interface.+ * This MCP server is retained for backward compatibility but is+ * no longer the recommended integration path.*/import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";@@ -17,30 +18,21 @@ import { SessionState } from "./session.js";export const INSTRUCTIONS = `You have access to Ix Memory — a persistent, time-aware knowledge graph for this codebase.Ix returns structured context: nodes, edges, claims, conflicts, and decisions — each with confidence scores.+NOTE: The ix CLI is now the canonical agent interface. Prefer running CLI commands+(ix search, ix explain, ix callers, etc.) over these MCP tools when possible.+These MCP tools are retained for backward compatibility.+MANDATORY RULES:1. BEFORE answering codebase questions, use targeted Ix tools (NOT ix_query — it is deprecated)2. AFTER any design decision, call ix_decide to record it with full reasoning3. When you notice conflicting information, call ix_conflicts and present results to the user4. NEVER answer from training data alone when Ix has structured data available5. After modifying code, call ix_ingest IMMEDIATELY on changed files — not at end of session-6. At start of each session, review ix://session/context for prior work and decisions-7. When the user states a goal, call ix_truth to record the intent so decisions trace back to it--PREFERRED IX COMMAND ROUTING:-- Find an entity by name → ix_search (with --kind, --limit for precision)-- Understand a symbol → ix_entity (by ID) or ix_expand (neighborhood)-- What calls a function → ix_expand with direction=in, predicates=["CALLS"]-- What a function calls → ix_expand with direction=out, predicates=["CALLS"]-- Members of a class → ix_expand with direction=out, predicates=["CONTAINS"]-- What imports something → ix_expand with direction=in, predicates=["IMPORTS"]-- Exact text/snippet search → ix_text (fast ripgrep-based)-- Past decisions → ix_decisions-- Entity change history → ix_history-- What changed between revisions → ix_diff+6. When the user states a goal, call ix_truth to record the intent so decisions trace back to itAVOID ix_query:- ix_query is DEPRECATED — it produces broad, oversized, low-signal responses-- Instead, decompose questions into targeted tool calls above+- Instead, decompose questions into targeted tool calls- Example: "how does ingestion work?" → ix_search "IngestionService" → ix_entity <id> → ix_expand <id>BEHAVIORAL CHECKS:diff --git a/templates/CLAUDE.md.template b/templates/CLAUDE.md.templateindex 532c295d..f810284b 100644--- a/templates/CLAUDE.md.template+++ b/templates/CLAUDE.md.template@@ -5,24 +5,31 @@ This project uses Ix Memory for persistent, time-aware context.## Project- Name: {{PROJECT_NAME}}+## Interface+Use the `ix` CLI exclusively. Do NOT use MCP tools — the CLI is the canonical agent interface.+All commands support `--format json` for machine-readable output.+## MANDATORY RULES-1. BEFORE answering codebase questions → use targeted Ix tools (see routing below), NOT ix_query-2. AFTER making any design/architecture decision → call ix_decide-3. When noticing contradictory information → call ix_conflicts+1. BEFORE answering codebase questions → use targeted `ix` CLI commands (see routing below)+2. AFTER making any design/architecture decision → run `ix decide`+3. When noticing contradictory information → run `ix conflicts`4. NEVER guess about codebase facts when Ix has structured data-5. After modifying code → call ix_ingest on changed files-6. At start of each session → review ix://session/context for prior work-7. When the user states a goal → call ix_truth to record it+5. After modifying code → run `ix ingest` on changed files+6. When the user states a goal → run `ix truth add`-## Preferred Ix Command Routing-- ix_search — find entities by name/kind/language-- ix_entity — get full entity details by ID-- ix_expand — traverse edges (CALLS, IMPORTS, CONTAINS)-- ix_text — fast lexical search (ripgrep)-- ix_decisions — list past design decisions-- ix_history — entity provenance chain-- ix_diff — changes between revisions+## Ix CLI Command Routing+- `ix search` — find entities by name/kind/language+- `ix explain` — understand a symbol (structure, container, calls)+- `ix read` — read source code by path or symbol+- `ix entity` — full entity details by ID+- `ix text` — fast lexical search (ripgrep)+- `ix callers` / `ix callees` — call graph navigation+- `ix contains` — members of a class/module+- `ix imports` / `ix imported-by` — import graph+- `ix depends` — dependency impact analysis+- `ix decisions` — list past design decisions+- `ix history` / `ix diff` — temporal queries-## Avoid ix_query-ix_query is deprecated — broad NLP-style queries produce oversized, low-signal responses.-Decompose questions into targeted ix_search + ix_entity + ix_expand calls.+## Do NOT Use+- `ix query` — deprecated, oversized low-signal responses+- MCP tools — deprecated, use CLI instead