Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat: deprecate ix_query — route LLMs through bounded composable primitives

riley0227ece523c7fe28
diff --git a/CLAUDE.md b/CLAUDE.md
index e72bf14c..e4564889 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@
This project uses Ix Memory — persistent, time-aware context for LLM assistants.
## MANDATORY RULES
-1. BEFORE answering any question about the codebase → call `ix_query` first. Do NOT answer from training data alone.
+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.
@@ -12,15 +12,68 @@ This project uses Ix Memory — persistent, time-aware context for LLM assistant
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.
+
+| Question type | 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"` |
+
+### 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
+
+**"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
+- 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. **Query** — Before any task, call `ix_query` to get relevant context from the knowledge graph.
+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".
diff --git a/README.md b/README.md
index d1089b98..396360e8 100644
--- a/README.md
+++ b/README.md
@@ -59,10 +59,12 @@ This checks the backend is running, creates `~/.ix/config.yaml`, and adds Ix rul
ix ingest ./src --recursive
```
-### 5. Query
+### 5. Explore
```bash
-ix query "What does the UserService class do?"
+ix search "UserService" --kind class
+ix explain UserService
+ix callers UserService
```
## CLI Commands
@@ -74,9 +76,18 @@ All commands accept `--format json` for machine-readable output.
| Command | Usage | Description |
|---------|-------|-------------|
| `ix status` | `ix status` | Check backend health |
-| `ix query` | `ix query <question>` | Query the knowledge graph |
| `ix ingest` | `ix ingest <path> [--recursive]` | Ingest source files |
| `ix search` | `ix search <term> [--limit N]` | Search nodes by term |
+| `ix explain` | `ix explain <symbol>` | Understand an entity |
+| `ix callers` | `ix callers <symbol>` | What calls a function |
+| `ix callees` | `ix callees <symbol>` | What a function calls |
+| `ix contains` | `ix contains <symbol>` | Members of a class/module |
+| `ix imports` | `ix imports <symbol>` | What an entity imports |
+| `ix depends` | `ix depends <symbol>` | Dependency impact analysis |
+| `ix text` | `ix text <term>` | Fast lexical search (ripgrep) |
+| `ix read` | `ix read <target>` | Read source code |
+| `ix locate` | `ix locate <symbol>` | Find a symbol (graph + text) |
+| `ix query` | `ix query <question> --unsafe` | [DEPRECATED] Broad graph query |
### Decisions & Intents
@@ -130,7 +141,7 @@ ix mcp-install
| Tool | Description |
|------|-------------|
-| `ix_query` | Query the knowledge graph (ALWAYS call before answering codebase questions) |
+| `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 |
diff --git a/ix-cli/src/cli/__tests__/init.test.ts b/ix-cli/src/cli/__tests__/init.test.ts
index 84bc63af..0748a0eb 100644
--- a/ix-cli/src/cli/__tests__/init.test.ts
+++ b/ix-cli/src/cli/__tests__/init.test.ts
@@ -19,14 +19,16 @@ beforeAll(async () => {
});
describe("CLAUDE_MD template", () => {
- it("contains all 7 mandatory rules", () => {
- expect(CLAUDE_MD).toContain("ix_query");
+ it("contains all 7 mandatory rules and 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");
});
it("contains a Workflow section", () => {
diff --git a/ix-cli/src/cli/commands/init.ts b/ix-cli/src/cli/commands/init.ts
index 4c2e177b..ae099ba8 100644
--- a/ix-cli/src/cli/commands/init.ts
+++ b/ix-cli/src/cli/commands/init.ts
@@ -16,7 +16,7 @@ export const IX_CLAUDE_MD_BLOCK = `${IX_MARKER_START}
This project uses Ix Memory — persistent, time-aware context for LLM assistants.
## MANDATORY RULES
-1. BEFORE answering any question about the codebase → call \`ix_query\` first. Do NOT answer from training data alone.
+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.
@@ -24,15 +24,43 @@ This project uses Ix Memory — persistent, time-aware context for LLM assistant
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
-A typical session follows this flow:
1. **Start** — Read \`ix://session/context\` and \`ix://project/intent\` to understand prior state.
-2. **Query** — Before any task, call \`ix_query\` to get relevant context from the knowledge graph.
+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".
@@ -43,13 +71,6 @@ 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.
-
-## 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
${IX_MARKER_END}`;
export function registerInitCommand(program: Command): void {
diff --git a/ix-cli/src/cli/commands/query.ts b/ix-cli/src/cli/commands/query.ts
index 77c96f28..9873c3ec 100644
--- a/ix-cli/src/cli/commands/query.ts
+++ b/ix-cli/src/cli/commands/query.ts
@@ -6,23 +6,32 @@ import { formatContext } from "../format.js";
export function registerQueryCommand(program: Command): void {
program
.command("query <question>")
- .description("Query the knowledge graph for structured context (use --unsafe to enable)")
+ .description("[DEPRECATED] Broad NLP-style graph query — prefer bounded commands instead")
.option("--as-of <rev>", "Time-travel to a specific revision")
.option("--depth <depth>", "Query depth (shallow|standard|deep)", "standard")
.option("--format <fmt>", "Output format (text|json)", "text")
.option("--unsafe", "Enable query (can produce large outputs)")
.action(async (question: string, opts: { asOf?: string; depth?: string; format: string; unsafe?: boolean }) => {
+ console.log("\n⚠ ix query is DEPRECATED — broad NLP-style graph queries produce oversized, low-signal responses.");
+ console.log(" Decompose your question into targeted commands instead:\n");
+ console.log(" ix search <term> Find entities by name/kind");
+ console.log(" ix explain <symbol> Structure, container, history, calls");
+ console.log(" ix callers <symbol> What calls a function (cross-file)");
+ console.log(" ix callees <symbol> What a function calls");
+ console.log(" ix contains <symbol> Members of a class/module");
+ console.log(" ix imports <symbol> What an entity imports");
+ console.log(" ix imported-by <symbol> What imports an entity");
+ console.log(" ix depends <symbol> Dependency impact analysis");
+ console.log(" ix text <term> Fast lexical search (ripgrep)");
+ console.log(" ix read <target> Read source code directly");
+ console.log(" ix decisions List design decisions");
+ console.log(" ix history <entityId> Provenance chain");
+ console.log(" ix diff <from> <to> Changes between revisions\n");
if (!opts.unsafe) {
- console.log("ix query is disabled by default to prevent large token outputs.");
- console.log("Use --unsafe to enable, or try these targeted alternatives:\n");
- console.log(" ix search <term> Find entities by name");
- console.log(" ix explain <symbol> Understand an entity");
- console.log(" ix callers <symbol> Find what calls a function");
- console.log(" ix contains <symbol> See members of a class/module");
- console.log(" ix text <term> Lexical search across code");
- console.log(" ix read <target> Read source code directly");
+ console.log("Pass --unsafe to run anyway (not recommended).\n");
return;
}
+ console.log("Running with --unsafe...\n");
const client = new IxClient(getEndpoint());
const result = await client.query(question, {
asOfRev: opts.asOf ? parseInt(opts.asOf, 10) : undefined,
diff --git a/ix-cli/src/mcp/__tests__/server.test.ts b/ix-cli/src/mcp/__tests__/server.test.ts
index ae8113c7..c797c328 100644
--- a/ix-cli/src/mcp/__tests__/server.test.ts
+++ b/ix-cli/src/mcp/__tests__/server.test.ts
@@ -35,17 +35,19 @@ describe("MCP server INSTRUCTIONS", () => {
expect(INSTRUCTIONS).toContain("ix_truth");
});
- it("is under 30 lines to stay concise", () => {
+ it("is under 40 lines to stay concise", () => {
const lines = INSTRUCTIONS.split("\n");
- expect(lines.length).toBeLessThan(30);
+ expect(lines.length).toBeLessThan(40);
});
it("contains behavioral checks section", () => {
expect(INSTRUCTIONS).toContain("BEHAVIORAL CHECKS");
});
- it("contains a stop-and-query nudge", () => {
- expect(INSTRUCTIONS).toContain("STOP and call it");
+ it("contains routing guidance for codebase questions", () => {
+ expect(INSTRUCTIONS).toContain("ix_search");
+ expect(INSTRUCTIONS).toContain("ix_entity");
+ expect(INSTRUCTIONS).toContain("ix_expand");
});
it("describes what Ix returns", () => {
diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.ts
index 2d2d26ce..d6f17df3 100644
--- a/ix-cli/src/mcp/server.ts
+++ b/ix-cli/src/mcp/server.ts
@@ -18,7 +18,7 @@ export const INSTRUCTIONS = `You have access to Ix Memory — a persistent, time
Ix returns structured context: nodes, edges, claims, conflicts, and decisions — each with confidence scores.
MANDATORY RULES:
-1. ALWAYS call ix_query before answering questions about the codebase — if you are about to answer and have not called ix_query yet, STOP and call it first
+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
@@ -26,8 +26,25 @@ MANDATORY RULES:
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
+
+AVOID ix_query:
+- ix_query is DEPRECATED — it produces broad, oversized, low-signal responses
+- Instead, decompose questions into targeted tool calls above
+- Example: "how does ingestion work?" → ix_search "IngestionService" → ix_entity <id> → ix_expand <id>
+
BEHAVIORAL CHECKS:
-- About to answer a codebase question? → Did you call ix_query? If not, STOP and call it.
+- About to answer a codebase question? → Use ix_search + ix_entity + ix_expand, NOT ix_query
- Just made a design choice? → Call ix_decide before moving on.
- Just edited a file? → Call ix_ingest now, not later.
- See something contradictory? → Call ix_conflicts before proceeding.
@@ -49,16 +66,38 @@ const server = new McpServer(
// ============================= TOOLS =======================================
-// --- ix_query ---------------------------------------------------------------
+// --- ix_query [DEPRECATED] ---------------------------------------------------
server.tool(
"ix_query",
- "ALWAYS call this tool BEFORE answering any question about the codebase, architecture, or technical decisions. Ix Memory contains structured, versioned knowledge with confidence scores. Never rely on your training data alone when Ix has data available. Results include confidence scores — mention uncertainty to the user when confidence is low.",
+ "[DEPRECATED] Broad NLP-style graph query — produces oversized, low-signal responses. Use targeted tools instead: ix_search (find entities), ix_entity (get details), ix_expand (traverse edges), ix_text (lexical search), ix_decisions (past decisions). Decompose questions into specific tool calls rather than issuing a single broad query.",
{
question: z.string().describe("The question to ask the knowledge graph"),
asOfRev: z.optional(z.number()).describe("Optional revision snapshot"),
depth: z.optional(z.string()).describe("Query depth: shallow | deep"),
},
async ({ question, asOfRev, depth }) => {
+ const deprecationWarning = [
+ "⚠ ix_query is DEPRECATED — broad NLP-style queries produce oversized, low-signal responses.",
+ "",
+ "Prefer these targeted alternatives:",
+ " ix_search — find entities by name/kind",
+ " ix_entity — get full entity details by ID",
+ " ix_expand — traverse edges (CALLS, IMPORTS, CONTAINS)",
+ " ix_text — fast lexical search (ripgrep)",
+ " ix_decisions — list design decisions",
+ " ix_history — entity change history",
+ " ix_diff — changes between revisions",
+ "",
+ "Decompose broad questions into specific tool calls.",
+ "Example: 'how does ingestion work?' →",
+ " 1. ix_search 'IngestionService'",
+ " 2. ix_entity <id>",
+ " 3. ix_expand <id> direction=out predicates=[CONTAINS]",
+ "",
+ "--- query results follow (not recommended) ---",
+ "",
+ ].join("\n");
+
try {
const ctx = await client.query(question, { asOfRev, depth });
// Track session
@@ -67,7 +106,7 @@ server.tool(
session.trackEntities(ctx.nodes.map((n: any) => n.id));
}
return {
- content: [{ type: "text" as const, text: JSON.stringify(ctx, null, 2) }],
+ content: [{ type: "text" as const, text: deprecationWarning + JSON.stringify(ctx, null, 2) }],
};
} catch (err) {
return {
@@ -462,7 +501,7 @@ server.tool(
// --- 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.",
+ "Fast lexical/text search across the codebase. Use for exact string matches, symbol lookups, and filename searches. Combine with ix_search and ix_entity for comprehensive results.",
{
term: z.string().describe("Text/pattern to search for"),
limit: z.optional(z.number()).describe("Max results (default 20)"),
diff --git a/scripts/install-mcp.sh b/scripts/install-mcp.sh
index 7fd45e93..dadc9b8f 100755
--- a/scripts/install-mcp.sh
+++ b/scripts/install-mcp.sh
@@ -42,7 +42,7 @@ while [[ $# -gt 0 ]]; do
echo ""
echo "What this does:"
echo " Writes MCP server config so the IDE auto-launches the IX MCP server."
- echo " The LLM then gets access to 13 tools (ix_query, ix_decide, etc.)"
+ echo " The LLM then gets access to 13 tools (ix_search, ix_decide, etc.)"
echo " and 2 resources (ix://session/context, ix://project/intent)."
echo ""
echo "Config file locations:"
@@ -104,7 +104,7 @@ echo ""
echo "[ok] MCP server installed"
echo ""
echo "The LLM will now have access to:"
-echo " Tools: ix_query, ix_ingest, ix_decide, ix_search, ix_entity,"
+echo " Tools: ix_search, ix_ingest, ix_decide, ix_entity, ix_expand,"
echo " ix_expand, ix_history, ix_truth, ix_diff, ix_conflicts,"
echo " ix_resolve, ix_assert, ix_patches"
echo " Resources: ix://session/context, ix://project/intent"
diff --git a/templates/CLAUDE.md.template b/templates/CLAUDE.md.template
index 112edbf9..532c295d 100644
--- a/templates/CLAUDE.md.template
+++ b/templates/CLAUDE.md.template
@@ -6,10 +6,23 @@ This project uses Ix Memory for persistent, time-aware context.
- Name: {{PROJECT_NAME}}
## MANDATORY RULES
-1. BEFORE answering any question about this codebase → call ix_query
+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
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
+
+## 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
+
+## 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.