ox query
Search across your team's accumulated knowledge — discussions, docs, session history, and optionally local code.
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 repository files | --source code or --source all |
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 | Current team |
--repo | Repo ID to search (searches Ledger) | — |
--mode | Search mode: hybrid, knn, or bm25 | hybrid |
--source | Search source: team, code, or all | team |
Example output
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 query instead of ox query. The behavior is identical, but ox agent query includes agent telemetry (agent ID, agent type) for observability.
When building prompts or CLAUDE.md instructions for AI coworkers, use ox agent 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 query |
| Human exploring team knowledge | ox query |
ox 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.