Context Bridge

克劳德记忆

claude-memory banner

一个MCP服务器，在终端重启、上下文窗口压缩和会话期间为Claude Code提供持久内存——有针对性地访问相关的Claude Desktop/Claude.ai对话——以及 与claude.ai项目双向同步.

问题解决

1.终端重启会清除所有内容

当您的终端关闭时——计算机重新启动、崩溃、意外关闭——Claude Code会丢失所有上下文。你必须重新解释项目、当前状态、做出的决定以及正在进行的工作。

克劳德内存修复： 克劳德代码调用 save_session_checkpoint() 在自然停车点。下一次会议呼叫 resume_session() --一个调用会返回最新的检查点和所有链接的对话，因此工作会立即恢复，而无需重新解释。

2.上下文压缩会丢失屏幕截图

当Claude Code会话增长到足以触发压缩时，早期的消息会被总结，图像数据也会消失。错误、UI状态和错误对话框的屏幕截图变得无法恢复。

克劳德内存修复： 当共享图像时，Claude Code会立即调用 save_image() 将其复制到稳定的本地存储并记录描述。压实后， get_image(image_id) 返回存储的路径；这 Read 该工具像以前一样重新嵌入图像。

3.对话比文档包含更丰富的上下文

规划对话包括完整的思维过程——提问、拒绝备选方案、讨论权衡、决策及其理由——而不仅仅是最终输出。Claude Code阅读对话不仅理解 *什么* 建设但是 *为什么*.

4.克劳德桌面作为您的上下文中心

在Claude Desktop中配置所有集成（Confluence、Jira、Slack、浏览器扩展），使用这些工具进行对话，然后让Claude Code读取这些对话——在保持Claude Code轻量级的同时，仍然可以访问丰富的外部上下文。

5.与claude.ai项目双向同步

在claude.ai中进行研究，在claude Code中实现，将进度向后推——所有这些都在同一个项目中。Claude Code将状态摘要、TODO和会话日志推送到项目的知识库中。在claude.ai中完成的研究可以从CLI读取。多个仓库可以映射到一个项目。

claude.ai Project
    ├── [manually added] Research notes, design docs
    ├── [cli] Status - repo-name.md     ← auto-pushed from CLI
    ├── [cli] TODOs - repo-name.md      ← pushed from CLI
    └── Project knowledge docs          ← readable from CLI

CLI (repos with  in CLAUDE.md)
    ├── reads Project knowledge docs
    └── pushes status/TODOs automatically

工具

会话工具——本地，无需Chrome

图像持久性——本地，无需Chrome

项目对话注册表--本地，无需Chrome

Claude.ai对话阅读-需要Chrome登录

claude.ai项目同步--需要Chrome登录

垃圾回收--全部默认为 dry_run=True

需求

• Python 3.10+
• Chrome浏览器登录claude.ai *（仅适用于对话阅读工具；所有本地存储工具无需Chrome即可使用）*

安装

1. 克隆此存储库：

git clone https://github.com/AmmarJawad/claude-memory.git
cd claude-memory

1. 安装依赖项：

pip install -r requirements.txt

1. 添加到您的Claude Code MCP设置中(~/.claude.json):

{
  "mcpServers": {
    "claude-memory": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/claude-memory/server.py"]
    }
  }
}

适用于克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上：

{
  "mcpServers": {
    "claude-memory": {
      "command": "python3",
      "args": ["/path/to/claude-memory/server.py"]
    }
  }
}

避免上下文膨胀

使用 resume_session 在每个会话开始时-一个调用，没有API，返回继续所需的一切：

resume_session("/path/to/project")
# → {
#     "checkpoint": { "summary": "...", "current_task": "...", ... },
#     "linked_conversations": [{ "conversation_id": "abc-123", "note": "auth design — JWT..." }]
#   }

仅凭笔记，你通常就可以决定要拿什么（如果有的话）。如果注释不足：

get_conversation_summary("abc-123")  # cached after first fetch — no Chrome needed
get_conversation("abc-123")          # full content — last resort only

链接对话时，如果您没有提供对话名称和第一条消息，则会根据对话名称和消息自动生成备注：

link_conversation("/path/to/project", "abc-123")
# auto-note: "Auth Design Session: How should we handle token refresh? ..."

切勿呼叫 list_conversations 浏览相关对话--使用 get_project_conversations 相反。仅限呼叫 list_conversations 当明确地寻找新的对话进行链接时。

配置Claude Code以自动使用这些功能

将以下内容添加到您的项目中 CLAUDE.md （或您的全球 ~/.claude/CLAUDE.md).这指示Claude Code自动使用所有功能，而无需询问。

## Session continuity (via claude-memory MCP)

**At the start of every session:**
Call `resume_session` with the project path. It returns both the latest
checkpoint and all linked conversations in a single call. Read the checkpoint
to restore context. Read the conversation notes — fetch a conversation only
if the note indicates the content is needed right now.

Fetch order (leanest to most expensive):
- Note alone — skip fetch if it answers your question
- `get_conversation_summary(id)` — cached, no Chrome required after first fetch
- `get_conversation(id)` — full content, last resort only

**During the session:**
Call `save_session_checkpoint` whenever a significant milestone is reached.
If a claude.ai conversation proves useful, call `link_conversation` with just
the conversation ID — the note is auto-generated.

**Before stopping work:**
Always call `save_session_checkpoint` with:
- `summary`: what was accomplished (specific files, features, fixes)
- `current_task`: anything in-progress or interrupted mid-task
- `key_files`: comma-separated paths of files created or modified
- `decisions_made`: architectural or design choices and their rationale
- `open_questions`: blockers or things to investigate next

Never call `list_conversations` to browse — use `resume_session` or
`get_project_conversations` instead. Only call `list_conversations` when
explicitly asked to discover a new conversation to link.

## Image / screenshot continuity (via claude-memory MCP)

**When any image or screenshot is shared:**
Immediately call `save_image` with:
- `source_path`: the file path (if the image came from a file)
- `description`: detailed description of everything visible — UI elements,
  error text, file paths, layout. This survives even if the file is lost.
- `tags`: relevant tags (e.g. "screenshot,bug,login-page")

Note the returned `image_id` and `stored_path`.

**After context compaction (if an image is no longer visible):**
Call `get_image(image_id)` to retrieve the stored path, then use the Read
tool on `stored_path` to re-embed the image.

## claude.ai Project sync (via claude-memory MCP)

**Setup:** Add `` to this project's
CLAUDE.md to map it to a claude.ai Project.

**Push progress automatically:**
After significant milestones, call `push_session_summary` to push a
git-derived status summary to the Project. Use `push_todos` to share
the TODO list. Use `push_to_project` for custom content (design notes,
decisions, research summaries).

**Read Project knowledge:**
Call `list_project_docs` to see what's in the Project (including docs
added manually in claude.ai). Call `get_project_doc` to read specific
documents. This enables research done in claude.ai to flow back into CLI.

双向项目同步

设置

将项目映射标签添加到存储库的 CLAUDE.md:

这将仓库映射到具有该名称的claude.ai项目。多个仓库可以映射到同一个项目。

从CLI推送

# Push arbitrary content
push_to_project(content="# Design Notes\n\nWe chose approach B because...", doc_name="design-notes.md")

# Auto-generate and push status from git state
push_session_summary()
# → creates "[cli] Status - repo-name.md" with recent commits, branch, ahead count

# Push a TODO list
push_todos(todos=["[x] Implement auth", "Write tests", "Update docs"])
# → creates "[cli] TODOs - repo-name.md"

从CLI读取

# List all Projects
list_projects()

# Browse Project knowledge docs
list_project_docs()  # uses project from CLAUDE.md
list_project_docs(project="My Project Name")  # or specify explicitly

# Read a specific doc
get_project_doc(doc_id="abc-123")

自动化

使用附带的钩子脚本自动推送git事件：

# hooks/post_push.sh — runs: python -m context_bridge.push --auto
# Configure as a Claude Code PostToolUse hook or git post-commit hook

自动推送尊重2分钟的冷却时间，以避免API垃圾邮件。

存储

所有本地数据都存储在 ~/.claude-memory/ --不向任何外部服务发送任何内容。

~/.claude-memory/
├── sessions/    one JSON file per checkpoint, keyed by project path
├── images/      copied image files + JSON metadata, keyed by image ID
├── projects/    conversation registry, one JSON file per project
└── summaries/   cached conversation summaries, keyed by conversation ID

垃圾收集

所有清理工具默认为 dry_run=True --删除前预览。

# Preview
cleanup_session_checkpoints("/path/to/project", keep_latest=10)
cleanup_images(older_than_days=30)
cleanup_summaries(older_than_days=90)

# Delete for real
cleanup_session_checkpoints("/path/to/project", keep_latest=10, dry_run=False)
cleanup_images(older_than_days=30, dry_run=False)
cleanup_summaries(older_than_days=90, dry_run=False)

会话阅读是如何工作的

服务器读取Chrome的cookie以使用claude.ai API进行身份验证-不需要API密钥：

1. 在Chrome浏览器中登录claude.ai
2. 可访问Claude Desktop和Claude.ai网站上的对话
3. get_conversation_summary 在第一次获取时缓存其结果；后续通话不需要Chrome会话

运行测试

# Local storage tools (sessions, images, registries)
pytest test_server.py -v

# Project sync tools (context_bridge package)
pytest tests/ -v

# All tests
pytest test_server.py tests/ -v

test_server.py 涵盖所有本地存储工具。 tests/ 涵盖了项目同步包（auth、config、项目API、内容生成）。Claude.ai API工具需要实时Chrome会话，并且没有经过单元测试。

局限性

• 仅限Chrome 对于对话和项目工具，Safari和Firefox不受支持
• 对话是只读的 --对话不能写入或修改（可以编写项目知识文档）
• 基于文件的图像 — save_image 没有 source_path 仅存储描述；剪贴板粘贴的没有文件路径的图像无法另存为文件
• 会话到期 --claude.ai会话到期后重新登录Chrome

许可证

麻省理工学院