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

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 and long-term context retention 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 first. Run inside a Claude Code session:

/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:

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:

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, 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:

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:

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

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

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

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.

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:

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

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

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

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:

{
  "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 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, 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 CLAUDE.md, rules, imports and auto memory: the built-in layer to set up first.

Skills for context and token discipline handoff, caveman and karpathy-guidelines for long tasks inside one context window.

Long-term context retention patterns What to persist, where, and what to leave ephemeral across all three tools.

The plugins worth installing Measured context cost and one example for each popular plugin.