Top-level help presents import, find, show, status, forget, model connect/fetch/list/show/status/auth login, doctor and selftest.
| History command | Contract |
|---|---|
cg import |
Import |
cg find, cg show |
Find and show |
cg status |
Status |
cg forget |
Forget |
cg find --format text prints the passage id and Context name.
--write-memory-limit-bytes BYTES overrides the configured writer budget reported by status.
Use each command’s --help for argument syntax; settings are in configuration.
History search returns JSON by default.
--format text selects the human search rendering.
See how it works for the architecture.
cd ~/projects/my-app
cg import .
A directory import selects the Claude Code session files recorded for that project.
JSONL files in the working tree and another project's history are excluded from capture.
Helper-agent transcripts are counted separately from imported project sessions.
An explicitly imported helper transcript belongs to its parent session.
Enter at the first interactive project import accepts the suggested Context name.
The Context prompt does not enter JSON stdout.
Enter declines linking to an existing same-name Context.
An explicit affirmative answer links that Context.
Later status calls and imports from a project subdirectory reuse its Context binding.
An unlinked project without a controlling terminal returns context_binding_required.
The receipt includes the suggested Context name.
The retry command supplies that name with --context.
The refused import writes nothing.
A project without matching history returns project_history_not_found.
That refusal writes nothing.
A bound project refuses a different explicit Context with context_binding_conflict.
The conflicting Context is not created.
A second path, unknown flag, missing value or invalid search mode returns a usage error.
The usage error names the offending token.
The usage error creates no data root.
Deferred capture remains readable in a later status call.
A deferred import builds no searchable passages: a later status reports every captured event as pending.
The default background import reports captured_search_scheduled.
An unchanged wait import reports complete.
Deferred import reports captured_search_deferred.
Missing local artifacts make a background import return captured_search_behind.
A wait import with missing artifacts returns the same state.
Capture still completes.
The retry names cg model fetch --defaults.
The retry includes --search wait.
A default background import downloads no model.
A foreground embedding failure also returns captured_search_behind.
The captured events remain durable.
Changing the configured passage profile makes the next wait import embed captured history again.
The replacement generation becomes the active search head.
The replacement head answers search.
Search scope and processing controls are in configuration.
An unchanged caught-up import reports zero search.local_embedding_calls.
With --search defer, a malformed selected file produces source_partial.
The command exits 1.
The receipt names the failed file.
The receipt identifies the failing line.
The receipt includes a reason.
The resulting capture is durable.
An import receipt includes ok.
The receipt distinguishes explicit selection from project binding selection.
The receipt names the selected Context.
Capture status is separate from search status.
The receipt omits source text and source paths.
An interrupted all-sessions oldest-first import prints a retry preserving that scope, order and explicit worker cap.
Exact-file retry templates contain the quoted '<session.jsonl>' placeholder.
Substituting the original separately quoted file path preserves the explicit Context selection.
Status retries preserve the saved session scope and order.
Unavailable search retries preserve the saved session scope and order.
A multi-Context refusal with mixed policies has no single shared retry.
It provides a separate action for each selected Context.
cg find "why did we choose that transport?" --format text
cg show <passage-id> --format text
A find hit includes the cosine_similarity field.
Without an explicit Context flag, find uses the current project's binding.
--context a,b supplies an explicit multi-Context selection.
--all-contexts uses all authorized Contexts.
A hit carries its Context name.
Its passage_id can be passed to show to expand the linked events.
An unknown Context name returns unknown_context.
That refusal returns no hits.
Captured but unsearchable Contexts appear in omitted_contexts.
A selection with no searchable history returns history_search_not_ready.
Find leaves pending search pending.
Library find reports published searchable-event coverage separately from pending-event coverage.
Library find reports events outside the selected work scope separately.
cg show returns the exact stored events linked by find.
The events appear in source sequence order.
The original source file is not required.
A passage outside the selected Context returns passage_not_found.
That refusal exposes neither the passage text nor its Context name.
cg status can read a store held by a writer.
That read leaves the data-root bytes unchanged.
Status reports store_needs_recovery for an interrupted store.
The message names cg import <project-directory> --search defer as the recovery command.
That import restores readable status.
Library history status reports captured events per Context.
It reports session counts.
Graph memory totals are distinct from captured history.
Unprojected history reports pending search.
Completed projection reports ready search.
CLI status reports blocked search when the local model is missing.
Library status keeps the active generation id visible during a replacement build.
The building generation id is distinct from the active generation id.
The building profile reports the replacement's actual passage profile.
Building pending coverage is separate from active pending coverage.
An incomplete first build can have no active generation.
Its building generation remains observable.
See projection and worker coordination for activation and failure ownership.
Status, find and show create nothing when the store is missing.
Missing-store status exits 1.
Its JSON is {"ok":false,"state":"store_not_found","store":{"db_path":"…"},"retry":"create_store_with_write_command"}.
Text status writes no stdout.
It writes an error and a next action on stderr.
Find and show also return store_not_found.
Their next action names cg import.
For model connections, see model status.
cg forget --session <ref>
cg forget --context my-app --yes
Session forget erases the selected session's events.
It erases derived search passages.
The project binding remains.
The Context remains.
Its search progress is purged before the retained history is rebuilt.
CLI session forget schedules a rebuild of remaining history.
A missing local model reports a blocked rebuild.
An invalid configured passage profile reports rebuild_not_started after erasure.
Without a terminal, forget requires confirmation.
Its retry supplies --yes.
Enter at the terminal leaves history unchanged.
Whitespace-only session forget erases its checkpoint and source locator.
Whitespace-only Context forget erases its checkpoint and source locator.
An empty history selection returns nothing_to_forget.
Forgetting history in a store placed as a tenant hub returns the typed EventHistoryForgetRequiresEdgeDiscard refusal.
A reader-held-store refusal names the store.
It names each verified reader's process id.
It names each verified reader's process name.
An observed reader without a verified identity is disclosed.
| Model or diagnostic command | Recipe |
|---|---|
cg model connect |
Connect |
cg model fetch |
Fetch |
cg model list |
List |
cg model show |
Show |
cg model status |
Model status |
cg model auth login |
Login |
cg doctor |
Doctor |
cg selftest |
Selftest |
Model connect records the chosen provider.
It records the chosen endpoint.
It records the chosen model.
It stores an environment-variable credential reference.
--consent records authorization.
Connect makes no model request.
Model list reports the registered local and connected models.
Model show includes model kind.
It includes the connection.
It includes license information.
License-gated entries display manual installation instructions.
Model auth login records the selected existing host session.
The consent prompt names the candidate account, and the login output names the account and its quota spend.
Declining leaves consent unrecorded.
Declining spends no completion call.
Model status reports the connection name.
It reports the spend owner.
It reports quota or subscription spend.
Without a connection it says “no model connection.”
It provides login guidance.
Doctor spends no completion call.
--json returns structured findings.
Selftest spends one live completion call per invocation.
Selftest does not persist the reply.
Selftest without recorded consent returns consent_not_recorded.
It makes no request.
| Command | Recipe |
|---|---|
import |
cg-import |
find |
cg-find |
show |
cg-show |
status |
cg-status |
forget |
cg-forget |
model connect |
cg-model-connect |
model fetch |
cg-model-fetch |
model list |
cg-model-list |
model show |
cg-model-show |
model status |
cg-model-status |
model auth login |
cg-model-auth-login |
doctor |
cg-doctor |
selftest |
cg-selftest |