memory-map
/memory-map
Use when installing or configuring memory_map, writing CLAUDE.md session-setup instructions, choosing what to save in memory vs history, managing cross-project memory, tuning compression, or troubleshooting why Claude isn't loading context at session start.
- Author
- MARUCIE ↗
- Repository
- openclaw-foundry ↗
- Licence
- MIT
- Last repository change
- 18.07.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 18.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when installing or configuring memory_map, writing CLAUDE.md session-setup instructions, choosing what to save in memory vs history, managing cross-project memory, tuning compression, or troubleshooting why Claude isn't loading context at session start.
Original author description
Use when installing or configuring memory_map, writing CLAUDE.md session-setup instructions, choosing what to save in memory vs history, managing cross-project memory, tuning compression, or troubleshooting why Claude isn't loading context at session start.
How it works
- 是什么
- 怎么用
- 架构图
- When to Activate
- Architecture
- Installation
- Memory Tools
- History Tools
- Cross-Project Tools
- Utility Tools
SKILL.md preview
---
name: memory-map
description: Use when installing or configuring memory_map, writing CLAUDE.md session-setup instructions, choosing what to save in memory vs history, managing cross-project memory, tuning compression, or troubleshooting why Claude isn't loading context at session start.
---
## 是什么
Memory Map 是给智能体安装长期记忆与情景记忆(Episodic Memory)的工程脚手架。
用它的效果是:智能体跨会话也能记住用户偏好、历史决策、未完成事项,告别金鱼脑。
## 怎么用
1. 先按记忆类型(事实型、偏好型、事件型)分库存储,让检索时按需取用而不是混在一起。
2. 在写入时做去重与冲突检测,让相同信息不会被反复落库污染检索质量。
3. 为每条记忆打上时效性标签(永久、季度、单次),让过期信息能自动降权或淘汰。
4. 在调用模型前根据当前上下文做记忆召回,把最相关的 3-5 条注入到提示里。
5. 定期做记忆审计,让无效或敏感的记忆能被人工标记后清理。
## 架构图
```mermaid
flowchart LR
用户输入 --> 记忆召回
记忆召回 --> 模型生成
模型生成 --> 记忆写入
记忆写入 --> 事实库
记忆写入 --> 偏好库
记忆写入 --> 事件库
```
# memory_map
Persistent memory and conversation history MCP server for Claude Code — key-value context store, rolling history, and cross-project recall across sessions.
## When to Activate
- Installing memory_map for the first time or on a new machine
- Writing `CLAUDE.md` session-setup instructions (`load_memory`, `load_history`)
- Deciding what belongs in memory vs history vs inline code comments
- Using cross-project or global memory tools
- Configuring history compression or external summarization
- Debugging why Claude starts a session without prior context
- Manually checkpointing conversation history with `/mem_save`
## Architecture
```
memory_map/
├── server.py — MCP server (stdio transport)
├── history_hook.py — hook script: saves history on UserPromptSubmit / Stop / PreCompact
├── CLAUDE.md — copy into any project to enable session-start loading
└── venv/ — Python virtualenv
Per-project files (written to the project root automatically):
├── .mcp_memory.json — key-value store (load_memory / save_memory)
└── .mcp_history.json — rolling conversation history (20 chunks)
```
MCP registration makes all tools available globally. Per-project activation is controlled by `CLAUDE.md` — Claude only calls `load_memory` / `load_history` automatically if the instructions tell it to.
## Installation
### Step 1 — Clone and Install
```bash
git clone https://github.com/kid-sid/memory_map.git
cd memory_map
# Windows
python -m venv venv
venv\Scripts\pip install -r requirements.txt
# Mac/Linux
python3 -m venv venv
source venv/bin/activate && pip install -r requirements.txt
```
### Step 2 — Register the MCP Server
```bash
# Global — available in every project (recommended)
# Windows
claude mcp add -s user memory_map \
"%USERPROFILE%\\memory_map\\venv\\Scripts\\python.exe" \
"%USERPROFILE%\\memory_map\\server.py"
# Mac/Linux
claude mcp add -s user memory_map \
python3 /home/yourname/memory_map/server.py
```
Registration scope options:
| Scope flag | Stored in | Available |
|---|---|---|
| `-s user` | `~/.claude/mcp.json` | All projects on this machine |
| `-s project` | `.claude/mcp.json` | This repo only (committed, shared) |
| `-s local` | `.claude/mcp.local.json` | This repo only (gitignored, personal) |
Always use `-s user` for memory_map — it stores files with local paths that differ per machine.
Verify: `claude mcp list` → should show `memory_map`.
### Step 3 — Lifecycle Hooks
Add to `~/.claude/settings.json` so history is captured automatically in every project:
```json
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [{
"type": "command",
"command": "python %USERPROFILE%\\memory_map\\history_hook.py",
"timeout": 10
}]
}
],
"PreCompact": [
{
"matcher": "",
"hooks": [{
"type": "command",
"command": "python %USERPROFILE%\\memory_map\\history_hook.py --force",
"timeout": 15
}]
}
],
"Stop": [
{
"matcher": "",
"hooks": [{
"type": "command",
"command": "python %USERPROFILE%\\memory_map\\history_hook.py --force",
"timeout": 15,
"async": true
}]
}
]
}
}
```
Mac/Linux: use `python3` and POSIX paths.
| Hook | When | Flag |
|---|---|---|
| `UserPromptSubmit` | Every message — incremental saves | none |
| `PreCompact` | Before context window compaction | `--force` |
| `Stop` | When Claude finishes a turn | `--force`, `async: true` |
### Step 4 — Enable Per-Project Memory
Copy `CLAUDE.md` from the memory_map repo into the project root:
```bash
# Windows
copy "%USERPROFILE%\\memory_map\\CLAUDE.md" CLAUDE.md
# Mac/Linux
cp ~/memory_map/CLAUDE.md ~/your-project/CLAUDE.md
```
Commit `CLAUDE.md` — teammates get session-start loading automatically. The file content Claude needs:
```markdown
## Session Setup (Required)
At the start of every session, before doing anything else:
1. Call `load_memory` with the current working directory
2. Call `load_history` with the current working directory
3. Read both outputs before exploring files or asking questions
```
---
## Memory Tools
### `save_memory` / `load_memory` / `delete_memory`
Per-project key-value store. Values persist in `.mcp_memory.json`.
```
save_memory(project_path, key, value)
load_memory(project_path) → returns all key-value pairs
delete_memory(project_path, key)
```
**Key conventions:**
| Key | What to store |
|---|---|
| `stack` | Language, framework, runtime versions |
| `current_work` | Active feature, bug, or initiative |
| `gotchas` | Non-obvious constraints, known failures, env quirks |
| `key_files` | Entry points, config files, critical paths |
| `conventions` | Non-obvious team decisions not in the code |
| `blockers` | Current blockers or dependencies on others |
Rules:
- Short, lowercase, underscore-separated keys
- Values: one or two sentences max — dense, not verbose
- Overwrite stale values with the same key; don't accumulate duplicates
- Convert relative dates to absolute: "Thursday" → "2026-05-15"
**What NOT to save in memory:**
- Code patterns and architecture (read the code)
- Git history / who changed what (`git log` / `git blame`)
- Fix recipes (the fix is in the code; commit message has context)
- Ephemeral task state (in-progress work, current conversation)
- Anything already in `CLAUDE.md`
### Global Memory
Shared across all projects on the machine:
```
save_global_memory(key, value)
load_global_memory()
```
Use for: user identity, preferred tools, cross-project conventions, API key locations (not values). Never store secrets.
---
## History Tools
### `load_history` / `save_history`
Rolling conversation history stored in `.mcp_history.json` (20 chunks max). `history_hook.py` calls `save_history` automatically via hooks — no manual calls needed during normal use.
```
load_history(project_path, last_n=5) → returns N most recent chunks
save_history(project_path, content)
```
### Manual Checkpoint: `/mem_save`
Run `/mem_save` at any time to force-save the current conversation as a history chunk. Use before long operations, context compaction, or ending a session mid-task.
---
## Cross-Project Tools
| Tool | What it does |
|---|---|
| `list_projects` | List all projects that have saved memory |
| `get_project_summary(project_path)` | One-line summary of a project's memory |
| `load_cross_project_memory(project_path)` | Load memory from a different project |
| `search_across_projects(query)` | Full-text search across all project memories |
Use cases:
- Referencing a pattern from a sibling project
- Finding which project owns a shared library
- Onboarding to a new project by comparing to a known one
---
## Utility Tools
| Tool | What it does |
|---|---|
| `get_local_structure(project_path)` | Gitignore-aware directory tree |
| `get_github_structure(owner, repo, branch?)` | GitHub repo file tree via API |
| `get_git_history(project_path, limit?)` | Recent commits |
These are read-only exploration tools — call them at session start to orient quickly without reading every file.
---
## Compression
```
set_compression(project_path, level)
```
| Level | Output | When to use |
|---|---|---|
| `0` | Raw — full fidelity | Debugging, inspecting history content |
| `1` | Compact — whitespace stripped | Normal use |
| `2` | Dense — abbreviations, no filler | Low context budget, large histories |
Set per-project; persists until changed. Default is compact (1).
---
## Privacy and External Summarization
History is stored **locally** by default using simple truncation — no data leaves the machine.
To enable OpenAI-backed summarization (richer history compression):
```bash
# Add to your environment / shell profile
export OPENAI_API_KEY="sk-..."
export MCP_HISTORY_EXTERNAL_SUMMARIZE=1
```
When both are set, `history_hook.py` sends up to 4 000 characters of recent conversation to `gpt-4o-mini` before storing the summary locally.
**What gets sent:** recent dialogue including source code, file contents, and environment details. Only enable if you're comfortable with that leaving your machine. Do not enable on machines with proprietary codebases unless your org has approved the OpenAI data-processing agreement.
---
## CLAUDE.md Session-Start Pattern
Minimal session-setup block for any project:
```markdown
## Session Setup (Required)
At the start of every session, before doing anything else:
1. Call `load_memory` with the current working directory
2. Call `load_history` with the current working directory
3. Read both outputs before exploring files or asking questions
Save or update memory entries whenever you learn something worth keeping across sessions.
If something loaded from memory is no longer accurate, update it with `save_memory` using the same key.
Use short, lowercase keys: `stack`, `current_work`, `gotchas`, `key_files`. Keep values concise.
```
Extend this block with project-specific keys or additional tool calls (`get_local_structure`, etc.) when the project benefits from them.
---
## Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Claude starts sessions cold with no memory | `CLAUDE.md` missing or not instructing `load_memory` | Copy `CLAUDE.md` from memory_map repo into project root |
| `load_memory` returns "no memory saved yet" | First session, or memory was deleted | Normal — save entries as context is established |
| History not saving between sessions | Hooks missing or wrong path in `settings.json` | Verify `history_hook.py` path; run it manually: `python memory_map/history_hook.py --force` |
| MCP server not found | Not registered, or wrong Python path | Re-run `claude mcp add`; verify with `claude mcp list` |
| `history_hook.py` hangs the session | No `timeout` on hook or slow Python startup | Ensure `"timeout": 10` is set; use virtualenv Python, not system Python |
| Memory values growing stale | Not updating keys after project shifts | Always overwrite with the same key rather than adding new ones |
---
## Red Flags
- **Putting API keys or passwords in `save_memory`** — memory is stored in `.mcp_memory.json` in the project root, which may be committed or shared; store only key names and env var references, never values
- **No `CLAUDE.md` after registering the MCP server** — registration makes tools available but doesn't call them; Claude only auto-loads memory if the session-setup instructions tell it to
- **Using `-s project` for memory_map registration** — project-scoped MCP servers are committed and affect all teammates, but memory_map stores files at local absolute paths that differ per machine; use `-s user` always
- **Saving entire file contents or code blocks in memory** — memory values should be one to two sentences; large values bloat `.mcp_memory.json`, slow load times, and crowd out useful keys
- **Setting `MCP_HISTORY_EXTERNAL_SUMMARIZE=1` on a machine with proprietary code** — history includes file contents; check your org's data policy before enabling OpenAI-backed summarization
- **Hooks without `timeout`** — a stalled `history_hook.py` (e.g., network timeout during OpenAI summarization) blocks Claude Code indefinitely; always set `"timeout": N`
- **Calling `load_history` + `get_history_chunks` manually at session start** — these are for inspection and the `/mem_save` flow only; use `load_history(last_n=5)` for session continuity, not the raw chunk API
---
## Checklist
- [ ] memory_map cloned; virtualenv created; `pip install -r requirements.txt` succeeded
- [ ] `claude mcp list` shows `memory_map` with correct Python path
- [ ] Registration used `-s user` (not `-s project` or `-s local`)
- [ ] Three lifecycle hooks present in `~/.claude/settings.json`: `UserPromptSubmit`, `PreCompact`, `Stop`
- [ ] Every hook has a `"timeout"` value; `Stop` hook has `"async": true`
- [ ] `CLAUDE.md` copied into the project root and committed
- [ ] `CLAUDE.md` instructs `load_memory` and `load_history` at session start
- [ ] No secrets stored in `save_memory` — only descriptive values and env var names
- [ ] Memory keys are short, lowercase, and overwrite stale values (no duplicates)
- [ ] Compression level set appropriately for the project's history volume
- [ ] External summarization (`MCP_HISTORY_EXTERNAL_SUMMARIZE=1`) only enabled after data-policy check
- [ ] `/mem_save` used before context compaction or ending a long session mid-task
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · MARUCIE/openclaw-foundry | 100 | MIT |
| kid-sid/codex-spellbook | 98 | MIT |
Database snapshot: 13.11.2026 · package version 0e7668287c4e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100project-memory
Use when setting up or organizing Claude Code project memory (CLAUDE.md, .claude/rules/) for better context awareness, consistent behavior, and project-specific instructions. - 95solo-memory-audit
Use when "audit memory", "check CLAUDE.md", "memory map", "rules audit", "context budget", "what loads in my session", or need to optimize agent context loading. - 95memory-management
Claude Code auto-memory 与 CLAUDE.md 的管理方法 — 判断值不值得记、记到哪一层(行内注释 / .claude/rules / memory / CLAUDE.md)、怎么写 frontmatter 与 description、何时 update 何时拆分、索引 MEMORY.md 的容量与 hub 化。用户说"记一下""新增/更新记忆""沉淀经验""复盘""改 memory schema""audit memory""记忆系统乱了"时使用;功能开发或长 debug 收尾有值得沉淀的结论时也用。 - 100claude-memory-curator
Audit and safely curate Claude Code instructions, rules, auto memory, and memory settings. Use when reviewing stale or misplaced Claude Code context, not Claude app memory or API memory stores. - 82where-to-put
Use when 加規則、CLAUDE.md被擋:判載體 - 100memory-kit
Persistent context management for Claude Code sessions. Save, load, update, share, and audit session memory via MEMORY.md. Prevents context loss on compaction or session restart. Use when starting a session, before compaction, syncing context across teammates, or pruning stale…