# Local memory (https://docs.ctxpipe.ai/docs/mcp/local-memory)

<Callout type="info" title="This page changes often">
  Local memory builds on features of coding agents (Cursor, Claude Code, Codex,
  OpenCode, VS Code) that change from month to month, and on ideas about agent
  memory that are still settling. Expect this page and `ctxpipe memory init` to
  change frequently. After upgrading the CLI, re-run `npx ctxpipe memory init`
  to pick up the latest hooks, rules, and skills.
</Callout>

## What it is

Local memory is a folder of Markdown files, `.ai/memory/`, that lives in your
repository. Coding agents read it when they start a task and add to it when they
learn something worth keeping: a convention, a decision, or a correction from an
engineer.

It is plain files in Git. There is no database and no background service, and
nothing leaves your machine until you commit and push.

## Why it exists

Agents forget. Every new chat starts from scratch, so engineers end up repeating
the same corrections ("we use pnpm here", "don't call that API directly"). Local
memory keeps those lessons:

* **Across chats and tools.** What one agent learns, the next one reads, whether
  it runs in Cursor, Claude Code, Codex, OpenCode, or VS Code.
* **With your team.** Memory is committed and reviewed like code, so a lesson one
  engineer teaches reaches everyone once it merges.
* **In ctxpipe.** When the repository is linked to a Workspace, merged lessons
  become part of that Workspace's knowledge, and the MCP read tools pass them on to
  agents working in other repositories too.

## How it works

1. **The agent notices.** When you tell an agent something that sounds lasting
   ("from now on…", "we decided…"), a small hook saves it as a *candidate* in
   `.ai/memory/events/`. Candidates stay on your machine; that folder is
   gitignored.
2. **The agent decides.** When the agent finishes its turn, the hook shows it the
   candidates. The agent writes the ones worth keeping into the right file (for
   example `lessons-learned.md`, or a new decision record) and discards the rest.
   Hooks never write lasting memory themselves.
3. **You commit it with the work.** Memory changes go in the same commit and pull
   request as the code they came from. If memory is left uncommitted, the agent
   is reminded once, and again if a later commit leaves it out.
4. **The pull request tells the story.** The agent summarizes the work in the
   pull request description: what changed, why, what was tried and ruled out, and
   what is left. That description is reviewed with the code.
5. **ctxpipe learns from what merges.** After merge, ctxpipe reads
   `lessons-learned.md` as instructions for how your team works, decision records
   as decisions, and, where pull request mirroring is enabled, pull request
   descriptions as the history behind each change.

## What each agent gets

Paths are for repository scope. With `--scope user`, the same files go in your
home directory.

| Agent             | Capture and reminders                           | Instructions                                                                                |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Cursor            | Hooks in `.cursor/hooks.json`                   | `.cursor/rules/ai-memory.mdc` and skills in `.cursor/skills/`                               |
| Claude Code       | Hooks in `.claude/settings.json`                | `.claude/rules/ai-memory.md` and skills in `.claude/skills/`                                |
| Codex             | Hooks in `.codex/config.toml`                   | A block in `AGENTS.md`                                                                      |
| VS Code (Copilot) | Hooks in `.github/hooks/ctxpipe-memory.json`    | `.github/copilot-instructions.md` and `.github/instructions/ctxpipe-memory.instructions.md` |
| OpenCode          | Plugin in `.opencode/plugins/ctxpipe-memory.js` | `.opencode/memory-capture.md`, `AGENTS.md`, and an `instructions` entry in `opencode.json`  |

`memory init` always writes the Cursor rule and skills in the repository, for
each choice of agents.

* **Codex** runs project hooks only after you trust the project and approve the
  hooks in `/hooks`.
* **VS Code** agent hooks are in preview.
* **OpenCode** has no end-of-turn hook yet, so the plugin posts the reminder as a
  new message after the agent finishes.
* **Cursor and VS Code** can also run Claude Code hooks from
  `.claude/settings.json`. ctxpipe detects this so capture runs once per turn.

## Install

```bash
npx ctxpipe memory init --agents cursor,claude --scope repo --non-interactive
```

Or with the main setup wizard, which also configures the ctxpipe MCP:

```bash
npx ctxpipe init --org acme --agents cursor,claude --scope repo --memory --non-interactive
```

`--agents` takes any of `cursor`, `claude`, `codex`, `opencode`, and `vscode`.
`--scope` is `repo`, `user`, or `both`. Without prompts, the default is `repo`.
The interactive wizard asks.

## What's in the folder

```
.ai/memory/
  README.md            # how agents should use this folder
  index.md             # map of the stores below
  lessons-learned.md   # confirmed conventions and corrections
  glossary.md          # project terms
  product-context.md   # product and architecture overview
  decisions/           # decision records (ADR-*.md) + index.md
  PRDs/                # product requirements + index.md
  sessions/            # summaries of work that has no pull request
  events/              # candidate inbox, gitignored
```

## Local memory and the ctxpipe MCP

|                            | What it does                                                                            |
| -------------------------- | --------------------------------------------------------------------------------------- |
| `ctxpipe` MCP (read tools) | Searches and reads your Workspaces: their knowledge files, connectors, and linked code. |
| Local memory (this page)   | Markdown in one repository plus agent hooks. It is not an MCP server.                   |

You can use local memory on its own (`memory init`) or alongside the ctxpipe MCP
(`init --memory`). Together, local memory is how agents learn, and the MCP is how
that learning reaches every agent in your organization.

## Finding things in memory

Agents start from `index.md` and each store's own `index.md`. For anything else
they search with ripgrep, skipping the candidate inbox:

```bash
rg -i "keyword" .ai/memory --glob '*.md' --glob '!events/**'
```

The installed `memory-search` skill describes the full procedure.

## Checking and upgrading

* `npx ctxpipe memory status` and `npx ctxpipe memory doctor` show whether memory
  is set up, and list the memory files that are not committed yet.
* The hooks call `npx ctxpipe memory capture`. Agents use
  `memory capture promote <id>` and `memory capture dismiss <id>` to keep or
  discard a candidate. You do not run these commands yourself.
* Re-run `npx ctxpipe memory init` after upgrading the CLI. It refreshes the
  rules, skills, and hooks, and keeps your own memory files. It also removes
  retired pieces from older versions: the `ctxpipe-memory` MCP entry, old memory
  skills, and an AgentMemory-era `README.md`, and it moves `patterns.md` into
  `lessons-learned.md`.