AI导哈

Claude代码记忆代理

一个实验性项目，通过结合内存服务器和流代理为Claude代码提供持久性记忆功能。

  • by shtratos
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 shtratos/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 当地参考：

先决条件

  • 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

  2. 启动流媒体代理

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

    验证它是否健康：

    curl http://localhost:15041/health

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

    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/<timestamp>/
  • 如果上游响应报告错误，则打印简短的故障排除提示
  • 要使用mitmproxy捕获流量，请导出 HTTP(S)_PROXY, NO_PROXY，以及在运行脚本之前的任何证书包变量。

助手脚本

脚本 描述 要求
scripts/invoke_memory_tool.py 发送强制调用内存工具的最小Anthropic API请求。适用于在没有完整客户端的情况下调试翻译。 requests (uv sync --group dev)
scripts/run_proxy.sh 使用环境变量启动代理的便利包装器。 无

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

测试与开发

  • 运行单元测试：

    uv run pytest

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

    uv sync --group dev

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

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

配置参考

变量 默认值 描述
MEMORY_DIR ./memories 存储内存的根目录
UPSTREAM_API_URL https://api.anthropic.com 人类API的基本URL
PROXY_HOST 127.0.0.1 代理绑定到的主机地址
PROXY_PORT 15041 代理监听的端口
ANTHROPIC_API_KEY （无） 已传递给上游请求 x-api-key
ANTHROPIC_BETA context-management-2025-06-27 逗号合并到 anthropic-beta 标题（不区分大小写）
CLAUDE_MODEL claude-sonnet-4-5 辅助脚本中使用的默认模型
SYSTEM_PROMPT_PATCHES （无） 包含系统提示补丁的JSON文件的路径（见下文）

两个工具前缀(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
    }
  ]
}

领域：

字段 类型 描述
find string 在系统提示块中搜索的文本模式
replace string 要替换的文本匹配
required boolean 如果 true，如果找不到模式，则使用HTTP 500请求失败

行为：

  • 补丁应用于系统提示数组中的所有文本块
  • 每个补丁都执行一个简单的字符串替换（不是正则表达式）
  • 如果 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 负责任的使用指南。

相关 MCP