Memories

Memories let a new Task recall useful context from earlier work. They are optional user-owned context—not instructions, policy, or a substitute for repository files such as AGENTS.md. Reading, contribution, and learning from external tool context are all off by default.

Choose the policy for new Tasks

Open Settings → Advanced → Memory & learning. The three controls are independent:

Control	What it permits
Use memories in new tasks	Read relevant entries from the configured primary memory store.
Contribute new tasks to memories	Extract and save useful context from eligible completed Tasks.
Learn from tool-assisted tasks	Off by default. When contribution is on, explicitly admit Tasks that used Browser, MCP, web search, or other tool results.

The choices are stored by the Java Host for the authenticated owner and frozen when a Task is created. Changing a default does not silently change the consent boundary of an existing Task. An upgrade also resets the former implicit external-context default once, so it must be explicitly enabled again. You can therefore contribute without recall, recall without contributing, enable both, or keep both off.

The browser is only a projection: it cannot create consent from local storage or override the Host by crafting Task-creation flags. Multiple devices update the same owner-scoped defaults with a revision check, so a stale screen cannot silently overwrite a newer choice. A different login or paired identity receives an independent, initially disabled record. If the consent authority is unavailable, the controls become unavailable and Task creation fails closed instead of guessing.

Put durable rules in the repository

Use memories for preferences and reusable context. Put required commands, architecture rules, security constraints, and review policy in AGENTS.md or another versioned project document.

Why owner isolation exists

Memory may contain personal preferences, repository decisions, or context learned from earlier Tasks. Kairo therefore binds consent, recall, management cursors, edits, and deletion receipts to one credential identity instead of treating a shared local database as globally readable.

This boundary prevents a login, API token, paired device, Task fork, handoff, or Subagent from silently crossing into another identity's saved context. A permitted child receives only a read-only view of its parent's owner scope. This is not a multi-tenant SaaS claim: one Kairo Code Host is for one operator, and separate people should use separate Hosts.

What happens during recall

For a Task that enables memory use, Kairo captures the current direct user intent once per request (at most 4,096 complete Unicode code points) and asks the one configured primary store for candidates. The same snapshot is reused across that request's model/tool iterations. The result is ranked and bounded before it enters model context. Tool output, system instructions, prior history, attachments, Browser content, and another user's memory collection are not used as the recall query.

Every candidate is revalidated at recall time. Only a direct user save, a model extraction backed by one verbatim user statement, or an owner-consented structured Memory write may enter model context. Unknown, legacy, automatic, and source/authority-mismatched records remain visible in the manager so that you can inspect or delete them, but Kairo does not silently inject them. Recall also enforces deterministic item, UTF-8 byte, conservative token-unit, age, and namespace bounds; credentials are redacted and stored text is delimited as untrusted evidence rather than instructions.

Task context compaction is separate from long-term memory: compacting a long conversation does not save its transcript or tool output as a memory. A child assignment is not used as an automatic recall query. When the parent Task opted into memory use and the child Profile permits memory_read, the child may explicitly query the same owner-scoped collection through a write-rejecting view. Children never receive memory_write, never run memory extraction, and receive no Memory tools when the parent did not opt into reading. The built-in explorer Profile also removes memory_read through its final tool ceiling.

Recall is assistive. A returned memory may be stale or irrelevant, so the Agent must still inspect the current repository and obey current project policy.

Review and manage saved memories

Open Settings → Advanced → Memory & learning → Manage saved memories to:

• search the current scope;
• load older entries page by page without a fixed collection-size cutoff;
• add a memory directly;
• see whether an entry was added by you, saved by an Agent, or extracted by a rule/model hook;
• edit the retained text; or
• delete the entry and inspect its durable deletion receipt.

The Kairo scope contains context for the Kairo Code Agent. The Personal scope contains user-level context. Both remain inside the current credential identity's ownership boundary. A Host admits one password account; its local identity, password login, API token, and paired devices still receive separate memory namespaces so crossing a sign-in or pairing boundary cannot silently reuse saved context. Raw login names, OAuth subjects, and bearer tokens are never used as memory paths or metadata. These credentials belong to one operator, not separate tenants; use separate Hosts for separate people.

The manager keeps each continuation bound to the signed-in owner, selected scope, and exact search. Changing the scope or search starts a new list. If the Host restarts or the collection cursor is no longer valid, Kairo shows an explicit reload action instead of silently returning the first page.

Understand deletion receipts

Deletion is not reported as complete merely because an API call returned. The manager shows the authoritative outcome:

Receipt state	Meaning
Verified	The entry is absent from Kairo's authoritative primary.
External unverified	Kairo removed its primary view, but a custom provider could not prove deletion of every external copy.
Pending / interrupted	Do not assume deletion completed; retry or diagnose the primary.
Incomplete	A provider step failed and the durable receipt remains available for investigation.

Receipts contain identifiers and status, not the deleted memory text.

Storage and availability

Kairo uses exactly one Java-authoritative primary for recall, writes, extraction, management, and deletion. The default is the local file store under the Kairo Code data directory; an administrator can select JDBC or an explicitly configured custom provider. Settings → Advanced → Memory & learning shows the backend class, durability, sharing scope, and health without revealing paths or credentials.

If the configured primary is unhealthy, memory becomes unavailable. Kairo does not silently split reads and writes into a fallback store. Automatic extraction is durable background work: temporary provider throttling defers an eligible job instead of creating a request storm or blocking the completed Task.

The default file primary serializes validated reads and mutations across cooperating processes that share the same real directory, using a JVM lock plus a crash-released operating-system file lock. It does not claim a crash-atomic transaction across several physical files, and that coordination does not make Kairo Code horizontally deployable. Management cursors and other Host authorities remain instance-owned, so the supported release topology is still one Host process. Use a transaction-capable JDBC primary when Memory itself must live in a database; do not treat the file lock as a multi-Host deployment contract.

Privacy checklist

Before enabling contribution:

1. Decide whether the Task contains information worth reusing later.
2. Leave Learn from tool-assisted tasks off when Browser or external tool results should never become a memory source.
3. Review recent memory activity in the Activity inbox.
4. Periodically inspect both scopes and remove stale entries.
5. Keep secrets out of prompts and repository text even when memory contribution is disabled; model and tool boundaries have their own data policies.