knowledge-ops

知識操作

管理多層知識系統，用於跨多個儲存庫匯入、整理、同步與檢索知識。

偏好即時工作區模型：

• 程式碼工作在實際複製的儲存庫中進行
• 活躍執行上下文存在於 GitHub、Linear 以及儲存庫本機的工作上下文檔案中
• 較廣泛的人員面向筆記可以放在非儲存庫的 context/archive 資料夾中
• 跨機器的持久記憶屬於知識庫，而非影子儲存庫工作區

何時啟用

• 使用者想要將資訊儲存到知識庫
• 將文件、對話或資料匯入結構化儲存
• 跨系統同步知識（本地檔案、MCP 記憶、Supabase、Git 儲存庫）
• 對現有知識進行去重或整理
• 使用者說「儲存到知識庫」、「同步知識」、「我知道關於 X 的什麼」、「匯入這個」、「更新知識庫」
• 任何超出簡單記憶回想的知識管理任務

知識架構

第 1 層：活躍執行真相

• 來源： GitHub issues、PRs、討論、發行說明、Linear issues/專案/文件
• 用途： 工作的當前操作狀態
• 規則： 如果某件事影響活躍的工程計畫、路線圖、上線或發行，優先放在這裡

第 2 層：Claude Code 記憶（快速存取）

• 路徑： ~/.claude/projects/*/memory/
• 格式： 帶有 frontmatter 的 Markdown 檔案
• 類型： 使用者偏好、回饋、專案上下文、參考
• 用途： 跨對話持續存在的快速存取上下文
• 在會話開始時自動載入

第 3 層：MCP 記憶伺服器（結構化知識圖譜）

• 存取： MCP 記憶工具（create_entities、create_relations、add_observations、search_nodes）
• 用途： 跨所有儲存記憶的語意搜尋、關係對映
• 跨會話持久性，具有可查詢的圖譜結構

第 4 層：知識庫儲存庫 / 持久文件儲存

• 用途： 精選的持久筆記、會話匯出、綜合研究、操作員記憶、長篇文件
• 規則： 當內容不屬於儲存庫擁有的程式碼時，這是跨機器上下文的首選持久儲存

第 5 層：外部資料儲存（Supabase、PostgreSQL 等）

• 用途： 結構化資料、大型文件儲存、全文搜尋
• 適用於： 對於記憶檔案過大的文件、需要 SQL 查詢的資料

第 6 層：本機 context/archive 資料夾

• 用途： 人員面向筆記、已歸檔的遊戲計畫、本地媒體整理、臨時非程式碼文件
• 規則： 可寫入用於資訊儲存，但不是影子程式碼工作區
• 請勿用於： 應存在於上游的活躍程式碼變更或儲存庫真相

匯入工作流程

當需要擷取新知識時：

1. 分類

這是哪種類型的知識？

• 商業決策 -> 記憶檔案（專案類型）+ MCP 記憶
• 活躍路線圖 / 發行 / 實作狀態 -> 先放 GitHub + Linear
• 個人偏好 -> 記憶檔案（使用者/回饋類型）
• 參考資訊 -> 記憶檔案（參考類型）+ MCP 記憶
• 大型文件 -> 外部資料儲存 + 記憶中的摘要
• 對話/會話 -> 知識庫儲存庫 + 記憶中的簡短摘要

2. 去重

檢查此知識是否已存在：

• 搜尋記憶檔案中的現有條目
• 使用相關詞彙查詢 MCP 記憶
• 在建立另一個本地筆記前，檢查資訊是否已存在於 GitHub 或 Linear 中
• 不要建立重複項。改為更新現有條目。

3. 儲存

寫入適當的層：

• 始終更新 Claude Code 記憶以快速存取
• 使用 MCP 記憶進行語意可搜尋性和關係對映
• 當資訊改變即時專案真相時，先更新 GitHub / Linear
• 提交到知識庫儲存庫以進行持久的長篇新增

4. 索引

更新任何相關的索引或摘要檔案。

同步操作

對話同步

定期將對話歷史同步到知識庫：

• 來源：Claude 會話檔案、Codex 會話、其他代理會話
• 目的地：知識庫儲存庫
• 產生會話索引以便快速瀏覽
• 提交並推送

工作區狀態同步

將重要的工作區配置和腳本鏡像到知識庫：

• 產生目錄對映
• 在提交前編輯敏感配置
• 追蹤隨時間的變更
• 不要將知識庫或 archive 資料夾視為即時程式碼工作區

GitHub / Linear 同步

當資訊影響活躍執行時：

• 更新相關的 GitHub issue、PR、討論、發行說明或路線圖執行緒
• 當工作需要持久的規劃上下文時，將支援文件附加到 Linear
• 之後僅在仍有價值時才鏡像本地筆記

跨來源知識同步

將來自多個來源的知識匯集到一處：

• Claude/ChatGPT/Grok 對話匯出
• 瀏覽器書籤
• GitHub 活動事件
• 寫入狀態摘要，提交並推送

記憶模式

# 短期：當前會話上下文
使用 TodoWrite 進行會話內任務追蹤

# 中期：專案記憶檔案
寫入 ~/.claude/projects/*/memory/ 以跨會話回憶

# 長期：GitHub / Linear / KB
將活躍執行真相放在 GitHub + Linear
將持久的綜合上下文放在知識庫儲存庫

# 語意層：MCP 知識圖譜
使用 mcp__memory__create_entities 建立永久結構化資料
使用 mcp__memory__create_relations 進行關係對映
使用 mcp__memory__add_observations 新增關於已知實體的新事實
使用 mcp__memory__search_nodes 尋找現有知識

最佳實踐

• 保持記憶檔案簡潔。歸檔舊資料，而不是讓檔案無限制增長。
• 在所有知識檔案上使用 frontmatter（YAML）作為元資料。
• 在儲存前先去重。先搜尋，然後建立或更新。
• 每組事實偏好一個規範的歸宿。避免在本地筆記、儲存庫檔案和追蹤器文件之間平行複製相同的計畫。
• 在提交到 Git 前編輯敏感資訊（API 金鑰、密碼）。
• 對知識檔案使用一致的命名慣例（小寫-連字號-分隔）。
• 使用主題/類別標記條目以便於檢索。

品質關卡

在完成任何知識操作之前：

• 沒有建立重複條目
• 敏感資料已從任何 Git 追蹤的檔案中編輯
• 索引和摘要已更新
• 為資料類型選擇了適當的儲存層
• 在相關處添加了交叉引用