Context Packs

Token-budgeted, cited retrieval bundles that give an LLM 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 LLM 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, 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 driving an LLM:

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

omgdb context <path> <collection> <field> <query> [--budget N] [--filter '<json>']

Argument / Flag	Description
`<path>`	Store directory, e.g. `app.omgdb`.
`<collection>`	Collection (namespace) to retrieve over.
`<field>`	The string field whose text is embedded and ranked.
`<query>`	The task / query text to rank against.
`--budget N`	Approximate token budget for the bundle. Default: 1000.
`--filter '<json>'`	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 machinery end to end:

The query and each document’s <field> are embedded with the offline HashingEmbedder (256 dimensions) — a deterministic, dependency-free bag-of-words embedder, not a neural model.
Documents are ranked by cosine similarity to the query, best-first (the same flat exact kNN scan as omgdb vsearch).
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).
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 <field> are silently skipped. See the 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 `<field>`.

Worked example

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. 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):

{
  "budgetTokens": 500,
  "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": "..." } ],
  "query": "database search",
  "truncated": false,
  "usedTokens": 13
}

The citations array mirrors the chunk _ids, 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 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:

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 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:

omgdb mcp --scope read

The companion semantic-search tool vsearch is also available at read scope. See 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).

Vector search — the embedder, cosine ranking, and vsearch/vsync/vstale commands context packs build on.
Query operators — the filter language used by --filter for hybrid retrieval.
MCP — exposing context_pack and other tools to LLM agents.
Agent mutations — the plan/apply/rollback workflow for grounded writes.