---
name: CAO Memory
slug: cao-memory
category: AI Engineering
description: CAO Memory stores, recalls, and forgets durable facts across sessions and providers. Use it to save preferences, project conventions, corrections, and other details the user should not have to repeat.
github: "https://github.com/awslabs/cli-agent-orchestrator/tree/main/skills/cao-memory"
language: Python
stars: 1087
forks: 226
install: "npx degit https://github.com/awslabs/cli-agent-orchestrator/tree/main/skills/cao-memory ~/.claude/skills/cao-memory"
installs_to: ~/.claude/skills/cao-memory
source_path: skills/cao-memory/SKILL.md
collection_size: 18
category_size: 2451
collection_url: "https://dirskills.com/collections/awslabs/cli-agent-orchestrator"
added: 2026-08-21T05:13:17.014Z
last_synced: 2026-08-21T05:13:17.014Z
canonical_url: "https://dirskills.com/skills/cao-memory"
---

# CAO Memory

CAO Memory stores, recalls, and forgets durable facts across sessions and providers. Use it to save preferences, project conventions, corrections, and other details the user should not have to repeat.

**Install:**

```bash
npx degit https://github.com/awslabs/cli-agent-orchestrator/tree/main/skills/cao-memory ~/.claude/skills/cao-memory
```

## README

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