Command reference

This table answers three questions: which command matches the user’s intent, whether it can change their knowledge base, and which model roles may be involved.

Add --help to any command for its current flags and examples:

akno --help
akno recall --help
akno dream --help

Commands that support machine-readable output accept --json.

When a command resolves an explicit memory or state directory, a running service must identify the same knowledge-base path in its handshake. Akno refuses a mismatched service instead of operating on the memory behind the default socket; pair --akno-path with that memory’s --state-dir when connecting.

• Use recall when you want ranked evidence results or intend to synthesize with another model.
• Use answer when you want Akno to answer a memory question and verify its support.
• Use read when you already know the exact slug or document id.
• Use graph when the relationship path matters more than page content.
• Use list --kind timelines to discover folder-owned timelines.
• Use timeline --timeline work/timeline for one chronology, or --timeline '*' to combine all. Without a selector, the root timeline excludes inner timelines. --migration-preview reports legacy entries needing review without editing them.
• Use timeline when time is the primary filter. Its clock is explicit in the result; --view actionable narrows active or accepted scheduled work without hiding history from the default view.
• Use context --profile auto_recall from an agent host before a substantive turn with no explicit memory question. Its activation receipt reports whether a local reference was resolved, ambiguous, or unresolved; the latter two inject no evidence.
• recall, answer, graph, and query-backed context accept --memory-view factual|history|planning|reports|questions|discussion|all. Omit it for conservative query inference; an explicit value always wins. This is independent of recall --mode and timeline --view.

See Reading memory for ranking, qualification, citations, and result-state details.

• Use write when destination and wording are already known.
• Use remember when Akno must decide what is durable and where it belongs.
• Use retain when a host has a stable source id and revision. Extract mode interprets and independently verifies coherent source context before automatic placement; provided mode accepts typed candidates with either exact or automatic placement. Input may be inline text/items or an indexed source page/document. Inline input may explicitly archive one source + remember: deny page in the same source-scoped change, and retracts can replace exact prior support atomically. Every mode validates byte-exact source spans, preserves discourse and attribution, suppresses identical revision replays, and retracts only explicitly addressed source support.
• A source receipt with retryable: true failed during extraction before producing candidates or writes. Replay normally to reconcile an uncertain socket result; send retry_failed: true only when explicitly retrying that exact source and revision. Semantic holds, corrections, and confirmed support are never retried this way. Changed source bytes or processing instructions still produce revision_conflict.
• Treat no_writable_destination as an authorization hold, not an empty memory result: inspect the typed approval reason and name or admit a destination. requires_folder instead asks the caller to declare taxonomy.
• maintenance.retain.fallback_page can provide one exact last-resort destination. It is used only after ordinary routing and managed-page creation fail, and only when page or folder policy independently admits it. akno doctor reports whether the configured fallback is ready. Managed-item curation treats it as a queue and never certifies an item there as correctly placed.
• Use ingest for a file, folder, or URL; use inbox for configured drop folders.
• URL ingest accepts only HTTP(S), resolves every address, rejects non-public destinations, pins the request to a validated address, and repeats the policy for redirects. ingest.trusted_url_origins is an exact scheme/host/port opt-in for a known internal service; it has no path or wildcard form.
• Use forget for a deliberate retraction and undo when reversing a known Akno change. forget --memory <id> addresses any sealed managed item, including one that has no derived fact.
• Use plan for maintenance decisions. approve and decline are for held remember/ingest routing proposals, not dream-plan items.
• Use plan revise when the proposed destination and transformation are right but the exact result is not. It creates a guarded immutable revision inside the existing path/evidence scope and invalidates approval; it does not edit the knowledge base by itself.
• Run migrate --dry-run before migrate when an upgrade introduces a new owned memory-marker grammar. Use migrate --observations --dry-run followed by migrate --observations for legacy detached observation lines. Both modes are operator-only, journalled, undoable, and never run as an indexing side effect.

See Writing and ingestion and The dream cycle.

The CLI names correspond to operations in the shared protocol registry. Agent hosts should discover schemas from MCP or use the typed client rather than constructing CLI arguments. Some operator-only surfaces—service management, journal listing, plan decisions, and broad private diagnostics—are intentionally not granted to an agent merely because it can call memory.