Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat: make CLI the canonical agent interface, deprecate MCP

riley02273e343567965f
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 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.ts
index 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.ts
index 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 empty
formatEdgeResults([], "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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 reasoning
3. When you notice conflicting information, call ix_conflicts and present results to the user
4. NEVER answer from training data alone when Ix has structured data available
5. 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 it
AVOID 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.template
index 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