Shelby MCP

The memory backbone for Shelby — and a standalone knowledge-graph memory server for any MCP-compatible AI tool.

Mem0-grade intelligence. Engram-grade simplicity.

Quick Start · Architecture · Agent Setup · Contributing

______________________________________________________________________

ShelbyMCP是什么？

每个AI内存服务器都是一个嵌入式包。 ShelbyMCP连接你的思想。

ShelbyMCP是 谢尔比 --您在Mac上的AI同事，以及一个零依赖的MCP内存服务器，您可以使用任何兼容MCP的AI工具独立运行。它为克劳德密码、光标、密码、风帆、双子座、反重力和其他人提供了持久的记忆，可以理解你的想法是如何相关的，而不仅仅是它们包含什么。

用 觅食技能，您在自己的Claude Code（或Codex/Gemini CLI）会话中运行的计划任务，以不断丰富、巩固和连接您的记忆。饲料用途 *你的* 订阅——就像你自己使用Claude Code一样——所以ShelbyMCP本身保持零成本和零云。没有Docker。没有Python。没有云帐户。只有一个二进制文件和一个数据库文件。

这适合谢尔比的地方Shelby是一个基于三层的人工智能同事——伴侣（体验）、工具（承载上下文、执行治理、保存历史的运行时）和内存（此服务器）。如果你想要完整的同事体验，请安装Shelby for Mac。如果你只想要现有AI工具的内存主干，ShelbyMCP单机版就是你想要的。

为什么选择ShelbyMCP？

______________________________________________________________________

快速开始

1.安装

# npx (no install needed)
npx shelbymcp

# Or install globally
npm install -g shelbymcp

# Or build from source
git clone https://github.com/Studio-Moser/shelbymcp.git
cd shelbymcp && npm install && npm run build

2.设置您的代理

CLI会自动配置一切——MCP服务器注册、内存协议和可选的Forage技能：

shelbymcp setup claude-code --forage    # Claude Code CLI
shelbymcp setup claude-desktop --forage # Claude Desktop app
shelbymcp setup cursor --forage         # Cursor IDE
shelbymcp setup codex --forage          # OpenAI Codex
shelbymcp setup windsurf --forage       # Windsurf (Codeium)
shelbymcp setup gemini --forage         # Gemini CLI
shelbymcp setup antigravity --forage    # Antigravity (Google)

掉落 --forage 如果你只想要MCP服务器，而不需要预定的丰富技能。

就是这样。CLI注册MCP服务器，将内存协议添加到正确的位置，并安装觅食技能。看 docs/AGENT-SETUP.md 有关手动配置和特定于平台的详细信息。

3.添加内存协议

大多数代理在安装过程中会自动添加内存协议。对于需要手动步骤的代理，CLI将确切地告诉您要做什么。以下是它的位置：

shelbymcp protocol >> ~/.claude/CLAUDE.md                              # Claude Code (auto)
shelbymcp protocol >> ~/.codex/AGENTS.md                               # Codex (auto)
shelbymcp protocol >> ~/.codeium/windsurf/memories/global_rules.md     # Windsurf (auto)
shelbymcp protocol >> ~/.gemini/GEMINI.md                              # Gemini CLI / Antigravity (auto)

对于光标，粘贴到 设置>规则>用户规则。对于Claude Desktop，请粘贴到 设置>常规>“克劳德在回答时应该考虑哪些个人偏好？”.内存协议告诉您的代理 *当* 保存和搜索——没有它，这些工具是可用的，但不会主动使用。

4.播种你的记忆

安装后数据库为空。有三种方法可以立即使其有用：

# Option A: Run the onboarding interview (recommended)
# Paste this into a conversation — it asks a few questions and saves 15-30 memories
shelbymcp onboard

# Option B: Import from another AI tool
# Paste this prompt into ChatGPT/Claude/Gemini, copy the response back
shelbymcp migrate

# Option C: Just start working — memories accumulate naturally over time

这 上船 skill会进行一次对话式面试，内容包括你是谁、你在建设什么、你的团队、偏好和反模式。大约需要5分钟。这 迁移 提示告诉你的其他人工智能工具以ShelbyMCP可以导入的结构化格式导出他们所知道的关于你的一切。

5.验证

问你的经纪人： *“你们有什么记忆工具？”*

它应该列出9个工具。然后测试： *“请记住，我在所有应用程序中都更喜欢黑暗模式。”* --在新的会议上： *“你对我的喜好了解多少？”*

______________________________________________________________________

运作原理

You (in Claude Code): "We decided to use CloudKit for sync instead of Firebase"

Claude Code → capture_thought tool → ShelbyMCP:
  1. Stores thought in SQLite
  2. Agent provides metadata (type: decision, topics: [sync, cloud])
  3. Agent suggests relationships to existing thoughts
  4. FTS5 indexes content for keyword search

Later:
You: "What did we decide about our sync strategy?"

Claude Code → search_thoughts tool → ShelbyMCP:
  1. FTS5 keyword search for "sync strategy"
  2. Returns thought + all connected thoughts via knowledge graph
  3. Agent has full context of decisions, alternatives considered, and related work

使用觅食技能（计划，每天）：

Forage runs on Claude Code's scheduler:
  1. Backfills embeddings for thoughts that don't have them
  2. Re-classifies poorly tagged thoughts
  3. Finds duplicate thoughts and merges them
  4. Detects contradictions ("we said PostgreSQL last month but SQLite this week")
  5. Discovers connections between thoughts across projects
  6. Sweeps for stale action items that fell through the cracks
  7. Generates a weekly digest of your thinking

______________________________________________________________________

MCP工具

9个专注的工具——研究表明，每台服务器5-8个工具是代理准确性的最佳选择。

______________________________________________________________________

知识图谱

ShelbyMCP与其他内存服务器的不同之处在于知识图。思想不是孤立的，它们是相互联系的。

边缘类型

代理在捕获时创建边缘（“这个决定与思维X有关”），随着时间的推移，觅食技能会发现额外的联系。

______________________________________________________________________

觅食技能

ShelbyMCP配备 shelby-forage，一项预定的技能 *你* 在您自己选择的AI工具（Claude Code、Codex、Gemini CLI）中运行，以不断提高您的记忆力。该技能在您的会话内、在您的订阅上执行——ShelbyMCP本身从不对呼叫进行身份验证。服务器保持零依赖性，您的订阅条款正常适用，智能来自您已经付费的工具。

设置

看 docs/AGENT-SETUP.md 有关每个代理的完整设置说明、平台兼容性表和陷阱。

没有饲料技能

ShelbyMCP在没有它的情况下工作得很好——你可以得到持久存储、FTS5搜索和知识图。觅食技能增加了智力层，使记忆随着时间的推移变得更聪明。将其视为可选但推荐的。

______________________________________________________________________

入门：入职和迁移

空内存数据库是一个冷启动问题——你的人工智能工具在了解你之前无法进行个性化设置。ShelbyMCP附带了两个工具来解决这个问题：

机载技能（推荐）

一次性对话式访谈，培养15-30个基础记忆。将提示粘贴到与主要AI工具的对话中：

shelbymcp onboard

它包括：

• 你是谁 --姓名、角色、专业知识
• 你正在建造什么 --项目、目标、技术栈
• 你和谁一起工作 --团队、角色、利益相关者
• 你喜欢怎么工作 --沟通风格、编码偏好、人工智能交互风格
• 避免什么 --反模式、讨厌的事、过去的挫折

大约需要5分钟。该技能会根据你的答案调整问题——如果你是一个独立创始人，它不会问团队结构。每一轮后都会保存记忆，这样你就可以看到它们实时积累。

迁移提示

已经在ChatGPT、Claude、Gemini或其他AI中存储了上下文？导出它：

shelbymcp migrate

这将打印您粘贴到其他AI工具中的提示。该工具以结构化格式转储它所知道的关于你的一切。将响应复制回ShelbyMCP连接的代理中——板载技能将解析并导入它，或者您可以将其粘贴到任何对话中并要求代理导入。

适用于任何有关于你的记忆或对话历史的人工智能。每个要从中迁移的工具运行一次。

______________________________________________________________________

CLI 参考

shelbymcp                          Start the MCP server (stdio)
shelbymcp --transport http         Start as HTTP server (Streamable HTTP)
shelbymcp setup             Set up ShelbyMCP for an agent
shelbymcp setup  --forage   ...and install the Forage skill
shelbymcp uninstall         Remove ShelbyMCP from an agent
shelbymcp protocol                 Print the Memory Protocol
shelbymcp forage                   Print the Forage skill prompt
shelbymcp onboard                  Print the onboarding interview prompt
shelbymcp migrate                  Print the migration prompt for other AI tools
shelbymcp help                     Show help
shelbymcp --version                Print version

支持的代理： claude-code, claude-desktop, cursor, codex, windsurf, gemini, antigravity

服务器标志：

远程服务器示例（流式HTTP）：

# Start ShelbyMCP as an HTTP server
shelbymcp --transport http --port 3100

# Connect from Claude Code
claude mcp add --transport http shelby http://localhost:3100/mcp

看 docs/AGENT-SETUP.md 用于手动配置、特定于平台的详细信息以及其他MCP兼容客户端的设置。

______________________________________________________________________

云部署

ShelbyMCP可以作为远程HTTP服务器运行，让您在多台机器上共享一个内存数据库。所有配置都是通过环境变量进行的：

CLI标志(--transport, --port, --host, --db)当两者都设置时，重写env变量。

码头工人

docker build -t shelbymcp .
docker run -d \
  -e SHELBY_TRANSPORT=http \
  -e SHELBY_API_KEY=your-secret-key \
  -v shelby-data:/data \
  -e SHELBY_DB_PATH=/data/memory.db \
  -p 3100:3100 \
  shelbymcp

从克劳德代码连接

claude mcp add --transport http shelby-cloud https://your-server.example.com/mcp \
  --header "Authorization: Bearer your-secret-key"

健康检查

GET /health 回报 200 {"status": "ok"} （未经身份验证）。将其配置为平台的健康检查端点。

认证

当 SHELBY_API_KEY 已设置，所有请求 /mcp 需要 Authorization: Bearer 头球没有密钥，请求返回 401.如果 SHELBY_API_KEY 未设置，身份验证已禁用（仅适用于本地使用）。

______________________________________________________________________

建筑

ShelbyMCP是一个单一的二进制文件，通过MCP进行通信，并将所有内容存储在一个SQLite文件中。支持两者 标准 （本地，默认）和 可流式传输的HTTP （远程/多客户端）传输。

AI Tool (Claude Code, Cursor, etc.)
    │
    │ MCP (stdio or Streamable HTTP)
    │
    ▼
┌──────────────────────┐
│      ShelbyMCP        │
│                        │
│  ┌──────────────────┐ │
│  │   MCP Protocol    │ │  ← JSON-RPC request/response
│  │ (stdio or HTTP)   │ │
│  └────────┬─────────┘ │
│           │            │
│  ┌────────▼─────────┐ │
│  │   Tool Router    │ │  ← Routes to capture/search/link/etc.
│  └────────┬─────────┘ │
│           │            │
│  ┌────────▼─────────┐ │
│  │    SQLite DB      │ │
│  │  ┌─────────────┐ │ │
│  │  │  thoughts    │ │ │  ← Content, metadata, embeddings
│  │  │  thought_fts │ │ │  ← FTS5 full-text index
│  │  │  edges       │ │ │  ← Knowledge graph relationships
│  │  └─────────────┘ │ │
│  └──────────────────┘ │
└──────────────────────┘
         │
         ▼
    ~/.shelbymcp/memory.db  (single file)

看 docs/ARCHITECTURE.md 对于完整的技术设计。

______________________________________________________________________

比较

______________________________________________________________________

谢尔比生态系统的一部分

ShelbyMCP是开源内存服务器。 Shelby for Mac （即将推出）是本机macOS应用程序，它添加了：

• 始终在线嵌入管道（不需要预定技能）
• 捕获时即时自动分类
• 语义向量搜索
• CloudKit在所有Mac上同步
• 心跳系统（脉搏/Tidyup/饲料）
• 原生菜单栏+全局热键快速捕获
• 扩展发现和管理

ShelbyMCP和Shelby for Mac使用相同的SQLite数据库。从MCP服务器开始，需要更多时升级到Mac应用程序。

______________________________________________________________________

贡献者设计原则

这些是不可谈判的。它们的存在是因为MCP服务器直接影响每条消息上每个用户的令牌成本。

1. 工具描述必须是静态的。 工具定义成为代理系统提示的一部分，并在每条消息上发送。描述中的动态数据（计数、时间戳、用户特定信息）会破坏提示缓存，使令牌的成本增加10倍。将动态数据放入工具 *回应*，而不是描述。看 架构：令牌效率模式.

1. 搜索返回摘要，而不是完整内容。 搜索20个想法，每个想法2000个单词，浪费了4万个代币。搜索结果返回提供的代理 summary 字段（一行）。代理人打电话来 get_thought 在需要时获取完整内容。

1. 所有列表/搜索工具都有 limit 参数。 默认值为20，最大值为100。回应包括 total_count 和 has_more。没有无限查询。

1. 服务器运行零推理。 代理在捕获时提供元数据（类型、主题、摘要、关系）。觅食技能处理丰富。服务器是纯存储+检索。

1. 所有日志记录到stderr。 console.error 只有。stdout是MCP JSON-RPC通道。一个 console.log 打破一切。

1. 保持工具计数集中。 9个工具。研究（Block、Phil Schmid、Docker）表明，每台服务器5-8台是最佳选择。将相关操作整合到具有操作参数的单个工具中。

1. 错误是指令。 返回 isError: true 带有可操作的信息。“未找到”是无用的。“没有想到ID abc123。尝试search_thoughts按内容查找它。“帮助代理人自我纠正。

1. 每个工具都有注释。 MCP规范注释(readOnlyHint, destructiveHint, idempotentHint, openWorldHint)在每个注册的工具上。看 架构：工具注释.

______________________________________________________________________

发展

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run in development
npm run dev -- --db ./test.db --verbose

看 docs/DEVELOPMENT.md 获取完整的开发指南。

______________________________________________________________________

贡献

我们欢迎捐款！看 贡献.md 对于工作流程。

• 问题优先 --在开始工作之前打开一个问题
• PR欢迎 --错误修复、新的MCP工具、文档改进
• 饲料任务 --提出新的觅食技能任务以丰富记忆

______________________________________________________________________

许可证

麻省理工学院-见 许可证 了解详情。

______________________________________________________________________

Built by Studio Moser. Your AI deserves a memory that connects the dots.