# Memory Map

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-shandar-memory-map`
- **Verified:** Pending review
- **Seller:** [shandar](https://agentstack.voostack.com/s/shandar)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shandar](https://github.com/shandar)
- **Source:** https://github.com/shandar/memory-map
- **Website:** https://affordance.design

## Install

```sh
agentstack add mcp-shandar-memory-map
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# memory-map

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

[](https://opensource.org/licenses/MIT)
[](https://github.com/shandar/memory-map/releases)
[](#install)
[](https://docs.claude.com)

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 | At session close, or when you say "save this" |
| **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 (one line)

```bash
curl -fsSL https://raw.githubusercontent.com/shandar/memory-map/main/install.sh | bash
```

The installer clones the repo, copies all three skills to `~/.claude/skills/`, initialises `~/.claude/memory.md`, and backs up any pre-existing skill folders.

### Claude Code (manual)

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

Restart Claude Code. The skills load automatically.

### claude.ai

Each skill installs separately on claude.ai:

1. Download the [latest release](https://github.com/shandar/memory-map/releases)
2. Extract the archive
3. Open Settings → Skills → Install from file
4. Upload `skills/memory-map/SKILL.md`, then `memory-recall/SKILL.md`, then `memory-prune/SKILL.md`

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 this · snapshot this · memorise this chat · update your memory · store this session · don't lose this context |
| **memory-recall** | what do you remember · what's the context · where did we leave off · catch me up · show me the memory map |
| **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:

```markdown
# 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.

---

## 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
├── marketplace.json                   ← plugin manifest
├── install.sh                         ← one-line installer
└── 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/
    │       ├── claude-ai.md
    │       └── claude-code.md
    └── memory-prune/
        ├── SKILL.md
        └── references/
            ├── claude-ai.md
            └── claude-code.md
```

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

---

## Roadmap

- [x] **v0.1** — memory-map, memory-recall, memory-prune
- [ ] **v0.2** — multi-project memory (separate stores per repo or workspace)
- [ ] **v0.3** — memory export/import for sharing project context across teams
- [ ] **v0.4** — memory diffing across sessions ("what changed since last week?")

Track progress in [issues](https://github.com/shandar/memory-map/issues) and [discussions](https://github.com/shandar/memory-map/discussions).

---

## Built by

[Shandar Junaid](https://shandarjunaid.com) — Founder, [Affordance Design Studio](https://affordance.design)

If you build on top of this, I would love to see what you make. Tag me on [LinkedIn](https://www.linkedin.com/in/shandarjunaid/) or [X](https://x.com/pixel8d).

---

## License

MIT — use it, fork it, extend it. See [LICENSE](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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shandar](https://github.com/shandar)
- **Source:** [shandar/memory-map](https://github.com/shandar/memory-map)
- **License:** MIT
- **Homepage:** https://affordance.design

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-shandar-memory-map
- Seller: https://agentstack.voostack.com/s/shandar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.