meridian

Meridian

为长期运行的 AI 编码工作提供共享的结构化项目状态。

提供源代码的 MCP 服务，用于持久化项目状态——共享任务日志、 置顶决策、人工参与的队列和分级交接。支持 Claude Code、Cursor、Cline、Claude Desktop 或任何 MCP 客户端。

内置的 Agent 记忆（例如 Claude Code 的 CLAUDE.md 文件和自动记忆） 会将笔记作为文件保存，供该 Agent 使用。Meridian 还提供可查询的共享项目 记录，多个会话和不同的 MCP 客户端都可以读取和更新。它与内置记忆协同工作， 而非取而代之。

为什么选择 Meridian

每次 AI 编码会话启动时都对项目一无所知。你得重新解释架构、重新描述 约束条件、重新列出已经尝试过的方法。任务进行到一半、上下文用满时， 细节就会丢失。这就是上下文债务，而且会不断累积。

Meridian 为你的会话提供共享记忆。它们看到相同的任务日志、相同的 置顶决策和相同的目标状态。上下文用满时，新会话可以从压缩后的交接内容继续。 无需复制粘贴，也无需从头解释。

30 秒了解它是什么

一个供所有 AI 会话连接的本地 MCP 服务。它们共享目标状态、查看彼此的 任务日志，并在上下文用满时从压缩后的交接内容继续工作。

运行 Meridian 的两种方式：

• 自托管 — 永久免费，团队规模不限。克隆后只需运行 2 条命令。
• 托管服务，位于 usemeridian.us — 免费试用 30 天（无需银行卡），之后 Standard 方案每月 $20。

快速入门

选项 1 — 二进制发行版（推荐）

预构建的下载文件附在每个 GitHub 发行版中。 这些文件未经签名；每个发行版都包含一个 SHA256SUMS 文件，可用于校验下载文件。

• Windows 托盘应用（meridian-tray.exe）：系统托盘图标，用于运行仪表板服务。从托盘菜单中选择打开仪表板，即可打开 **http://127.0.0.1:7878**。
• macOS 托盘应用（meridian-tray-mac.dmg）：功能相同的托盘应用。该应用未经公证，因此首次启动时需要右键单击 > 打开。
• Linux：暂时没有托盘应用。请使用下方的 uv 安装方式。
• meridian.exe、meridian-linux、meridian-mac-arm64：仅为隧道客户端（需运行 meridian --tunnel --repo .，并要求 Pro 方案和 API 令牌）。它们不会提供仪表板服务。

通过 uv 使用仪表板（Linux、macOS、Windows）：

uv tool install meridian-server
meridian

仪表板会在 http://localhost:7878 打开。数据目录默认为 ./data；设置 MERIDIAN_DATA_DIR 即可更改。

Pro 隧道客户端（可选）：

meridian --tunnel --repo .

Linux / macOS（安装脚本，使用 uv）：

curl -fsSL https://usemeridian.us/install.sh | sh

Windows（PowerShell，安装隧道客户端 meridian.exe）：

irm https://usemeridian.us/install-windows.ps1 | iex

选项 2 — 从源代码安装（开发环境 / 自托管）

Linux / macOS：

git clone https://github.com/meridianmcp/Meridian
cd Meridian
./install.sh
pixi run start

Windows（PowerShell）：

git clone https://github.com/meridianmcp/Meridian
cd Meridian
.\install.ps1
pixi run start

控制面板会在 http://localhost:7878 打开。数据会持久保存在 ./data/meridian.db 中。

将其接入 AI 客户端

Claude Code

在项目根目录下放置一个 .mcp.json。

托管版（无需安装） — 在 usemeridian.us/settings 生成 API 密钥：

{
  "mcpServers": {
    "meridian": {
      "type": "http",
      "url": "https://usemeridian.us/mcp",
      "headers": { "Authorization": "Bearer sk_meridian_YOUR_KEY_HERE" }
    }
  }
}

自托管（从源代码安装）：

{
  "mcpServers": {
    "meridian": {
      "command": "pixi",
      "args": ["run", "python", "-m", "meridian", "--mcp"],
      "cwd": "/absolute/path/to/Meridian"
    }
  }
}

自托管（托盘应用或 uv 安装已在端口 7878 上运行）：

{
  "mcpServers": {
    "meridian": {
      "type": "http",
      "url": "http://127.0.0.1:7878/mcp"
    }
  }
}

在 ~/.claude.json 中使用相同的 mcpServers 键，即可在每个项目中使用。自托管服务无需 API 密钥。如果设置了 MERIDIAN_PORT，请将 URL 中的端口改为对应值。

Cursor / Windsurf

使用相同的 JSON 片段——这两个客户端都会从项目根目录读取 .mcp.json。

Claude Desktop

将相同的 mcpServers 代码块添加到：

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

重启 Claude Desktop。新聊天中即可使用 Meridian 工具。如果新部署的 工具仍然不可用，请先按照 MCP 工具界面更新指南 操作，再编辑任何客户端缓存。

claude.ai 网页版（推荐用于规划聊天）

claude.ai 连接器无法访问 http://localhost。请选择以下方式之一：

• 托管版（无需安装）： 在 claude.ai 中前往 Customize > Connectors > Add custom connector，将 URL 设为 https://usemeridian.us/mcp，然后完成 OAuth 提示。
• 自托管，Chrome 桥接： 使用 dnakov/claude-mcp，该项目已作为子模块包含在内：

  git clone --recurse-submodules https://github.com/meridianmcp/Meridian
  

  打开 chrome://extensions，启用 Developer mode，点击 Load unpacked，然后选择 extensions/claude-mcp。将桥接 URL 设为 http://localhost:7878/mcp/sse。
• 自托管，公开 URL： 通过 HTTPS 暴露你的服务，并将 https://<your-host>/mcp 添加为连接器。

完整步骤请参阅浏览器连接器指南。

托管版（无需安装）

在 usemeridian.us 登录 → Settings → MCP client setup → Generate API key → Copy config。

或手动配置：

{"mcpServers":{"meridian":{"type":"http","url":"https://usemeridian.us/mcp","headers":{"Authorization":"Bearer sk_meridian_YOUR_KEY_HERE"}}}}

**claude.ai（浏览器）**用户：托管版 Meridian 无需扩展程序。在 Customize > Connectors 下添加 https://usemeridian.us/mcp。请参阅浏览器连接器指南。

登录后，在 usemeridian.us/settings 获取 API 密钥。免费套餐：30 天，无需银行卡，功能完整。

你将获得

• 控制面板，地址为 http://localhost:7878 — 会话、任务、冲刺看板、 泳道时间线、HITL 队列、置顶决策。
• MCP 工具 — start_session、log_task、claim_task、set_decision、 pin_decision、request_hitl、generate_handoff 等约 50 个工具。
• 符号级并行安全 — claim_file 可以认领单个类或 函数（使用 ast / tree-sitter 解析），让两个会话安全地编辑同一个文件； 如果认领范围重叠，则会阻止操作并列出可用符号。
• 实时工作队列 — 规划器可在运行过程中注入冲刺事项；执行器会在下一个事项边界 通过 board_change 信号接收这些事项，不会中断当前工作。
• 推荐选项 HITL — request_hitl 可标记一个安全默认选项，供控制面板重点显示； 按 Enter 提交，按数字键选择其他选项。
• GitHub 中枢（托管版）— 在 Settings 中连接一次仓库；会话会自动注入 read_file、 list_files、meridian_github_search_code、git_log 和 meridian_github_get_commit。无需额外安装。
• 分层交接 — 通过 L0/L1/L2 压缩，让新会话从上一个会话停止的位置继续。
• Webhook 接收 — 将 LangGraph / Autogen / 自定义 Agent 发送的事件推送到同一控制面板。
• 随处可用 — Claude Code、Claude Desktop、Cursor、Windsurf、LangGraph、自定义集成。

工作原理

> start_session(project_id="meridian", session_name="feature-x")
  ✓ session registered · sprint loaded · 12 active tasks

> get_tasks(project_id="meridian", limit=5)
  [DONE]    backend / wire decisions_pinned table
  [PENDING] frontend / add notes vtab (claimed by session-2)

> claim_task(task_id="a1f3...")
  ✓ claimed — other sessions skip this one

状态存储在 data/meridian.db（SQLite）中，也可以通过 MERIDIAN_DB_URL 使用 Postgres URL。 本地使用无需云服务。

团队协作

将 MERIDIAN_DB_URL 指向共享的 Postgres（Neon 免费套餐非常好用）。每位 队友都在同一个数据库上运行自己的本地 Meridian，即可立即共享会话， 无需在云端运行 Meridian 服务。

使用钩子自动创建检查点

只需一条命令，即可将 Claude Code 和 Codex 接入 Meridian。每次会话开始时都会自动注入 项目上下文。每次会话结束时都会保存已完成工作的快照，并写入增量交接信息。

Mac/Linux：

curl -fsSL https://usemeridian.us/hooks.sh | bash

Windows：

irm https://usemeridian.us/hooks.ps1 | iex

系统会提示你输入 Meridian 服务 URL（默认值为 http://localhost:7878），然后打开 浏览器以连接这台机器——无需粘贴项目 ID 或 API 令牌。配置会写入 ~/.claude/settings.json（Claude Code）或 ~/.codex/config.toml（Codex）。设置完成后， 每次会话都会自动执行以下操作：

1. 开始时——调用 POST /hooks/session-start → 通过 additionalContext 将目标、冲刺事项、 最近任务和置顶决策注入会话上下文。
2. 停止时——调用 POST /hooks/stop → 运行 auto_capture 并写入增量 交接信息，让下一次会话从本次会话结束的地方继续。

无需再手动调用 start_session()。上下文填满时也不会丢失工作。

托管套餐

	Standard	Pro
价格	$20/mo	$49/mo（候补名单）
存储空间	包含 1 GB	包含 10 GB
计算资源	2 CU · 100 hrs/mo	4 CU · 300 hrs/mo
使用自有 Postgres	✓	✓
OAuth + 邮箱魔法链接	✓	✓
额外存储空间	$0.50 / GB-month	$0.50 / GB-month
支持	邮件	优先支持

30 天免费试用 · 无需信用卡

许可证

MSL-1.0——可免费用于本地和任意规模团队的内部用途。如果你将 Meridian 作为服务托管并提供给他人使用，则需要付费许可证。6 年后转为 MIT 许可证。

许可相关问题请联系：[email protected]

贡献者

由 @ajc3xc 构建