/cao-memory

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.

For native memory, forgetting removes the CAO-managed topic file. For vault-backed memory, it removes CAO's derived index entry and leaves the vault note in place for the operator to edit or delete in Obsidian. The `memory_forget` result's `action` is authoritative; its legacy `deleted` boolean means CAO completed the forget operation, not that the vault file was removed. Inspect `path` when the action reports vault deindexing.

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

1. **Recall before asking.** The answer may already be stored. 2. **Store the instant you learn something durable** — corrections, conventions, preferences, constraints. 3. **One fact per memory, 1–2 sentences.** Conclusions, not conversation. 4. **Pick the right scope:** user-wide → `global`; this repo → `project`.