# Persistent Memory for Agents: claude-mem, planning-with-files and MCP Memory Servers

URL: https://developertoolkit.ai/en/ecosystem/plugins/memory-plugins/
Description: Keep a multi-day agent task alive across /clear with planning-with-files, and add claude-mem, the Memory MCP server or basic-memory only where they earn it.

Persistent agent memory comes in two kinds: an on-disk task plan that survives `/clear` and compaction (planning-with-files), and a recall store for past decisions (claude-mem, the Memory MCP server, basic-memory). If you are a developer running a task across several sessions, start with the plan on disk and add a recall store only when you need answers across weeks.

It is day two of a feature. Yesterday's session hit 80% context, you ran `/clear`, and this morning the agent spends twenty minutes re-reading the repository, proposes the retry design you rejected on day one, and has no idea which tests already pass. This page is for developers who run agent tasks longer than one context window, and for tech leads deciding which memory tools are allowed near company code.

## What persistent memory gives you on a multi-day task

- A decision table for the five places agent memory can live, with what each costs and where your data goes
- planning-with-files installed in Claude Code, Codex or Cursor, and a check that its hooks actually fire
- A worked example: resume a half-finished task after `/clear` without re-explaining it
- A multi-day feature workflow built on `task_plan.md`, `findings.md` and `progress.md`, with a verification gate per phase
- Safe installs for claude-mem, the Memory reference server and basic-memory, and the traps in each

## Which memory tool fits which job?

Start with what your agent already has. `CLAUDE.md`, `.claude/rules/` and auto memory in Claude Code, and `AGENTS.md` in Codex, carry durable project knowledge through reviewed commits; the [Claude Code memory system](/en/claude-code/build/memory-system/) and [long-term context retention patterns](/en/workflows/context/memory-patterns/) cover them. Codex also has a `memories` feature, stable but off by default (checked with `codex features list` on 0.157.1). The tools on this page solve two different problems those files do not.

| Tool | What it keeps | Where it lives | Always-on cost | Leaves your machine? | Best for |
| ---- | ------------- | -------------- | -------------- | -------------------- | -------- |
| planning-with-files | The live plan for one task: phases, findings, progress | Three Markdown files in the project | ~1,124 tokens (plugin 3.20.8) | No; the skill has no upload path | Tasks that span sessions or days |
| claude-mem | Compressed observations of every session, searchable | SQLite (`~/.claude-mem/claude-mem.db`) plus Chroma | ~2,000 tokens (13.25.3) plus injected context | Depends on `--provider`; the default offers a hosted observer | Recall across many tasks and weeks |
| Memory reference server | A knowledge graph of entities, relations, observations | One JSONL file (`MEMORY_FILE_PATH`) | MCP tool schemas only | No | Small, explicit facts a chat client should keep |
| basic-memory | Markdown notes linked into a graph | `~/basic-memory` by default | MCP tool schemas only | No, unless you route a project to its cloud | Human-readable notes shared with Obsidian |
| `CLAUDE.md`, `AGENTS.md`, auto memory | Conventions and decisions for the repo or for you | The repo, or `~/.claude/projects/` | The file size | No | Anything the whole team should know |

Token costs are what `claude plugin details` reported on Claude Code 2.1.283 on 2026-09-26, from the research for this page. The claude-mem figure was measured on 13.25.3; 13.28.0 is current, so rerun `claude plugin details claude-mem@thedotmack` after installing. Hooks cost no context unless they inject text, and claude-mem's `SessionStart` hook does.

**Popularity, as of 2026-09-26** (GitHub stars read through the GitHub API that day): thedotmack/claude-mem 94.7k, OthmanAdi/planning-with-files 27.1k, basicmachines-co/basic-memory 4.0k. The Memory server lives in modelcontextprotocol/servers (90.6k stars for the whole repository, not for Memory alone). Stars measure attention on a repository, not fitness for your codebase.

**A plan and a memory are different things**

planning-with-files manages the state of the task you are doing now: which phase is active, what the next step is, what passed. A recall store answers questions about the past. The planning-with-files README says the two are complementary. Most teams need the plan first.

## Install planning-with-files in your agent

The hooks are what make planning-with-files work: they re-inject the plan on every prompt and after `/clear`. Every route below keeps the hooks; the one-line skills install does not, so it comes last.

**Claude Code**

If plugins and marketplaces are new to you, read [how plugins work in the three agents](/en/ecosystem/plugins/) first. Run inside a Claude Code session:

```text
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```

Then, in a terminal, check what it loads into every session:

```bash
claude plugin details planning-with-files@planning-with-files
```

On 3.20.8 that reported 14 skills, 6 hooks and about 1,124 always-on tokens; the README listed v3.21.0 on 2026-09-26, so rerun the command after every update. Back in the session, run `/planning-with-files:plan-doctor`: it prints one PASS, WARN or FAIL line each for plan resolution, injection, attestation, install surfaces and hook latency.

**Codex**

The vendor's Codex guide installs a repository skill plus standalone hooks. Run in the project root:

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
mkdir -p .agents/skills .codex
cp -r /tmp/planning-with-files/.agents/skills/planning-with-files .agents/skills/
cp /tmp/planning-with-files/.codex/hooks.json .codex/hooks.json
cp -r /tmp/planning-with-files/.codex/hooks .codex/hooks
rm -rf /tmp/planning-with-files
```

Hooks are stable and on by default in codex-cli 0.157.1 and 0.162.1 (`codex features list`, checked 2026-10-12), but Codex only runs a new hook after you trust it: open the TUI, run `/hooks`, and review each entry. If `.codex/hooks.json` already exists, merge the entries instead of overwriting the file. The repository also ships a Codex plugin package; do not enable it together with the standalone hooks, because Codex runs every matching hook from every source.

**Cursor**

The vendor's Cursor guide copies a `.cursor` directory with the skill, `hooks.json` and hook scripts:

```bash
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
mkdir -p .cursor
cp -r /tmp/planning-with-files/.cursor/skills /tmp/planning-with-files/.cursor/hooks .cursor/
cp /tmp/planning-with-files/.cursor/hooks.json .cursor/hooks.json
rm -rf /tmp/planning-with-files
```

Merge `hooks.json` by hand if the project already has one. On Cursor the plan is injected when a conversation starts (`sessionStart`), not on every prompt, so start a new chat after `/clear`-style resets. The vendor guide says Cursor Cloud Agents do not run `sessionStart`, so a cloud run gets no plan context from the hook. These details come from the project's `docs/cursor.md`; cursor.com was unreachable from our environment on 2026-09-26.

For any other agent, the Agent Skills route installs the skill in one line:

```bash
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
```

The README describes this route as the pattern "without lifecycle hooks": no slash commands, no per-turn plan injection and no `SessionStart` recovery. Use it when your agent has no plugin route, and expect to ask for the plan explicitly after a reset.

## Resume a task after /clear with planning-with-files

This example uses Claude Code. The Codex and Cursor routes above install no slash commands, so there you start the plan by asking for it (the first prompt below already does), skip the `/planning-with-files:*` commands, and reset with `/new` in Codex or a new chat in Cursor.

1. Start the plan. Run `/planning-with-files:plan`, then paste the task prompt below. The agent writes `task_plan.md`, `findings.md` and `progress.md` in the project root. Type the namespaced command: in Claude Code, a bare `/plan` is the built-in plan mode.

2. Work through the first phases. As it goes, the agent appends research to `findings.md`, logs commands and test results in `progress.md`, and ticks items in `task_plan.md`. Check `/planning-with-files:status` for the current phase and totals.

3. Checkpoint before the reset. When context runs high, paste the checkpoint prompt further down so the three files hold everything the next session needs.

4. Run `/clear`. The conversation is gone; the files are not.

5. Paste the resume prompt. The `UserPromptSubmit` hook injects the plan head before the model sees your message.

6. Check what you see. The agent's first reply names the current phase and the next step exactly as `task_plan.md` states them, and it runs the last recorded test command before editing code. If it starts re-exploring the repository instead, run `/planning-with-files:plan-doctor`.

**Copy-paste prompt: start a plan with verifiable phases**

```text
Plan this task with planning-with-files before writing any code.

Task: move webhook retries from in-process setTimeout calls to a D1-backed outbox table,
so a Worker restart never drops a retry.

In task_plan.md, write 4-6 phases. Every phase must end with an exit check that is a
command I can run (a test file, a typecheck, a SQL query against local D1), not a
description. Record constraints in findings.md: no schema change without a numbered
migration, no Date objects bound to D1, existing webhook tests must keep passing.
Stop after the plan is written and show me the phases.
```

**Copy-paste prompt: resume after /clear**

```text
Resume the active plan. Before you touch any code:
1. Tell me the current phase and the Next Step from task_plan.md, word for word.
2. Summarise the last three entries in progress.md, including which checks passed.
3. Run the exit check of the last completed phase and show me the result.
If the check fails or the files disagree with the code, stop and tell me what differs.
```

## Run a multi-day feature on plan, findings and progress files

The example above covers one reset. A feature that spans a week needs the files to carry the whole loop, from plan to merge, and to carry proof, not only intent.

1. **Plan (day 1).** Agree the approach in plan mode, then have the agent write it into `task_plan.md` as phases, each with a runnable exit check. For larger features, write the spec first; see [spec-driven development](/en/workflows/plan/spec-driven-development/). Lock the approved plan with `/planning-with-files:plan-attest`: hooks then stop injecting the plan, and print `[PLAN TAMPERED]`, if `task_plan.md` no longer matches the attested SHA-256, which catches silent rewrites.

2. **Build (days 1–4).** One phase at a time. The agent logs every decision in `findings.md` with its reason ("rejected exponential backoff in memory: lost on restart"), so a later session cannot re-propose it.

3. **Verify at every phase boundary.** A phase moves to `complete` only after its exit check passes and the output is pasted into `progress.md`. For unattended stretches, gated mode (run `/planning-with-files:pwf` and ask for gated mode in the task text, or initialise with the skill's `init-session.sh --gated`) holds the agent's stop while a phase is still `in_progress`, with a block cap (`PWF_GATE_CAP`, default 20 consecutive blocks) so an unfinished plan cannot trap the session.

4. **Checkpoint at the end of each day.** Paste the checkpoint prompt below, then close the session. Tomorrow starts with the resume prompt.

5. **Review.** Give the reviewer, human or agent, the diff plus `task_plan.md` and `progress.md`. The question is no longer "is every line right?" but "does every phase have passing evidence, and does the diff stay inside the plan?"

6. **Ship and promote.** The plan files are working memory: the README says they are gitignored by default and the next task overwrites the root plan. Before you merge, move durable knowledge out of them: architecture decisions into an ADR, conventions into `CLAUDE.md` or `AGENTS.md`. Then delete the files.

**Copy-paste prompt: end-of-day checkpoint**

```text
We stop for today. Update the planning files so a fresh session can continue without me:
- task_plan.md: set Current Phase and Next Step to the exact next action, mark finished items.
- findings.md: add every decision made today with its reason, and every approach we rejected.
- progress.md: log the commands you ran today and paste the result of the last test run.
Then list anything that exists only in this conversation and is not yet in the files.
```

Two or more tasks in one repository need their own plans. `init-session.sh "<name>"` creates `.planning/YYYY-MM-DD-<slug>/` with the same three files, and `PLAN_ID` pins a terminal to one of them. On the Codex and standalone hook routes, several named plans and no `PLAN_ID` means the hooks refuse to inject context rather than guess. On Cursor, the bash hooks read only the root `task_plan.md`, so use one root plan per worktree there. Separate git worktrees, one per task, are the simpler alternative; see [running agents in parallel](/en/ecosystem/agent-tools/parallel-agents/).

## Add cross-session recall with claude-mem

claude-mem records what happens in every session through hooks, compresses it with a model, and lets a later session search it through the `mem-search` skill and an MCP server with `search`, `timeline` and `get_observations` tools. It answers questions that no task plan holds, across weeks and tasks.

The default installer finishes setup and then asks you to sign in to the hosted "claude-mem observer" (a 30-day free trial, per the README; afterwards it falls back to your Anthropic plan unless you subscribe). For company code, choose the provider yourself. Run in a terminal:

```bash
npx claude-mem install --provider claude     # compress with your own Anthropic plan; no sign-in
npx claude-mem telemetry disable             # anonymous telemetry is on by default
npx claude-mem doctor                        # checks Bun, uv and the worker
```

`--provider` accepts `claude`, `gemini`, `openrouter` or `host` (`npx claude-mem --help`, 13.28.0, the npm `latest` on 2026-09-26). The same help lists `--ide codex-cli` and `--ide cursor` for Codex and Cursor; we did not run those routes. The installer's `--disable-auto-memory` flag turns off Claude Code's own auto memory; decide deliberately whether you want both stores writing notes. Wrap anything that must never be stored in `<private>` tags.

**Copy-paste prompt: recall a past decision with evidence**

```text
Search claude-mem for what we decided about webhook retry backoff in the last two weeks.
Use search first, then get_observations only for the relevant IDs.
Quote each decision with its observation ID and date, then check it against the current
code and git log. Tell me which decisions still hold and which the code has since changed.
```

## Use an MCP memory server: the reference Memory server or basic-memory

An MCP memory server exposes memory as tools the agent calls on purpose, and the setup is the same idea in all three tools. The reference Memory server keeps a knowledge graph in one JSONL file; set `MEMORY_FILE_PATH`, or the file lands inside the `npx` package cache. basic-memory writes plain Markdown notes to `~/basic-memory`, readable in any editor or Obsidian; it is AGPL-3.0, and its cloud sync is optional.

**Claude Code**

```bash
claude mcp add memory -e MEMORY_FILE_PATH=$HOME/.agent-memory/memory.jsonl -- npx -y @modelcontextprotocol/server-memory
claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp
```

**Codex**

```bash
codex mcp add memory --env MEMORY_FILE_PATH=$HOME/.agent-memory/memory.jsonl -- npx -y @modelcontextprotocol/server-memory
codex mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp
```

**Cursor**

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global), with your own absolute path:

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": { "MEMORY_FILE_PATH": "/Users/me/.agent-memory/memory.jsonl" }
    },
    "basic-memory": {
      "command": "uvx",
      "args": ["--prerelease=allow", "basic-memory", "mcp"]
    }
  }
}
```

Versions on 2026-09-26: npm `@modelcontextprotocol/server-memory` 2026.8.31, PyPI `basic-memory` 0.23.2. For a coding team, a fact the whole team needs belongs in `CLAUDE.md` or `AGENTS.md`, where it changes through review; the [reference MCP servers page](/en/ecosystem/mcp/reference-servers/) explains when the Memory server is worth running at all.

**Memory traps checked on 2026-09-26**

- `npm install -g claude-mem` installs only the SDK. It registers no hooks and starts no worker. Use `npx claude-mem install` or the `/plugin` route.
- An interactive `npx claude-mem install` without `--provider` offers the hosted observer sign-in. The 13.28.0 help says a non-interactive fresh install defaults to `claude`; behaviour has changed between releases, so pass `--provider` explicitly in both cases.
- planning-with-files through `npx skills add` has no slash commands and no `SessionStart` recovery. If recovery matters, use the plugin or the per-tool hook install and run `/planning-with-files:plan-doctor`.
- Codex runs no new hook until you trust it in `/hooks`, and runs both copies if you enable the plugin package and the standalone hooks.
- `PLANNING_DISABLED=1` stops a one-shot session in the same directory from being pulled into an unfinished plan.
- The Memory server without `MEMORY_FILE_PATH` writes into the `npx` cache, and a cache cleanup deletes the graph.

## How do you prove agent memory is helping?

Memory is context, not evidence. Every recalled fact can be stale, so put a cheap check at each point where memory re-enters the work:

- **The resume test.** After `/clear`, the first reply must repeat the current phase and Next Step from `task_plan.md` and rerun the last exit check. A reply that does not is a failed install, not a bad prompt.
- **Evidence per phase.** A phase is complete only when `progress.md` holds the passing output of its exit check. The reviewer, or a [review agent](/en/ecosystem/observability/ai-code-review-bots/), checks the diff against the plan and that evidence instead of reading every line.
- **Citations for recall.** A claude-mem answer carries observation IDs and dates, and a basic-memory answer carries note paths; the prompt then checks the claim against code and `git log`.
- **Context cost.** Run `/context` in Claude Code before and after installing a memory tool. If a recall store injects more than it saves, remove it.
- **Who signs off.** The developer owns the plan and its exit checks. The tech lead decides which stores may hold company code, especially any tool whose provider sends session content to a third party.

## What breaks with persistent agent memory?

- **The agent ignores the plan after `/clear`.** The hooks are not firing: the skills-only route, an untrusted Codex hook, or a Cursor Cloud Agent. In Claude Code, run `/planning-with-files:plan-doctor` and fix the failing line; in Codex, open `/hooks` and trust each planning-with-files hook; in Cursor, start a new chat so `sessionStart` fires. Then paste the resume prompt again. On a Cursor Cloud Agent, no hook fires: start the run with "Read task_plan.md, findings.md and progress.md first" as the opening instruction.
- **The wrong plan is injected.** Two named plans exist and the pointer moved. Run the plugin's `set-active-plan.sh --list`, then start the session with `PLAN_ID` set to the right one.
- **The agent re-proposes a rejected design.** The rejection lived only in the conversation. Add it to `findings.md` with the reason, and make the end-of-day checkpoint a habit.
- **Recall contradicts the code.** claude-mem or the Memory graph holds a decision that a later commit reversed. Trust the code and `git log`, delete or correct the stale observation, and keep "check against the code" in every recall prompt.
- **Sessions got expensive.** Two memory tools plus auto memory inject overlapping context. Keep one recall store, measure with `/context`, and uninstall the rest (`npx claude-mem uninstall` for claude-mem).
- **Company code reached a hosted service.** Someone accepted the claude-mem sign-in. Rerun the installer with an explicit `--provider`, and have the tech lead add the approved install command to the team's setup notes.

## Where to go next with agent memory

- [Claude Code memory system](/en/claude-code/build/memory-system/) — CLAUDE.md, rules, imports and auto memory: the built-in layer to set up first.
- [Skills for context and token discipline](/en/ecosystem/skills/context-and-token-skills/) — handoff, caveman and karpathy-guidelines for long tasks inside one context window.
- [Long-term context retention patterns](/en/workflows/context/memory-patterns/) — What to persist, where, and what to leave ephemeral across all three tools.
- [The plugins worth installing](/en/ecosystem/plugins/top-plugins/) — Measured context cost and one example for each popular plugin.
