ox query
Search across your team's accumulated knowledge: discussions, docs, session history, and optionally local code or the locally-cached Ledger.
Usage
Returns the most relevant chunks from your team's indexed content, ranked by relevance.
What gets searched
| Source | What it includes | Controlled by |
|---|---|---|
| Team Context | Discussions, team docs, distilled memory, AGENTS.md | --source team (default) |
| Ledger | Session history, commit summaries, code decisions | --repo flag |
| Code | Local code index | --source code or --source all |
| Local Ledger | Locally-cached Ledger only, with zero network (fast hook path) | --local or --source local |
By default, ox query searches Team Context only. Add --source all to include local code in the search.
Flags
| Flag | Description | Default |
|---|---|---|
-k, --limit | Max results to return | 5 |
--team | Team ID to search | Project config, else the credential's team |
--repo | Repo ID to search (searches Ledger) | From project config |
--mode | Search mode: hybrid, knn, or bm25 | hybrid |
--source | Search source: team, code, local, or all | team |
--local | Search the locally-cached Ledger only (zero network) | — |
--json | Emit machine-readable JSON | On in agent context |
Examples
Search modes
| Mode | How it works | Best for |
|---|---|---|
hybrid | Combines semantic similarity (knn) with keyword matching (bm25) | Most queries, balances meaning and exact terms |
knn | Pure vector similarity search | Conceptual questions ("how do we approach X?") |
bm25 | Pure keyword matching | Exact term lookup ("what is PARCEL_ID?") |
Hybrid mode is the default and works well for most queries. Use --mode knn when searching for concepts without specific terminology, and --mode bm25 when you know the exact terms you're looking for.
Searching across teams and repos
Search a specific team's context:
Search a repo's Ledger (session history and code decisions):
Agent version
AI coworkers use ox agent <agent_id> query instead of ox query. The behavior is identical, but the agent form includes agent telemetry (agent ID, agent type) for observability.
When building prompts or CLAUDE.md instructions for AI coworkers, use ox agent <agent_id> query so that queries are attributed to the agent session.
When to use query vs. prime
| Scenario | Use |
|---|---|
| Start of session, load team norms | ox agent prime |
| Mid-session, find specific knowledge | ox agent <agent_id> query |
| Human exploring team knowledge | ox query |
ox agent prime loads the core context files (AGENTS.md, SOUL.md, etc.) at session start. ox query searches the full corpus (discussions, docs, memory) for specific information during a task.
What's next
- ox agent prime: Load team context at session start
- ox doctor: Diagnose configuration issues
- ox init: Initialize a repository (needed to search local code:
--source codeor--source all)