# ox query (/docs/cli/commands/query)



ox query [#ox-query]

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

Usage [#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 [#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 [#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 [#example-output]

<Terminal title="ox query">
  <TerminalCommand>
    ox query "error handling conventions"
  </TerminalCommand>

  <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>
    \[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>
    \[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 [#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 />

  <TerminalComment>
    Keyword search for specific terms
  </TerminalComment>

  <TerminalCommand>
    ox query "PARCEL_BOUNDARY" --mode bm25
  </TerminalCommand>
</Terminal>

Searching across teams and repos [#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 [#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 />

  <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 [#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 [#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 repository (required for query)