Mcp Shared Memory Server

MCP 共享记忆服务（junto-memory）

Junto 多 Agent 协调系统中的 记忆组件。若要使用 docker-compose 搭建可运行的整套系统并按照采用者指南进行操作，请从 junto-stack 开始。

基于模型上下文协议（MCP）构建的共享记忆与协调服务，供多个 AI 编码 Agent 使用。

📋 已经在运行服务？ 请参阅 CHANGELOG.md 中的发行说明——当前版本（1.39.0）调整了全局指南的初始化方式，并将 execute-don't-ask 默认设置推广到更多场景；两项变更均附有升级说明。

重要

此工具旨在由 AI Agent 配置，而非手动安装。 Junto 的用途是协调多个编码 Agent，因此安装说明是为这些 Agent 编写的，方便它们阅读和执行——克隆代码库并将其交给 Claude Code（或任何支持 MCP 的）会话，然后让它来操作。本 README 和 AGENT_INSTALL.md 中的命令旨在让你跟进操作，并为 Agent 提供准确的执行步骤；它们不是精心编写的人类教程，通读这些说明也不是预期的使用方式。你始终掌握控制权——遇到每个实际决策（密码、端口、身份验证）时，Agent 都会暂停。如果你不愿意让 Agent 负责配置，这个工具可能不适合你。

当多个 AI Agent 在同一个代码库上工作时，以下三件事很快就会出问题：

1. 它们会忘记不同会话之间发生的一切。 Agent 暂停工作，知识也随之消失。下一个 Agent 会重新阅读相同的代码、重新发现相同的 Bug、重新学习相同的注意事项。
2. 它们会互相妨碍。 两个 Agent 修改同一个文件。没人知道其他 Agent 在做什么，或锁定了哪些内容。
3. 会话变长时，它们会变得越来越迟钝。 研究人员将这种现象称为“上下文腐化”——随着上下文窗口被填满，模型性能会下降。最终，每个 Agent 都必须交接；如果没有共享大脑，交接时就会丢失它学到的一切。

此服务解决了这三个问题。它为你的 Agent 提供可跨会话持久保留的共享大脑，协调多个 Agent 的工作，并让它们记录所学内容，使下一个 Agent 可以从上一个 Agent 停下的地方继续。

经实战检验。 此服务已在生产环境中运行，在商用 IoT 平台上协调 6 个专用 Agent，历经 500 多个会话——涵盖 C#/.NET 服务端、Raspberry Pi 上的 Python、.NET MAUI 移动端、MQTT、Redis 等。它所解决的问题，都是在实践中切实遇到的。

---

功能介绍

• 持久化知识库 —— 存储架构文档、经验、注意事项和代码片段，让它们在不同会话间留存，并可通过向量相似度搜索（ChromaDB）进行检索。
• 多 Agent 协作 —— 文件锁定、Agent 间消息传递、心跳监控和重叠检测，让多个 AI Agent 能够在同一代码库上协作，而不会互相干扰。
• 任务和待办事项管理 —— 跟踪工作项、为 Agent 分配任务、管理检查清单，并在会话间移交上下文。
• 具备自动丰富功能的函数注册表 —— 只需注册一次函数，图书管理员守护进程便会分析源代码，补充函数签名、注意事项和语义搜索摘要。
• 委托本地模型处理任务 —— Agent 可将常规文本工作（分类、提取、摘要、监控邮箱）交给通过 Ollama 在你自己的硬件上运行的模型，按计划执行或仅执行一次，并将结果返回给 Agent。这样可以将云端 Agent 的使用留给确实需要它的工作。参见本地模型任务委托。
• 管理 Web UI —— 服务端的 /admin：设置、Agent 及其上下文填充情况、提醒、本地任务与运行记录、连接和变更日志。参见管理 Web UI。

---

对比

PulseMCP 上列出了 370 多个 MCP 记忆服务。大多数为单个 Agent 提供持久化记忆。此服务则专为在数周乃至数月内协同处理同一项目的 Agent 团队而构建。

功能	典型的 MCP 记忆服务	此服务
持久化存储	是	是 — MongoDB + ChromaDB 向量搜索
多 Agent 会话跟踪	否	是 — Agent 注册表、心跳、重叠检测
Agent 间消息传递	否	是 — 发送/接收消息，并提供线程和状态跟踪
函数注册表	否	是 — 注册一次，图书管理员守护进程自动通过代码分析丰富内容
任务待办列表	否	是 — 创建任务、分配给 Agent、跟踪状态和优先级
版本化规范与契约	否	是 — 所有者强制执行、语义化版本历史
文件锁定	否	是 — 原子锁，支持过期检测，并在会话结束时自动释放
行为准则	否	是 — 只需设置一次，每台机器上的每个 Agent 都会收到这些规则
过期管理	否	是 — 年限提醒、替换、归档、按标签批量清理
图书管理员模式	否	是 — Agent 分析源代码并丰富知识库
外部数据库访问	否	是 — 对项目数据库执行只读 SQL 查询（MSSQL、MySQL）
检查清单	否	是 — 共享的发布准备、部署步骤等清单
本地模型任务委托	否	是 — 由 Agent 发起的任务在本地 Ollama 运行器上执行；结果返回给 Agent 或汇总为每日报告
数据源密钥	否	是 — 加密保险库；Agent 请求连接，由操作员启用连接，Agent 永远看不到密钥
操作员 Web UI	否	是 — /admin：设置、Agent、提醒、任务、连接、变更日志

涵盖 23 个类别的 63 种工具。这不是玩具，而是一套协作系统。

---

也适用于单 Agent

你无需使用多个 Agent，也能从此服务中获益。单个 Claude Code 或 Cursor 实例即可获得：

• 跨会话持久记忆 — 你的 Agent 会记住它昨天学到的内容
• 函数注册表 — Agent 不会重复阅读已经分析过的代码
• 经验记录 — 注意事项、变通方法和不明显的行为会在会话重启后留存
• 图书管理员丰富内容 — 随着时间推移，你的代码库会建立索引并可供搜索
• 待办列表 — 在不同会话间跟踪已完成事项和后续工作
• 状态规范 — 从中断处准确继续

协作功能（消息传递、文件锁定、多 Agent 感知）只会闲置在那里，不会造成任何影响——在你扩大规模之前，Agent 不会调用这些工具。

从一个 Agent 开始。准备好时即可使用多 Agent 功能；在你需要它们之前，它们不会妨碍你。

---

架构

graph LR
    A1[Claude Code] -->|MCP/HTTP| S[MCP Shared Memory Server]
    A2[Cursor] -->|MCP/HTTP| S
    A3[Other MCP Client] -->|MCP/HTTP| S
    S -->|Vector search| C[(ChromaDB)]
    S -->|Documents & state| M[(MongoDB)]
    S -.->|Optional| E[(External DBs)]

服务器以单个 Docker Compose 堆栈的形式运行。AI Agent 通过 MCP 连接（使用 8080 端口上的可流式 HTTP 传输）。所有知识、消息和协调状态都会持久化在 MongoDB 和 ChromaDB 卷中，并在重启后保留。

---

安装——交给你的 AI

此服务器专为 AI 编码 Agent 设计，因此安装流程也是如此。克隆仓库，然后让你的 Agent 帮你安装：

git clone https://github.com/tlemmons/junto-memory.git
cd junto-memory
# Now hand the prompt below to your AI agent in a fresh session.

在克隆目录中打开一个全新的 Claude Code（或 Cursor，或任何兼容 MCP 的 Agent）会话，并将此提示词复制给它：

请为我在此仓库中安装 MCP Shared Memory Server。阅读 AGENT_INSTALL.md 并逐步执行。使用根目录下的 docker-compose.yml。执行任何破坏性操作、进行任何需要真实值的更改（密码、API 密钥、端口选择）以及启用身份验证之前，请先暂停并征求我的确认。安装完成后，运行文档中所述的冒烟测试，并向我报告全部六项完成条件的结果。

Agent 会逐步完成前置条件、环境文件配置、容器启动、健康检查和 MCP 客户端配置，并在需要你做出决定时（密码、端口、是否启用身份验证）暂停询问。

为什么要这样做？ 此安装流程积累了许多容易踩坑的运维细节——Chroma 卷挂载路径、Mongo 初始化凭据、带软回退机制的身份验证环境变量、本地主机与远程主机信任模型之间的差异——因此，6 行快速入门往往弊大于利。AGENT_INSTALL.md 内容详尽、分支众多，并经过针对当前实际代码的测试；Agent 只需几分钟便能阅读并执行。如果你不信任 AI Agent 来运行安装流程，那么此服务器可能不适合你——它的全部用途就是协调一组在真实代码库上工作的 AI Agent。

无论如何都要手动操作？ AGENT_INSTALL.md 对人类来说也很容易阅读，只要仔细遵循，安装就能成功——但它是为 Agent 执行而编写的，因此内容详尽、分支众多，对人类教程通常会提供的引导较少。上面的 Agent 驱动流程才是受支持的方式。

安装后，MongoDB 将监听 localhost:27019，ChromaDB 将监听 localhost:8001，MCP 服务将监听 localhost:8080。

首次会话

连接后，你的 Agent 会这样开始交互：

Agent: memory_start_session(project="my-app", claude_instance="main")
→ Returns: session ID, any prior learnings, active work, handoff notes

Agent: memory_record_learning(
    session_id="...",
    topic="postgres connection pooling",
    content="PgBouncer silently drops connections after 5 min idle.
             Must set keepalive_idle=60 in connection string or
             requests fail with 'server closed the connection unexpectedly'."
)
→ Stored. Next session, memory_start_session returns this automatically.

Agent: memory_register_function(
    session_id="...",
    name="retry_with_backoff",
    file_path="src/utils/resilience.py:42",
    purpose="Retry async calls with exponential backoff and jitter",
    gotchas="Max 5 retries. Raises RetryExhausted, not the original exception."
)
→ Registered. Any future agent asking "how do we handle retries?"
  finds this via memory_find_function.

只需调用三次工具。现在，你的 Agent 已拥有持久化记忆，之后的每个会话都会从已有上下文开始，而不是一片空白。

---

连接你的 AI

Claude Code

添加到 ~/.claude.json（或项目的 .mcp.json）：

{
  "mcpServers": {
    "shared-memory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

关于传输名称的说明： 底层 MCP 协议使用“可流式 HTTP”，但在 Claude Code 2.x 的 JSON 配置文件中，该值为 "http"。在配置中使用 "streamable-http" 会触发架构验证错误。

Cursor

添加到项目根目录下的 .cursor/mcp.json：

{
  "mcpServers": {
    "shared-memory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

任何兼容 MCP 的客户端

将客户端指向 MCP 端点：

URL:       http://localhost:8080/mcp
Transport: Streamable HTTP (stateless)

也支持 Stdio 传输，适用于偏好这种传输方式的客户端。启动服务器时传入 --transport stdio：

# From the project root:
python server.py --transport stdio

# Or as a module (from the src/ directory):
python -m shared_memory --transport stdio

Stdio 模式的 MCP 客户端配置示例：

{
  "mcpServers": {
    "shared-memory": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "shared_memory", "--transport", "stdio"],
      "cwd": "/path/to/mcp-shared-memory/src"
    }
  }
}

本地使用无需 API 密钥或身份验证令牌（远程部署请参阅安全性）。

---

工具参考

共有 63 个工具，分为 23 个类别。（规范且最新的列表，包含分组和端到端流程，请参阅服务器内的架构规范：memory_get_spec(name="architecture:shared-memory-v1", project="junto")。）

会话管理（2 个工具）

工具	描述
memory_start_session	注册会话并获取上下文：近期经验、活跃 Agent、文件锁和待处理信号。请首先调用此工具。
memory_end_session	记录摘要、已修改的文件和交接备注，并释放所有锁。完成后请调用此工具。

知识库（4）

工具	描述
memory_query	使用自然语言搜索知识库。返回相关文档及相关性分数。
memory_get_by_id	通过文档的确切 ID 获取指定文档。
memory_store	存储新文档（架构、API 规范、代码片段、接口契约等）。
memory_record_learning	快捷记录经验、注意事项或技巧，供其他 Agent 使用。

搜索与发现（2）

工具	描述
memory_search_global	一次搜索所有项目和共享集合。
memory_list_projects	列出所有项目及其文档数量。无需会话。

文件锁定（3）

工具	描述
memory_lock_files	以原子方式锁定文件，以便独占编辑。支持目录锁定。会在会话结束时自动释放。
memory_unlock_files	释放指定文件的锁，或释放当前会话持有的所有锁。
memory_get_locks	查看当前文件锁，并检测已过期的锁（非活动时间超过 30 分钟）。

待办事项管理（4）

工具	描述
memory_add_backlog_item	向待办列表添加任务、功能请求或技术债务事项。
memory_list_backlog	使用项目、状态、优先级、负责人和里程碑等筛选条件列出待办事项。
memory_update_backlog_item	更新待办事项的状态、优先级、负责人或描述。
memory_complete_backlog_item	将待办事项标记为已完成或不予处理，并可选填写解决说明。

Agent 间消息传递（7）

工具	描述
memory_send_message	向其他 Agent 发送消息。支持分类（任务、问题、阻塞事项等）和消息串。
memory_get_messages	获取发给当前 Agent 的待处理消息。按项目限定范围。
memory_acknowledge_message	将消息标记为已收到（状态更新快捷方式）。
memory_update_message_status	跟踪消息生命周期：待处理、已发送、已收到、已完成、失败。
memory_heartbeat	发送包含当前状态（空闲、忙碌、错误）的心跳。用于检测过期状态。
memory_get_agent_status	获取 Agent 的心跳状态。标记超过 5 分钟未活动的 Agent。
memory_list_agents	查找各项目中已注册的 Agent，包括其角色和最近活动时间。

函数注册表（5）

工具	描述
memory_register_function	注册函数引用，包括名称、文件、用途和可选的注意事项。会触发资料管理员补充信息。
memory_find_function	按用途或名称搜索函数。实现前先检查，以避免重复。
memory_enrich_function	为函数引用添加深入分析：签名、参数、副作用和复杂度。供资料管理员使用。
memory_get_enrichment_queue	查看等待资料管理员补充信息的函数。
memory_become_librarian	获取提示词和未补充信息的函数，以便在本机进行补充。

规范管理（3）

工具	描述
memory_define_spec	创建或更新带版本的规范，并强制执行仅所有者可操作。支持语义化版本控制和历史记录。
memory_get_spec	按名称获取规范，也可选择指定历史版本。
memory_list_specs	列出所有规范，并可选择显示版本历史和按类型筛选。

项目注册表（1 个 CRUD 工具）

工具	描述
memory_project	管理项目和 Agent。操作：create、get、list、delete、add_agent、remove_agent、update_agent。

检查清单（1 个 CRUD 工具）

工具	描述
memory_checklist	用于发布就绪情况、部署步骤等的共享检查清单。操作：create、get、add、check、delete、list。

外部数据库查询（1 个 CRUD 工具）

工具	说明
memory_db	对已注册的外部数据库执行只读查询。操作：list、schema、query。内置 SQL 注入防护。

服务端管理的指南（1 个）

工具	说明
memory_guidelines	管理所有 Agent 在会话开始时都会收到的行为规则。操作：list、set、delete、get。更新一次后，每台机器上的每个 Agent 都会获取更新。

管理（1 个 CRUD 工具）

工具	说明
memory_admin	管理 API 密钥并查看审计日志。操作：create_key、revoke_key、list_keys、audit_log、auth_status。启用身份验证后，需要所有者角色。

文档生命周期（4 个）

工具	说明
memory_update_work	更新当前工作状态和修改过的文件。支持检测工作重叠并发送依赖信号。
memory_change_status	更改文档状态：active、deprecated、superseded、archived。保留历史记录。
memory_archive_by_tag	批量归档所有匹配某个标签的文档（例如，版本结束时的清理）。
memory_restore_by_tag	按标签批量恢复先前归档的文档。

协调与活动（2 个）

工具	说明
memory_get_active_work	查看其他 Agent 当前正在处理的任务、修改过的文件和时间戳，避免工作重叠。
memory_claim_message	认领一条消息，确保组内恰好由一个 Agent 处理（多消费者协调）。

提醒与日程安排（3 个）

工具	说明
memory_set_reminder	在指定时间向未来的自己（或同伴）安排一条消息，例如截止日期、后续跟进或“在 X 之后提醒我”。
memory_cancel_reminder	取消先前安排的提醒。
memory_list_reminders	列出待处理的已安排提醒。

技能（6 个）

可重复使用、按任务调用的操作指南。以 draft 状态编写，通过信任关卡后晋升为 active，再由启动器写入 .claude/skills/，使客户端的原生匹配器能在任务过程中触发这些技能。

工具	说明
memory_register_skill	编写可重复使用的技能（触发条件、步骤、注意事项和前提条件）。始终创建为 draft。
memory_confirm_skill	将草稿技能晋升为 active——即信任关卡。仅限所有者或人工操作。
memory_get_skill	按 ID 或名称获取某项技能的完整内容。
memory_list_skills	列出按项目、角色、目录或状态筛选的技能（标题）。置顶项优先，其次为 active 项。
memory_pin_skill	置顶或取消置顶某项技能，使其在展示时排名靠前。
memory_export_skills	将与范围匹配的 active 技能导出为可直接写入的 SKILL.md 内容，供启动器写入。

行为指令（1 个）

工具	说明
memory_ack_directive	确认服务端发出的指令（例如暂停或行为指示），以便将其清除。

推送控制、告警与遥测（2 个）

让运营人员了解消息速率限制／推送控制子系统的运行情况（链深度上限、每个 Agent 的每小时限额、静默抑制）。

工具	说明
memory_list_alerts	列出推送控制告警——限额警告、超限事件和硬上限触发事件，供运营仪表板使用或作为轮询备用方案。
memory_get_emission_stats	按 Agent 统计消息发送计数器和限额使用情况。

团队状态与健康（3）

工具	说明
memory_report_context	报告来自任意机器的 Agent 上下文窗口占用情况（由每台机器上的 contrib/context-report 报告程序使用）。随后，memory_get_agent_status 会显示每个 Agent 的上下文使用量，而空闲→暂停提醒也会使用它（参见上下文使用量与空闲暂停提醒）。
memory_standup	自动汇总项目团队站会信息——每个 Agent 当前的任务、阻塞项、过时的状态规范，以及汇总后的决策队列。只读，无需 Agent 生成。
memory_health	服务健康状态——MongoDB + ChromaDB 状态，以及活动会话／锁／信号数量。无需会话。

复制／同步（2，服务间）

第 2 阶段的本地优先复制端点（admin／owner 级别）。局域网内的 junto-memory 通过传送操作日志条目与中央实例协调——对等端不会重新嵌入文本。

工具	说明
memory_sync_pull	拉取比调用方各来源游标更新的操作日志条目。
memory_sync_push	应用从对等端收到的一批操作日志条目（序号单调递增，并对意图去重）。

待办事项 — 批量（1）

工具	说明
memory_batch_backlog	一次调用即可创建或更新多个待办事项。

本地模型委派（4）

将工作交给在你自己的硬件上运行的模型。工作原理：本地模型委派。

工具	说明
memory_delegate	为本地模型创建任务：数据源（范围）、指令、JSON 输出架构、路由、可选的计划和金丝雀。没有计划 = 立即运行一次。同一次调用中可以请求新连接。
memory_schedule	管理任务：list、get、edit（带版本控制）、pause、resume、delete、run_now、history、runs、approve（操作员）。
memory_job	单次运行：status、result（每个条目的输出及其经过的路由）、cancel。仅限所有者。
memory_runners	运行器和连接：list（主机、模型、上次心跳）、scopes（你可以使用的连接）、request_connection；仅限操作员使用的 define_scope、create_runner_key。

---

本地模型委派

许多 Agent 工作并不需要前沿模型：整理支持收件箱、从日志中提取字段、总结长篇转储内容、监控列表变化。通过委派，Agent 可以将这些工作交给在你自己的硬件上运行的模型（通过 Ollama），让云端 Agent 处理真正需要云端能力的工作。接口约定：memory_get_spec(name="interface:delegated-inference-v0", project="junto")。

工作原理

graph LR
    A[Agent] -->|memory_delegate| S[junto-memory]
    S -->|claim run + sealed secret| R[Runner on your GPU box]
    R -->|fetch items| D[(Connection: imap / mcp / file / inline)]
    R -->|one JSON result per item| O[Ollama]
    R -->|results| S
    S -->|routes: notify / digest / drop| A2[Agents]

1. 连接（范围）。 一种带类型的数据源：inline（任务中传入的文本）、imap（只读邮箱）、mcp（另一 MCP 服务上的只读工具）、file（运行器主机上允许访问的根目录），或 gmail（只读 API；需要你自己的 Google OAuth 客户端）。每种连接都会列出获准使用它的 Agent，以及获准使用它的运行器主机。memory_runners(action="scopes") 会显示你可用的连接。
2. 任务。 由 Agent 持有：instructions、output_schema（用于单个条目结果的 JSON Schema）、source_params、routes、可选的 schedule（{"every": "15m"} 或 {"cron": "0 7 * * *"}，最短间隔为 5 分钟）以及可选的 canaries。之后可以编辑任何字段，编辑会保留版本记录。没有计划表示立即运行一次。
3. 运行。 服务将运行任务排入队列。GPU 主机上的运行器会领取一项任务，获取条目，将每个条目连同任务指令一起发送给模型，根据架构验证回复，然后报告结果。每个运行器一次只处理一项运行任务。
4. 路由。 决定如何处理每项结果的是服务，而不是模型：通过模板向某个 Agent 发送 notify，将结果加入所有者的每日摘要，或将其 drop。采用第一个匹配的规则；没有匹配项时则加入摘要。本地模型不能执行操作——它提出的任何建议都会作为数据发送给 Agent。

memory_delegate(
    session_id=sid, name="ticket-sort", scope="myproject:inline",
    instructions="Classify this support message.",
    output_schema={"type": "object", "properties": {
        "classification": {"type": "string", "enum": ["bug", "billing", "how_to", "spam"]},
        "summary": {"type": "string"}}, "required": ["classification", "summary"]},
    source_params={"items": ["text of message 1", "text of message 2"]},
    routes=[{"if": {"field": "classification", "op": "in", "value": ["bug"]},
             "then": "notify", "to": "myproject/backend", "category": "task",
             "template": "{classification}: {summary}"},
            {"if": {"field": "classification", "op": "eq", "value": "spam"}, "then": "drop"}],
    run_now=True)
# → a "Delegated job done" notice; then memory_job(run_id, action="result")

安全模型

• 条目内容是不可信数据。 内容会以围栏形式传给模型，并在其后重述任务。默认模型 gpt-oss:20b 在测试中抵御了所有提示注入案例；qwen3:14b 速度更快，但会遵循植入看似可信邮件中的指令，因此只能用于可信文本。
• 金丝雀测试是带有预期输出的已知条目。它们每天（或每次运行时）执行，并在每次编辑指令、架构、模型或来源后执行。金丝雀测试失败时会通知所有者。
• 只读来源。 IMAP 使用 EXAMINE 和 BODY.PEEK 打开。MCP 工具仅限于连接的 tools_allowed，并与任务要求的工具取交集。
• 失败条目绝不会被悄然略过。 没有有效输出的条目不会被路由；对于计划任务，所有者会收到操作通知，其中列出每个此类条目（引用、发件人／主题、错误），因为来源游标已越过这些条目。
• 可见性。 只有任务所有者能查看运行结果。标记为 "x-sensitive": true 的架构字段不会发送给连接的 content_visible_to 之外的 Agent。

连接与密钥库

Agent 不会处理凭据。Agent 请求连接（memory_runners(action="request_connection")，或在 memory_delegate 中使用 connection=）。操作员在 /admin → Connections 中粘贴密钥以激活连接；此操作即表示批准。等待该连接的任务随后会启动。

• 密钥以加密形式（Fernet）存储在 JUNTO_VAULT_KEY 下。每次认领时，系统都会将新副本加密封装到该运行器的 X25519 密钥；运行器仅在本次运行期间于内存中解密，绝不记录或缓存密钥。
• 撤销连接会删除密文并取消排队的运行。已认领的运行会在其 10 分钟租约内完成。
• 每次请求、激活、轮换和撤销都会记录在连接审计中（/admin → Connections）。
• JUNTO_VAULT_KEY 位于 .env 中，不在 Mongo 备份中。备份仅保存密文；若密钥丢失，则必须重新输入密钥。

运行运行器

运行器（contrib/runner/junto-runner.py）是一个独立的 Python 文件，需要 cryptography（MCP 来源还需要 mcp）。它只与 junto 服务、本地 Ollama 以及连接自身的来源通信。

首先，在所有者／管理员的 Agent 会话中创建运行器密钥（密钥只会显示一次）： memory_runners(session_id=sid, action="create_runner_key", runner_id="gpu-1", host="gpubox")。

# On the GPU box
cp contrib/runner/junto-runner.py ~/.local/bin/ && chmod 755 ~/.local/bin/junto-runner.py
mkdir -p ~/.config/junto-runner && chmod 700 ~/.config/junto-runner
# save that key to ~/.config/junto-runner/runner.key (mode 600)
# config.json (mode 600): {"server": "http://<server>:8080", "runner_id": "gpu-1",
#   "key_file": "~/.config/junto-runner/runner.key", "ollama": "http://localhost:11434"}
cp contrib/runner/junto-runner.service ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now junto-runner
loginctl enable-linger $USER

运行器会在首次启动时创建 X25519 密钥对，并注册已安装的模型。运行器 API（/runner/api/*）仅限局域网访问。

限制和注意事项

限制	值
每个 Agent 的任务数	最多 25 个正在运行（使用 memory_schedule(action="delete") 删除一次性任务）
每次运行的项目数	200
指令	20,000 个字符
内联项目	20,000 个字符（imap 的 max_chars 默认为 12,000）
模型上下文	运行器会为每次运行选择 num_ctx：在 8,192 / 16,384 个 token（配置项 num_ctx_buckets）中选取能容纳最长项目的最小值，同时受模型训练时的上下文长度、每个模型的 num_ctx_max 限制；对于超过 30 GB 的模型，还限制为 4,096（它们无法装入一张 24 GB 显卡）。每次运行只使用一个值，因为更改 num_ctx 会重新加载模型。仍然无法容纳的项目会被运行器截断，并显示标记；运行证据会显示 num_ctx 和 items_truncated。预留回复预算后，16K 可容纳约 20,000 个字符的项目。
回复长度	每次模型调用的 num_predict = min(8,192, context/2) 个 token，包括推理内容（即使设置了 think: false，gpt-oss 仍会进行推理；2,048 太小）。回复达到上限时会以 reply cut at num_predict=… 失败。对于 gpt-oss，达到上限的回复会在 think: "low" 下重试一次（在运行证据中计为 low_effort_retries）；默认推理力度仍优先使用，因为它更能抵御提示词注入（默认力度为 0/16，低力度为 1/16）。
队列	一个运行器一次处理一个运行。计划任务的运行会先于一次性批次被领取；每组内部按时间从早到晚处理。
计划	间隔至少为 5 分钟；除非设置了 digest_at，否则每日摘要会在任务时区的 07:00 发送

无法装入显存的模型（例如在 2×24 GB 显卡上运行 72B 模型）会部分使用 CPU，并逐出其他所有已加载的模型。请勿将大型模型放入批次。

---

管理员 Web UI

服务会在 http://<server>:8080/admin 提供操作员页面。该页面仅限 局域网访问：通过隧道发出的请求会收到 403。局域网内的任何人都可以查看；所有更改都需要 所有者 API 密钥（粘贴到页面中，并作为 Bearer 标头发送）。

标签页	显示内容 / 操作
概览	关键计数，并提供指向 /dashboard（活动动态）和 /health 的链接
设置	所有可调设置：代码默认值与服务端值，并可按服务或项目编辑
Agents	已注册的 Agent、最近活动、上下文占用率仪表
警报	推送控制警报（预算警告和超限）；确认警报
本地任务	委派任务（暂停 / 恢复 / 立即运行 / 批准）、包含证据的近期运行、金丝雀、路由和错误，以及运行器心跳
连接	已请求和已启用的连接：粘贴密钥以启用或轮换、撤销连接，以及连接审计记录
变更日志	所有设置变更：操作者、时间、更改前后的值

如需通过主机名访问，请使用 nginx 或类似工具代理 /admin，并确保该虚拟主机同样仅限局域网访问。

---

上下文仪表和空闲停放提醒

上下文仪表。 contrib/context-report/junto-context-report.py 会在每台机器上运行（systemd 用户定时器）。它会查找本地的 claude 进程，读取各 Agent 的状态行写入的上下文占用指标，并调用 memory_report_context。随后，memory_get_agent_status 和 /admin → Agents 会显示所有机器上每个 Agent 的上下文占用情况。

空闲停放提醒。 如果某个 Agent 在 idle_park_minutes（默认 50 分钟，略短于约 60 分钟的提示词缓存 TTL）内没有进行实际工具调用，服务就会推送一条通知，建议它在合适的节点停放。只有上报的上下文至少达到 idle_park_min_context（默认 200K）的 Agent 才会收到提醒。列在 idle_park_autoreset 中的 Agent 会进一步处理：收到停放提醒后，报告程序会检查 Agent 的 tmux 窗格是否可以安全输入，然后输入 /clear 和 go。使用 memory_admin push_control_set_config 或 /admin → Settings 进行配置。

---

配置

所有配置均通过环境变量完成。完整参考请参阅 .env.example。

必需变量

变量	默认值	描述
MONGO_PASSWORD	changeme	MongoDB root 密码。请修改此密码。
MONGO_USER	mcp_orch	MongoDB 用户名。
MONGO_DB	mcp_orchestrator	MongoDB 数据库名称。
MONGO_HOST	localhost	MongoDB 主机（在 Docker Compose 中自动设置）。
MONGO_PORT	27019	MongoDB 外部端口。（.env.example 当前显示为 27018，已过时——docker-compose.yml 使用 27019。）
CHROMA_HOST	localhost	ChromaDB 主机（在 Docker Compose 中自动设置）。
CHROMA_PORT	8001	ChromaDB 外部端口。

可选变量

变量	默认值	描述
MCP_AUTH_ENABLED	false	启用 API 密钥身份验证。启用后，memory_start_session 需要有效密钥——可通过 api_key 工具参数或 Authorization: Bearer <key> HTTP 标头传入（参见安全性）。
JUNTO_VAULT_KEY	--	用于连接密钥保险库（本地模型委派）的 Fernet 密钥。仅在需要存储连接密钥时才需要。使用 python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" 生成。请勿将其纳入备份或提交到 git。
ANTHROPIC_API_KEY	--	仅独立的 librarian 丰富服务需要。
LIBRARIAN_PROJECT_ROOTS	--	将项目名称映射到文件系统路径的 JSON 映射，用于 librarian 代码分析。
DB_<NAME>_TYPE	--	注册外部数据库。支持：mssql、mysql。完整配置模式请参见 .env.example。
DB_<NAME>_HOST	--	外部数据库主机名。
DB_<NAME>_PORT	1433	外部数据库端口。
DB_<NAME>_NAME	--	外部数据库名称。
DB_<NAME>_USER	--	外部数据库用户名。
DB_<NAME>_PASS	--	外部数据库密码。
DB_<NAME>_READONLY	true	强制使用只读查询。
DB_<NAME>_TIMEOUT	30	查询超时时间，单位为秒。
DB_<NAME>_MAX_ROWS	500	每次查询返回的最大行数。

---

项目结构

mcp-shared-memory/
├── server.py                     # Entry point (imports from package)
├── src/
│   └── shared_memory/
│       ├── __init__.py
│       ├── __main__.py           # CLI argument parsing
│       ├── app.py                # FastMCP server instance
│       ├── config.py             # All configuration and constants
│       ├── clients.py            # MongoDB and ChromaDB client setup
│       ├── state.py              # In-memory state (sessions, locks, signals)
│       ├── helpers.py            # Shared utility functions
│       ├── auth.py               # API key auth, RBAC, tenant isolation
│       ├── audit.py              # Audit logging to MongoDB
│       ├── delegation.py         # Local-model tasks, scopes/connections, scheduling, routes
│       ├── vault.py              # Encrypted connection secrets, sealed per runner
│       ├── runner_api.py         # /runner/api/* (register, heartbeat, claim, complete, fail)
│       ├── admin_ui.py           # /admin web UI + its JSON API
│       ├── idle_park.py          # Idle→park nudge and auto-reset
│       └── tools/
│           ├── __init__.py       # Tool registration
│           ├── sessions.py       # Session start/end
│           ├── query.py          # Knowledge base queries
│           ├── storage.py        # Document storage and learnings
│           ├── search.py         # Cross-project search, list projects
│           ├── locking.py        # File lock management
│           ├── backlog.py        # Backlog/task management
│           ├── messaging.py      # Inter-agent messaging and status
│           ├── functions.py      # Function registry and enrichment
│           ├── specs.py          # Versioned spec management
│           ├── projects.py       # Project and agent registry
│           ├── checklists.py     # Shared checklists
│           ├── database.py       # External database queries
│           ├── lifecycle.py      # Document lifecycle and work status
│           ├── delegation.py     # memory_delegate / schedule / job / runners
│           └── admin.py          # API key management and audit logs
├── librarian.py                  # Standalone enrichment daemon (uses Haiku)
├── contrib/runner/               # Local-model runner + systemd user unit
├── contrib/context-report/       # Per-machine context-fill reporter
├── docker-compose.yml            # Full stack: server + MongoDB + ChromaDB
├── Dockerfile
├── requirements.txt
├── .env.example
└── LICENSE

---

开发

前置条件

• Python 3.11+
• Docker 和 Docker Compose（用于 MongoDB 和 ChromaDB）

本地运行

启动后端服务：

docker compose up -d mongodb chromadb

安装 Python 依赖：

pip install -r requirements.txt

直接运行服务：

python server.py --host 0.0.0.0 --port 8080

或作为模块运行：

cd src && python -m shared_memory --host 0.0.0.0 --port 8080

使用 Docker Compose 运行（完整堆栈）

docker compose up -d

这会启动全部三项服务（MCP 服务、MongoDB、ChromaDB），并启用健康检查和自动重启。

查看日志

# All services
docker compose logs -f

# Just the MCP server
docker compose logs -f mcp-server

---

安全性

此服务专为本地或受信任网络环境设计。身份验证为可选项，但可以启用。

内置 API 密钥身份验证

在 .env 中设置 MCP_AUTH_ENABLED=true，即可要求所有会话使用 API 密钥。密钥通过 memory_admin 工具管理，并采用基于角色的访问控制：

角色	访问权限
owner	完全访问权限——管理 API 密钥、指南和所有项目
admin	管理所有项目中的待办事项、规格、函数和消息
agent	标准 Agent 访问权限，仅限分配的项目
readonly	仅查询和搜索，不可写入

每个 API 密钥都可限定到特定项目，实现租户隔离——Agent 只能查看其获准访问的项目中的数据。所有安全敏感操作都会写入审计日志（保留 90 天）。

禁用身份验证时（默认设置），所有工具均可开放访问——适用于本地单用户配置。

传递密钥：工具参数或 Authorization 标头

密钥可以通过两种方式传递到服务端（design:header-auth-v0）：

1. api_key 工具参数 — 将 api_key="smk_..." 传递给 memory_start_session。显式指定的参数始终优先。

2. Authorization: Bearer 标头 — 在 MCP 客户端配置中添加 headers 块（MCP 标准约定）。未提供 api_key 参数时，服务端会从标头读取密钥：

   {
     "mcpServers": {
       "junto": {
         "type": "http",
         "url": "https://your-host/mcp",
         "headers": { "Authorization": "Bearer smk_..." }
       }
     }
   }
   

优先级：显式的 api_key 参数 > 标头 > 无密钥。未提供密钥的会话（两者均未提供）会回退到 agent 层级。已提供但无效的密钥（无论通过参数还是标头提供）都会被直接拒绝（明确报错，而不是静默降级）。标头方式已通过 Claude Code 验证，它会原样转发静态标头。

网络安全

如果需要远程访问，请勿直接暴露端口 8080。请改用以下方式：

• Tailscale / WireGuard — 将服务端接入专用网状网络。这是最简单、最安全的选项。
• 带身份验证的反向代理 — 在服务端前面使用 nginx 或 Caddy，并配置 HTTP 基本身份验证、mTLS 或 OAuth2。
• SSH 隧道 — 使用 ssh -L 8080:localhost:8080 your-server 进行临时远程访问。

.env.example 中的 MONGO_PASSWORD 默认值为 changeme。使用此值也能启动服务端，但在任何非临时部署中，都必须更改此值。Docker Compose 默认也会暴露 MongoDB 和 ChromaDB 端口 — 如果你的机器可通过网络访问，请使用防火墙规则限制这些端口。

---

CLAUDE.md 文件

这些是供 Claude Code 使用的指令文件。如果你不使用 Claude Code，可以放心忽略它们。

• GLOBAL_CLAUDE.md.example — 复制到每台机器上的 ~/.claude/CLAUDE.md。这是最精简的引导文件，告知 Claude 启动会话并遵循服务端管理的指南。
• CLAUDE.md.template — 复制到每个项目目录，并根据项目名称、Agent 名称和关键文件进行自定义。
• CLAUDE.md — 本项目自身的 Claude Code 配置（用于开发服务端）。

行为规则由服务端管理，而非由这些文件管理。使用 memory_guidelines(action="set", ...) 添加或更新规则 — 每台机器上的每个 Agent 都会在下次启动会话时自动获取这些规则。

---

Agent 规范问题

仅有共享记忆服务还不够。Agent 还需要始终如一地实际使用它。

Agent 容易偏离规范。它们会忘记调用 memory_record_learning。它们会把所有内容都塞进一个庞大的状态规范，而不是按主题划分记忆。它们会写入其他 Agent 无法查看的本地文件。它们会进行超长会话，直到上下文腐化，让自己忘记指令。

此服务包含用于应对这种偏离的工具：

服务端管理的准则

每个 Agent 在会话开始时都会收到一组行为规则（位于 memory_start_session 响应中）。这些规则分为两个层级：

内置全局默认规则（随项目发布，普遍适用）。 Junto 在代码中提供一组 scope="global" 规则 — src/shared_memory/global_guidelines.py — 并在每次服务端启动时将其重新写入数据库。因此，全新的服务端（无论是你自己的，还是隔离的对等环境或工作环境）都能获得合理的默认规则，无需任何手动设置；更新默认规则也会随部署生效。这些规则刻意保持普遍适用于流程 — 优先查询记忆、运行更长的会话并在干净的停止点暂停、准确性优先于认同、将知识持久化到服务端、立即记录经验、遵守会话纪律、明确消息语义、提供指针而非摘要、先定契约再写代码、检查信息时效性、输出简洁，以及在断言前阅读源代码。这里不包含任何特定于团队或部署的内容。全局作用域由代码管理，且无法通过工具修改 — 要更改默认规则，请编辑该文件并部署（数据写入器会重新应用这些规则），而不是在线编辑。

你自己的规则（项目作用域，运行时设置）。 使用 memory_guidelines(action="set", scope="<project>", name=..., rule=...) 添加特定于团队或项目的规则 — 这些规则可在运行时写入，且仅提供给该项目中的 Agent。部署细节应放在这里。

审批边界。 内置的“执行，不要询问”规则刻意保持通用 — 它阐明了原则（执行可逆操作；只有不可逆操作需要人工批准），并将具体边界交由你自己的 Agent 群审批契约定义。请将其定义为规范（例如 memory_define_spec(name="approval-contract", spec_type="interface", ...)）或项目作用域准则；当某项操作的可逆性存疑时，Agent 会获取该规范。不要将某个 Agent 群的预发布／生产／合并策略写进随项目发布的默认规则。

对于其涵盖的流程，服务端准则具有权威性 — 即使项目的 CLAUDE.md 中还留有过时的上下文或会话启发式规则，也应以服务端准则为准。

过时信息管理

每个 memory_query 结果都会包含时效性警告。Agent 会在遇到过时信息时将其更新替换 — 在日常工作中分布式地清理，而不是另设一项任务。使用 memory_archive_by_tag 批量归档已完成的功能。

请参阅 docs/WORKED_EXAMPLE.md，了解两个 Agent 如何协调完成实际任务。

---

路线图

欢迎贡献！以下是已知的项目待完善之处：

• 身份验证和租户隔离 — 已完成！支持基于 API 密钥的 RBAC 和项目范围控制。请参阅安全。
• 支持 PostgreSQL — memory_db 工具支持 MSSQL 和 MySQL，尚未实现 PostgreSQL 支持。
• 为 librarian 提供本地模型支持 — 集成 Ollama，使增强守护进程无需云 API 密钥即可运行
• TTL 和过时数据清理 — 在后台清理过期会话、锁和消息，并支持配置保留期限
• 数据导出／备份工具 — 提供用于迁移和灾难恢复的转储与还原脚本

请参阅 docs/WORKED_EXAMPLE.md，了解多 Agent 协作的端到端示例。

---

托管版本

不想自行运行服务端？我们提供托管版本 — 你将获得配有 MongoDB 和 ChromaDB 的专属实例，只需将 Agent 指向该 URL 即可使用。

• 无需设置服务端 — 几分钟内即可连接 Agent
• 自动备份
• 相同的 57 个工具和功能
• 多项目隔离

感兴趣？ 请提交 issue 或联系我们了解详情。

---

许可证

完整文本请参阅 LICENSE。

版权所有 (c) 2024-2026 Thomas Lemmons。

---

参与贡献

欢迎贡献。在提交拉取请求之前，请先创建 issue 讨论重大变更。本项目使用标准 Python 工具，除 requirements.txt 中的依赖项外，无需特殊的构建系统或测试框架。

如果你在运行多 Agent 配置，并且有行之有效的协调模式，我很乐意听听。

---

如果这个项目为你节省了时间，可以考虑 赞助 项目开发。