The memory lifecycle

This guide explains Akno from the perspective of the people and agents using it: who may do what, when a change becomes memory, and what the dream cycle can do with it later.

The short version is:

The files are the memory. Akno reads and indexes them, agents may change only admitted parts, and maintenance must plan an exact change before anyone—or an autonomous curator—can authorize it.

The human and agent may use the same Akno service, but they are not interchangeable actors. MCP calls are agent calls. CLI writes also default to agent authority; --actor user is an explicit assertion that the person at the terminal is making that request. User authority bypasses the agent approval gate, not structural validation, safe paths, journalling, or re-indexing.

Akno has four kinds of state with different recovery rules:

An indexed fact, summary, embedding, or graph edge is not a second source of truth. It is valid only while its source locator and source hash still match the files.

An Akno write performs targeted structural reconciliation before it reports success. Expensive model derivation may finish afterward. A direct editor change is noticed by the running watcher; if no watcher is running, use akno index. Retrieval can therefore be temporarily degraded while optional derivation catches up, but the file is already authoritative.

Direct editing is the simplest and strongest authorship path. Save the file and the watcher re-indexes it. Akno does not require a special adoption or approval step for a valid existing page.

A direct edit is not recorded in Akno’s change journal. Use the editor, sync history, Git, or a backup to reverse it. Akno may still report that the edit invalidated a pending plan or changed the evidence behind an inferred fact.

Commands such as write, remember, retain, forget, move, ingest, and folder validate the request. When an operation is accepted, Akno uses guarded filesystem operations, records a change id, and reconciles the affected index. Use --actor user only when the request really is a human decision:

akno write --actor user --slug equipment/zephyr --append "The inspection is due in 2030."
akno remember --actor user "Ada Marlow extended the Zephyr QX-100 warranty to five years."

These writes are reversible with akno undo <change-id>. They are still constrained by safe paths and operation semantics; human authority is not an instruction to accept malformed input.

A human can inspect exact planned bytes without granting broad editor access to a model:

akno dream --mode audit
akno plan list
akno plan diff <plan-id> --item <item-id>

# When the configured profile permits human review:
akno dream --mode review
akno plan list --status awaiting_review
akno plan decide <plan-id> --item <item-id> --approve --reason "Matches the source."
akno plan apply <plan-id>

The command-line mode can lower configured authority but cannot raise it: an installation configured for audit must first be deliberately changed to review or autonomous authority. The decision and application remain separate. Between them, Akno checks that the plan, evidence, policy, and current files still match.

An agent can use memory without receiving general filesystem authority:

• context(profile: "auto_recall") supplies a small, precision-first pre-turn evidence bundle;
• recall discovers and ranks relevant evidence;
• answer produces and verifies a direct cited answer;
• read, timeline, and graph inspect known memory more precisely;
• remember extracts durable claims and finds an authorized destination;
• retain extracts or accepts typed memory from identified, replayable source revisions;
• exact mutation operations change only the requested and permitted scope.

The agent cannot promote itself to human through MCP. It also cannot turn a related search result into a writable destination. Search relevance and write authority are separate decisions. An MCP host exposes only the operations in its configured allow list; dream, plan, and service management are operator commands rather than ordinary memory tools. A host must separately and deliberately provide access if it wants an agent to operate them.

remember is not “append this prompt to the nearest page.” Its normal path is:

A successful retained item has a stable marker around the generated sentence. That marker is an ownership boundary: later maintenance may inspect and repair that item without acquiring authority over the human prose around it.

Both keyed retain and unkeyed remember reach the same owned-block writer and exact evidence validator. Keyed sources additionally keep durable replay receipts and may point at an existing source page/document, atomically archive inline input when explicitly requested, or replace exact earlier support. Full inline input is never stored implicitly. Its bounded exact frames remain private while live memory or nonterminal maintenance work needs them, then become eligible for secure pruning after evidence_grace_days.

When the marker carries typed world time, reads preserve the original precision, relation, status, timezone, and recurrence while computing currentness from the caller’s clock. This lets a past state remain inspectable without being injected as a current fact, and lets an accepted plan answer a future-oriented question without becoming a factual claim. An actor’s reported undertaking to act by a date remains a reported plan with its deadline and planned or scheduled time status; it does not become a completed event. An offer awaiting a decision is a proposed plan. Akno checks that distinction against the original source before retaining a generated plan.

The marker’s other semantics matter at read time too. Akno projects retained claims, reports, plans, decisions, questions, and tentative discussion into separate semantic views without moving or duplicating their Markdown. Generic agent recall stays factual. A prompt explicitly asking what was reported, planned, rejected, left open, or discussed selects that qualified form before retrieval; the returned sentence still carries its attribution, commitment, disposition, basis, and answer eligibility. If no in-view item matches, an out-of-view match may be shown as context, but it is not automatically injected or restated as true.

Possible results matter:

Only the first result means the knowledge base changed.

Immediate write-gate proposals are distinct from dream maintenance plans:

akno approve --list
akno approve <proposal-id>
akno decline <proposal-id>

Use akno plan ... only for the exact multi-stage maintenance workflow.

These are deliberately independent capabilities:

Folder rules can supply these choices for many pages; page frontmatter can make one page stricter or more specific. An opt-in only makes planning possible. Profile, transformation policy, evidence, model availability, budgets, stale-input checks, and verification can still refuse the change.

This is why reference notes can remain intact while still helping retrieval, and why allowing an agent to retain facts does not silently grant permission to rewrite the containing page.

Removing a marker is therefore the explicit way for a human to take a retained sentence out of managed-item maintenance without deleting the sentence itself. Adding remember: integrate, by contrast, admits future retained items; it does not transfer ownership of the page’s surrounding authored text.

Observation ownership is narrower still. observe: integrate admits only an akno:observation block for the page’s exact resolved subject. Removing that marker turns the remaining sentence into ordinary authored prose; changing or removing its support instead makes the projected L2 line ineligible until a planned lifecycle transition updates the marker.

A full dream is a maintenance transaction with visible stages, not an unrestricted rewrite prompt:

Conflict analysis runs before phases that infer or synthesize knowledge. Observe creates marker-owned L2 blocks on admitted exact-subject pages; reflect appends derived, cited L3 principles. Curate handles explicitly enabled page transformations and narrow owned-item maintenance. Adopt can organize searchable orphan documents. Housekeeping reports remaining structural work.

Per-transformation policy can lower that authority. For example, an autonomous installation may apply broken links automatically while keeping merges in human review.

Persisted dry-run diagnostics remain visible in history but do not replace a real full cycle in nightly schedule health. Use --mode audit for the durable, realistic no-write workflow.

Timing determines which guard handles it:

1. Before the planning snapshot: the new bytes are ordinary input to the cycle once indexed.
2. During full-cycle planning: watcher reconciliation waits behind the planner barrier. A foreground Akno mutation preempts the barrier and aborts the dream before decisions or writes.
3. After planning but before decision or apply: repeated preflight detects changed evidence or target bytes and marks affected items stale.
4. After unrelated maintenance writes: whole-run verification preserves the unrelated edit but refuses to certify the run as fully attributable.

Akno does not lock editors and does not provide an operating-system filesystem snapshot. There is necessarily a small race between a final check and an atomic rename, especially for direct editor or sync-client changes that bypass the service. For important knowledge bases, keep ordinary version control or backups and avoid editing the same page during the short apply portion of an autonomous cycle. See Limitations.

Start with the least private status surface and open exact details only when needed:

akno dream status
akno dream status --last 10
akno dream status --run <run-id>
akno dream status --pending
akno plan show <plan-id>
akno plan diff <plan-id>
akno undo --list

Default run receipts contain counts, policy, timing, model usage, typed degradation, verification, and change or plan ids—not page bodies, prompts, or source excerpts. Exact diffs are private and requested explicitly.

• Read-only exploration: use model-free or model-backed retrieval, keep remember destinations denied, and leave maintenance in audit.
• Human-curated memory: admit intended memory folders, use review mode, and inspect plan diffs before apply.
• Trusted agent-connected memory: admit narrow destinations, keep reference areas read-only, start with an audit cycle, then enable autonomous policies transformation by transformation.

Whichever style you choose, keep the same invariant: files stay readable and useful without Akno. For command details continue with Writing and ingestion; for the maintenance phases and safety mechanisms see The dream cycle; for implementation architecture see How Akno works.