Give your AI agents a shared memory that survives every session

---
name: shared-agent-memory
description: Give AI agents a shared memory that survives every session — a version-controlled, file-based brain agents read at session start and write at session end, so knowledge compounds instead of resetting. Use when running agents repeatedly on the same project, especially more than one agent.
---

# Set up a shared brain for a user's agents

You are giving a developer's AI agents a durable, file-based shared memory in their
own repo. Implement it here, adapting to their setup. No database, no vector store —
plain markdown in version control plus a read/write protocol.

## Detect their setup

Which agent(s) they use (Claude Code, Cursor, etc.) and where each reads its
standing instructions (e.g. `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, a rules dir).
Whether they have a repo to hold the brain (use it) or need one. Whether they run
multiple agents (raises the value of one shared brain).

## Build this

1. **Pick the brain's home** — a version-controlled repo (or a `memory/` + docs
   tree inside their existing one). Git so history is a free audit log.

2. **Create the four homes, separated by how knowledge changes:**
   - durable knowledge / preferences (one fact per file)
   - current status (overwritten, not appended)
   - decisions (append-only, with the why)
   - time-bound plans (dated, lifecycle draft→active→done→archived)

3. **Memory file schema** — each durable memory is a small file with frontmatter:
   `name` (stable slug), `description` (one line, used to judge relevance on
   recall), `type`. Body = the one fact, linking related memories with
   `[[other-name]]`. See `reference/memory-file.example.md`.

4. **The index** — one file listing one line per memory (`- [title](file.md) —
   hook`) so an agent scans what exists before loading bodies. See
   `reference/MEMORY.index.example.md`.

5. **Write the read/write protocol into their agent's rules file** — the crucial
   step. At session start: read the index + relevant files. At session end: write
   back what changed. Adapt `reference/AGENTS.md` into their `CLAUDE.md` /
   `.cursorrules` / rules dir. Without this the brain is a folder nobody opens.

6. **Add the "artifacts over chat" habit** — results that matter get filed, not
   left in a conversation. And the "don't store the derivable" rule — nothing that
   restates the code, git history, or a ticket.

7. **Set up the pulse** — a periodic curation pass (a scheduled task, or a
   dedicated curator agent role) that merges duplicates, fixes stale facts against
   reality, prunes, and keeps files small + the index honest.

## Guardrails to enforce

- The read AND write halves both go in the rules file — a read-only brain stops
  compounding.
- One fact per file + an index. Never one monolithic memory file.
- Recalled memory is a lead to verify, not ground truth — instruct the agent to
  check anything that names a file/flag/function against live code before asserting.
- Store only the non-obvious; skip anything derivable from the repo.

## Verify before done

Open a fresh session and confirm the agent reads the index unprompted, can answer
a project question from memory alone, and writes a new/updated memory at session
end. Confirm two memories don't duplicate the same fact.

## Read alongside

`RECIPE.md` (the why + receipts) and `reference/` (protocol + schema to adapt).

<!-- Reference: the read/write protocol. Adapt into the agent's own standing
     instructions file (CLAUDE.md, AGENTS.md, .cursorrules, or a rules dir).
     This is the piece that makes the brain live — without it, the folder is
     never opened. -->

# Shared brain protocol

This repo is the shared brain. Read from it at session start; write back at
session end.

## At session start
1. Read `MEMORY.md` — the index. One line per memory; scan for what's relevant.
2. Read the current-status file for what exists / is live / is in flight.
3. Read the specific memory files, decisions, or plans the task touches.

## At session end (write back what changed)
| If you… | Write to… |
|---|---|
| Learned a durable fact or preference | a new one-fact memory file + a line in `MEMORY.md` |
| Changed what's live / shipped / in flight | the current-status file (overwrite to current state) |
| Made a settled decision | append it to the decisions log, with the why |
| Started time-bound work | a dated plan file (status: draft/active) |

## Rules
- **One fact per memory file**, with frontmatter (`name`, `description`, `type`).
  Link related memories with `[[name]]`.
- **Current state, not history** in status files — the git log holds the past.
- **Artifacts over chat** — file what's meant to compound; don't leave it only in
  a reply.
- **Don't store the derivable** — nothing recoverable from the code, git history,
  or a ticket. Store the non-obvious.
- **Recalled memory is point-in-time** — before acting on a memory that names a
  file, flag, or function, verify it against the live code.
- Before saving, check for an existing memory that already covers it — update that
  file rather than create a duplicate.

<!-- Reference: one durable memory = one small file with this frontmatter.
     `description` is what an agent reads to judge relevance before loading the body. -->
---
name: deploy-target-is-staging
description: App pushes go to the staging environment, which is what real users hit
type: reference        # user | preference | project | decision | reference
---

App builds are pushed to the **staging** environment, not a separate prod — staging
is what real users are on. Verify the target before any release.

Related: [[release-checklist]], [[no-direct-prod-deploys]]

<!-- Notes on the fields:
     name        — stable kebab-case slug; also the link target for [[name]]
     description — ONE line; the recall filter, so make it specific
     type        — the four homes: durable knowledge (user/preference/reference),
                   project status, or a decision. Plans live as dated files, not here.
     body        — the single fact. For preferences/decisions, add a line on WHY
                   and HOW to apply it. Link related memories liberally. -->

<!-- Reference: the index (step 4). One line per memory file, so an agent can
     scan what exists BEFORE loading any bodies. Keep it short — a hook, not a
     summary. Regenerate or hand-edit whenever a memory file is added, renamed,
     or retired; a stale index is worse than no index. -->

# Memory index

One line per durable memory. Format: `- [name](relative/path.md) — description`.

## User / preferences
- [deploy-target-is-staging](memory-file.example.md) — app pushes go to
  staging, which is what real users hit; verify the target before any release.

## Project / reference
- [release-checklist](release-checklist.md) — the steps that precede any deploy
  (not written yet — a link to a memory that doesn't exist is fine; it marks
  something worth writing later).

## Decisions
- [no-direct-prod-deploys](no-direct-prod-deploys.md) — all releases go through
  staging first; settled, with the why, in the decisions log (illustrative —
  your decisions log has its own home; see RECIPE.md step 2).

<!-- Notes:
     - Group however makes sense for your project (by type, by area) — the
       index is a scan surface, not a schema.
     - A link to a memory that doesn't exist yet is fine; it marks something
       worth writing later (see RECIPE.md, "link related memories").
     - Keep entries current: retire the line when the file is archived, don't
       just delete the file and leave a dangling index entry.
-->