Records CLI reference¶
Experimental
Command names and output fields may change before a stable release.
Conventions¶
- Output. Every command prints one JSON object on stdout with a
statusfield.exportwithout--outputprints the JSONL on stdout and its summary on stderr.recall --format textandwake --format markdownprint rendered text instead. - Exit status.
0on success;1whenstatusiserrorordrift(for exampledoctorfound a problem,importmet a conflict, orconsolidate statusfound a summary that is not valid);2when the command failed. A failure printserror[<code>]: <message>on stderr, or{"status": "error", "error": {"code": ..., "message": ...}}on stdout with--json-errors. - Scope. Every command except
schema templates,recallandwaketakes--scope project:<id>|agent:<id>|shared:<id>, plus--repo PATHfor project scope (default: the current directory).recalltakes any number of--scopeoptions, andwaketakes--agentand any number of them. - Actor.
--actor NAMErecords who acted. The default is$AKMS_RECORDS_ACTOR, then the operating-system user name. - Idempotency. Write commands take
--event-id ID. Running the same write again with the same ID returns the first result with"noop": trueand writes nothing. Without--event-ida random ID is used. - Revision preconditions.
amend,supersedeandretractrequire--expect-revision N, the revision you last read. If the record has moved on, the command fails withstale_revisionand writes nothing.
Schemas¶
| Command | Purpose |
|---|---|
schema register PATH [--name N] [--version V] [RULES] |
Register a schema file. Name and version come from the file's x-akms-records block or the flags; rules from the block's rules or the rule options, not both. |
schema register --template NAME |
Register a built-in template (with its rules). |
schema list |
Registered schemas, with an error entry for any that fail their digest check. |
schema show REF |
One schema with its content. REF is name/vN, or name for the newest version. |
schema templates |
Names of the built-in templates. |
schema rules set REF [--file RULES.json] [--search-text P]... [--label P] [--time-field P] [--summary-template T] [--unset KEY]... |
Change a schema version's extraction rules. --file replaces them; the options change single rules of the current set. |
schema rules show REF |
The rules, their digest, who set them and when, and the change log. |
schema policy set NAME --source human\|agent --status tentative\|established --confidence X [--yes] |
Set a schema's promotion policy. |
schema policy show NAME |
The current policy, the effective one (the default when none is set), and the change log. |
RULES on register is --rules RULES.json and/or the same rule options
as schema rules set. Rules are kept beside the schema, outside its digest:
changing them needs no new schema version and leaves records untouched. Every
change goes to the rules log with the actor, the time and the previous value.
Each pointer must name a property the schema declares, or the command fails
with invalid_rules. See schemas and templates.
schema policy set is a human operation. It asks for confirmation on an
interactive terminal and refuses (confirmation_required) when standard input
is not a terminal. --yes skips the prompt for a person running it from a
script; an agent must never pass it. Every change is appended to the policy
log with the actor, the time and the previous value. An agent-sourced policy
cannot be established.
Records¶
| Command | Purpose |
|---|---|
add --file DOC [--schema REF] |
Create a record. |
amend RECORD --expect-revision N [--file DOC] |
Amend fields; fields not given keep their value, except that a summary from the schema's template follows a new payload (see templates). |
supersede RECORD --expect-revision N (--by OTHER \| --file DOC [--schema REF]) [--reason TEXT] |
Mark a record superseded by an existing record, or by a new one created from DOC. |
retract RECORD --expect-revision N --reason TEXT |
Mark a record retracted. |
show RECORD |
The current state: record (envelope and payload) and state (update time, head digest, successor, reason). |
history RECORD |
Every event, oldest first. |
list |
The scope's records, by reading the files (not the index), plus any that fail to replay. |
A review does not outlive the text it was of. When an agent changes a record's
content (its payload, summary or origin), a reviewed record becomes unreviewed, so
it stops being offered to other agents as checked. Tags, source references and
sensitivity are not content and keep the state, and promote's link changes nothing.
rejected stays rejected.
- Who keeps the state: the person the record belongs to, meaning an actor equal
to
origin.actor_idon a record whoseorigin.kindishumanorhuman-confirmed. Every other actor counts as an agent, because actor names say nothing else. A person changing someone else's record confirms it again in a separate amend. - Naming a state in the same amend:
unreviewedandagent_reviewedare allowed, since an agent can say it reviewed its own edit.user_confirmedis refused withreview_reassertand nothing is written. - The limit: this is a rule for cooperating agents. An agent can pass a person's
name as
--actor, or setuser_confirmedin a later amend. The second step shows inhistory, with the actor. Without$AKMS_RECORDS_ACTOR, the default actor is the operating-system user, the same for a person and any agent they run, so set it for agents.
Recall and wake¶
| Command | Purpose |
|---|---|
recall [--scope S]... [--agent ID [--visible]] [--query WORDS] [--match auto\|all\|any] [--semantic [--embed-sensitive]] [--schema REF] [--tag TAG]... [--since T] [--until T] [--review-state MIN] [--include-retracted] [--include-superseded] [--include-sensitive] [--limit N] [--full] [--format json\|text] |
Search one or more scopes through the index: every word, else any word, ranked by BM25, then newest first. |
wake --agent ID --task TEXT --budget-tokens N [--scope S]... [--include-sensitive] [--include-unreviewed] [--include-promoted] [--include-imported] [--exclude-nodes MANIFEST] [--review-state MIN] [--format json\|markdown] [--generated-at] |
Prioritised, deduplicated records for an agent within a hard token budget, with a truncation report. By default: reviewed records plus the agent's own unreviewed ones, without promoted records and imported failure lessons; --include-unreviewed adds everyone's. |
Both are described in recall and wake, including the visibility and eligibility rules and the output shapes.
Consolidation¶
| Command | Purpose |
|---|---|
consolidate create [--tag T]... [--query Q] [--topic-name NAME] [--review-state MIN] [--method extractive\|provider] [--agent ID] [--event-id ID] [--summarizer-timeout S] [--summarizer-cmd ARGV...] |
Write a source-linked summary of the topic's records. --summarizer-cmd (last option; no shell) selects the provider method. |
consolidate status [ID] |
valid, stale or invalid, with each source's state and the topic check; every active summary without ID. Exit 1 when any is not valid. |
consolidate refresh ID [--expect-revision N] [--event-id ID] [--summarizer-timeout S] [--summarizer-cmd ARGV...] |
Rewrite a stale summary as an amendment; stale_revision if another refresh won. |
consolidate list |
The scope's summaries, without checking them. |
See consolidation for the payload, the citation rules, invalidation, the erasure cascade and the provider protocol.
add and amend also take --summary, --tag TAG (repeatable),
--sensitivity public|internal|sensitive,
--review-state unreviewed|agent_reviewed|user_confirmed|rejected and
--origin-kind human|human-confirmed|agent|tool|import; these override the
document. The default origin is agent with the actor as actor_id.
A record document is a JSON object with any of schema_ref, payload,
summary, tags, origin, source_refs, sensitivity and review_state.
Payload fields go under payload. Fields the store sets (record_id,
revision, schema_sha256, recorded_at, lifecycle) are refused, and so
is a scope that differs from --scope. When summary is absent on create,
the schema's summary template fills it.
supersede --file creates the successor with the event ID <event-id>.new
and adds {"kind": "supersedes", "ref": RECORD} to its source_refs, so a
retry with the same --event-id repeats neither write. Only active records
can be amended, superseded or retracted.
Promotion¶
| Command | Purpose |
|---|---|
promote RECORD --review approved [--min-review-state MIN] [--scope-ok] [--allow-sensitive] [--allow-imported] [--update] [--domain D] [--yes] |
Write a reviewed record as an AKMS project-local node and link it. --update replaces this record's verified managed block while preserving unrelated prose (needs akms-records[akms]). |
promotion status [RECORD] |
Read-only source/node consistency report; exits 1 for drift. |
promotion withdraw RECORD --reason TEXT (--expect-revision N \| --erased) [--yes] |
Remove only this record’s verified managed projection, without deleting the source. Erased sources require the matching scoped erasure log. Human-node writes retain confirmation rules. |
user_confirmed is the default threshold; --min-review-state agent_reviewed is
an opt-in. A write labelled source: human asks for confirmation on an interactive
terminal, or takes --yes, and without either it is refused with
confirmation_required, not sent down the default path. --yes makes the step
deliberate; it does not prove a person took it. See
promotion and import for the two paths, every refusal and
the crash order.
Maintenance¶
| Command | Purpose |
|---|---|
erase RECORD --reason TEXT [--force] |
Remove a record's files and log a content-free erasure line; summaries that cite it are erased too. |
doctor [--fix [--force-tmp]] |
Check the store root; with --fix, also repair what is safe. |
export [--output FILE] [--include-sensitive] [--skip-broken] |
Write the scope as JSONL. |
import FILE |
Replay an export into the scope. |
import --from-failure-memory CONFIG [--failure-memory-repo PATH] |
Read a failure-memory registry into failure-lesson/v1 records, without writing back. See the importer. |
index rebuild |
Rebuild the store root's search index from the files. |
index check |
Compare the index with the files; status: drift (exit 1) lists missing, extra and stale records. Changes nothing. |
index reconcile |
Replay every record and fix what differs. |
erase writes {record_id, scope, at, actor, reason} to
_erasures.jsonl, deletes the record directory, and removes the record from
this worktree's index without leaving its bytes in the database files (the
result's index field; see search index). Never put
protected content in the reason. The result lists what erasure cannot reach
(see limits). --force erases a record that does not replay and
whose scope cannot be read; a record that names another scope is never erased.
Every summary whose history cites the
record is erased with it, each with its own log line carrying cascade_of;
the result lists them under cascade.
doctor covers every scope in the store root. Without options it only
reports and changes nothing. --fix repairs what is safe to repair;
--force-tmp (only with --fix) also removes temp files whose writer still
looks alive, which is safe only when no writer is running.
The result follows failure-memory doctor: a status of ok or error
(exit code 0 or 1), and a checks list. Each check has check, status
(ok, warning or error), severity, repairable (whether --fix
handles it) and the items it found. repairs lists what --fix changed
(tmp_removed, empty_dirs_removed, erasures_reapplied,
summaries_erased, index_reconciled, and semantic_index_deleted when the
semantic index held an erased record), mode is report or fix, and
records_checked counts the records replayed. --actor names who --fix
logs as erasing a summary.
| Check | Severity | Repaired by --fix |
|---|---|---|
stale_tmp_files: temp files whose writer has exited |
error | yes |
empty_dirs: empty record directories older than a minute, empty month directories |
error | yes |
erased_but_present: records in the erasure log that are back, for example after a merge |
error | yes (erased again) |
summaries_citing_erased: summaries whose history cites an erased record |
error | yes (erased, logged as a cascade) |
replay_errors: gaps, broken chains or seals, malformed events |
error | no |
conflicts: records with git conflict markers |
error | no |
schema_errors: schemas that fail their digest check |
error | no |
schema_mismatch: records whose schema digest differs from the registry |
error | no |
rules_drift, policy_drift: rules or policy files that fail their digest or disagree with their log |
error | no |
erasure_log: unreadable erasure-log lines |
error | no |
tmp_in_progress, recent_empty_dirs: a writer may still be working |
warning | no |
stray_files, noncanonical: unexpected files, event files that are not byte-canonical |
warning | no |
index_drift: index rows that are missing, extra or stale against the files, or an index in another format |
error | yes (reconciled) |
index_unavailable: the index exists but cannot be opened (for example no FTS5) |
warning | no |
export writes a header, every registered schema with its digest, the
scope's erasure lines, every event, and a footer with counts and a digest of
all preceding lines. Records whose current sensitivity is sensitive are left
out unless --include-sensitive is given. A scope with records that do not
replay is refused unless --skip-broken is given.
import checks the footer, schema digests, every event's seal and chain,
every rules digest, and every payload, before writing anything. It then
registers missing schemas with their rules, stores rules for a local schema
that has none, appends new erasure lines, and writes the missing event files.
Where the local rules differ from the exported ones, the local rules are kept
and the schema is listed under rules_differ.
Importing the same file again writes nothing. A record whose local history
diverges is reported under conflicts and left alone (status: drift). A
record in the local erasure log is never brought back. The export's scope must
equal --scope.
Error codes¶
| Code | Meaning |
|---|---|
usage |
Missing or contradictory arguments |
invalid_scope, invalid_record_id, invalid_event_id |
Malformed identifiers |
invalid_record |
The record document breaks an envelope rule |
envelope_shadow |
A payload key or schema property reuses an envelope key |
payload_invalid |
The payload does not match its schema (details.errors lists paths) |
not_found, schema_not_found, template_not_found |
Nothing by that name in this store |
scope_violation |
The record belongs to another scope |
stale_revision |
--expect-revision is no longer the head; nothing written |
not_active |
The record is superseded or retracted |
qmd_missing |
recall --semantic needs the qmd command, which is not on PATH |
semantic_model_missing |
recall --semantic needs qmd's embedding model as a local file; nothing is downloaded |
semantic_failed |
qmd failed, timed out or printed something unexpected |
semantic_locked |
Another process kept the semantic index busy for too long |
review_reassert |
An agent changed a record's content and named user_confirmed in the same amend; nothing written |
event_id_reused |
The event ID was already used for a different kind of event, or in another scope |
replay_error |
The record's files do not replay (details.replay_code says why) |
invalid_schema, invalid_rules |
The schema or its extraction rules are not acceptable (for example a pointer to an undeclared property) |
rules_invalid |
A stored rules file no longer matches its digest |
schema_ref_refused |
The schema has a non-local reference, $id or another dialect |
schema_exists |
That name/vN is registered with different content |
schema_tampered |
A registered schema no longer matches its digest |
invalid_policy |
A promotion-policy value is not acceptable |
confirmation_required, not_confirmed |
schema policy set or a human-policy promote had no terminal and no --yes, or was not answered yes; nothing written |
confirmation_stale |
The record, node or policy changed while a human-policy promote was being confirmed; nothing written |
export_corrupt, digest_mismatch |
An export failed its integrity checks |
link_unsupported |
The filesystem has no hard links |
invalid_query |
A recall query has no searchable words, or cannot be run |
budget_too_small |
The wake budget cannot hold the header and truncation report (details.minimum_tokens) |
citation_invalid |
A summary assertion is uncited or cites something it may not (details.problem) |
consolidation_write |
A summary was written or changed outside consolidate |
consolidation_schema, reserved_schema |
consolidation/v1 differs from the built-in, or another schema used a reserved name (consolidation, failure-lesson) |
empty_topic, topic_too_large |
The topic gathers no records, or more than 64 |
summary_exists |
An active summary of the same topic exists (details.record_id); refresh it |
summary_invalid, not_a_summary |
The summary cannot be refreshed; the record is not a summary |
summarizer_required, summarizer_failed, summarizer_timeout, summarizer_output_invalid |
Provider errors: none given, it failed or exited non-zero, it ran too long, or its output is not the expected JSON |
fts5_unavailable |
Python's sqlite3 has no FTS5; recall, wake and index commands need it |
index_unavailable, index_format |
The index file cannot be opened, or has another format (rebuild it) |
manifest_missing, manifest_invalid |
wake --exclude-nodes found no file, or not a v1 resolution manifest |
reserved_source_ref, source_refs_full |
A writer set the promoted-to reference kind that only promote writes; a record has no room for its promotion link |
akms_unavailable, review_required, review_below_threshold, scope_not_project, record_retracted, record_superseded, record_erased, schema_mismatch, record_sensitive, summary_unreviewed, summary_stale, imported_not_promotable, policy_drift, global_vault_target, already_promoted, node_not_updatable, node_exists, promote_locked, promote_graph_failed, promote_write_failed, node_not_loaded, promote_ledger_exhausted, projection_conflict, projection_source_changed, projection_source_mismatch, source_not_erased |
Promotion refusals |
failure_memory_config, failure_memory_registry |
The failure-memory config or registry cannot be read as documented; nothing was written |
internal_error |
An unexpected failure |
Authoring and review workflows¶
See Authoring, search and review for draft,
validate, review queue, review set, payload-only inputs, human-readable
show, and the search alias. JSON is still the default output.