金大哥 - mnemo MCP 详情

article

README

🚀 Mnemo

Mnemo借助Gemini上下文缓存为AI助手提供扩展内存。

Mnemo（希腊语：记忆）通过利用Gemini的100万个标记上下文窗口和上下文缓存功能，让Claude等AI助手能够访问大型代码库、文档网站、PDF文件等。

🚀 快速开始

部署选项

Mnemo可以根据你的需求以三种方式进行部署。

选项1：本地服务器（开发与全功能）

适用于开发以及需要加载本地文件的场景。

# 克隆并安装
git clone https://github.com/logos-flux/mnemo
cd mnemo
bun install

# 设置你的Gemini API密钥
export GEMINI_API_KEY=your_key_here

# 启动服务器
bun run dev

Claude Code MCP配置：

{
  "mcpServers": {
    "mnemo": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

选项2：自托管Cloudflare Worker（推荐用于Claude.ai）

部署到你自己的Cloudflare账户。你可以控制自己的数据和成本。

前提条件：

Cloudflare账户（免费套餐即可）
Gemini API密钥

# 克隆并安装
git clone https://github.com/logos-flux/mnemo
cd mnemo/packages/cf-worker

# 配置密钥
bunx wrangler secret put GEMINI_API_KEY
bunx wrangler secret put MNEMO_AUTH_TOKEN  # 可选，但推荐

# 创建D1数据库
bunx wrangler d1 create mnemo-cache

# 部署
bunx wrangler deploy

Claude.ai MCP配置：

{
  "mcpServers": {
    "mnemo": {
      "type": "http",
      "url": "https://mnemo.<your-subdomain>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}

为何使用此选项？ Claude.ai无法连接到本地主机。Worker可为你提供一个Claude.ai能够访问的外部端点。

选项3：托管服务（VIP）

如果你不想管理基础设施，我们为特定客户提供完全托管的Mnemo服务。

包含内容：

专用Worker部署
优先支持
自定义域名
使用情况监控

联系信息： 请发送邮件至lf@logosflux.io了解价格和可用性。

✨ 主要特性

为何选择Mnemo？

与使用嵌入和检索的复杂RAG管道不同，Mnemo采用了更简单的方法：

将整个代码库加载到Gemini的上下文缓存中
使用自然语言进行查询
让Claude进行编排，同时由Gemini保存上下文

这将为你带来以下优势：

完美回忆 - 无需分块或检索，不会丢失上下文
低延迟 - 缓存的上下文可以快速提供服务
节省成本 - 缓存标记的成本比常规输入标记低75 - 90%
简单易用 - 无需向量数据库、嵌入或复杂的检索逻辑

📦 安装指南

根据上述部署选项操作即可完成安装。

💻 使用示例

基础用法

命令行示例

# 加载GitHub仓库
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://github.com/honojs/hono", "alias": "hono"}'

# 加载文档网站（爬取至标记目标）
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://hono.dev/docs", "alias": "hono-docs"}'

# 加载PDF文件
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://arxiv.org/pdf/2303.08774.pdf", "alias": "gpt4-paper"}'

# 加载私有仓库（使用GitHub令牌）
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://github.com/owner/private-repo", "alias": "private", "githubToken": "ghp_xxx"}'

# 将多个源加载到一个缓存中
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"sources": ["https://github.com/owner/repo", "https://docs.example.com"], "alias": "combined"}'

# 查询缓存
curl -X POST http://localhost:8080/tools/context_query \
  -H "Content-Type: application/json" \
  -d '{"alias": "hono", "query": "How do I add middleware?"}'

# 列出活动缓存
curl -X POST http://localhost:8080/tools/context_list \
  -H "Content-Type: application/json" -d '{}'

# 获取使用统计信息并跟踪成本
curl -X POST http://localhost:8080/tools/context_stats \
  -H "Content-Type: application/json" -d '{}'

# 完成后清除缓存
curl -X POST http://localhost:8080/tools/context_evict \
  -H "Content-Type: application/json" \
  -d '{"alias": "hono"}'

CLI示例

# 启动服务器
mnemo serve

# 启动MCP标准输入输出传输（适用于Claude桌面版）
mnemo stdio

# 加载项目
mnemo load ./my-project my-proj

# 查询
mnemo query my-proj "What's the main entry point?"

# 列出缓存
mnemo list

# 删除缓存
mnemo evict my-proj

📚 详细文档

Mnemo可以加载哪些内容？

| 源 | 本地服务器 | 工作器 | |--------|--------------|--------| | GitHub仓库（公共） | ✅ | ✅ | | GitHub仓库（私有） | ✅ | ✅ | | 任何URL（文档、文章） | ✅ | ✅ | | PDF文档 | ✅ | ✅ | | JSON API | ✅ | ✅ | | 本地文件/目录 | ✅ | ❌ | | 多页爬取 | ✅ 无限制 | ✅ 最多40页 |

MCP工具

| 工具 | 描述 | |------|-------------| | context_load | 将GitHub仓库、URL、PDF或本地目录加载到Gemini缓存中 | | context_query | 使用自然语言查询缓存的上下文 | | context_list | 列出所有活动缓存，包括标记计数和过期时间 | | context_evict | 删除缓存 | | context_stats | 获取使用统计信息并跟踪成本 | | context_refresh | 使用新内容重新加载缓存 |

context_load参数

| 参数 | 描述 | |-----------|-------------| | source | 单个源：GitHub URL、任何URL或本地路径 | | sources | 多个源，合并到一个缓存中 | | alias | 此缓存的友好名称（1 - 64个字符） | | ttl | 存活时间（秒）（60 - 86400，默认3600） | | githubToken | 用于私有仓库的GitHub令牌 | | systemInstruction | 用于查询的自定义系统提示 |

配置

| 变量 | 描述 | 默认值 | |----------|-------------|---------| | GEMINI_API_KEY | 你的Gemini API密钥 | 必需 | | MNEMO_PORT | 服务器端口（仅本地） | 8080 | | MNEMO_DIR | 数据目录（仅本地） | ~/.mnemo | | MNEMO_AUTH_TOKEN | 受保护端点的认证令牌 | 无 |

认证

当配置了MNEMO_AUTH_TOKEN时，/mcp和/tools/*端点需要进行认证：

# 设置认证令牌（工作器）
bunx wrangler secret put MNEMO_AUTH_TOKEN

# 请求必须包含头部信息：
Authorization: Bearer your-token-here

公共端点（无需认证）：

GET /health - 健康检查
GET / - 服务信息
GET /tools - 列出可用工具

成本

无论采用何种部署选项，你始终需要支付Gemini API的使用费用。Mnemo使用Gemini的上下文缓存，其成本远低于标准输入：

| 资源 | 成本 | |----------|------| | 缓存存储 | 每100万个标记每小时约$4.50 | | 缓存输入 | 比常规输入便宜75 - 90% | | 常规输入 | 每100万个标记约$0.075（Flash） |

示例： 一个10万个标记的代码库缓存1小时并进行10次查询，费用约为$0.47

Cloudflare成本（自托管）：

工作器：免费套餐每天包含10万次请求
D1：免费套餐每天包含500万次读取
适度使用可能费用为$0

🔧 技术细节

架构

┌─────────────────────────────────────────────────────────────┐
│                         Mnemo                                │
├─────────────────────────────────────────────────────────────┤
│  MCP Tools                                                   │
│  • context_load    - Load into Gemini cache                 │
│  • context_query   - Query cached context                   │
│  • context_list    - Show active caches                     │
│  • context_evict   - Remove cache                           │
│  • context_stats   - Token usage, costs                     │
│  • context_refresh - Reload cache                           │
├─────────────────────────────────────────────────────────────┤
│  Adapters (v0.2)                                             │
│  • GitHub repos (via API)                                   │
│  • URL loading (HTML, PDF, JSON, text)                      │
│  • Token-targeted crawling                                  │
│  • robots.txt compliance                                    │
├─────────────────────────────────────────────────────────────┤
│  Packages                                                    │
│  • @mnemo/core      - Gemini client, loaders, adapters      │
│  • @mnemo/mcp-server - MCP protocol handling                │
│  • @mnemo/cf-worker - Cloudflare Workers deployment         │
│  • @mnemo/local     - Bun-based local server                │
└─────────────────────────────────────────────────────────────┘

📄 许可证

本项目采用MIT许可证。

致谢

本项目由Logos Flux和Voltage Labs开发。

mnemo