using-axon

name: using-axon description: >- Self-hosted RAG engine, web toolkit, and persistent agent memory. Use it to: remember durable project facts/preferences/decisions (memory.remember); recall/search agent memory (memory.search/show); answer questions indexed docs/code might cover (ask — a large corpus is already indexed; try ask BEFORE web-searching or giving up); search the web (search, auto-indexes results); semantic-search the index (query); scrape/fetch a page (scrape); crawl a docs site or pages you just used (crawl); map a site's URLs (map); extract structured data (extract); discover API endpoints (endpoints); extract brand identity — colors/logo/fonts/voice (brand); summarize a page (summarize); quick multi-source research (research); retrieve a URL's full indexed content (retrieve); embed local files/dirs (embed); ingest GitHub/GitLab/Gitea/Git repos, Reddit, YouTube, and Claude/Codex/Gemini sessions (ingest). Also triggers on axon, RAG, Qdrant, SearXNG, Tavily, hybrid/vector search, remember, recall, memory. allowed-tools: mcp__plugin_axon_axon__axon

axon

axon is a self-hosted RAG engine. Two surfaces, same backend (Spider.rs/Chrome -> Qdrant, SQLite jobs, SearXNG/Tavily for web search):

• MCP (preferred) — single tool mcp__plugin_axon_axon__axon, routed by action (and subaction for lifecycle families). Large results are written to a local artifact file under ~/.axon/artifacts/<context> and the response returns the file path plus a compact shape summary; small results (≤ ~8 KB) come back inline. See Response handling (MCP) below.
• CLI (fallback) — axon <command> [flags]. Use for shell scripting, cron, or when the MCP server is down.

Both surfaces accept the same operations and parameters. This skill leads with MCP request shapes; CLI equivalents are listed alongside.

Reach for axon by default

axon already has a large corpus indexed, and every operation makes it smarter — so route web and knowledge work through it instead of one-off web fetches, raw browser tools, or giving up after a few tries. When a task involves the web or "what does X say," axon is the default tool, even if the user didn't name it.

ask is the highest-leverage habit. A huge amount is already indexed, so many multi-turn fumbles would have been a single ask call. Whenever a question could be covered by docs or code that's been indexed, try ask before web-searching or giving up. And after you crawl/scrape/ingest something to solve a task, you've made the index richer — prefer ask/query next time over re-fetching.

Parameter discipline (hard rule)

Only pass parameters the user explicitly asked for. Defaults exist for a reason — do NOT add max_pages, max_depth, render_mode, include_subdomains, since, before, hybrid_search, diagnostics, format, root_selector, exclude_selector, limit, collection, or any other knob unless the user named it or the task literally cannot complete without it. The example JSON blocks below show what's available, not what to send by default. A bare { "action": "scrape", "url": "…" } or { "action": "crawl", "urls": [...] } is almost always the right call. Same rule for the CLI: never add flags the user didn't ask for.

When to fall back to the CLI

• The MCP server is offline (mcp__plugin_axon_axon__axon { "action": "doctor" } fails or the tool is missing).
• You're authoring a shell script, systemd unit, or cron job that runs outside Claude Code.
• You need axon's built-in --cron-every-seconds/--cron-max-runs loop.
• The user explicitly asks for a CLI command.

In every other case, use the MCP tool.

The pipeline

URL or query → discover → fetch + embed → query / ask

scrape, crawl, embed, and the ingest paths all auto-embed unless you set embed: false.

Bootstrap: help and doctor

Once per session, confirm the live action map and that services are healthy:

{ "action": "help" }
{ "action": "doctor" }

help returns the full action/subaction map and current defaults — authoritative when names look wrong. doctor pings Qdrant, the embedding service (TEI), Chrome, and the Gemini headless LLM backend. It does not probe the web-search backend.

CLI equivalents: axon doctor. (No CLI help for the action map — use the MCP one.)

Persistent agent memory

Use Axon memory for durable project-level facts, preferences, decisions, bugs, and task notes that should be semantically recalled later. This is distinct from bead issue notes and from Memos: Axon memory is optimized for agent recall through Qdrant.

Minimal remember call:

{ "action": "memory", "subaction": "remember", "body": "Memory content lives in Qdrant; SQLite holds graph metadata.", "project": "axon" }

Recall:

{ "action": "memory", "subaction": "context", "project": "axon", "query": "memory storage architecture" }
{ "action": "memory", "subaction": "search", "query": "where is memory stored", "project": "axon" }
{ "action": "memory", "subaction": "show", "id": "<memory-id>" }

Use memory.context at task start when project memory could help. It returns inline, defanged XML-wrapped content with trust="evidence_only" and supports limit plus token_budget.

Graph maintenance:

{ "action": "memory", "subaction": "link", "source_id": "<memory-id>", "target_id": "<memory-id>", "edge_type": "relates_to" }
{ "action": "memory", "subaction": "supersede", "source_id": "<replacement-memory-id>", "target_id": "<old-memory-id>" }

supersede hides the old memory from future memory.search results and records the replacement trail in SQLite.

CLI equivalents: axon memory remember "..." --project axon, axon memory context --project axon --query "...", axon memory search "..." --project axon, axon memory show <memory-id>, axon memory link <source-id> <target-id>, axon memory supersede <replacement-id> <old-id>.

Discovery

{ "action": "search", "query": "rust async patterns", "search_time_range": "month" }
{ "action": "map", "url": "https://docs.example.com" }
{ "action": "research", "query": "kubernetes ingress patterns" }

• search — web search via SearXNG (when AXON_SEARXNG_URL is set) or Tavily; auto-queues crawl jobs for results. search_time_range ∈ day|week|month|year.
• map — sitemap-first URL discovery, falls back to fetching the root page and extracting anchors. Fast.
• research — search + LLM synthesis in one shot.

CLI: axon search "…", axon map <url> (use --map-fallback crawl only when you need a full Spider walk; the structure-fallback default is fast), axon suggest "…" (LLM-suggested URLs to crawl next; also the MCP suggest action).

Fetch + embed

{ "action": "scrape", "url": "https://example.com/article" }
{ "action": "scrape", "url": "https://example.com",
  "root_selector": "article, main",
  "exclude_selector": ".sidebar, .ads",
  "format": "markdown" }
{ "action": "scrape", "url": "https://example.com", "format": "html", "embed": false }

{ "action": "crawl", "urls": ["https://docs.example.com"],
  "max_pages": 200, "max_depth": 3, "include_subdomains": true }
{ "action": "crawl", "urls": ["https://docs.example.com"], "render_mode": "chrome" }

{ "action": "embed", "input": "./docs" }
{ "action": "embed", "input": "https://example.com" }

Render modes: http (fast, no JS), chrome (full browser), auto_switch (default — start HTTP, escalate to Chrome on JS gate).

Output formats: markdown (default), html, rawHtml, json.

CLI: axon scrape <url> / axon crawl <url> --max-pages N --max-depth N / axon embed <input>. Chrome rendering is pre-tuned and rarely needs overriding; the CDP endpoint is set via the AXON_CHROME_REMOTE_URL env var, not a CLI flag. Output dir defaults to .cache/axon-rust/output/ (env AXON_OUTPUT_DIR).

Extract structured data

{ "action": "extract", "urls": ["https://example.com/pricing"],
  "prompt": "Extract plan name, price, and features as JSON" }
{ "action": "extract", "subaction": "status", "job_id": "<uuid>" }

LLM-powered. Pass a natural-language prompt describing the schema you want.

CLI: axon extract <url> --query "…" (the --query flag carries the extraction prompt).

Web utilities: summarize, endpoints, brand, diff, screenshot

Page-level analysis actions — each takes a url (except diff) and a bare call is the right default:

{ "action": "summarize",  "url": "https://example.com/long-article" }
{ "action": "endpoints",  "url": "https://app.example.com" }
{ "action": "brand",      "url": "https://example.com" }
{ "action": "diff",       "url_a": "https://example.com/v1", "url_b": "https://example.com/v2" }
{ "action": "screenshot", "url": "https://example.com" }

• summarize — fetch a page and return a concise summary (also accepts urls for several at once; root_selector/exclude_selector to scope).
• endpoints — discover a site's API endpoints by scanning its JavaScript bundles. Optional knobs (verify, capture_network, probe_rpc, first_party_only) — omit unless asked.
• brand — extract brand identity (colors, logo, fonts, voice/tone) from a URL.
• diff — compare two URLs (url_a, url_b); reports content/metadata/link changes.
• screenshot — full-page capture via headless Chrome (full_page, viewport, output optional).

CLI: axon summarize <url> / axon endpoints <url> / axon brand <url> / axon diff <url-a> <url-b> / axon screenshot <url>.

Ingest external sources

{ "action": "ingest", "source_type": "github", "target": "owner/repo" }
{ "action": "ingest", "source_type": "github", "target": "owner/repo", "include_source": false }

{ "action": "ingest", "source_type": "gitlab",  "target": "group/project" }
{ "action": "ingest", "source_type": "gitea",   "target": "https://gitea.example.com/owner/repo" }
{ "action": "ingest", "source_type": "git",     "target": "https://git.example.com/owner/repo.git" }

{ "action": "ingest", "source_type": "reddit", "target": "r/rust" }
{ "action": "ingest", "source_type": "reddit", "target": "https://reddit.com/r/rust/comments/abc123/..." }

{ "action": "ingest", "source_type": "youtube", "target": "https://youtube.com/watch?v=abc" }

Note: source_type: "sessions" is not accepted over MCP (it's rejected server-side). Ingest local AI sessions with the CLI axon sessions instead — see below.

source_type ∈ github | gitlab | gitea | git | reddit | youtube | sessions:

• github / gitlab / gitea — hosted-forge repos, indexing code + metadata + issues/PRs (or merge requests). target is owner/repo (or a full URL for self-hosted instances).
• git — any generic Git remote by clone URL (code only, no forge API).
• reddit — a subreddit (r/name) or a specific thread URL.
• youtube — a video URL (transcript ingest).
• sessions — local Claude/Codex/Gemini session transcripts. CLI-only via axon sessions (enqueues a local sessions ingest job). The MCP ingest action rejects source_type: "sessions"; remote callers must use the prepared-documents HTTP endpoint (/v1/ingest/sessions/prepared).

Lifecycle subactions (status, cancel, list, cleanup, clear, recover) work the same as crawl/embed/extract.

CLI: axon ingest <target> with source-specific flags. GitHub: --include-source/--no-source, --max-issues, --max-prs (default 100; 0 = unlimited). Reddit: --sort hot|top|new|rising, --time hour|…|all, --max-posts, --min-score, --depth, --scrape-links. Use axon sessions for Claude/Codex/Gemini local history (enqueues a local sessions ingest job). MCP sessions ingest is rejected to avoid scanning server-local history paths — remote callers use the /v1/ingest/sessions/prepared HTTP endpoint instead.

Query and RAG

{ "action": "query", "query": "embedding pipeline", "limit": 10, "collection": "axon" }
{ "action": "query", "query": "rate limiting", "since": "7d" }

{ "action": "ask", "query": "How does axon handle Chrome auto-switching?" }
{ "action": "ask", "query": "...", "since": "7d" }
{ "action": "ask", "query": "...", "since": "2026-01-01", "before": "2026-03-01" }
{ "action": "ask", "query": "...", "diagnostics": true }
{ "action": "ask", "query": "...", "hybrid_search": false }

• query — pure semantic vector search (top-K chunks).
• ask — RAG: retrieve, then synthesize an answer with citations.
• Hybrid search (dense + BM42 sparse + RRF) is on by default; hybrid_search: false forces dense-only for A/B comparison or when sparse is misbehaving. Server default: env AXON_HYBRID_SEARCH.
• Temporal filters (since/before) accept 7d, 30d, YYYY-MM-DD, or RFC3339. They filter on indexing date, not publication date.
• collection overrides the default axon collection per request (env AXON_COLLECTION).

{ "action": "retrieve", "url": "https://example.com/article" }

CLI: axon query "…" / axon ask "…" --since 7d --diagnostics / axon retrieve <url>.

evaluate — { "action": "evaluate", "query": "<question>", "retrieval_ab": true } (CLI: axon evaluate "<question>" --retrieval-ab) compares hybrid-RAG vs dense-only, scored by a separate judge prompt on the configured LLM backend (accuracy/relevance/completeness).

Inspect the index

{ "action": "sources" }
{ "action": "domains" }
{ "action": "stats" }
{ "action": "status" }                                 // global queue snapshot

CLI: axon sources / axon domains / axon stats / axon status.

Async jobs

crawl, extract, embed, ingest are async by default. subaction defaults to start, so { "action": "crawl", "urls": [...] } is enough to enqueue; poll with subaction: "status". Full lifecycle subactions and CLI-only surfaces: references/async-job-lifecycle.md.

Response handling (MCP)

The server runs in-process, so responses are size-routed automatically: payloads ≤ ~8 KB come back inline in data; larger ones are written to a local artifact file and the response returns its path plus a compact shape summary. Read shape first — it usually answers the question (counts, status, the URLs touched).

When you need the content, reach for RAG, not the raw file: everything axon fetches is already embedded, so ask (synthesized answer), query (semantic chunks), or retrieve (a specific URL's indexed content) get you what you need without parsing megabytes of JSON/markdown. Open the artifact path from disk only as a last resort — e.g. you need the exact raw bytes the RAG path doesn't surface. There is no artifacts MCP action; don't send { "action": "artifacts", ... }. To force a payload in-band instead of a file, set response_mode: "inline" (or "auto_inline").

Full response-mode contract and the JSON-RPC error model: references/mcp-response-protocol.md.

MCP resources

• axon://schema/mcp-tool — full JSON schema and routing contract (read this when you need exact field types/enums).
• ui://axon/status-dashboard — interactive MCP App widget for live queue status.

Configuration

This skill names only the handful of env vars that matter at the point of use (AXON_COLLECTION, AXON_SEARXNG_URL, AXON_HYBRID_SEARCH, AXON_OUTPUT_DIR, AXON_DATA_DIR, …). The full surface — every AXON_* env var and ~/.axon/config.toml tuning key — is documented authoritatively and is not duplicated here:

• config.example.toml (repo root) — all config.toml tuning knobs with defaults.
• .env.example (repo root) — service URLs, API keys, and secrets.
• docs/guides/configuration.md — full environment-variable reference + the two-layer (.env + config.toml) priority model.

Priority: CLI flags > env vars > ~/.axon/config.toml > built-in defaults.

Choosing parameters — quick guide

Tips and gotchas

• Read shape, then reach for RAG — not the raw artifact. path mode keeps multi-megabyte results out of the conversation; pull the content back with ask/query/retrieve (it's already embedded) rather than reading/grepping the file. There is no artifacts action — it was removed precisely because RAG is the intended way to get content.
• Don't paste raw axon <cmd> --help output. Most CLI subcommands inherit the entire Chrome flag set even when irrelevant. Use the action tables here instead.
• help and doctor are cheap. Call help once per session to confirm the live action map; call doctor whenever something looks wrong.
• Async by default. Lifecycle actions return a job_id; poll with subaction: "status". CLI users can pass --wait true for synchronous one-shots.
• Cache reuse is on by default (CLI). Disable with --cache false; add --cache-http-only to force the HTTP path even when the cached job used Chrome.
• graph: true is deprecated. Use hybrid search diagnostics and source coverage checks for retrieval debugging.
• Temporal filters use indexing date, not document publication date — useful for "what did I add this week", not "what was published this week".
• evaluate scores with a separate judge prompt (distinct role + reference material) on the same configured LLM backend. Available as both the MCP evaluate action and axon evaluate.
• subaction defaults to start for lifecycle families — { "action": "crawl", "urls": [...] } is enough to enqueue a job.