# ox query (https://sageox.ai/docs/cli/query)

# ox query

Search across your team's accumulated knowledge: discussions, docs, session history, and optionally local code.

## Usage

<Terminal>
  <TerminalCommand>ox query "how do we handle authentication?"</TerminalCommand>
</Terminal>

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

<Terminal title="ox query">
  <TerminalCommand>ox query "error handling conventions"</TerminalCommand>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>[1] score: 0.92  type: doc</TerminalOutput>
  <TerminalOutput>    Error Handling Guide</TerminalOutput>
  <TerminalOutput>    All API errors return a JSON body with code and message fields...</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>[2] score: 0.87  type: discussion</TerminalOutput>
  <TerminalOutput>    Discussion: API Review (2024-01-15)</TerminalOutput>
  <TerminalOutput>    We decided to use structured error codes instead of HTTP status...</TerminalOutput>
  <TerminalOutput> </TerminalOutput>
  <TerminalOutput>[3] score: 0.81  type: memory</TerminalOutput>
  <TerminalOutput>    Weekly Summary (2024-01-12)</TerminalOutput>
  <TerminalOutput>    Team standardized on returning 4xx for client errors with...</TerminalOutput>
</Terminal>

## 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.

<Terminal>
  <TerminalComment>Semantic search for concepts</TerminalComment>
  <TerminalCommand>ox query "our approach to caching" --mode knn</TerminalCommand>
  <TerminalOutput> </TerminalOutput>
  <TerminalComment>Keyword search for specific terms</TerminalComment>
  <TerminalCommand>ox query "PARCEL_BOUNDARY" --mode bm25</TerminalCommand>
</Terminal>

## Searching across teams and repos

Search a specific team's context:

<Terminal>
  <TerminalCommand>ox query "deployment process" --team team_abc123</TerminalCommand>
</Terminal>

Search a repo's Ledger (session history and code decisions):

<Terminal>
  <TerminalCommand>ox query "why did we refactor the auth module" --repo repo_xyz789</TerminalCommand>
</Terminal>

## 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.

<Terminal>
  <TerminalComment>Human usage</TerminalComment>
  <TerminalCommand>ox query "error handling"</TerminalCommand>
  <TerminalOutput> </TerminalOutput>
  <TerminalComment>AI coworker usage (includes telemetry)</TerminalComment>
  <TerminalCommand>ox agent query "error handling"</TerminalCommand>
</Terminal>

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.

## Related commands

- [ox prime](/docs/cli/prime): Load team context at session start
- [ox doctor](/docs/cli/doctor): Diagnose configuration issues
- [ox init](/docs/cli/init): Initialize a repository (needed to search local code: `--source code` or `--source all`)