context pack

What It Does

context pack turns retrieved knowledge into a bounded packet for a specific goal. It uses the same retrieval planner/executor as query, then applies budget-based trimming for the next agent prompt.

When To Use / When Not To Use

When to use it

You have a goal and want a compact context handoff.
You need token budgeting.
You want to pass structured input to an agent reliably.

When not to use it

You only want to inspect raw retrieval hits. Use query.
You want to resume active work with open loops and working state. Use memory recall.

Syntax

pnpm ragit context pack [goal] [--input <path|->] \
  [--budget <tokens>] \
  [--scope durable|session|harness|evidence|all] \
  [--at <sha>] [--view minimal|default|full] \
  [--format text|json|both]

Arguments And Options

goal: The goal that should drive context selection.
--input <path|->: Provide a JSON payload with goal, optional budget, and optional at.
--budget <tokens>: Token budget for the selected packet.
--scope durable|session|harness|evidence|all: Choose whether the packet is built from durable snapshot knowledge only or from explicit artifact scopes too.
--at <sha>: Use a specific snapshot instead of the current HEAD state.
--view minimal|default|full: Control how much detail is projected into the packet.
--format text|json|both: Choose text, JSON, or both.
--cwd <path>: Run against another repository.

Input And Output Contract

{
  "goal": "implementation plan for auth",
  "budget": 1200,
  "at": "HEAD"
}

JSON output includes goal, snapshotSha, budget, usedTokens, selectedHits, hits, and redactionSummary.
Hit selection is not a separate search path. It is the same retrieval result, trimmed down to fit the requested budget.
Output is re-masked before projection, so packets stay safe for downstream agent prompts.
--view minimal is the safest default for agent context windows.
--view default preserves a balanced amount of detail.
--view full is useful only when downstream reasoning truly needs richer text.

Examples

Human terminal flow:

pnpm ragit context pack "implementation plan for auth" --budget 1200

Agent-oriented flow:

pnpm ragit context pack --input context-pack.json --view minimal --format json

Failures And Cautions

Do not mix --input with positional goal, --budget, or --at.
An empty goal is rejected.
This command never includes working-memory state.
--scope durable stays snapshot-bound.
--scope session|harness|evidence|all can merge explicit artifact/evidence overlays, but the resulting packet is still sanitized before output.

context pack

On this page