Skip to content

cn

ContextNest client. ContextNest is the substrate that remembers sessions, features and outcomes across projects; cn probes it, searches it, and settles outcomes back into it. Every call is bounded and fails soft except in the secure tier, where a missing token fails closed.

mini-ork works without ContextNest. When MO_DISABLE_CN=1 is set, or the server is unreachable, the run proceeds and the context section is simply empty — it never blocks a run.

Usage

mini-ork cn status [--json]
mini-ork cn ack-overlap <overlap_id> [--by <principal>] [--json]
mini-ork cn search <memories|sessions|features|files> <query>
               [--all-projects] [--limit N] [--json]
mini-ork cn seen-before <run_id> [--node <node_id>]
               [--all-projects] [--top-k N] [--json]
mini-ork cn outcome <atom_id> <success|failure>
               [--run <run_id>] [--evidence <text>] [--yes] [--json]

status

mini-ork cn status
mini-ork cn status --json

One line: tier, endpoint, whether the server answered, and latency. It probes /api/v1/substrate/health with the ping timeout, separate from the read timeout, so a slow server is reported as down instead of hanging the display. status exits 0 whether the server is up or not — "down" is a fact to report, not a command failure.

mini-ork cn search memories "why did the gate abstain"
mini-ork cn search sessions "worktree merge"
mini-ork cn search features "run page"
mini-ork cn search files mini_ork/cli/board_cmd.py
Mode Query is Returns
memories Free text Semantic matches over stored memories
sessions Free text Sessions that shipped the feature
features Free text Project-scoped feature records
files A path or partial path Rows attached to that file

By default only this project's rows are returned; --all-projects widens the search. --limit (default 20) caps rows per mode. Without --json the result is written to the cache slot the IDE's Search tab reads; with --json the envelope is printed and the slot is left alone.

The search uses CN_SEARCH_TIMEOUT_SEC (default 90) as its budget — a long budget for an interactive search, distinct from the short background read.

seen-before

mini-ork cn seen-before <run-id> --node implement

Caches a ContextNest retrieve for a failing run into <run_dir>/contextnest-seen-before.json, which the run's outcome and node pages render. The verb reads the error tail from the node's log or session transcript when --node is omitted, and defaults to the run's failing node.

Flag Meaning
--node <id> Failing node to draw the query from
--all-projects Include other projects' rows
--top-k N top_k sent to /api/v1/tools/retrieve (default 5)
--json Print the envelope instead of writing the stored file

The page always renders the top 3 by similarity even when --top-k is higher.

outcome

mini-ork cn outcome <atom-id> success --run <run-id> --evidence "gate passed" --yes

Settles one atom's outcome against /api/v1/agent/outcome and prints the response's updated count. --run scopes the evidence recorded in the audit log; --evidence is capped at 480 characters. On a typed invocation the command asks for confirmation unless --yes is passed — the IDE buttons already carry their own confirmation payload.

ack-overlap

mini-ork cn ack-overlap <overlap-id> --by agent-a

Acknowledges a coordination overlap reported by /api/v1/coord/overlaps. --by defaults to $CONCORD_PRINCIPAL or human:$USER.

Configuration

Resolved highest precedence first: environment, then $MINI_ORK_HOME/config/contextnest.yaml, then the shipped example.

Variable Default Meaning
CN_BASE_URL http://127.0.0.1:28080 Server endpoint
CN_TIER simple simple (no auth, fails soft) or secure
CN_TOKEN_KEY CN_TOKEN Secret-store key holding the bearer token
CN_TIMEOUT_SEC 8 Read budget
CN_SEARCH_TIMEOUT_SEC 90 cn search budget
CN_PING_TIMEOUT_SEC 1 Health-probe budget
CN_PING_TTL 30 Seconds a probe result is reused
CN_HOOK_TIMEOUT_SEC 3 Fire-and-forget hook push budget
MO_DISABLE_CN 0 1 disables every ContextNest call

The secure tier fails closed

Under CN_TIER=secure a missing token is an error that names the key; the request is never sent and there is no silent fallback to the simple tier. Under simple there is no auth header at all, which is correct only for a loopback server.

Exit codes

0 success (including status reporting a down server), 1 the server returned an error or a required file was missing, 2 usage.