Enum Commands 

pub enum Commands {
    Init(InitArgs),
    Remember(RememberArgs),
    RememberBatch(RememberBatchArgs),
    Ingest(Box<IngestArgs>),
    Recall(RecallArgs),
    Read(ReadArgs),
    List(ListArgs),
    Forget(ForgetArgs),
    Purge(PurgeArgs),
    Rename(RenameArgs),
    SplitBody(SplitBodyArgs),
    Edit(EditArgs),
    History(HistoryArgs),
    Restore(RestoreArgs),
    HybridSearch(HybridSearchArgs),
    Health(HealthArgs),
    Migrate(MigrateArgs),
    NamespaceDetect(NamespaceDetectArgs),
    Optimize(OptimizeArgs),
    Stats(StatsArgs),
    SyncSafeCopy(SyncSafeCopyArgs),
    Backup(BackupArgs),
    Vacuum(VacuumArgs),
    Link(LinkArgs),
    Unlink(UnlinkArgs),
    DeepResearch(DeepResearchArgs),
    Related(RelatedArgs),
    Graph(GraphArgs),
    Export(ExportArgs),
    Fts(FtsArgs),
    Vec(VecArgs),
    PruneRelations(PruneRelationsArgs),
    PruneNer(PruneNerArgs),
    Slots(SlotsArgs),
    Pending(PendingArgs),
    Embedding(EmbeddingArgs),
    PendingEmbeddings(PendingEmbeddingsArgs),
    CleanupOrphans(CleanupOrphansArgs),
    MemoryEntities(MemoryEntitiesArgs),
    Cache(CacheArgs),
    DeleteEntity(DeleteEntityArgs),
    Reclassify(ReclassifyArgs),
    RenameEntity(RenameEntityArgs),
    MergeEntities(MergeEntitiesArgs),
    Enrich(Box<EnrichArgs>),
    ReclassifyRelation(ReclassifyRelationArgs),
    NormalizeEntities(NormalizeEntitiesArgs),
    Completions(CompletionsArgs),
    Schema(SchemaArgs),
    DebugSchema(DebugSchemaArgs),
    Config(ConfigArgs),
}

Every subcommand the CLI dispatches, in the order --help renders them.

Variants

Init(InitArgs)

Initialize the database and write the schema (no model download, no subprocess)

Remember(RememberArgs)

Save a memory with optional entity graph

RememberBatch(RememberBatchArgs)

Batch-create memories from NDJSON stdin (one invocation, one slot)

Ingest(Box<IngestArgs>)

Bulk-ingest every file under a directory as separate memories (NDJSON output)

Recall(RecallArgs)

Search memories semantically

Read(ReadArgs)

Read a memory by exact name

List(ListArgs)

List memories with filters

Forget(ForgetArgs)

Soft-delete a memory

Purge(PurgeArgs)

Permanently delete soft-deleted memories

Rename(RenameArgs)

Rename a memory preserving history

SplitBody(SplitBodyArgs)

Split an oversized memory body into N child memories (v1.1.03, GAP-V8)

Edit(EditArgs)

Edit a memory’s body or description

History(HistoryArgs)

List all versions of a memory

Restore(RestoreArgs)

Restore a memory to a previous version

HybridSearch(HybridSearchArgs)

Search using hybrid vector + full-text search

Health(HealthArgs)

Show database health

Migrate(MigrateArgs)

Apply pending schema migrations

NamespaceDetect(NamespaceDetectArgs)

Resolve namespace precedence for the current invocation

Optimize(OptimizeArgs)

Run PRAGMA optimize on the database

Stats(StatsArgs)

Show database statistics

SyncSafeCopy(SyncSafeCopyArgs)

Create a checkpointed copy safe for file sync

Backup(BackupArgs)

Back up the database using the SQLite Online Backup API

Vacuum(VacuumArgs)

Run VACUUM after checkpointing the WAL

Link(LinkArgs)

Create an explicit relationship between two entities

Unlink(UnlinkArgs)

Remove a specific relationship between two entities

DeepResearch(DeepResearchArgs)

Deep parallel multi-hop GraphRAG research

Related(RelatedArgs)

List memories connected via the entity graph

Graph(GraphArgs)

Export a graph snapshot in json, dot or mermaid

Export(ExportArgs)

Export memories as NDJSON (one JSON line per memory, plus a summary line)

Fts(FtsArgs)

FTS5 full-text search index management (rebuild or check)

Vec(VecArgs)

Vector index maintenance (orphan detection, purge, stats) — G39

PruneRelations(PruneRelationsArgs)

Bulk-delete all relationships of a given type (e.g. mentions)

PruneNer(PruneNerArgs)

Remove NER bindings (memory_entities rows) for an entity or all entities

Slots(SlotsArgs)

Inspect and manage cross-process LLM slot semaphore (GAP-004, v1.0.82)

Pending(PendingArgs)

Inspect and manage the remember checkpoint queue (GAP-001, v1.0.82)

Embedding(EmbeddingArgs)

Health and per-entry inspection of the pending-embeddings queue (GAP-005, v1.0.82)

PendingEmbeddings(PendingEmbeddingsArgs)

Batch operations over the pending-embeddings queue (GAP-005, v1.0.82)

CleanupOrphans(CleanupOrphansArgs)

Remove entities that have no memories and no relationships

MemoryEntities(MemoryEntitiesArgs)

List entities linked to a specific memory

Cache(CacheArgs)

Manage cached resources (embedding models, etc.)

DeleteEntity(DeleteEntityArgs)

Delete an entity and all its relationships from the graph

Reclassify(ReclassifyArgs)

Reclassify one entity or a batch of entities to a new type

RenameEntity(RenameEntityArgs)

Rename an entity preserving all relationships and memory bindings

MergeEntities(MergeEntitiesArgs)

Merge multiple source entities into a single target entity

Enrich(Box<EnrichArgs>)

Enrich graph memories and entities using an LLM provider

ReclassifyRelation(ReclassifyRelationArgs)

Reclassify relationship types across the graph using rules or LLM judgment

NormalizeEntities(NormalizeEntitiesArgs)

Normalize entity names (deduplicate, kebab-case, merge near-duplicates)

Completions(CompletionsArgs)

Generate shell completions for Bash, Zsh, Fish, PowerShell, or Elvish

Schema(SchemaArgs)

List every shipped JSON Schema, or emit one by id (--name <ID>)

DebugSchema(DebugSchemaArgs)

debug-schema subcommand.

Config(ConfigArgs)

Manage API keys and diagnose provider configuration (v1.0.93)

Implementations

impl Commands

pub fn agent_surface_slug(&self) -> Option<&'static str>

Names the subcommand for crate::agent_surface alias suppression.

The suppression table used to match on the KEY alone, so results meant the same thing everywhere. It does not: in recall, results really is the concatenation of direct_matches and graph_matches, so dropping the halves loses nothing. In hybrid-search the two arrays are DISJOINT by construction — the graph expansion skips every id already fused — and they do not even hold the same type. Suppressing there deleted unique rows and then labelled them redundant, which is worse than losing them silently: the envelope asserted the removal was safe.

None for every subcommand that declares no alias, which makes the default fail-safe: a new command is never suppressed until someone adds it to the table deliberately.

pub fn mutates(&self) -> bool

true when this subcommand can change durable state.

GAP-SG-205 reads it to decide whether the target database may be inherited from ambient configuration; crate::agent_surface::gate reads it to decide whether a refusal is still safe.

The refusal question is the sharper one. The agent-native surface runs at OUTPUT time, after the handler has already done its work, so refusing there would hand the caller a non-zero exit for an operation that succeeded — and a caller that retries a succeeded remember writes the memory twice. The gate therefore stays silent on anything this reports as mutating.

Read-only variants are listed EXPLICITLY and everything else answers true. The default has to be the conservative one: a subcommand added later and forgotten here loses a refusal it might have wanted, which costs a diagnostic, while the opposite default would let the gate fire after an unlisted write, which costs data.

pub fn may_inherit_target(&self) -> bool

Whether this subcommand may resolve its target from ambient configuration.

GAP-SG-207. Self::mutates answers “does this change durable state”; this answers “is naming the target nonetheless optional for THIS invocation”. The two differ, and reusing mutates alone would have been a defect: it lists the read-only variants explicitly and answers true for everything else, which is the right conservative default for the output-time refusal fence and the WRONG one here. For the fence a mistaken true costs a diagnostic; here it would cost a false refusal on a command that has no side effect to protect — fts check, vec stats, pending list and embedding status all read and write nothing.

So the families whose subcommands split between reading and writing are classified at the SUBCOMMAND level. The Explicit Target Designation rule governs side effects, and a read inherits no authority it could misuse.

Enforcement lives in crate::paths::AppPaths::resolve. That placement keeps this list short: a subcommand that never resolves a database — config, completions, locale, slots, cache — is exempt by construction and needs no entry here at all.

pub fn is_embedding_heavy(&self) -> bool

Returns true for subcommands that load the ONNX model locally.

pub fn uses_cli_slot(&self) -> bool

Return whether this command occupies a CLI concurrency slot.

pub fn tolerates_missing_embedding_key(&self) -> bool

Read-only / no-embedding subcommands that MUST run without an embedding API key. init warms a best-effort smoke test internally and degrades to ok_no_embedding when the backend is unreachable; the enrich queue inspectors (--status / --list-dead / --requeue-dead / --prune-dead-orphans) never embed and never call the LLM. The eager OpenRouter key preflight in main must skip its hard-fail for these.

Trait Implementations

impl Debug for Commands

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for Commands

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for Commands

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand