Mem Persistence

mem持久性

🧠 用于AI代理的持久内存MCP服务器——一个内存，每个代理，你的文件。

mem持久化允许Claude Desktop、Claude Code、Cursor、Zed和任何兼容MCP的客户端共享相同的持久内存，由您拥有的纯Markdown文件支持，可以手动编辑。

为什么？

人工智能代理有健忘症。每个工具都有自己的筒仓——Claude Code忘记了OpenClaw所知道的，Cursor不记得你昨天告诉Claude了什么。你的上下文分散在蒸发的会话中。

mem持久性解决了这个问题：

• Markdown是真理的源泉 --不是数据库，也不是二进制blob。您可以使用git读取、编辑和版本的文件。
• 混合搜索 --标记匹配+语义嵌入，实现准确回忆。
• 嵌入提供者 --Gemini（免费）、OpenAI或无（仅代币）。已缓存到磁盘。
• 去重 --防止将同一事实写入两次（令牌+实体重叠检测）。
• 离线工作 --无云依赖。嵌入是可选的。

MCP工具

______________________________________________________________________

快速开始

1.安装和构建

git clone https://github.com/emiliotorrens/mem-persistence.git
cd mem-persistence
npm install
npm run build

2.启动服务器

node dist/index.js --workspace /path/to/your/workspace --port 3456

3.连接客户端

选择与您的客户端匹配的设置——请参阅 客户端设置 在......下面

4.添加代理说明

复制 AGENT_INSTRUCTIONS.md 进入您代理的指令文件：

______________________________________________________________________

客户端设置

有两个MCP传输。你需要哪一个取决于客户：

HTTP客户端（克劳德代码、游标、Zed）

指向正在运行的服务器URL:

{
  "mcpServers": {
    "memory": {
      "url": "http://127.0.0.1:3456/mem-persistence/mcp"
    }
  }
}

对于通过Tailscale进行远程访问，请更换 127.0.0.1 使用服务器的Tailscale主机名：

{
  "mcpServers": {
    "memory": {
      "url": "http://my-machine.tail1234.ts.net:3456/mem-persistence/mcp"
    }
  }
}

克劳德桌面（stdio，同一台机器）

Claude Desktop只支持stdio——它将内存持久性作为子进程生成。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": [
        "/path/to/mem-persistence/dist/index.js",
        "--workspace", "/path/to/your/workspace"
      ],
      "env": {
        "MEM_PERSISTENCE_EMBEDDINGS": "gemini",
        "GOOGLE_API_KEY": "your-key-here"
      }
    }
  }
}

WSL用户（Windows）： 替换 "command": "node" 随着 "command": "wsl" 并添加 "node" 作为第一要素 args.

⚠️ 禁止通行 --port 在stdio模式下。 它会导致 EADDRINUSE 如果HTTP实例已在运行，则会发生冲突。

通过代理远程克劳德桌面

如果Claude Desktop在 不同的机器 （例如，笔记本电脑）如果没有安装内存持久性，请使用捆绑的 mcp-proxy.js 将stdio桥接到远程HTTP服务器。

客户端机器的要求： Node.js+Tailscale。就是这样——没有克隆，没有 npm install.

1. 复制 mcp-proxy.js 到笔记本电脑（一个文件，零依赖）。
2. 添加到Claude桌面配置：

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-proxy.js"],
      "env": {
        "MCP_REMOTE_URL": "http://my-machine.tail1234.ts.net:3456/mem-persistence/mcp"
      }
    }
  }
}

Desktop认为它正在与本地stdio服务器通信；代理通过HTTP转发所有内容。

集 MCP_DEBUG=1 将代理流量记录到stderr以进行故障排除。

______________________________________________________________________

作为服务运行（PM2）

对于生产使用，使用PM2将服务器作为持久后台服务运行：

# 1. Install pm2
npm install -g pm2

# 2. Copy and edit the config
cp ecosystem.config.cjs.example ecosystem.config.cjs
# → Set workspace path and optional API keys

# 3. Start and persist
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup    # autostart on reboot (follow the printed instructions)

健康检查： curl http://127.0.0.1:3456/health

______________________________________________________________________

网络绑定

默认情况下，服务器会监听 127.0.0.1 只有。使用 --bind 控制它绑定到哪些接口：

# Localhost + Tailscale (recommended for remote access)
node dist/index.js --workspace /path --port 3456 --bind 127.0.0.1,tailscale

# Localhost + explicit VPN IP
node dist/index.js --workspace /path --port 3456 --bind 127.0.0.1,10.0.0.5

# All interfaces (⚠️ only behind a firewall)
node dist/index.js --workspace /path --port 3456 --bind all

在 ecosystem.config.cjs:

args: '--workspace /path --port 3456 --bind 127.0.0.1,tailscale',

或者通过环境变量： MEM_PERSISTENCE_BIND=127.0.0.1,tailscale

⚠️ 安全： mem持久性没有内置身份验证。 切勿将端口暴露于公共互联网。 使用 --bind 127.0.0.1,tailscale 限制对localhost+您的专用网络的访问。

______________________________________________________________________

工作区

这 --workspace 标志指向包含内存文件的目录。mem持久性索引全部 .md 递归文件。

任何目录 .md 文件工作。分层布局可以提高搜索质量：

有关此结构的自动设置（使用crons、dedup和知识图），请参阅 分层内存堆栈.

您还可以通过环境变量设置工作空间： MEM_PERSISTENCE_WORKSPACE=/path/to/workspace

______________________________________________________________________

嵌入

默认情况下，搜索使用 仅进行令牌匹配 （Jaccard+包容+实体重叠）。无API调用，可脱机工作。

启用嵌入会增加 语义理解:

获取免费的Gemini API密钥 → aistudio.google.com → 获取API密钥。

通过环境变量进行配置：

MEM_PERSISTENCE_EMBEDDINGS=gemini    # "gemini" or "openai"
GOOGLE_API_KEY=your-key              # Gemini — free
OPENAI_API_KEY=your-key              # OpenAI — $0.02/M tokens

细节：

• 混合评分：0.4×令牌+0.6×矢量
• 磁盘缓存: .mem-persistence/embeddings/ -没有重复的API调用
• 默认模型: gemini-embedding-001 （免费，1500次/分钟）
• 无声回退：如果API不可用，则仅自动回退到标记

______________________________________________________________________

去重

在编写之前，mem持久性检查是否已经存在类似的内容：

Input:  "GitHub configured with gh auth login, user emiliotorrens"
Match:  "gh auth login hecho — cuenta emiliotorrens, protocolo HTTPS"
Result: DUPLICATE (score: 0.90) — not written

使用令牌相似性（Jaccard+包含）和实体重叠（ID、日期、版本、URL）。

调整阈值： MEM_PERSISTENCE_DEDUP_THRESHOLD=0.65 （默认值--更低=更严格）。

______________________________________________________________________

OpenClaw集成

如果你使用 开爪，mem持久性与OpenClaw的原生内存共存：

• 外部客户端 （克劳德桌面、代码、光标）→ 通过内存持久性（stdio或HTTP）连接
• OpenClaw 智能体 → 使用其原生 memory-core 具有混合搜索+嵌入功能的插件

两个系统都索引相同的Markdown文件。mem持久性是外部客户端的MCP桥梁；OpenClaw处理自己的回忆、维基编译和做梦。

______________________________________________________________________

路线图

• \[x\] 重复数据删除引擎
• \[x\] 混合搜索（标记+向量+MMR+时间衰减）
• \[x\] MCP服务器——stdio和HTTP传输，6个工具，TypeScript+ESM
• \[x\] 嵌入提供者：Gemini（免费）和OpenAI，带磁盘缓存
• \[x\] 请求/响应日志记录(.mem-persistence/logs/)
• \[x\] HTTP模式——尾标友好，pm2就绪
• \[x\] stdio→远程Claude Desktop的HTTP代理
• \[\]CLI(mem-persistence search "query")
• \[\]通过transformers.js的本地嵌入（离线，无API密钥）
• \[\]npm发布

______________________________________________________________________

相关

• 分层内存堆栈 --OpenClaw技能，建立具有自动维护功能的3层内存系统。使用内存持久性作为外部客户端的MCP桥。

学分

• 开爪 --诞生并经过战斗测试的代理框架
• 主控程序 --使跨代理内存成为可能的协议

许可证

麻省理工学院

______________________________________________________________________