--- title: Context Packs description: Token-budgeted, cited retrieval bundles that give a model the most relevant document chunks for a task within a bounded token budget. --- A context pack is a token-budgeted, citation-tagged bundle of the most relevant document chunks for a single agent task. Instead of dumping raw documents into a prompt and hoping the model finds what it needs, `omgdb context` ranks documents by semantic similarity to a task query, then packs them best-first until an approximate token budget is exhausted. Each chunk carries the source document's `_id` as a citation, so the answer the model produces can be traced back to its evidence. This is the "give me context for this task, with sources" surface. It is built directly on the same embedder and cosine ranking used by [vector search](/docs/vector-search/), and it is exposed both as the `omgdb context` CLI command and as the MCP `context_pack` tool for agents. ## Why context packs matter for agents Three properties make context packs useful when preparing context for a model: - **Bounded.** The result fits inside an approximate token budget you control, so a retrieval step can never blow up the context window. The pack reports exactly how many tokens it used and whether relevant documents were left out. - **Grounded.** Only the most relevant chunks for the task are included, ranked by cosine similarity. Irrelevant documents (a chocolate-cake recipe in a database-search query) rank at the bottom, so they are the first to be left out when the budget overflows; with a generous budget they are still included with a low (possibly zero) score. - **Cited.** Every chunk is tagged with its source `_id`, and the pack carries a flat `citations` list. The model's answer can be attributed back to specific documents in the store. > **Tip:** Because retrieval, budgeting, and citation happen in one local call against an embedded store, an agent can fetch grounded context with no external embedding service and no separate vector database. ## Synopsis ```text omgdb context [--budget N] [--filter ''] ``` | Argument / Flag | Description | | --- | --- | | `` | Store directory, e.g. `app.omgdb`. | | `` | Collection (namespace) to retrieve over. | | `` | The string field whose text is embedded and ranked. | | `` | The task / query text to rank against. | | `--budget N` | Approximate token budget for the bundle. Default: **1000**. | | `--filter ''` | Optional MongoDB-style filter (JSON) that pre-filters candidates before ranking (hybrid retrieval). | The command prints the context pack as a single line of canonical JSON to stdout. ## How it works Context packs reuse the [vector search](/docs/vector-search/) machinery end to end: 1. The query and each document's `` are embedded with the offline `HashingEmbedder` (256 dimensions) — a deterministic, dependency-free bag-of-words embedder, **not** a neural model. 2. Documents are ranked by cosine similarity to the query, best-first (the same flat exact kNN scan as `omgdb vsearch`). 3. Chunks are added to the pack in rank order. For each chunk, an approximate token cost is computed (`approx_tokens`, a crude ~4-characters-per-token heuristic). 4. Packing **stops at the first chunk that would overflow** the budget. That chunk and everything after it are left out, and the pack is marked `truncated`. The result is therefore a contiguous top-relevance prefix. > **Limitation:** Packing is greedy and stops at the first overflowing chunk rather than skipping it to fit smaller, lower-ranked chunks. A single large top-ranked chunk can leave most of the budget unused while `truncated` is still `true`. A budget too small to fit even the top chunk yields an empty, truncated pack. > **Note:** Relevance is only as good as the bundled `HashingEmbedder`, which is a reproducible offline baseline, not a transformer model. Budget accounting is approximate because `approx_tokens` is a heuristic, not a real tokenizer. Only string fields are considered; documents lacking a string value at `` are silently skipped. See the [vector search](/docs/vector-search/) caveats for details. ## Output shape The pack serializes to a canonical JSON document with these keys: | Key | Type | Meaning | | --- | --- | --- | | `query` | string | The task query the pack was built for. | | `budgetTokens` | int | The requested approximate token budget. | | `usedTokens` | int | Approximate tokens actually consumed by the included chunks. | | `truncated` | bool | `true` if relevant documents were dropped because the budget filled up. | | `chunks` | array | The included chunks, most relevant first. Each is `{id, score, tokens, text}`. | | `citations` | array | A flat list of the source `_id`s of the included chunks. | Each entry in `chunks` has: | Field | Type | Meaning | | --- | --- | --- | | `id` | value | The source document's `_id` — the citation. | | `score` | double | Cosine similarity to the query (best-first ordering). | | `tokens` | int | Approximate token cost of the chunk text. | | `text` | string | The chunk text taken from ``. | ## Worked example ```sh omgdb create app.omgdb omgdb insert app.omgdb docs '{"text":"database search and indexing"}' omgdb insert app.omgdb docs '{"text":"chocolate cake recipe"}' omgdb context app.omgdb docs text "database search" --budget 500 ``` The command prints a single canonical-JSON line (pretty-printed here for readability; key order is preserved). With the documents above, the database-search document ranks first and the chocolate-cake recipe ranks last (score `0.0`); both have a string `text` field and both fit within the 500-token budget, so both are included and the pack is not truncated. `usedTokens` is 13 (7 + 6): ```json { "query": "database search", "budgetTokens": 500, "usedTokens": 13, "truncated": false, "chunks": [ { "id": { "$oid": "..." }, "score": 0.7071, "tokens": 7, "text": "database search and indexing" }, { "id": { "$oid": "..." }, "score": 0.0, "tokens": 6, "text": "chocolate cake recipe" } ], "citations": [ { "$oid": "..." }, { "$oid": "..." } ] } ``` The `citations` array mirrors the chunk `_id`s, so a downstream prompt can render the bundled `text` and attribute it back to specific documents. ### Hybrid retrieval with a pre-filter `--filter` applies a MongoDB-style [query filter](/docs/query-operators/) before ranking, so only documents that match the structured predicate are eligible for the pack. This combines a structured pre-filter with semantic ranking in one pass: ```sh omgdb context app.omgdb docs text "database search" \ --budget 500 --filter '{"status":"published"}' ``` Only `published` documents are considered, even if a draft document is equally relevant. This is the same hybrid behavior as `omgdb vsearch --filter`. ## MCP tool equivalent The same capability is exposed to agents over the [Model Context Protocol](/docs/mcp/) as the `context_pack` tool. It takes `path`, `collection`, `field`, `query`, an optional `budget` (default **1000**), and an optional `filter`, and returns the same canonical-JSON `ContextPack`. The tool is annotated read-only / idempotent and gated at the read scope, so it is available even on an MCP server started with `--scope read`: ```sh omgdb mcp --scope read ``` The companion semantic-search tool `vsearch` is also available at read scope. See [MCP](/docs/mcp/) for the full tool surface and scope model. > **Note:** There is no `context.forTask()` programmatic API. The real surfaces are the `omgdb context` CLI command and the `context_pack` MCP tool documented above; the underlying Rust function is `omgdb_vector::context_pack` (and `context_pack_where` for the filtered variant). ## Related - [Vector search](/docs/vector-search/) — the embedder, cosine ranking, and `vsearch`/`vsync`/`vstale` commands context packs build on. - [Query operators](/docs/query-operators/) — the filter language used by `--filter` for hybrid retrieval. - [MCP](/docs/mcp/) — exposing `context_pack` and other tools to coding agents. - [Agent mutations](/docs/agent-mutations/) — the plan/apply/rollback workflow for grounded writes.