istok context

istok context manages saved context: short rules, decisions, constraints, and notes stored with the current project. Agents read and update it through MCP. For how records reach a run and the budgets involved, see Context and knowledge; for the user’s side, see Project rules and knowledge.

Commands

Command	Purpose
`add TITLE`	Add a context record.
`list`	List context records.
`show [ID]`	Render project context or inspect one record.
`search QUERY`	Search project context.
`update ID`	Update a context record.
`enable ID`	Enable an instruction.
`disable ID`	Disable an instruction.
`delete ID`	Archive a context record.
`preview TASK`	Preview the context a claim of TASK would get.
`doctor`	Diagnose context growth and lifecycle issues.

All commands work on the current project. Records have canonical UUIDv7 IDs and revisions.

Kinds

Kind	Use
`note`	Project knowledge or implementation notes. The default.
`decision`	Decisions that should remain available to future work.
`instruction`	Guidance agents apply when working in the project.
`constraint`	Rules or limitations that affect implementation.

Add context

istok context add "Public API naming" \
  --kind constraint \
  --body "Public API fields use snake_case." \
  --tag api \
  --tag conventions

--tag can be repeated.

Record metadata

Flag	Values	Default
`--source`	`user`, `agent`, `import`	`user`
`--visibility`	`shared`, `local_only`	`shared`
`--sensitivity`	`normal`, `private`	`normal`
`--delivery`	`always`, `ranked`, `manual`	`always` for instructions, `ranked` otherwise

shared records take part in the normal project workflow; local_only marks a record that should stay local to the current Istok environment. Sensitivity is stored with the record so it keeps how the content should be treated.

Delivery

Mode	Behaviour
`always`	Delivered to every run.
`ranked`	Delivered when relevant to the task.
`manual`	Delivered only when a claim references the record by ID.

Keep a long note out of automatic delivery:

istok context add "Legacy billing migration notes" \
  --kind note \
  --delivery manual \
  --body "..."

Keep always records short: they are included in every run and count against the durable budget each time.

Lifecycle dates

Dates are RFC 3339 timestamps.

Flag	Effect
`--review-after`	After this time, the record is still delivered but flagged as due for review.
`--expires-at`	After this time, the record is excluded from automatic assembly.
`--superseded-by`	UUIDv7 of the active record that replaces this one; the record is excluded from automatic assembly.

istok context add "Feature freeze until the 2.0 release" \
  --kind constraint \
  --expires-at 2026-12-01T00:00:00Z \
  --body "Only bug fixes are accepted on main."

With context update, pass an empty value to clear a date, for example --expires-at "".

Instructions

An instruction has extra policy fields: enabled state, --priority, and --scope.

istok context add "Do not edit generated SDK files" \
  --kind instruction \
  --priority high \
  --body "Regenerate them from the OpenAPI schema instead."

Priority is critical, high, normal, or low; higher-priority instructions are placed first when context is assembled. Scope is project: the instruction applies to work in the current project.

List, show, and search

istok context list
istok context show
istok context show RECORD_ID
istok context search "naming"

show without an ID renders the active project context as plain Markdown, ready to paste elsewhere. With an ID, it shows one record with its metadata and current revision; use that before a change that needs --expected-revision.

Flag	Applies to	Effect
`--include-disabled`	`list`, `show`, `search`	Include disabled instructions.
`--deleted`	`list`, `show`, `search`	Include archived records.
`--limit`	`list`, `search`	Maximum number of records.
`--kind`, `--source`, `--visibility`, `--sensitivity`	`list`	Filters; each can be repeated.

Update context

istok context show RECORD_ID
istok context update RECORD_ID \
  --expected-revision REVISION \
  --delivery ranked

update accepts replacement values for the title, body, kind, tags, source, visibility, sensitivity, delivery, priority, scope, and lifecycle dates.

Enable and disable instructions

istok context disable RECORD_ID --expected-revision REVISION
istok context enable RECORD_ID --expected-revision REVISION

Disabling keeps the record and its history but stops it from taking part in context assembly. Disabled instructions are left out of normal listing, search, export, and context packages unless explicitly requested.

Archive context

istok context delete RECORD_ID --expected-revision REVISION

The record is archived and no longer part of active context. The CLI asks for confirmation; with --json, pass --yes.

Revisions

update, enable, disable, and delete require --expected-revision. If the record changed since that revision, the command fails instead of overwriting newer state. Read it again and retry with the latest revision.

Bounded context assembly

When a task is claimed, Istok assembles a context package from:

always records, with enabled instructions ordered by priority;
records named with --context-id;
ranked records that match the task’s title, description, acceptance criteria, and notes;
code retrieved from the repository index;
a briefing of current knowledge.

The package becomes the run’s context snapshot. Later edits to live context do not change it.

Limit	Default
Durable context	16 KiB
Code retrieval	32 KiB
Total	48 KiB
Durable records	12, expanded up to 64 for required `always` records
Size of one record	12 KiB
Knowledge briefing	20 items, 4 KiB, counted separately

Ranked records fill whatever durable budget remains after always and explicit records. Expired and superseded records are skipped, and the snapshot records a warning for them. A snapshot also warns when always context grows beyond 8 KiB.

If required always or explicit records do not fit, the claim fails instead of dropping them. The error names the records and suggests a fix: shorten a record, change a nonessential record to ranked, or use a larger --context-limit.

Preview context for a task

See what a claim of task 12 would deliver, without creating a run:

istok context preview 12

The output shows the number of durable records against the item limit, byte usage against each budget, the knowledge briefing, each selected record with its lane (always, explicit, or ranked) and score, and any warnings.

preview accepts the same context options as istok task claim:

istok context preview 12 --context-id RECORD_ID
istok context preview 12 --context-limit 20

--all-context requires --context-override-reason, and --without-retrieval requires --retrieval-override-reason.

Diagnose context

istok context doctor

doctor reports:

active records and their total size;
how many records use each delivery mode;
expired, superseded, and review-due records;
issues with a severity, the affected record IDs, and a suggested action.

Issues include records larger than the per-record limit, always context above its soft limit or above the durable budget, more always records than the default item limit, expired and review-due records, and records with duplicate titles. Run it when claims fail on context budgets, or from time to time as context grows.

JSON output

Context commands accept --json and return a versioned response. show --json returns a structured list instead of the rendered Markdown. See JSON output.

Help

istok context add --help
istok context update --help
istok context preview --help
istok context doctor --help