Local memory

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.

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

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

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

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

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:

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.