Operations

Akno can run for one command at a time or as a long-lived macOS or Linux user service. The service is the normal agent integration: it keeps the index warm, watches the knowledge base, owns the single write handle, and exposes the same operation registry through several transports.

akno index
akno recall "Zephyr QX-100 warranty"

Without a service, most CLI commands open Akno in the current process. With a service, commands that need the writer are forwarded to it. --connect requires a live service and disables the in-process fallback.

Akno verifies the service handshake against the resolved knowledge-base path before forwarding anything. A command with --akno-path, --state-dir, AKNO_CONFIG, AKNO_PATH, or AKNO_STATE_DIR therefore cannot silently use a conventional socket owned by another memory. If the requested memory has its own service, pass the matching state directory; otherwise stop that service or let the command run in process. An invalid explicit config remains a configuration error even when another Akno service is available.

For foreground integrations:

akno serve
akno serve --mcp
akno serve --http 127.0.0.1:7777

• The Unix socket is the default local door. Owner-only filesystem permissions are its authentication.
• MCP is a stdio adapter for agent hosts. server.mcp_allow controls which operations the agent receives, including when the adapter forwards through an already-running service. --allow can narrow that policy; it cannot widen it.
• HTTP is for a containerized or remote agent that cannot open the host socket. Unauthenticated loopback callers receive only server.http_public_allow, which may narrow but cannot widen the read-only public surface. A non-loopback bind requires at least one resolved bearer identity in server.http_access; each credential owns its actor and allowlist.

For authenticated HTTP, keep the credential in the environment and only name it in config:

{
  "server": {
    "http": "0.0.0.0:7777",
    "http_access": [
      {
        "name": "vulpine-agent",
        "token": { "env": "AKNO_HTTP_AGENT_TOKEN" },
        "actor": "agent",
        "allow": ["recall", "answer", "read"],
      },
    ],
  },
}

The typed client passes that credential with connect({ http, token }). HTTP rejects x-akno-actor and client actor overrides, because identity is assigned by the server credential. The built-in listener is plain HTTP; put a non-loopback deployment behind a trusted tunnel or TLS reverse proxy so the bearer token is encrypted in transit, and restrict access from that proxy to Akno.

akno service install --no-dream
akno service install
akno service install --dream-hour 2
akno service status
akno service uninstall

service install writes background user-service definitions:

On macOS these are launchd agents. On Linux they are systemd user service/timer units under $XDG_CONFIG_HOME/systemd/user (or ~/.config/systemd/user). Installation reloads the user manager, enables the nightly timers, starts or restarts the main service, and waits until its socket accepts connections. --no-dream disables and removes any previously installed timers. The generated commands retain explicit --akno-path and --state-dir targets.

The scheduled command resolves maintenance.profile and policies at run time. Changing authority therefore does not require reinstalling the schedule. Re-run installation after an Akno upgrade when release notes say the launchd or systemd definition changed.

On macOS the dream agent runs both at its calendar time and when launchd loads it. The internal --scheduled --if-due guard starts work only when the current expected window has no full-cycle receipt, so a login or reboot after 03:00 catches up without duplicating an on-time, running, or already-failed attempt. Linux systemd timers use Persistent=true for the equivalent catch-up. This is one nightly window, not a retry queue: a recorded failed attempt remains visible for review and is not silently rerun.

During the initial planner wave, the service holds one index revision. Watcher and explicit index passes that reach the shared indexer are queued, not discarded, then drained before curator decisions and apply. Filesystem edits themselves remain available and are handled by stale-input and whole-tree verification after the barrier. A foreground memory mutation instead takes priority: its structural index completes immediately, invalidates the planner revision, and makes the dream stop before curator decisions or writes. Post-response model derivation may finish later without delaying the foreground result.

service uninstall stops and removes Akno’s launchd or systemd user definitions, then reloads the relevant user manager. It does not remove the knowledge base or state directory.

akno dream status
akno dream status --last 10
akno dream status --run <run-id>
akno dream status --pending
akno plan list --status awaiting_review
akno plan prune

Status includes the next expected schedule, recent durable runs, policy, typed model degradation, decisions, item verification, final run verification, and budget use. Final verification rechecks each path’s last applied sealed disk/index outcome, surviving paths of earlier managed-item repairs, budget and model accounting, and the complete indexable knowledge-base diff. An unrelated concurrent add, edit, or removal is preserved but fails certification as an aggregate unattributed_file_change; paths never enter the run receipt. Inspect exact private planned changes only with akno plan diff <plan-id>.

Schedule health and launch-time catch-up use the latest non-dry-run full cycle. A later --dry-run remains visible in run history but cannot replace a healthy nightly result with a diagnostic failure. Use --mode audit when you want a durable, realistic no-write maintenance cycle that does count as a full attempt.

If a newer run makes queued work obsolete, retire the old plan without touching the knowledge base:

akno plan supersede <plan-id> --reason "Replaced by a newer review."

Only work that has not begun applying can be superseded. Interrupted apply and verification states stay in the queue so recovery cannot be hidden as cleanup.

For an automated review client, make response-loss retries explicit:

akno plan decide <plan-id> --item <item-id> --approve \
  --idempotency-key review:PLAN_ID:ITEM_ID:approve
akno plan apply <plan-id> --idempotency-key apply:PLAN_ID

The key is bound to the exact request and survives service restarts. An exact retry is a no-op; reuse for a different decision or action is rejected as a conflict. Completed apply retries report replayed: true and no new file changes.

akno plan prune is a content-safe preview of the configured two-stage retention boundary, including exact private bytes eligible for removal. Add --apply for an immediate manual pass. Every writable dream run also enforces the same policy: terminal exact operations/evidence expire before compact audit receipts, while active or recovery-relevant plans are retained without an age limit. This state cleanup never touches Markdown or the separate change journal.

Writable dream runs also enforce retained-source evidence lifetime. Exact private frames from active support are never age-pruned. After a retraction or explicit forget, a frame becomes eligible only when the configured grace has elapsed and no nonterminal maintenance item names its managed memory. Cleanup securely removes the quote and checkpoints the local database while preserving replay hashes, compact receipts, and page/document source bindings. Dream output reports only counts and removed byte totals.

Local notifications are off by default:

{
  "maintenance": { "notifications": "actionable" },
}

actionable reports review backlog, failures, incomplete verification, exhausted budgets, repeated typed degradation, and missed schedules. all also reports healthy scheduled completion. macOS uses a local user notification; Linux writes to the local system log with logger, which is suitable for headless servers and journald-backed systems. If that command is absent, delivery reports a typed backend_missing outcome rather than silently succeeding. Notifications contain counts, states, timestamps, and run ids—not note text, paths, diffs, prompts, model output, or provider errors.

Run these before changing configuration or deleting state:

akno doctor
akno doctor --no-probe
akno doctor --no-probe --admission-preview
akno doctor --no-probe --quarantine-details
akno doctor --refresh-api
akno config
akno rules
akno rules products/zephyr-qx-100.md
akno service status

doctor reports:

• knowledge-base and state locations;
• whether this process can acquire the writer;
• page, chunk, fact, event, document, and broken-link counts;
• admitted, explicit read-only, and implicit read-only fact-injection counts; the opt-in admission preview adds top-level folder globs and authority-preserving remember: deny patches without page identities or content;
• content-safe Markdown quarantine counts by reason; --quarantine-details explicitly adds private relative paths and known stable ids, but never source bodies;
• storage-only lookup latency;
• model-role availability, schema probes, latency, and the cost of each missing role;
• extraction support; and
• reserved-path collisions.

Probe failures are operational evidence, not a reason to erase the index. Use --no-probe for an immediate configuration-and-index report without network model calls. --refresh-api ignores cached api: auto selections and repeats only the invented transport probes; it cannot be combined with --no-probe. Repairing the source files and running akno index is the complete Markdown-quarantine resolution path; there is no second conflict workflow to approve or synchronize.

config shows every loaded source and the resolved configuration. API keys, authorization headers, passwords, tokens, and similarly named future secret fields are redacted recursively. rules explains effective path and maintenance policy, including why a transformation is off, audit-only, reviewable, or potentially automatic.

The default installed state lives under ~/.akno on macOS and $XDG_STATE_HOME/akno on Linux (with the XDG fallback ~/.local/state/akno); state_dir can move it. Its important contents are:

<state_dir>/
  akno.db       derived index, journal, gates, plans, and run receipts
  akno.sock     local service socket on macOS, Linux fallback, or an explicit state_dir
  akno.lock     current writer metadata
  provider-capabilities.json  content-free api:auto selections
  trash/        recoverable forgotten files
  logs/         service and scheduled-cycle logs

Recovery depends on what is wrong:

Do not delete akno.db merely to refresh search: it also contains undo history, gated writes, retained-source receipts, maintenance plans, recovery state, and run receipts. akno index --rebuild re-hashes every file and recomputes reproducible page, chunk, embedding, derivation, and graph projections in place. It is safe through the running service and preserves every durable record.

Database schema upgrades and new read projections are automatic and never rewrite Markdown. The intent-aware memory upgrade adds derived semantic rows and changes chunk boundaries around managed items, so its first full index pass re-reads pages and refreshes affected embeddings and graph edges. akno migrate is not needed unless the release notes separately name a Markdown marker migration.

Akno’s trash and journal are not backups. Keep the Markdown knowledge base under normal backup or version control.

akno dream status reports durable recovery state separately from configured authority. Akno pauses the whole automatic profile when final verification cannot prove its live bytes, sealed plan, or journal receipt. Three distinct automatically rolled-back items of one transformation pause only that class; unrelated maintenance continues. A verified later attempt clears a pre-threshold streak, but a pause never silently clears itself.

After inspecting the referenced run and private plan details, resume explicitly:

akno dream resume --profile
akno dream resume --transform merge

Resume clears the selected safety state; it does not alter configuration, approve a plan, or apply anything. Audit and review runs remain available while the autonomous profile is paused. Transient request retries stay bounded inside the model client, while ordinary nightly cadence supplies the later retry for model outages and fresh run budgets—Akno does not create a hidden multi-day retry schedule.

pnpm typecheck
pnpm lint
pnpm test
pnpm akno redeploy

redeploy builds packages, continues in a fresh CLI process, restarts the launchd or systemd user service, and waits until the replacement socket is ready. It uses a 30-second fast readiness window and, when the platform service manager confirms that the replacement is still running, a bounded three-minute live-handoff window. --timeout <seconds> replaces both with an explicit hard deadline. Building matters: the service imports the compiled core package, and hosts import compiled core or client packages, so restarting without a build can silently keep old behavior. The fresh process ensures the restart itself resolves config and package exports from the artifacts that were just built.

Use pnpm akno redeploy --no-restart for a checkout without an installed service, or --no-build only when no compiled package changed.

Akno sends only the content needed by an invoked model role to the configured endpoint. A lexical-only setup sends nothing to a model. doctor uses invented probe text; opt-in live benchmarks use their own invented corpora rather than the configured knowledge base.

Operational output is content-safe by default. Commands that deliberately display memory—such as recall, read, answer, and plan diff—are private-content surfaces and should not be copied into public logs or bug reports without inspection.

The owner controls both the files and service. Akno currently has no per-user authorization, tenancy, or untrusted collaborative-write model.

Akno’s core and CLI packages support macOS and Linux with Node 22.18 or newer. The protocol and client packages remain portable and do not carry Akno’s native index dependencies. Windows is not a supported core/CLI runtime.

If XDG_RUNTIME_DIR is absent or not absolute, the Linux socket falls back to the private XDG state directory. The corresponding state fallback is ~/.local/state/akno, and the config fallback is ~/.config/akno.

On Debian or Ubuntu, install the complete Linux extraction toolchain with:

sudo apt-get install poppler-utils tesseract-ocr libreoffice-writer

The tools are discovered independently. Missing LibreOffice affects supported office files; missing Tesseract affects image and scanned-PDF OCR; missing Poppler affects PDF extraction. doctor reports the selected backend and each command, while ingestion returns typed missing-dependency or partial-extraction degradation instead of claiming that the document was fully read. A systemd user manager is required only for akno service; foreground and in-process operation do not depend on it.