Junê (june-mcp)

june-mcp

為你的 agent 賦予記憶。 june-mcp 是 Junê 的官方 MCP 伺服器——它將任何 MCP 主機（Claude Desktop、Claude Code 等）連接到 June 知識圖譜，讓你的 agent 可以針對共享、具引用、租戶隔離的記憶進行詢問、搜尋與記住。

這個套件是一個輕薄、零邏輯的連接器：所有檢索、圖譜組裝與回答都在你指向的 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 服務通訊。有三種方式可以取得：

1. Junê 桌面應用程式（本地優先）。 執行 Junê 應用程式 並連接到其本地引擎——你的檔案、圖譜和金鑰都留在你的機器上。
2. 你自己的 June 服務。 執行 june-local 引擎套件的 Pro/Team 客戶可將 JUNE_BASE_URL 指向他們自己的伺服器。
3. 託管（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 僅暴露編碼 agent 使用的六個動詞（june_answer / june_context / june_search / june_remember / june_learn / june_usage），附一段話的握手，約 2.5k token——適用於只需要詢問與記住的會話
JUNE_FILES_ROOT	選填	選擇加入的目錄，agent 可透過 june_ingest_file 從中上傳檔案——未設定 ⇒ 該工具不存在
JUNE_TIMEOUT_READ / JUNE_TIMEOUT_ANSWER	選填	每個動詞的逾時（預設 15 秒 / 120 秒）
JUNE_TOOL_CONCURRENCY	選填	此連線上同時執行的最大工具呼叫數（預設 8）。主機會透過單一資料流管線化請求；這是明確的上限——超出的呼叫會排隊，絕不暴衝
JUNE_DOCS_CANVAS	選填	存放agent 文件（常駐指示/技能——見下方 Agent 記憶）的畫布。預設 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	選填	選擇加入的儲存庫目錄，agent 可將 June 頁面/文件匯出為檔案（見下方 儲存庫同步）——未設定 ⇒ 三個儲存庫同步工具不存在
JUNE_EXPORT_GIT	選填	1 僅提交每次匯出所寫入的檔案（限制路徑規格，絕不推送）
JUNE_EXPORT_DIR	選填	根目錄內的 agent 文件子樹（預設 docs/agent）
JUNE_LOG_LEVEL	選填	記錄僅輸出至 stderr 是刻意設計——stdout 是 MCP 線路

在 agent 之前先檢查

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 退出，而不是以半接線狀態啟動。先執行醫生；它會在 agent 看到伺服器之前捕捉所有常見的錯誤設定。

接入 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 起的預設精簡介面。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。

舊名稱在你儲存的 agent 文件中仍可運作：常駐文件摘要攜帶舊名稱 → 新名稱對應表，呼叫摺疊名稱時會以確切的替代名稱拒絕（june_page_get is not a tool on this surface (compact): call june_page_read with op='get'）。

每個操作的用途：

工具	你的 agent 獲得什麼
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	讀取 agent 的常駐文件——完整摘要、註冊表列表、單一文件的內文
june_doc_save / june_doc_delete / june_learn	寫入它們——建立/取代文件或技能、兩階段刪除、附加一則帶日期的課程
june_usage	用量收據——June 實際提供的服務，以具名 tokenizer 量測，絕不估算。一份完整收據（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，因此引擎可以記錄此 agent 會話已擁有哪些文件（它避免的重新讀取）。頁尾絕不說「已節省」：這個詞只存在於持有已量測配對的收據上。沒有收據的引擎不會傳送頁尾，且 june_usage 會直接回答它們已關閉。

描述是為 agent 撰寫的（什麼 → 何時 → 回傳），且每個被限制的輸入都會明顯地回報給 agent，而不是靜默截斷。

Agent 記憶——文件、技能與防遺忘摘要

長時間的會話會遺忘：agent 在會話開始時讀取的指示（其 CLAUDE.md、你的慣例）在數千個 token 之後會失去效力。june-mcp 從結構上解決這個問題。

Agent 將常駐文件儲存到 June——kind='doc' 用於持久指示（pinned=true = 永遠生效）、kind='skill' 用於具一行 when_to_use 觸發的具名程序（內文延遲載入，如同技能應有的行為）、kind='learnings' 用於透過 june_learn 寫入的僅附加、帶日期的日誌。每份文件都是文件畫布（JUNE_DOCS_CANVAS，預設 agent_docs）中的普通 June 頁面，以一個小型中繼資料區塊標記——因此你可以在 Junê 應用程式中開啟 agent 的記憶、閱讀並編輯；agent 會在下次重新整理時接收你的編輯。

防遺忘的另一半：在每個會話的第一次工具呼叫時，然後每 12 次呼叫或 10 分鐘（可調整），連接器將一份精簡的 standing_docs 摘要附加到普通工具結果——完整釘選的內文、技能觸發行、文件一行摘要。工具結果總是重新進入模型的新鮮上下文，因此指示不會像系統提示詞那樣衰減，在任何 MCP 主機上、無需主機配合。無法建構的摘要（服務忙碌、畫布缺失）會被靜默跳過——它絕不讓攜帶它的呼叫付出任何代價。設定 JUNE_DOCS_REFRESH=0 可關閉摘要；文件工具仍可運作。 June 教導代理程式如何從自身內部使用它。 第一次儲存會建立 docs 畫布，並植入 agent-memory-guide：操作手冊（系統畫布與工作串流畫布中各應放置什麼、 三種類型及何時使用每一種、命名規則、要釘選什麼、修訂紀律、儲存庫同步）。 它會列在每個登錄和摘要中，代理程式在不確定時會用 june_doc_get('agent-memory-guide') 閱讀它——而且它是一個普通頁面，所以你可以編輯它， 你的代理程式就會遵循你的版本。在儲存任何內容之前，空狀態會回傳 setup 逐步引導，而不是聳肩，而 june_memory_setup 提示會讓代理程式訪談你， 並將你的慣例儲存為第一份文件。

讓 June 自動化——代理程式無需被告知就會依賴它

「使用 June」永遠不應該需要說出口。三種機制層層堆疊，讓使用自動化，每一種 都涵蓋前一項的盲點：

1. 主機掛鉤（關閉冷啟動）。 伺服器在代理程式第一次呼叫之前無法發言—— 所以將 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、 不經提示記住事實、在事情發生時學習教訓——放入系統提示本身。

2. 主動式工具描述（永不衰減）。 核心動詞的描述告訴模型 何時應主動使用它們——而描述在每個 MCP 主機的每一輪都會被重新讀取， 無需任何合作。

3. 釘選的 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，每次匯出都只提交 它寫入的檔案——受限於 pathspec，因此你暫存的工作永遠不會被捲入，而且永遠不會推送。 匯出的檔案帶有 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 將「文件是最新的嗎？」從希望變成失敗的建置。

Free 與 Pro——june-pro 標籤

june-mcp 是適用於所有人的單一套件；沒有單獨的「pro 建置」。Pro 是端點 的屬性，而不是連接器的屬性：連接到已啟用 Pro 的 June（應用程式中的 Pro 授權、 託管工作區上的 Pro 金鑰），相同的工具就會攜帶 Pro 等級的結果：每個 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 讀取的（與伺服器端 Pro 路由閘道相同的授權狀態）， 因此它不可能與你實際獲得的內容不一致——而且它僅供顯示： 無論任何用戶端列印什麼，授權都在服務上強制執行。沒有 /v1/whoami 的 較舊服務只會不顯示標籤。

安全模型

工具表面不暴露畫布/工作區參數——工作區是從你連線的內容伺服器端綁定的， 失敗即關閉。跨租戶讀取不是可能開放失敗的權限檢查；它從用戶端是無法表示的。 JUNE_READONLY=1 為唯讀部署增加了第二道圍欄。你自帶的 LLM 金鑰會作為標頭伴隨每個 答案請求，而且服務永遠不會持久化或記錄它。

錯誤

每個上游失敗都會對應到一個型別化、編輯過的錯誤負載（僅從例外型別 + HTTP 狀態建置——絕不從回應主體），因此伺服器能承受端點拋出的任何情況， 而你的代理程式會看到乾淨、可操作的訊息。

授權

MIT。Junê 引擎本身是一個獨立、封閉原始碼的產品——這個連接器是開放 的部分，這是設計使然。