Claude Code Memory Proxy

Claude代码内存代理

一个实验性的周末项目，为Claude Code（和其他MCP客户端）提供持久内存 今天 通过组合：

• memory-server –实现Anthropic的模型上下文协议（MCP）服务器 memory_20250818 该工具位于本地文件系统之上，具有严格的路径验证。
• memory-proxy –一个FastAPI流式代理，在MCP格式之间重写工具元数据(mcp__memory__memory_20250818 / memory__memory_20250818)以及上游人类API格式(memory)同时保留SSE流语义。

ℹ️ 这是在官方的Claude Code内存功能发布之前构建的。它可能很快就会过时，但翻译模式和代理工作流程仍然有用。

______________________________________________________________________

特性

• 下面的文件备份内存存储 /memories，防止路径遍历和根删除。
• 双向工具名称转换（支持两者 mcp__memory__memory_20250818 以及遗产 memory__memory_20250818 前缀）。
• 流安全SSE重写，这样客户端可以看到前缀为MCP的工具名称，而上游API可以看到本机名称。
• 用于端到端验证的辅助脚本（curl烟雾测试、mitmproxy日志检查、Claude CLI场景运行器）。

______________________________________________________________________

官方文件：

• Claude代码概述：https://docs.claude.com/en/docs/claude-code/overview
• 人类记忆工具参考：https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool

项目规划说明： docs/TASK_PLAN.md 当地参考：

• 记忆工具参考
• 内存SDK示例

先决条件

• Python 3.12+
• 什么之中的一个：

- uv （推荐） - 标准 pip /virtualenv工具

• 访问无烟煤API(https://api.anthropic.com)
• 可选：

- claude CLI（用于自动场景脚本） - mitmproxy 如果你想捕捉上游流量

______________________________________________________________________

安装

克隆存储库并安装依赖项 uv:

uv sync

全局公开CLI入口点（可选但方便）：

uv tool install -e .

这将安装：

• memory-server –MCP内存服务器入口点
• memory-proxy –流媒体代理入口点

使用 pip 相反：

python -m venv .venv
source .venv/bin/activate
pip install -e .

______________________________________________________________________

快速开始

1. 启动MCP内存服务器

   MEMORY_DIR=./memories uv run memory-server

您可以使用MCP检查器进行检查：

   npx @modelcontextprotocol/inspector memory-server

1. 启动流媒体代理

   UPSTREAM_API_URL=https://api.anthropic.com \
   PROXY_PORT=15041 \
   uv run memory-proxy

验证它是否健康：

   curl http://localhost:15041/health

1. 通过代理转发请求 （必要时更换型号）

   curl -N http://localhost:15041/v1/messages \
     -H "Content-Type: application/json" \
     -H "anthropic-version: 2023-06-01" \
     -H "x-api-key: $ANTHROPIC_API_KEY" \
     -d '{
       "model": "'${CLAUDE_MODEL:-claude-sonnet-4-5}'",
       "stream": true,
       "tools": [{"name": "mcp__memory__memory_20250818"}],
       "messages": [{"role": "user", "content": "Check your memory."}]
     }'

代理在向上游转发之前删除MCP前缀，并将其添加回流式响应中。

______________________________________________________________________

自动化场景（Claude CLI）

scripts/run_claude_memory_scenario.sh 对代理驱动一个三提示非交互式会话，以确认内存读/写行为。

要求：

• claude CLI已安装并配置
• mitmproxy 证书可在 ~/.mitmproxy
• （可选）已导出 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 覆盖默认值

脚本：

• 在下面创建一个隔离的内存目录 data/
• 生成每次运行的Claude设置/MCP配置
• 日志输出到 data/random-access-memories//
• 如果上游响应报告错误，则打印简短的故障排除提示
• 要使用mitmproxy捕获流量，请导出 HTTP(S)_PROXY, NO_PROXY，以及在运行脚本之前的任何证书包变量。

______________________________________________________________________

助手脚本

所有辅助脚本都尊重 HTTP(S)_PROXY 因此，在需要时，它们可以通过mitmproxy进行路由。

______________________________________________________________________

测试与开发

• 运行单元测试：

  uv run pytest

• 开发依赖关系（包括 pytest, requests，以及 mitmproxy)可以通过以下方式安装：

  uv sync --group dev

• 代理和辅助脚本荣誉 HTTP_PROXY / HTTPS_PROXY 环境变量，因此您可以使用mitmproxy或其他工具检测上游调用。

• 持续集成尚未建立；在打开pull请求之前，在本地运行测试套件。

______________________________________________________________________

配置参考

两个工具前缀(mcp__memory__memory_20250818 和 memory__memory_20250818)被代理接受并重写为上游本机 {"name": "memory", "type": "memory_20250818"} 格式。

代理转发除逐跳报头之外的所有报头（例如。， host, content-length, connection).客户端设置的令牌和跟踪标头将被保留。

系统提示修补

代理支持在向上游转发请求之前修改系统提示内容。这对于定制Claude的行为或注入上下文非常有用。

要启用系统提示修补，请设置 SYSTEM_PROMPT_PATCHES 到JSON配置文件的路径：

SYSTEM_PROMPT_PATCHES=/path/to/patches.json uv run memory-proxy

配置格式：

JSON文件必须包含 replacements 数组，其中每个条目指定一个查找/替换操作：

{
  "replacements": [
    {
      "find": "text to find in system prompt",
      "replace": "replacement text",
      "required": false
    },
    {
      "find": "another pattern",
      "replace": "another replacement",
      "required": true
    }
  ]
}

领域：

行为：

• 补丁应用于系统提示数组中的所有文本块
• 每个补丁都执行一个简单的字符串替换（不是正则表达式）
• 如果 required 是 true 和那个 find 模式不存在于任何系统提示块中，代理返回HTTP 500错误
• 如果 required 是 false （默认），缺失的模式将被默认忽略
• 补丁按照它们在配置中出现的顺序应用

______________________________________________________________________

兼容性和注意事项

• 实施目标 memory_20250818如果Anthropic修改了内存工具模式或标识符，则相应地更新代理转换常数。
• 文件备份存储是运行MCP服务器的计算机的本地存储。此项目不提供身份验证、配额或远程存储。
• 将其视为参考/实验性实现。一旦官方的Claude Code内存功能发布，预计将再次访问。

______________________________________________________________________

限制和注意事项

• 这是一个基于本地文件的原型，不实现身份验证、配额或远程存储。
• 使用自主代理快速构建；期待粗糙的边缘，并将其视为参考实现。
• Claude Code memory的官方Anthropic支持可能很快就会取代这个项目。

______________________________________________________________________

故障排除

• 上游回报 400 –双重检查 ANTHROPIC_API_KEY, ANTHROPIC_BETA以及型号可用性。辅助脚本默认为安全占位符值。
• 使用mitmproxy时出现SSL错误 –确保 ~/.mitmproxy/combined-ca-bundle.crt 存在和 claude CLI信任它。
• 工具未被调用 –确认客户广告 mcp__memory__memory_20250818 （或 memory__memory__20250818)代理会重写它（请参阅助手脚本和代理日志）。

______________________________________________________________________

许可证

根据 MIT许可证.

______________________________________________________________________

致谢

• 人类MCP 对于服务器框架
• fastapi, httpx，以及 uvicorn 对于代理堆栈
• 在一个周末帮助原型制作的许多代理工作流程
• 看 建筑.md 查看高级组件概述。
• 看 安全.md 负责任的使用指南。