cao-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

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`.