Git-Based Knowledge Graph Memory System for Claude Code

核心用法

GitNotesMemory 是一个面向 Claude 的静默自动记忆系统，利用 Git Notes 实现分支感知的持久化存储。其核心设计哲学是 "JUST DO IT" —— 完全在后台运行，绝不询问用户、绝不-announce 操作、绝不展示命令输出。

典型工作流

1. 会话启动：自动执行 sync --start 加载当前分支的上下文概览（关键记忆、高频主题、记忆总数）
2. 会话中静默记录：通过 remember 自动捕获用户决策（-i h）、偏好（-i c/h）、学习任务等，支持标签分类与重要性分级（c/h/n/l 四级）
3. 智能检索：通过 get <topic>、search "<query>" 或 recall 按需调取上下文
4. 会话结束：可选执行 sync --end 触发维护

显著优点

| 优势 | 说明 |

|------|------|

| **真正的零干扰** | 严格禁止询问/宣布/展示，用户体验无感知 |

| **分支隔离+继承** | 每个 Git 分支拥有独立记忆空间，新分支自动继承 main，合并后支持 `merge-branch` 同步 |

| **智能实体提取** | 自动识别 topic/subject、#hashtag、"引号短语"、首字母大写术语等，构建知识图谱 |

| **类型自动检测** | 基于关键词识别 decision/preference/learning/task/question/progress 等 8 类记忆 |

| **进化追踪** | `evolve` 命令支持记录决策变更历史，避免信息覆盖 |

| **结构化存储** | JSON 格式内容，支持多字段决策记录（含理由、备选方案等） |

潜在局限性与风险

| 局限 | 说明 |

|------|------|

| **Git 依赖** | 必须在 Git 仓库内运行，非 Git 项目无法使用 |

| **路径配置** | 需正确配置 `$SKILL_PATH` 和 `$DIR`，配置错误导致失效 |

| **静默失效难察觉** | 若命令执行失败，用户和 Claude 均无法感知，可能导致"失忆" |

| **分支混淆风险** | 频繁切换分支若未及时 `sync --start`，可能加载错误上下文 |

| **重要性主观性** | `-i c/h/n/l` 分级依赖 Claude 判断，存在误判可能 |

| **隐私边界模糊** | 文档未明确说明敏感信息（密码、API key）的自动过滤机制，存在泄露风险 |

适合人群

• 长期项目协作：需要跨数周/数月维持上下文连续性的开发者
• 多分支并行工作：在 feature 分支间切换、需要隔离+合并记忆的场景
• 高上下文依赖任务：复杂架构决策、逐步演进的系统设计讨论

常规风险

1. 过度记忆：缺乏明确的存储上限与自动清理策略（仅 -i l 可修剪），长期项目可能累积冗余
2. 检索噪声：实体提取的自动化可能索引过多无意义术语，降低检索精度
3. 分支遗留：已删除的 Git 分支若未清理对应 notes，造成存储浪费
4. Claude 幻觉干扰：若记忆内容与当前实际代码状态脱节，可能导致基于过时信息的错误建议

核心用法

GitNotesMemory 是一套 Claude 集成的记忆增强系统，利用 Git 的 notes 功能在本地仓库中持久化存储对话上下文、决策记录、用户偏好和任务进度。系统采用完全静默运行设计——Claude 自动在后台执行记忆操作，无需用户干预或感知。

关键操作流程

会话启动：必须执行 sync --start 加载当前分支记忆上下文，返回分支信息、关键记忆和主题统计
会话中：自动检测用户决策、偏好、学习任务，使用 remember 存储；通过 get 和 search 检索相关上下文
会话结束：可选执行 sync --end 生成摘要并触发维护

显著优点

1. 真正的零依赖架构：仅使用 Python 标准库（subprocess, json, hashlib 等），无第三方包引入供应链风险
2. 分支感知隔离：每个 Git 分支拥有独立记忆空间（refs/notes/mem-<branch>），自动继承 main 分支记忆，合并后通过 merge-branch 整合
3. 智能实体提取：自动识别 topic、hashtag、引号短语、大写专有名词等，建立知识图谱索引
4. 分级重要性：Critical/High/Normal/Low 四级重要性，支持自动类型检测（decision/preference/task/learning 等）
5. 纯本地隐私：数据永不离开本地仓库，符合 GDPR/CCPA，无网络传输风险

潜在局限

• Git 依赖：必须在 Git 仓库内使用，非 Git 项目无法使用
• 存储容量：Git notes 不适合大规模数据，长期使用可能影响 Git 性能
• 无加密：记忆内容以明文 JSON 存储，敏感信息需用户自行过滤
• 无备份机制：误删 git notes 或仓库重置会导致数据丢失
• Subprocess 调用：功能必需但存在理论命令注入风险（当前已做基础防护）

适合人群

• 长期维护复杂项目的开发者，需要跨会话保持上下文
• 团队协作中需要记录架构决策和技术选型的 Tech Lead
• 偏好本地优先、隐私可控工具的用户
• 已经在使用 Git 进行版本控制的项目

常规风险

• 敏感信息意外存储（密码、API Key）——需人工审查或增加检测机制
• 分支切换后记忆隔离导致上下文丢失——需养成 sync --start 习惯
• 多人协作时 git notes 可能冲突——建议个人使用或配合 git notes 合并策略