星战科技xingzhan.cloud
返回市场
克劳德记忆mcp

克劳德记忆mcp

作者：WhenMoon-afk40 星标更新：2025-11-05
安装使用来源：spider==github.com

项目介绍

claude-memory-mcp

npm 版本 许可证: MIT Node.js >= 18

适用于任何兼容MCP的AI的本地持久内存 这是一个轻量级的、零云服务、令牌高效的模型上下文协议（MCP）服务器，它为您的AI提供持久、可搜索且具有上下文感知的记忆——完全在您的控制之下。

使用TypeScript、SQLite + FTS5和最少的运行时依赖项（MCP SDK + better-sqlite3）构建，它在本地运行并将所有内容存储在一个便携的.db文件中。

与Claude Desktop、Cursor、Windsurf或任何MCP客户端兼容。

📦 现在可在npm上获取：通过npx @whenmoon-afk/memory-mcp安装

为什么选择本地内存？

您控制云服务
数据永远不会离开您的机器发送到远程服务器
便携的.db文件锁定在专有存储中
完整审计及备份不透明的保留策略
零持续成本需要订阅

功能

功能优点
双响应模式返回所有匹配项（紧凑索引）+ 在令牌预算内的完整详情
令牌预算自动尊重max_tokens（约30%索引，约70%详情）
混合相关性评分40%相关性，30%重要性，20%时效性，10%频率
自动总结生成≤20字的自然语言摘要
实体提取检测人物、工具、概念、偏好
FTS5全文搜索子10毫秒查询，Unicode，词干化——无需嵌入
来源追踪完整审计跟踪：来源、时间戳、更新
软删除保留记忆以供调试/回滚
单文件数据库memory.db ——自由复制、备份、移动

安装

先决条件

  • Node.js ≥ 18
  • 一个兼容MCP的客户端（Claude Desktop、Cursor、Windsurf等）

方案1：带有自动设置的NPM包（推荐）

自动安装（为您配置Claude Desktop）：

npx @whenmoon-afk/memory-mcp

这将自动：

  • 检测您的操作系统（macOS/Windows/Linux）
  • 将内存服务器添加到您的Claude Desktop配置中
  • 创建现有配置的备份
  • 配置正确的命令格式以适应您的平台

安装后，请完全重启Claude Desktop（退出并重新打开）。

或者全局安装：

npm install -g @whenmoon-afk/memory-mcp
memory-mcp

方案2：从源码安装

用于开发或定制：

git clone https://github.com/WhenMoon-afk/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build

输出：dist/index.js ——您的内存服务器。

与您的MCP客户端集成

添加到您的客户端MCP配置文件中：

Claude Desktop：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Cursor/Windsurf：检查您编辑器的MCP设置

💡 推荐：使用自动安装程序（npx @whenmoon-afk/memory-mcp），它会自动处理平台差异。

手动配置（macOS/Linux）

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@whenmoon-afk/memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}

手动配置（Windows）

Windows需要cmd /c包装器来正确执行npx：

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@whenmoon-afk/memory-mcp"],
      "env": {
       - "MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}

使用全局安装

{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp",
      "env": {
        "MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}

从源码

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/绝对路径/to/claude-memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}

重启或重新加载MCP服务器。

MCP工具

工具输入描述
memory_store{ content, type, importance?, entities?, ttl_days?, provenance? }存储或更新记忆，带有自动摘要
memory_recall{ query, type?, entities?, limit?, max_tokens? }搜索记忆，带有令牌感知加载
memory_forget{ id, reason? }软删除记忆（保留来源信息）

存储偏好

{
  "tool": "memory_store",
  "input": {
    "content": "用户在专注的90分钟工作块和15分钟休息时表现最佳。",
    "type": "事实",
    "importance": 8
  }
}

→ 自动创建：

  • 摘要："用户遵循90/15专注工作周期。"
  • 实体：专注工作，90分钟工作块
  • 来源：当前会话

智能召回（双响应）

{
  "tool": "memory_recall",
  "input": {
    "query": "工作习惯",
    "max_tokens": 1200
  }
}

响应：

{
  "index": [
    { "id": "mem_8b1", "summary": "用户遵循90/15专注工作周期。", "score": 96 },
    { "id": "mem_2c9", "summary": "用户避免上午10点前的会议。", "score": 88 }
  ],
  "details": [
    {
      "id": "mem_8b1",
      "content": "用户在专注的90分钟工作块和15分钟休息时表现最佳。",
      "entities": ["专注工作", "90分钟工作块"],
      "provenance": { "source": "chat_2025-11-03", "created_at": "2025-11-03T14:10Z" }
    }
  ],
  "meta": {
    "tokens_used": 698,
    "total_matches": 2,
    "truncated": false
  }
}

您的AI知道它所知道的——并且可以请求更多。

忘记记忆

{
  "tool": "memory_forget",
  "input": {
    "id": "mem_8b1",
    "reason": "信息不再相关"
  }
}

响应：

{
  "success": true,
  "memory_id": "mem_8b1",
  "message": "记忆已成功软删除。原因：信息不再相关"
}

被软删除的记忆在数据库中保留完整的来源信息。它们不会出现在搜索结果中，但仍然可以恢复。

双响应模式

[index]   → 所有匹配摘要（每个约20个令牌）
[details] → 最高记忆的完整内容（预算限制）
[meta]    → 使用的令牌数，总匹配数，是否截断
  • 索引：始终包含 → 发现
  • 详情：预算安全 → 精确度
  • 后续：使用ids: [...]扩展

数据库及便携性

  • 文件：memory.db（SQLite）——路径通过MEMORY_DB_PATH
  • 便携：复制到USB、云同步或新机器
  • 备份：只需复制文件
  • 提示：为了额外的安全性，将memory.db存储在VeraCrypt加密USB驱动器上（增加摩擦，但最大控制）。

依赖项

此项目使用最少的运行时依赖项以保持包的轻量级：

依赖项版本目的
@modelcontextprotocol/sdk^1.0.4官方MCP协议实现
better-sqlite3^11.0.0快速的原生SQLite3绑定，支持FTS5

为什么这些依赖项？

  • MCP SDK：实现模型上下文协议标准所需
  • better-sqlite3：全文搜索和数据库操作的原生性能，对于记忆召回速度至关重要

所有其他依赖项仅用于开发（TypeScript、测试、代码检查）。

环境变量

变量默认值描述
MEMORY_DB_PATH./memory.db数据库文件位置
DEFAULT_TTL_DAYS90记忆默认生存期（天）

安全性

这是一个仅限本地的MCP服务器。 数据存储在一个普通的SQLite文件（memory.db）中。 对于敏感数据，使用操作系统级别的加密（FileVault，BitLocker）。

最佳实践

  1. 从max_tokens: 1000开始 — 根据模型和任务调整。
  2. 按type过滤以减少噪音并提高相关性。
  3. 使用实体过滤以缩小特定主题的搜索范围。
  4. 参考来源：跟踪来源和上下文以进行审计跟踪。
  5. 定期备份memory.db — 它只是一个文件！

快捷链接

贡献

欢迎贡献！您可以：

  • 通过GitHub Issues报告错误或请求功能
  • 提交改进的拉取请求
  • 分享您的用例和反馈

许可证

MIT 许可证 - 详情见LICENSE文件。

版权所有 (c) 2025 WhenMoon-afk

为MCP社区打造 ❤️