Junê (june-mcp)

官方

为您的智能体赋予记忆：适用于任何MCP主机的共享、可引用、租户隔离的知识图谱记忆。基于本地优先的Junê端点提供有依据的答案——宁可弃答，也不猜测。

你可以用 Junê (june MCP 做什么？

基于记忆的引用回答 — 让您的助手基于您的六月知识图谱回答问题，并附上来源，在不确定时通过 june_answer 选择不回答。
搜索与上下文组装 — 让您的助手使用 june_search 或 june_context 为查询检索排名证据，或构建一个受 token 预算限制的上下文包。
记住事实和笔记 — 告诉您的助手将事实或笔记保存到图谱中，以便日后通过 june_remember 立即检索和引用。
探索知识图谱 — 让您的助手使用 june_graph 展示某个节点周围的邻域，或导出有界子图，可带或不带参数。
管理常驻指令 — 指示您的助手保存持久文档或技能、列出它们，或追加带日期的经验教训，以便通过 june_doc_save、june_doc_list 或 june_learn 永不忘记您的约定。
将文档同步到您的仓库 — 让您的助手使用 june_docs_export 或 june_page_import 将代理文档或页面作为受管文件导出到您的仓库，或将您的编辑导入回来。

文档

june-mcp

给你的智能体一个记忆。 june-mcp 是 Junê 的官方 MCP 服务器——它将任何 MCP 主机（Claude Desktop、Claude Code 等）连接到 June 知识图谱，让你的智能体能够针对一个共享、带引用、租户隔离的记忆进行提问、搜索和记忆。

这个包是一个轻量的、零逻辑的连接器：所有的检索、图谱组装和回答都发生在你所指向的 June 端点上。这里没有引擎代码——这就是为什么它小到可以一口气读完。

Claude Desktop / Claude Code  ──stdio──▶  june-mcp  ──HTTPS──▶  your June endpoint
                                                                 (graph · retrieval · answers)

安装

pip install june-mcp          # just the connector   (or: pipx install june-mcp)
pip install june-ai           # umbrella: june-mcp + june-bench (the benchmark suite)
pip install "june-bench[mcp]" # the bench, with the connector as an extra

指向一个 June 端点

june-mcp 可以与任何 June 服务通信。有三种方式可以获得一个：

Junê 桌面应用（本地优先）。 运行 Junê 应用并连接到其本地引擎——你的文件、图谱和密钥都保留在你的机器上。
你自己的 June 服务。 运行 june-local 引擎包的 Pro/Team 客户可以将 JUNE_BASE_URL 指向他们自己的服务器。
托管（Team）。 使用你控制台中的 API 密钥，指向你托管的 June 工作区端点。

配置

服务器是故障关闭的：除非它知道连接到何处以及以谁的身份连接，否则拒绝启动，并且会一次性告诉你所有缺失的信息（而不是一次一个错误）。

环境变量	必需	含义
`JUNE_BASE_URL`	✅	你的 June 端点，例如 `http://localhost:8000`
`JUNE_CANVAS`	✅	要绑定到此连接的画布（工作区）——一个名称（`work`）或画布 ID。名称在启动时解析为 ID；有歧义的名称会故障关闭
`JUNE_CANVAS_CREATE`	可选	`1` 在首次运行时创建指定的画布（如果它尚不存在）（在只读模式下会被拒绝）
`JUNE_API_KEY`	✅	你的 June API 密钥（`JUNE_ALLOW_ANON=1` 明确选择退出无密钥的本地设置）
`JUNE_LLM_KEY`	可选	自带 LLM 密钥，用于带引用的回答——按请求作为标头转发，从不记录，从不存储在服务上
`JUNE_READONLY`	可选	`1` 隐藏并拒绝所有写入工具（记忆变为只读）
`JUNE_TOOL_PROFILE`	可选	`compact`（默认）、`full` 或 `lean`。compact 将 17 个相关工具折叠为七个接受 `op` 的工具族——列出 20 个工具而不是 30 个，在 Pro 读写连接上为 11,359 个提示词 token 而不是 13,236 个。每次调用都分派到与之前相同的代码，因此门控、画布规则、回执和两阶段确认都不变。在它成为默认值之前在四个主机上测量：Claude Code 1.000 任务成功率（基线 0.987），GPT-5.4 直接 0.983（0.957），Codex 0.922（0.763），每个分支零次不安全擦除。full 以各自的名称列出全部 30 个成员——相同的 0.4.2 代码，每个一个名称。lean 只暴露编码智能体使用的六个动词（`june_answer` / `june_context` / `june_search` / `june_remember` / `june_learn` / `june_usage`），带一段握手说明，约 2.5k token——适用于只需要提问和记忆的会话
`JUNE_FILES_ROOT`	可选	选择加入的目录，智能体可以通过 `june_ingest_file` 从中上传文件——未设置 ⇒ 该工具不存在
`JUNE_TIMEOUT_READ` / `JUNE_TIMEOUT_ANSWER`	可选	每个动词的超时时间（默认 15 秒 / 120 秒）
`JUNE_TOOL_CONCURRENCY`	可选	此连接上同时执行的最大工具调用数（默认 8）。主机通过一个流管道化请求；这是显式上限——超出部分排队，绝不蜂拥
`JUNE_DOCS_CANVAS`	可选	保存智能体文档（常驻指令/技能——见下文智能体记忆）的画布。默认 `agent_docs`；在第一次 `june_doc_save` 时创建
`JUNE_DOCS_REFRESH`	可选	`0` 禁用定期的 `standing_docs` 摘要（默认开启——它是防遗忘的安全网）
`JUNE_DOCS_REFRESH_CALLS` / `JUNE_DOCS_REFRESH_MINUTES`	可选	摘要节奏：每 N 次工具调用（默认 12）或 M 分钟（默认 10）到期，以先到者为准
`JUNE_DOCS_DIGEST_CHARS`	可选	序列化摘要大小上限（默认 2000）
`JUNE_EXPORT_ROOT`	可选	选择加入的仓库目录，智能体可以将 June 页面/文档导出为文件（见下文仓库同步）——未设置 ⇒ 三个仓库同步工具不存在
`JUNE_EXPORT_GIT`	可选	`1` 只提交每次导出写入的文件（路径限定，绝不推送）
`JUNE_EXPORT_DIR`	可选	根目录内的智能体文档子树（默认 `docs/agent`）
`JUNE_LOG_LEVEL`	可选	日志设计上仅输出到 stderr——stdout 是 MCP 线路

在智能体之前检查它

JUNE_BASE_URL=http://localhost:8000 JUNE_API_KEY=... JUNE_CANVAS=work june-mcp --doctor

诊断器按顺序验证：配置 → 服务可达 → 画布解析（你的画布名称 → 其 ID，例如 name "work" → 9147bee6-…）→ 搜索接缝健康 → 工具清单，并逐项打印 PASS/FAIL 及映射提示（例如，缺少名称时会列出确实存在的画布并指向 JUNE_CANVAS_CREATE=1）。诊断器仅在每项检查都通过时以 0 退出（否则为 1）；服务器本身在配置错误时以 2 退出，而不是半连接地启动。先运行诊断器；它能在你的智能体看到服务器之前捕获所有常见的配置错误。

接入 Claude

Claude Desktop — 合并到 claude_desktop_config.json（设置 → 开发者）：

{
  "mcpServers": {
    "june": {
      "command": "june-mcp",
      "env": {
        "JUNE_BASE_URL": "http://localhost:8000",
        "JUNE_API_KEY": "your-key",
        "JUNE_CANVAS": "work",
        "JUNE_LLM_KEY": "your-llm-provider-key"
      }
    }
  }
}

Claude Code：

claude mcp add june -e JUNE_BASE_URL=http://localhost:8000 \
  -e JUNE_API_KEY=your-key -e JUNE_CANVAS=work \
  -e JUNE_LLM_KEY=your-llm-provider-key -- june-mcp

完全重启主机（macOS 上按 Cmd+Q），然后检查服务器是否显示 20 个工具——即自 0.4.2 以来的默认 compact 表面。JUNE_TOOL_PROFILE=full 以 30 个单独命名的工具列出相同的能力（当你通过 JUNE_FILES_ROOT 选择加入 june_ingest_file 时为 31 个）。

工具

默认表面是 compact：20 个工具，其中七个将相关操作分组在一个 op 参数后面。JUNE_TOOL_PROFILE=full 以各自的名称列出全部 30 个成员——相同的能力、相同的门控、相同的行为。

工具族	操作	折叠
`june_graph`	`neighborhood`、`subgraph`	`june_neighborhood`、`june_subgraph`
`june_maintain`	`enrich`、`resolve`	`june_enrich`、`june_resolve`
`june_page_read`	`list`、`get`、`grammar`	`june_page_list`、`june_page_get`（+ 按需的块语法）
`june_page_edit`	`create`、`append`、`update`	`june_page_create`、`june_page_append`、`june_page_update`
`june_canvas_read`	`list`、`current`、`use`	`june_canvas_list`、`june_canvas_current`、`june_canvas_use`
`june_canvas_erase`	`clear`、`delete`	`june_canvas_clear`、`june_canvas_delete`
`june_docs_read`	`refresh`、`list`、`get`	`june_docs_refresh`、`june_doc_list`、`june_doc_get`

其他所有工具都保留自己的名称：june_answer、june_search、june_enumerate、june_context、june_usage、june_remember、june_ingest、june_page_write、june_page_delete、june_canvas_create、june_doc_save、june_doc_delete、june_learn。一个可以移除某物的动词永远不会与不能移除的动词折叠在一起——因此 june_page_write 和 june_page_delete 与 june_page_edit 保持分离，每个工具族都携带一个诚实的 destructiveHint。

旧名称在你保存的智能体文档中继续有效：常驻文档摘要携带旧名称 → 新名称的映射，调用折叠名称会被拒绝并给出确切的替代名称（june_page_get is not a tool on this surface (compact): call june_page_read with op='get'）。

每个操作的作用：

工具	你的智能体得到什么
`june_answer`	来自图谱的、有依据的、带引用的回答——宁可弃权也不猜测
`june_search`	查询的排序证据（支持多跳）
`june_context`	在 token 预算下组装好的上下文包
`june_neighborhood`	单个节点周围的图谱
`june_subgraph`	有界子图导出
`june_remember`	将事实/笔记写入图谱（立即可检索 + 可引用）。长文本作为引擎作业运行：`{state: running, job_id}` 的结果通过 `june_remember(job_id=…)` 收集——绝不重新发送文本。粘贴的文本在引擎上按内容寻址（v0.0.13），因此重新发送相同文本会更新相同的节点；它不会重复
`june_ingest`	结构化节点/边摄取
`june_enumerate`	匹配谓词的每个节点——召回完整的“列出所有 X”（不是 top-k）
`june_ingest_file`	从操作员批准的文件夹上传一个本地文件（pdf/docx/xlsx/csv/html/md/图片/音频）——仅在你设置 `JUNE_FILES_ROOT` 时存在
`june_enrich`	Pro：使用更丰富的引擎对画布进行后台重新提取（幂等；作业 + 轮询；免费版返回 403）
`june_resolve`	维护：通过可逆的 `same_as` 边合并重复实体（在服务器端运行；`strong_only=false` 在 Pro 上解锁语义层）
`june_docs_refresh` / `june_doc_list` / `june_doc_get`	读取智能体的常驻文档——完整摘要、注册表列表、单个文档正文
`june_doc_save` / `june_doc_delete` / `june_learn`	写入它们——创建/替换文档或技能、两阶段删除、追加一条带日期的经验
`june_usage`	用量回执——June 实际服务的内容，由命名的分词器测量，从不估算。一条完整回执（`receipt_id`）或窗口摘要（`window`）；节省数字只出现在两个提供商报告的用量确实被测量的调用上

每次读取的回执

当引擎以 JUNE_USAGE=1 运行时（桌面：设置 → 用量回执），每次 june_answer / june_context / june_search 结果也携带 receipt 和一行 receipt_footer：

receipt r_7f…: served 812 tokens (exact, tiktoken:cl100k_base) from 3 blocks across 2 docs
· 1 doc this session already had — june_usage(receipt_id="r_7f…") shows it in full

连接器为每个服务器进程发送 X-June-Source: mcp 和一个 X-June-Session ID，以便引擎可以记录此智能体会话已经拥有哪些文档（它避免的重复读取）。页脚从不显示“已保存”：这个词只存在于持有测量对的回执上。没有回执的引擎不发送页脚，june_usage 会直白地回答它们已关闭。

描述是为智能体编写的（什么 → 何时 → 返回什么），每个被截断的输入都会可见地回注给智能体，而不是静默截断。

智能体记忆——文档、技能和防遗忘摘要

长会话会遗忘：智能体会话开始时读取的指令（它的 CLAUDE.md、你的约定）在数千个 token 之后会失去效力。june-mcp 从结构上解决了这个问题。

智能体将常驻文档保存到 June——kind='doc' 用于持久指令（pinned=true = 始终生效），kind='skill' 用于带一行 when_to_use 触发的命名程序（正文懒加载，就像技能应该的那样），kind='learnings' 用于通过 june_learn 写入的仅追加的带日期日志。每个文档都是文档画布（JUNE_DOCS_CANVAS，默认 agent_docs）中的普通 June 页面，带有一个小的元数据块标记——因此你可以在 Junê 应用中打开智能体的记忆、阅读并编辑它；智能体会在下次刷新时拾取你的编辑。

防遗忘部分：在每个会话的第一次工具调用时，然后每 12 次调用或 10 分钟（可调），连接器将一个紧凑的 standing_docs 摘要附加到普通工具结果上——固定正文完整、技能触发行、文档一句话摘要。工具结果总是重新进入模型的新鲜上下文，因此指令不会像系统提示词那样衰减，在任何 MCP 主机中，无需主机配合。无法构建的摘要（服务繁忙、画布缺失）会被静默跳过——它绝不会让承载调用付出任何代价。设置 JUNE_DOCS_REFRESH=0 可关闭摘要；文档工具继续工作。 June 教会智能体如何使用它——从它自身内部开始。 首次保存会创建文档画布并植入 agent-memory-guide：操作手册（系统画布与工作流画布中各应放置什么内容、三种画布类型及各自的使用时机、命名规范、固定内容、修订纪律、仓库同步）。它被列在每一个注册表和摘要中，智能体在不确定时会用 june_doc_get('agent-memory-guide') 阅读它——而且它是一个普通页面，所以你可以编辑它，你的智能体会遵循你的版本。在保存任何内容之前，空状态会返回一个 setup 的引导说明，而不是一个无意义的耸肩，并且 june_memory_setup 提示会让智能体对你进行访谈，并将你的约定保存为第一批文档。

让 June 自动化——智能体无需被告知即可依赖它

“使用 June”永远不需要说出口。三种机制叠加使使用变得自动化，每一种都弥补了前一种的盲区：

宿主钩子（解决冷启动）。 服务器在智能体首次调用之前无法发言——因此将 June 的常驻指令安装到你的宿主每次会话原生加载的文件中：
```
JUNE_EXPORT_ROOT=/path/to/project june-mcp --install-instructions            # → CLAUDE.md
JUNE_EXPORT_ROOT=/path/to/project june-mcp --install-instructions AGENTS.md  # other agents
```
它被写成一个受管区块（你自己的内容永远不会被触碰；重新运行会在原位置更新它），它将 june-first 的姿态——在声称不知道之前先检查 June、主动记住事实、在事情发生时吸取教训——放入系统提示本身。
主动式工具描述（永不衰减）。 核心动词的描述告诉模型何时应主动使用它们——而描述在每一轮对话中都会被重新读取，在任何 MCP 宿主中，无需任何配合。
固定的 june-first 文档（在整个会话中反复强调）。 它与指南一起被植入，随每次 standing_docs 摘要一起出现，因此这种姿态会在会话中期被重复，正好在长上下文漂移可能侵蚀它的地方。与所有被植入的内容一样，它是一个普通页面——编辑它，你的智能体就会遵循你的版本。

诚实地讲，任何 MCP 服务器都无法做到的是强制宿主采取行动：一个宿主既隐藏了 SERVER_INSTRUCTIONS，又没有指令文件，也从未进行过一次 June 调用的智能体，仍然会保持冷启动。机制 1 的存在正是为了确保这种情况在实践中永远不会发生。

仓库同步——仓库与 June 所知保持同步

通过 JUNE_EXPORT_ROOT=<your repo> 选择启用后，会出现三个额外的工具：

工具	功能
`june_docs_export`	将每个智能体文档镜像到 `docs/agent/<name>.md`——仓库始终持有当前的常驻指令
`june_page_export`	将任何页面导出为受管文件，或导出到现有文件中标记之间的受管区块中（`path=KNOWHOW.md section=june-learnings`）——只有标记区域会被触碰
`june_page_import`	反向操作：在你的编辑器中编辑导出的文件，并将其导入回其 June 页面——智能体文档保持其身份，过时的文件会被拒绝，而不是允许覆盖更新的知识

安全规则全部在代码中强制执行并由测试固定：每个路径都被限制在根目录内（词法 .. 检查以及符号链接解析）；从未覆盖非 june-mcp 写入的文件；从不删除任何内容；并且使用 JUNE_EXPORT_GIT=1 时，每次导出只提交它写入的文件——路径规范受限，因此你暂存的工作永远不会被卷入，并且推送永远不会发生。导出的文件带有 frontmatter 并且是字节确定性的，因此未更改的文档重新导出会生成相同的文件，git 保持安静。

清单（.june-export.json）使同步状态可检查——两种 CLI 模式用于 CI：

june-mcp --export         # sync agent docs + every managed page/section, commit if enabled
june-mcp --export-check   # write NOTHING; exit 1 if the repo has drifted from June

在 CI 中使用 --export-check 将“文档是最新的吗？”从一个希望变成一个失败的构建。

免费版与专业版——`june-pro` 标签

june-mcp 是面向所有人的单一包；没有单独的“专业版构建”。专业版是端点的属性，而不是连接器的属性：连接到已激活专业版的 June（应用中的专业版许可证，托管工作区上的专业版密钥），相同的工具会带来专业级的结果：每次 june_remember 和 june_ingest_file 写入都会自动运行更丰富的实体/边引擎（结果会报告运行了哪些 engine），june_resolve 升级为语义匹配，june_enrich 会回填你在升级前在免费层写入的记忆。终端会显示你所在的世界：--doctor 打印一行 edition，服务器的启动横幅会标记连接——

june-mcp: connected http://localhost:8000 canvas name "work" → 11d2… [june-pro]

该标签从服务自身的 /v1/whoami 读取（与服务器端门控专业版路由的授权状态相同），因此它不可能与你实际获得的内容不一致——而且它仅用于显示：无论客户端打印什么，授权都在服务端强制执行。没有 /v1/whoami 的旧服务只是不显示标签。

安全模型

工具表面不暴露画布/工作区参数——工作区在服务器端根据你连接的上下文绑定，失败即关闭。跨租户读取不是一个可能开放失败的权限检查；它在客户端是无法表示的。JUNE_READONLY=1 为只读部署增加了第二道围栏。你自带的 LLM 密钥随每个答案请求作为请求头传递，服务端从不持久化或记录它。

错误

每个上游失败都会映射为一个类型化、脱敏的错误负载（仅由异常类型 + HTTP 状态构建——绝不来自响应体），因此服务器能承受端点抛出的任何情况，你的智能体会看到清晰、可操作的消息。

许可证

MIT。Junê 引擎本身是一个独立的闭源产品——这个连接器是开放的部分，这是设计使然。