Memory Map

是什么

Memory Map 是给智能体安装长期记忆与情景记忆（Episodic Memory）的工程脚手架。 用它的效果是：智能体跨会话也能记住用户偏好、历史决策、未完成事项，告别金鱼脑。

怎么用

1. 先按记忆类型（事实型、偏好型、事件型）分库存储，让检索时按需取用而不是混在一起。
2. 在写入时做去重与冲突检测，让相同信息不会被反复落库污染检索质量。
3. 为每条记忆打上时效性标签（永久、季度、单次），让过期信息能自动降权或淘汰。
4. 在调用模型前根据当前上下文做记忆召回，把最相关的 3-5 条注入到提示里。
5. 定期做记忆审计，让无效或敏感的记忆能被人工标记后清理。

架构图

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

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

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

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:

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

Step 4 — Enable Per-Project Memory

Copy CLAUDE.md from the memory_map repo into the project root:

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

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

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

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

These are read-only exploration tools — call them at session start to orient quickly without reading every file.

Compression

set_compression(project_path, level)

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

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

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

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