| name | cao-memory |
| description | Store, recall, and forget durable facts with CAO memory — user preferences, project conventions, decisions, and corrections that should persist across sessions and agents. Use proactively to check memory before asking the user, and to save anything worth remembering. Distinct from any provider-native memory. |
CAO Memory
CAO gives every agent a shared, persistent memory. A fact you store in one session is
available to a brand-new agent in a later session — even on a different provider. Use it so
the user never has to repeat themselves.
These are CAO's cross-provider memory tools (memory_store, memory_recall,
memory_forget), exposed by the CAO MCP server. They are distinct from any
provider-native memory the CLI tool may have.
Scopes and types
Every memory has a scope (where it applies) and a type (what kind of fact it is).
| Scope | Applies to | Use for |
|---|
project (default) | This repo / working directory | Conventions, architecture, build rules |
global | Every project | User identity, durable cross-project preferences |
federated | Every project on this machine | Reusable, repo-independent lessons worth sharing across all your work (rejects credentials) |
session | This run only | Short-lived task context |
agent | This agent role | Role-specific working notes |
Types: project (default), user (who the user is / preferences), feedback
(corrections and how-to-work guidance), reference (pointers to docs, tickets, URLs).
Recall — check memory BEFORE asking the user
At the start of a task, and whenever you're about to ask the user something they may have
already told you, search memory first.
memory_recall(query="database widgets endpoint testing")
Omit scope to search all scopes (results follow precedence session → project → global → agent → federated).
Filter with scope= or memory_type= when you know where to look. Recall is for searching
beyond what was auto-injected (see below) — don't re-recall what's already in front of you.
Store — save anything worth remembering, immediately
Store the moment you learn something durable. Don't wait until the end of the session.
Store conclusions, not transcript. Keep each memory to 1–2 sentences.
Store when you hit any of these:
- A correction — "No, we use DynamoDB here, not SQL." → store it so no agent makes that
mistake again.
- A decided convention — "Every endpoint must have a pytest test before merge."
- A user preference — how they like work done, tools they prefer.
- A non-obvious project constraint — something you couldn't infer from the code.
memory_store(
content="Use DynamoDB for widgets-api; never SQL.",
scope="project",
memory_type="project",
key="widgets-database", # optional; auto-slugged from content if omitted
)
Same key + scope upserts (updates in place) rather than duplicating.
Share across all your projects — scope="federated"
When a lesson is durable and not specific to this repo — a reusable library gotcha, a
debugging trick, a tooling preference that holds everywhere — store it with
scope="federated" so it follows you into every project on this machine, not just this one.
memory_store(
content="tmux paste-buffer needs `-p` or multi-line input loses bracketed-paste framing.",
scope="federated",
memory_type="reference",
)
Federated memories sit at the lowest recall precedence — a project-local fact with the
same key always wins — so federating is safe: it only adds a fallback, never overrides what's
true here. To un-share, memory_forget(key=..., scope="federated").
- Never federate secrets. Tokens, keys, and passwords are rejected automatically on a
federated write — and they'd be exposed to every project anyway. Keep credentials out of
memory entirely.
- When in doubt, use
project. Federate only what you're confident is reusable everywhere.
Forget — remove what's wrong or superseded
memory_forget(key="widgets-database", scope="project")
Use this when a stored fact becomes outdated or was wrong. Prefer correcting (re-store with
the same key) over leaving stale facts in memory.
Auto-injection (already happening)
On launch, CAO writes the most relevant memories for this working directory into the file
your CLI reads on startup (Claude Code: .claude/CLAUDE.md; Codex: AGENTS.md; Kiro:
.kiro/steering/cao-memory.md). So you usually begin a task already knowing the project's
key facts — memory_recall is for digging up anything that wasn't injected.
Habits
- Recall before asking. The answer may already be stored.
- Store the instant you learn something durable — corrections, conventions,
preferences, constraints.
- One fact per memory, 1–2 sentences. Conclusions, not conversation.
- Pick the right scope: user-wide →
global; this repo → project.
