Skip to content

About

A complete memory loop for Claude — snapshot, recall, and prune project context across sessions

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

memory-map

A complete memory loop for Claude. Snapshot, recall, and prune project context across sessions.

License: MIT Version Compatible SKILL.md

Three skills, bundled as one plugin. Works in claude.ai, Claude Code, Cursor, Windsurf, and Codex CLI.


The problem

Every new Claude conversation starts blank.

You re-explain your project. You re-describe what you are building. You re-state the decisions you already made. Every. Single. Time.

It is a tax on every session. And it gets worse the longer your project runs.

The fix

Three skills that give Claude a working memory across sessions:

Skill What it does When it triggers
memory-map Snapshots your session — what was built, decided, pending — to persistent memory, and restores one project from its STATUS.md At session close, when you say "save this", or "catch me up on [project]"
memory-recall Loads stored memory and surfaces what is relevant right now At session start, or when you ask "what do you remember?"
memory-prune Identifies stale entries and proposes a cleanup, with your confirmation When memory gets cluttered, or on request

The loop: write → recall → prune. Together they make Claude feel like it actually remembers your work.


Works everywhere

Same protocol, two storage backends, detected automatically:

Environment Storage
claude.ai Persistent memory API (memory_user_edits)
Claude Code Local file at ~/.claude/memory.md

Compatible with the open SKILL.md format, also works in Cursor, Windsurf, Codex CLI, and any tool that supports Anthropic's Agent Skills spec.


Install

Claude Code plugin (recommended)

Upgrading from install.sh or a manual copy? Before installing, remove the old skill folders so the skills do not load twice: ~/.claude/skills/memory-map, ~/.claude/skills/memory-recall, ~/.claude/skills/memory-prune, and any ~/.claude/skills/memory-*.backup-* folders the installer left behind. Your ~/.claude/memory.md stays as it is. If you also uploaded the skills on claude.ai and they show up in Claude Code, turn those off in claude.ai Settings → Skills.

/plugin install memory-map --marketplace shandar/memory-map

On older Claude Code versions, add the marketplace first:

/plugin marketplace add shandar/memory-map
/plugin install memory-map@memory-map-marketplace

That gives you the three skills plus four commands:

Command What it does
/memory-map:save Snapshot this session: global index + this project's STATUS.md
/memory-map:status [project] Restore one project from its STATUS.md
/memory-map:recall [topic] Cross-project briefing from memory
/memory-map:prune Propose a cleanup; nothing changes without your yes

Without the plugin system

Claude Code (manual)

git clone https://github.com/shandar/memory-map.git
cd memory-map
cp -r plugins/memory-map/skills/* ~/.claude/skills/

Restart Claude Code. The skills load automatically.

Prefer a script? After cloning, read install.sh and run it from the clone with bash install.sh. It installs from that clone, so what you read is what you get: it copies the three skills to ~/.claude/skills/, initialises ~/.claude/memory.md, and backs up any pre-existing skill folders.

claude.ai

Each skill installs separately on claude.ai:

  1. Download the latest release
  2. Extract the archive
  3. Open Settings → Skills → Install from file
  4. Upload plugins/memory-map/skills/memory-map/SKILL.md, then memory-recall/SKILL.md, then memory-prune/SKILL.md from the same folder

After all three are installed, they trigger automatically based on what you say.


Usage

After install, just talk normally. The skills trigger themselves.

At the start of a session

You: "What do you remember about my dashboard project?"

Claude: Picking up where we left off:

Current state — Auth flow shipped to staging. API rate limiting
implemented with Redis backend. Dashboard refactor in progress.

Pending items:
→ Finish the analytics widget refactor
→ Review PR #142 from Sarah
→ Migrate billing service to new endpoint

Active projects: dashboard refactor, auth flow, billing migration.

At the end of a session

You: "Save this conversation"

Claude: MEMORY MAP — updated April 27 2026

UPDATED  →  Auth flow status (now in staging)
UPDATED  →  Current state snapshot
NEW      →  API rate limiting decisions (Redis backend)
──────────────────────────────────────────────────
UNCHANGED: 8 entries

When memory gets cluttered

You: "Clean up the memory"

Claude: MEMORY PRUNE — proposed changes

REMOVE (stale)
→ Entry 7: "Old auth design (v1)" — superseded by v3 in entry 11
→ Entry 14: "Q1 sprint planning" — quarter is closed

CONSOLIDATE
→ Entries 3 + 9 → single "API conventions" entry

KEEP all 6 operating preference entries

Apply these changes? [yes / modify / cancel]

Trigger phrases

The skills activate on natural language, no commands to memorise.

Skill Trigger phrases
memory-map (save) save this · snapshot this · memorise this chat · update your memory · store this session · don't lose this context
memory-map (restore one project) catch me up on [project] · [project] status · restore context · where did I/we leave off (inside a project folder that has a STATUS.md)
memory-recall (all projects) what do you remember · what's the context · show me the memory map · where did I/we leave off · catch me up (when no project is named and the folder has no STATUS.md)
memory-prune clean up memory · prune memory · consolidate memory · trim the memory map

All three also fire proactively when conditions are right — at the close of a productive session, at the start of a new one, or when memory is approaching its limits.


How memory is stored

Claude Code: ~/.claude/memory.md

Plain markdown, readable, editable, version-controllable:

# Claude Memory Map
Last updated: April 27 2026

## 1. CURRENT STATE SNAPSHOT (April 2026)
Auth flow in staging. API rate limiting shipped with Redis. Dashboard refactor
in progress. Next: analytics widget, PR #142 review, billing migration.

## 2. AUTH SERVICE
JWT with refresh tokens. Redis session store. 15-min access, 7-day refresh.
PR: github.com/team/repo/pull/127. Owner: backend team.

## 3. CODING CONVENTIONS
TypeScript strict mode. Vitest for tests. Conventional commits. Trunk-based dev.

You can edit this file directly. memory-prune will respect your edits.

claude.ai: Persistent memory API

Stored via Anthropic's memory_user_edits tool. Visible in Settings → Memory. Works the same way functionally — same category labels, same density rules, just managed via API instead of file.

Per project: STATUS.md

The global store above is the cross-project index. Each project also gets a STATUS.md in its root with five sections: TL;DR, Last session, Next up, Open threads, Key locations. On the first write in a project, STATUS.md is added to that project's .gitignore; remove the line if you want to commit it for team handoff. On claude.ai, the skill produces STATUS.md as an artifact for you to save.


Design principles

  • Proactive, not reactive — skills run when they should, without being asked
  • Replace over accumulate — stale entries are replaced, never stacked
  • Density over prose — every entry is scannable, fact-packed, no filler
  • One source of truth — CURRENT STATE SNAPSHOT is always exactly one entry
  • Confirm before destruction — memory-prune always proposes, never deletes autonomously
  • Environment-aware — same skill, right storage for the right tool

Repository structure

memory-map/
├── README.md                          ← you are here
├── LICENSE                            ← MIT
├── CHANGELOG.md                       ← version history
├── CONTRIBUTING.md                    ← how to contribute
├── SUBMISSION.md                      ← plugin directory submission notes
├── install.sh                         ← installer for non-plugin setups
├── .claude-plugin/
│   └── marketplace.json               ← marketplace manifest (this repo)
├── docs/brand/icon-source.svg         ← source for the listing icon
└── plugins/memory-map/                ← the plugin itself: markdown, JSON and one PNG
    ├── .claude-plugin/
    │   ├── plugin.json                ← plugin manifest
    │   └── icon.png                   ← listing icon
    ├── README.md
    ├── LICENSE
    ├── commands/                      ← /memory-map:save, :status, :recall, :prune
    └── skills/
        ├── memory-map/
        │   ├── SKILL.md
        │   └── references/
        │       ├── claude-ai.md       ← memory_user_edits API
        │       └── claude-code.md     ← ~/.claude/memory.md file
        ├── memory-recall/
        │   ├── SKILL.md
        │   └── references/
        └── memory-prune/
            ├── SKILL.md
            └── references/

Each skill is self-contained and can be used independently. The plugin bundles them for one-command install.


Roadmap

  • v0.1 — memory-map, memory-recall, memory-prune
  • v0.2 — two-tier memory (global index + per-project STATUS.md), READ mode, Claude Code plugin and commands
  • v0.3 — local mirror at ~/.memory-map/ (unlimited size) and a generated cross-project PROJECTS_INDEX.md
  • Later — memory export/import for teams, memory diffing across sessions ("what changed since last week?")

Track progress in issues and discussions.


Built by

Shandar Junaid — Founder, Affordance Design Studio

If you build on top of this, I would love to see what you make. Tag me on LinkedIn or X.


License

MIT — use it, fork it, extend it. See LICENSE.


Credits

The SKILL.md format and Agent Skills specification are from Anthropic. This plugin is an independent open-source project, not affiliated with Anthropic.

About

A complete memory loop for Claude — snapshot, recall, and prune project context across sessions

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages