Ratary Memory Mcp

Ratary — MCP 服务

**类别：**记忆 · **传输方式：**stdio（本地）+ Streamable HTTP（远程，可选）
代码库：github.com/ontorata/ratary
**提交：**通过链接 https://github.com/ontorata/ratary/tree/main/MCP 提交至 mcpservers.org

为 AI 助手提供持久化的编码记忆——保存、搜索、构建节省令牌的上下文、遍历知识图谱，并支持多客户端同步。适用于 Cursor、Claude Code、Roo、Cline、Gemini CLI 和远程 MCP 托管平台（部署后可使用 ChatGPT App URL）。

生态系统：由 Ontorata 构建。本文档介绍 Ratary Memory MCP（ID：ratary）。Ontorata MCP 和 Ontorata Studio 是独立代码库。

**npm：**托管 REST 代理 — @ratary/mcp-server（@ratary 组织）。完整的 stdio（30 个工具）需要克隆此代码库。

---

服务代码在哪里？

模式	位置	适用场景
完整服务（30 个工具）	src/mcp/stdio.ts → src/transport/mcp/mcp-server.ts	克隆代码库；适用于任何 SQL_PROVIDER（D1、Postgres、Supabase、MariaDB，……）
npm 代理（6 个工具）	packages/mcp-server/（@ratary/mcp-server）	使用 RATARY_API_KEY 连接到托管 REST API
远程 HTTPS	src/transport/mcp/remote/	在 Vercel 上部署时设置 REMOTE_MCP_ENABLED=true

工具注册表 SSOT：src/capabilities/mcp-tool-names.ts

---

快速开始（本地 stdio）

首先配置一个 SQL 元数据提供方——请参阅 CONFIGURATION — SQL metadata store。

1. 先决条件

git clone https://github.com/ontorata/ratary.git
cd ratary
npm install
cp .env.example .env
# Set SQL_PROVIDER + matching credentials (D1, DATABASE_URL, or MARIADB_CONNECTION_STRING)
npm run db:migrate   # D1 only — use db:apply-postgres-schema for Postgres / Supabase

REST 开发服务器： npm run dev → http://localhost:9876（Swagger /docs）。在 .env 中使用 PORT 覆盖默认值。

2. 生成 MCP 配置

npm run setup

自动写入 .cursor/mcp.json 和 .mcp.json。

3. 手动配置（任意 IDE）

请参阅 docs/examples/mcp/cursor.mcp.json.example——将 REPO_PATH 替换为你的克隆路径。

{
  "mcpServers": {
    "ratary": {
      "command": "npx",
      "args": ["-y", "tsx", "REPO_PATH/src/mcp/stdio.ts"],
      "cwd": "REPO_PATH"
    }
  }
}

在 IDE 中重新加载 MCP。使用直接 D1 模式时，Cursor 无需 API 密钥。

---

远程／托管 API（npm 包）

适用于使用已部署 Ratary REST 端点的团队：

npm install -g @ratary/mcp-server
export RATARY_BASE_URL=https://ratary.ontorata.com
export RATARY_API_KEY=aic_...
ratary-mcp

配置示例：docs/examples/mcp/remote-api.mcp.json.example

---

远程 MCP URL（ChatGPT／网页客户端）

使用以下配置部署：

REMOTE_MCP_ENABLED=true

端点：https://your-host/mcp（启用后可使用 Bearer aic_... 或 OAuth）。
CI 烟雾测试：tests/transport/remote-mcp-chatgpt-smoke.test.ts（ChatGPT 风格的 initialize 负载）。
详情：GUIDE — ChatGPT · CONFIGURATION — Tier 4

---

工具（完整服务端 — 28）

工具	用途
save_memory、update_memory、delete_memory	增删改查
get_memory、get_memory_by_codename、get_memory_by_path、search_memory	读取与搜索（当 PRECISION_SEARCH_ENABLED=true 时启用精准模式）
get_context、build_prompt	高效利用令牌的上下文（默认节省约 85%）
list_projects、list_tags	导航
link_memories、list_relations、traverse_relations、get_graph_capabilities	知识图谱
list_workspaces、list_agents、register_agent	多 AI 工作区
get_capabilities、negotiate_capabilities	Agent 发现
submit_signal	质量反馈（排名调整）
run_stewardship、get_compression_status	维护
sync_pull、sync_push、sync_status	多客户端同步（可选启用）
toggle_favorite、archive_memory	生命周期

---

错误约定（{error, retryable}）

工具故障不会作为 MCP 协议错误呈现。任何处理程序异常，以及任何无效或缺失的参数，都会返回结构化工具结果（isError: true），其文本为可解析的 JSON：

{ "error": "<message>", "retryable": false }

retryable 是客户端行为提示，并不代表当前实现的状态：

• retryable: true — 幂等读取（search_memory、get_memory*、get_context、build_prompt、list_*、traverse_relations、get_capabilities、negotiate_capabilities、get_compression_status、sync_pull、sync_status）发生暂时性故障。请以短暂且有限的退避间隔重试（2–3 次）。
• retryable: false — 所有变更操作（save_memory、update_memory、delete_memory、link_memories、toggle_favorite、archive_memory、register_agent、submit_signal、sync_push），以及 run_stewardship（一次运行可能在多个子阶段中部分成功；自动重试可能导致重复维护）。此外，任何工具发生确定性故障（验证失败、未找到、身份验证失败）时也应设为此值——使用相同输入重试不会成功。

客户端指南：

1. 遇到不确定的超时，绝不要盲目重试写入操作——静默成功后再重试会产生重复项。请传入 request_id（如下所述）以确保重试安全，或继续当前轮次，并在下一轮通过 search_memory/回忆进行核对。
2. **将记忆视为尽力提供的上下文，而非硬性依赖。**如果调用失败，请使用已有上下文继续，并在下一轮重试。写入遗漏可以恢复；Agent 轮次崩溃则无法恢复。
3. 分类的权威来源：src/transport/mcp/mcp-tool-retry-classification.ts · 约定回归测试套件：tests/mcp-error-contract/。

幂等创建（request_id）

save_memory 接受可选的 request_id（UUID，格式与 submit_signal 的 signal_id 相同）。每次逻辑创建生成一个 ID，并在该次创建的每次重试中重复使用：

• 使用给定的 request_id 首次调用时，会正常创建记忆。
• 使用相同 request_id 重试时（包括发生不确定超时后），会将原始记忆作为成功结果返回，并附加 "duplicate": true, "replayed": true。即使首次尝试在写入过程中崩溃，也绝不会创建第二条记录。
• sync_push 创建项会自动获得相同保护，以该项的 memory_id 为键——重新推送批次时会重放，而不是重复创建。

只要意图记录存在，幂等性就有保障。 完成的意图记录会在 WRITE_INTENT_TTL_DAYS（默认 30 天）后清理，这是清理策略的一部分；在此时间窗口后到达的重试可能会创建重复项。清理绝不会删除尚未解决的意图（已声明但无结果）；此类意图会保留，并在治理检查结果中显示。不提供 request_id 时，行为不变：内容相同的保存操作会创建不同的记忆。

设计：ADR-067 · 契约测试套件：tests/idempotent-writes/。

---

目录列表（Phase 31L）

使用 MCP/submission/ 中的复制粘贴包，将 Ratary Memory MCP 提交到公共目录。

Pack 文件	目录
submission/mcpservers-org.md	mcpservers.org/submit — Memory 类别
submission/official-registry.server.json	Official MCP Registry
submission/awesome-mcp-servers-entry.md	awesome-mcp-servers GitHub PR
submission/cursor-marketplace.md	Cursor 插件市场
submission/claude-marketplace.md	Claude Code 插件市场
submission/directory-status.md	运营方跟踪（就绪 → 已提交 → 已列出）

mcpservers.org（快速复制）

字段	值
服务名称	Ratary
简短描述	为 AI 助手提供持久化编码记忆——保存、搜索、混合检索、知识图谱、高效利用上下文 token。支持 MCP stdio（30 个工具）、npm 代理或远程 Streamable HTTP。可在 D1、Postgres、Supabase、MariaDB 或 Docker 上自托管。
链接	https://github.com/ontorata/ratary/tree/main/MCP
类别	记忆
联系邮箱	[email protected]

Harness 市场清单文件

路径	用途
harness/marketplace/ratary-marketplace.json	Claude Code /plugin marketplace add 源
harness/claude-code/plugin.json	插件元数据存根
harness/marketplace/README.md	发布说明

元数据单一事实来源（SSOT）

供工具使用的仓库本地元数据：server.json（stdio、npm 和远程标志）。注册表发布使用 submission/official-registry.server.json。

范围： 仅列出 Ratary Memory MCP（ratary），不包括 Ontorata MCP 或 Ontorata Studio。

---

文档

文档	用途
docs/install/README.md	各种 Harness 的安装说明（Cursor、Claude、远程等）
MCP/submission/README.md	目录列表提交包（31L）
docs/GUIDE.md	设置与使用
docs/DOCKER.md	容器自托管
docs/README.md	面向用户的文档索引
docs/examples/	MCP 配置、IDE 模板、SDK 模式

License

MIT — see LICENSE in repository root.