claude-mem 分支記憶可視化在 Viewer 觀察卡片中展示 Git 分支與 Commit SHA【免費下載鏈接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More項目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文基于 claude-mem 的分支記憶branch-memory特性開發(fā) playbook 中BRANCH-PARITY-02-Viewer-Branch-Display.md階段文檔展開講解如何把數據庫中已存儲的branch與commit_sha觀察元數據打通類型定義 → 分頁查詢 → React 卡片渲染三層鏈路最終在http://localhost:37777的 Viewer UI 中以分支徽章的形式呈現。讀完本文你將掌握 claude-mem Viewer 的數據流全貌、觀察卡片組件的渲染機制以及單文件 Viewer 的構建與驗證流程。1. 背景數據庫有分支信息Viewer 卻沒有claude-mem 的核心工作流是記錄 Agent 會話中的操作 → 用 AI 壓縮為觀察Observation → 在未來會話中重新注入相關上下文。分支記憶特性進一步要求記憶與 Git 分支邊界對齊——同一條觀察應當能被追溯它是在哪個分支、哪個提交上產生的。按 playbook 的原始描述此時系統(tǒng)的狀態(tài)是數據庫已經在每條觀察上存儲了branch與commit_sha由 migrations 24-25 引入的列但 React Viewer 中展示觀察卡片時只有類型、項目、標題、副標題、事實、敘事和元數據沒有分支信息原因很具體為 Viewer 供數的PaginationHelper查詢有意省略了這兩個列導致數據雖然入庫卻斷供于界面。因此這一階段的目標非常聚焦給觀察卡片加上分支可見性讓用戶一眼看出每條觀察來自哪個 git 分支從而補全分支記憶的視覺層。從源碼結構看當前倉庫快照中 PaginationHelper 的 SELECT 列表確實不含branch/commit_shaViewer 類型定義 的Observation接口也尚未包含這兩個字段——這與 playbook 描述的基線狀態(tài)一致該特性在 branch-memory 工作分支上開發(fā)playbook 中標記了各任務的完成狀態(tài)。2. 類型層給 Observation 接口加上可選的分支字段第一處改動發(fā)生在 Viewer 的 TypeScript 類型系統(tǒng) src/ui/viewer/types.ts。當前Observation接口為export interface Observation { id: number; memory_session_id: string; project: string; merged_into_project?: string | null; platform_source: string; type: string; title: string | null; subtitle: string | null; narrative: string | null; text: string | null; facts: string | null; concepts: string | null; files_read: string | null; files_modified: string | null; prompt_number: number | null; created_at: string; created_at_epoch: number; }需要追加兩個可選且可為 null的字段branch?: string | null; commit_sha?: string | null;關鍵設計決策是可選性branch?: string | null而非必填。因為存在大量早于分支記憶特性的歷史觀察它們的branch值為NULL——若聲明為必填字段舊數據會被類型系統(tǒng)誤判為非法。這一約定同時體現在 Viewer 側接口和 Worker 側接口 src/services/worker-types.tsPaginationHelper從后者導入Observation類型playbook 在任務完成備注中特別指出由于查詢結果是泛型透傳paginateObservation()類型更新后其余部分自動生效無需改動映射邏輯。3. 查詢層PaginationHelper.getObservations() 補列數據供給的斷點在 src/services/worker/PaginationHelper.ts 的getObservations()方法。當前實現對observations表執(zhí)行硬編碼列列表的 SELECT并按created_at_epoch DESC排序let query SELECT o.id, o.memory_session_id, o.project, o.merged_into_project, COALESCE(s.platform_source, claude) as platform_source, o.type, o.title, o.subtitle, o.narrative, o.text, o.facts, o.concepts, o.files_read, o.files_modified, o.prompt_number, o.created_at, o.created_at_epoch FROM observations o LEFT JOIN sdk_sessions s ON o.memory_session_id s.memory_session_id ;改動只有一處在列列表末尾追加o.branch, o.commit_sha。由于結果集通過db.prepare(query).all(...)取出后直接斷言為Observation[]列補上之后新字段會自動出現在返回對象里配合第 2 節(jié)的類型更新即完成整條鏈路。理解這段查詢的幾個配套細節(jié)有助于把握改動邊界分頁的 hasMore 探測params.push(limit 1, offset)——每次多取一行若返回行數超過limit則判定hasMore: true隨后slice(0, limit)截斷。這是無COUNT(*)的輕量分頁模式新增列不影響該邏輯。項目過濾指定project時匹配o.project ? OR o.merged_into_project ?支持已合并項目的歸屬追溯未指定時排除OBSERVER_SESSIONS_PROJECT觀察者自身會話來自 src/shared/paths.ts 的常量。返回前的清洗sanitizeObservation()會用stripProjectPaths()把files_read/files_modified中的絕對路徑剝離為相對路徑保證卡片不泄露本機目錄結構。分支字段不經過任何清洗原樣透傳。4. 渲染層ObservationCard 中的分支徽章展示邏輯落在 src/ui/viewer/components/ObservationCard.tsx。當前卡片的頭部結構card-header-left容器內依次渲染四枚徽章div classNamecard-header-left span className{card-type type-${observation.type}}{observation.type}/span span className{card-source source-${observation.platform_source || claude}} {observation.platform_source || claude} /span span classNamecard-project{observation.project}/span {observation.merged_into_project ( span classNamecard-merged-badge title{Merged into ${observation.merged_into_project}} merged → {observation.merged_into_project} /span )} /divplaybook 對該卡片的具體改造規(guī)格如下逐條對應現有代碼模式位置分支徽章放在card-header-left內、現有card-project徽章旁對應上面代碼中約第 51 行附近。條件渲染僅在observation.branch為 truthy 時渲染——遷移前的觀察該字段為null徽章必須靜默缺省不能占位。這與card-merged-badge的條件渲染寫法{observation.merged_into_project ...}完全同構可直接參照。圖標與文本一個簡化的 git 分支分叉 SVG 圖標fork 造型加分支名整體樣式仿照現有card-project的 span 寫法。Commit SHA 縮寫可選增強在分支名旁/下方展示commit_sha前 7 個字符commit_sha.slice(0, 7)使用等寬字體。配色區(qū)分徽章顏色需與項目徽章可區(qū)分——playbook 建議使用var(--color-text-muted)文字搭配柔和背景。配套的.card-branch新 CSS 類規(guī)格寫入 Viewer 樣式模板 src/ui/viewer-template.html屬性取值依據字號~11px與.card-project徽章一致背景var(--color-surface-hover)一類柔和表面色playbook 建議值圓角與現有徽章一致模板中徽章圓角為 3px參照 viewer-template.html 中.card-merged-badge的border-radius: 3pxSHA 部分等寬字體保證十六進制串等寬對齊作為參照現有徽章體系在模板中的定義是.card-project僅設color: var(--color-text-muted).card-merged-badge則是 9px 小字號、background: var(--color-type-badge-bg)、1px 邊框、opacity: 0.85的弱化樣式。分支徽章介于兩者之間——比 merged 徽章醒目、比 type 徽章克制——符合次要元數據的視覺層級。5. 構建與驗證單文件 Viewer 的產出鏈路Viewer 不是獨立部署的 Web 應用而是構建為單文件 HTML內嵌 CSS/JS源樣式模板src/ui/viewer-template.html含--color-text-muted等主題 CSS 變量多套主題下各有取值構建產物plugin/ui/viewer.html——Worker 服務啟動后由http://localhost:37777直接提供。驗證流程playbook 的任務清單在 package.json 中確認構建腳本生產構建入口為npm run build-and-sync其展開為npm run build npm run sync-marketplace node scripts/restart-marketplace-worker.cjs類型檢查有獨立腳本typecheck:viewer即tsc --noEmit -p src/ui/viewer/tsconfig.json可在完整構建前單獨快速校驗 Viewer 側改動本例中類型層與組件層改動都在這里被覆蓋運行npm test確認無回歸檢查構建產物plugin/ui/viewer.html中是否出現新的.card-branch樣式與渲染分支。6. 放到分支記憶全景中看本 playbook 是 Branch-Parity 階段的第 02 部分同目錄下還有BRANCH-PARITY-01-Chroma-Branch-Sync.md讓向量檢索層ChromaDB感知分支邊界——在StoredObservation/StoredSummary/ChromaMetadata三處接口加字段、在formatObservationDocs()中把分支元數據寫進 Chroma 文檔、在buildWhereFilter()中用{ commit_sha: { $in: commitShas } }加$or兼容無 commit_sha 的舊文檔實現分支感知過濾BRANCH-PARITY-03-MCP-Output-And-Verification.mdMCP 輸出層的收尾與整體驗證。三個階段共同指向同一架構思路分支元數據在 SQLite 中一次性落庫migrations 24-25 給observations加列Phase 01 還補了session_summaries的同名列此后每一層消費方——分頁查詢、Chroma 同步、MCP 工具輸出——都只是把已有列透傳出去。Viewer 展示本文主題是這條透傳鏈路的最后一環(huán)讓分支記憶從數據可查變成用戶可見。7. 小結改動極小、鏈路極清晰可選字段進兩個Observation接口types.ts 與 worker-types.tsSELECT 補兩列PaginationHelper.ts卡片條件渲染一枚徽章ObservationCard.tsx即可讓分支元數據從數據庫直達界面向后兼容是硬性約束branch?: string | null的可選聲明與truthy 才渲染徽章的組合保證遷移前的舊觀察在類型系統(tǒng)與 UI 上都自然降級為無分支不產生占位或報錯驗證閉環(huán)完整typecheck:viewer→npm test→npm run build-and-sync產出 plugin/ui/viewer.html構建產物可人工核驗新徽章的渲染結果?！久赓M下載鏈接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More項目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 claude-mem 分支記憶可視化：在 Viewer 觀察卡片中展示 Git 分支與 Commit SHA
claude-mem 分支記憶可視化在 Viewer 觀察卡片中展示 Git 分支與 Commit SHA【免費下載鏈接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More項目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文基于 claude-mem 的分支記憶branch-memory特性開發(fā) playbook 中BRANCH-PARITY-02-Viewer-Branch-Display.md階段文檔展開講解如何把數據庫中已存儲的branch與commit_sha觀察元數據打通類型定義 → 分頁查詢 → React 卡片渲染三層鏈路最終在http://localhost:37777的 Viewer UI 中以分支徽章的形式呈現。讀完本文你將掌握 claude-mem Viewer 的數據流全貌、觀察卡片組件的渲染機制以及單文件 Viewer 的構建與驗證流程。1. 背景數據庫有分支信息Viewer 卻沒有claude-mem 的核心工作流是記錄 Agent 會話中的操作 → 用 AI 壓縮為觀察Observation → 在未來會話中重新注入相關上下文。分支記憶特性進一步要求記憶與 Git 分支邊界對齊——同一條觀察應當能被追溯它是在哪個分支、哪個提交上產生的。按 playbook 的原始描述此時系統(tǒng)的狀態(tài)是數據庫已經在每條觀察上存儲了branch與commit_sha由 migrations 24-25 引入的列但 React Viewer 中展示觀察卡片時只有類型、項目、標題、副標題、事實、敘事和元數據沒有分支信息原因很具體為 Viewer 供數的PaginationHelper查詢有意省略了這兩個列導致數據雖然入庫卻斷供于界面。因此這一階段的目標非常聚焦給觀察卡片加上分支可見性讓用戶一眼看出每條觀察來自哪個 git 分支從而補全分支記憶的視覺層。從源碼結構看當前倉庫快照中 PaginationHelper 的 SELECT 列表確實不含branch/commit_shaViewer 類型定義 的Observation接口也尚未包含這兩個字段——這與 playbook 描述的基線狀態(tài)一致該特性在 branch-memory 工作分支上開發(fā)playbook 中標記了各任務的完成狀態(tài)。2. 類型層給 Observation 接口加上可選的分支字段第一處改動發(fā)生在 Viewer 的 TypeScript 類型系統(tǒng) src/ui/viewer/types.ts。當前Observation接口為export interface Observation { id: number; memory_session_id: string; project: string; merged_into_project?: string | null; platform_source: string; type: string; title: string | null; subtitle: string | null; narrative: string | null; text: string | null; facts: string | null; concepts: string | null; files_read: string | null; files_modified: string | null; prompt_number: number | null; created_at: string; created_at_epoch: number; }需要追加兩個可選且可為 null的字段branch?: string | null; commit_sha?: string | null;關鍵設計決策是可選性branch?: string | null而非必填。因為存在大量早于分支記憶特性的歷史觀察它們的branch值為NULL——若聲明為必填字段舊數據會被類型系統(tǒng)誤判為非法。這一約定同時體現在 Viewer 側接口和 Worker 側接口 src/services/worker-types.tsPaginationHelper從后者導入Observation類型playbook 在任務完成備注中特別指出由于查詢結果是泛型透傳paginateObservation()類型更新后其余部分自動生效無需改動映射邏輯。3. 查詢層PaginationHelper.getObservations() 補列數據供給的斷點在 src/services/worker/PaginationHelper.ts 的getObservations()方法。當前實現對observations表執(zhí)行硬編碼列列表的 SELECT并按created_at_epoch DESC排序let query SELECT o.id, o.memory_session_id, o.project, o.merged_into_project, COALESCE(s.platform_source, claude) as platform_source, o.type, o.title, o.subtitle, o.narrative, o.text, o.facts, o.concepts, o.files_read, o.files_modified, o.prompt_number, o.created_at, o.created_at_epoch FROM observations o LEFT JOIN sdk_sessions s ON o.memory_session_id s.memory_session_id ;改動只有一處在列列表末尾追加o.branch, o.commit_sha。由于結果集通過db.prepare(query).all(...)取出后直接斷言為Observation[]列補上之后新字段會自動出現在返回對象里配合第 2 節(jié)的類型更新即完成整條鏈路。理解這段查詢的幾個配套細節(jié)有助于把握改動邊界分頁的 hasMore 探測params.push(limit 1, offset)——每次多取一行若返回行數超過limit則判定hasMore: true隨后slice(0, limit)截斷。這是無COUNT(*)的輕量分頁模式新增列不影響該邏輯。項目過濾指定project時匹配o.project ? OR o.merged_into_project ?支持已合并項目的歸屬追溯未指定時排除OBSERVER_SESSIONS_PROJECT觀察者自身會話來自 src/shared/paths.ts 的常量。返回前的清洗sanitizeObservation()會用stripProjectPaths()把files_read/files_modified中的絕對路徑剝離為相對路徑保證卡片不泄露本機目錄結構。分支字段不經過任何清洗原樣透傳。4. 渲染層ObservationCard 中的分支徽章展示邏輯落在 src/ui/viewer/components/ObservationCard.tsx。當前卡片的頭部結構card-header-left容器內依次渲染四枚徽章div classNamecard-header-left span className{card-type type-${observation.type}}{observation.type}/span span className{card-source source-${observation.platform_source || claude}} {observation.platform_source || claude} /span span classNamecard-project{observation.project}/span {observation.merged_into_project ( span classNamecard-merged-badge title{Merged into ${observation.merged_into_project}} merged → {observation.merged_into_project} /span )} /divplaybook 對該卡片的具體改造規(guī)格如下逐條對應現有代碼模式位置分支徽章放在card-header-left內、現有card-project徽章旁對應上面代碼中約第 51 行附近。條件渲染僅在observation.branch為 truthy 時渲染——遷移前的觀察該字段為null徽章必須靜默缺省不能占位。這與card-merged-badge的條件渲染寫法{observation.merged_into_project ...}完全同構可直接參照。圖標與文本一個簡化的 git 分支分叉 SVG 圖標fork 造型加分支名整體樣式仿照現有card-project的 span 寫法。Commit SHA 縮寫可選增強在分支名旁/下方展示commit_sha前 7 個字符commit_sha.slice(0, 7)使用等寬字體。配色區(qū)分徽章顏色需與項目徽章可區(qū)分——playbook 建議使用var(--color-text-muted)文字搭配柔和背景。配套的.card-branch新 CSS 類規(guī)格寫入 Viewer 樣式模板 src/ui/viewer-template.html屬性取值依據字號~11px與.card-project徽章一致背景var(--color-surface-hover)一類柔和表面色playbook 建議值圓角與現有徽章一致模板中徽章圓角為 3px參照 viewer-template.html 中.card-merged-badge的border-radius: 3pxSHA 部分等寬字體保證十六進制串等寬對齊作為參照現有徽章體系在模板中的定義是.card-project僅設color: var(--color-text-muted).card-merged-badge則是 9px 小字號、background: var(--color-type-badge-bg)、1px 邊框、opacity: 0.85的弱化樣式。分支徽章介于兩者之間——比 merged 徽章醒目、比 type 徽章克制——符合次要元數據的視覺層級。5. 構建與驗證單文件 Viewer 的產出鏈路Viewer 不是獨立部署的 Web 應用而是構建為單文件 HTML內嵌 CSS/JS源樣式模板src/ui/viewer-template.html含--color-text-muted等主題 CSS 變量多套主題下各有取值構建產物plugin/ui/viewer.html——Worker 服務啟動后由http://localhost:37777直接提供。驗證流程playbook 的任務清單在 package.json 中確認構建腳本生產構建入口為npm run build-and-sync其展開為npm run build npm run sync-marketplace node scripts/restart-marketplace-worker.cjs類型檢查有獨立腳本typecheck:viewer即tsc --noEmit -p src/ui/viewer/tsconfig.json可在完整構建前單獨快速校驗 Viewer 側改動本例中類型層與組件層改動都在這里被覆蓋運行npm test確認無回歸檢查構建產物plugin/ui/viewer.html中是否出現新的.card-branch樣式與渲染分支。6. 放到分支記憶全景中看本 playbook 是 Branch-Parity 階段的第 02 部分同目錄下還有BRANCH-PARITY-01-Chroma-Branch-Sync.md讓向量檢索層ChromaDB感知分支邊界——在StoredObservation/StoredSummary/ChromaMetadata三處接口加字段、在formatObservationDocs()中把分支元數據寫進 Chroma 文檔、在buildWhereFilter()中用{ commit_sha: { $in: commitShas } }加$or兼容無 commit_sha 的舊文檔實現分支感知過濾BRANCH-PARITY-03-MCP-Output-And-Verification.mdMCP 輸出層的收尾與整體驗證。三個階段共同指向同一架構思路分支元數據在 SQLite 中一次性落庫migrations 24-25 給observations加列Phase 01 還補了session_summaries的同名列此后每一層消費方——分頁查詢、Chroma 同步、MCP 工具輸出——都只是把已有列透傳出去。Viewer 展示本文主題是這條透傳鏈路的最后一環(huán)讓分支記憶從數據可查變成用戶可見。7. 小結改動極小、鏈路極清晰可選字段進兩個Observation接口types.ts 與 worker-types.tsSELECT 補兩列PaginationHelper.ts卡片條件渲染一枚徽章ObservationCard.tsx即可讓分支元數據從數據庫直達界面向后兼容是硬性約束branch?: string | null的可選聲明與truthy 才渲染徽章的組合保證遷移前的舊觀察在類型系統(tǒng)與 UI 上都自然降級為無分支不產生占位或報錯驗證閉環(huán)完整typecheck:viewer→npm test→npm run build-and-sync產出 plugin/ui/viewer.html構建產物可人工核驗新徽章的渲染結果?！久赓M下載鏈接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More項目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考