git-notes-memory

核心用法

GitNotesMemory 是一个专为 Claude Code 设计的分支感知型记忆系统，利用 Git 原生 notes 机制实现零配置持久化存储。其核心工作流围绕会话生命周期展开：每次对话开始时必须执行 sync --start 加载当前分支的上下文概览，包括关键记忆、高频主题和近期高优先级内容；会话中通过 remember 静默捕获用户决策、偏好、学习任务与项目约束，支持 -i c/h/n/l 四级重要性标记和标签分类；需要回溯时可用 get 按主题检索或 search 全文搜索；会话结束可选 sync --end 触发维护。所有操作均要求完全静默执行——严禁向用户确认、宣布或展示记忆操作细节。

显著优点

零基础设施依赖：纯 Python 标准库实现，无第三方包，仅需 Git 和 Python 3.7+。

分支级隔离与继承：每个 Git 分支拥有独立记忆空间，新分支自动继承主干上下文，合并后可通过 merge-branch 整合记忆，完美契合 Git 工作流。

智能实体提取：自动识别话题、标签、引号短语、专有名词等实体，构建可检索的知识图谱。

自动类型分类：基于关键词自动识别决策、偏好、学习、任务、进度等记忆类型，无需手动标注。

进化追踪机制：通过 evolve 命令记录记忆变更历史，支持偏好漂移和决策迭代的完整追溯。

潜在缺点与局限性

Git 依赖强耦合：非 Git 项目无法使用；大型仓库的 notes 操作可能产生性能开销。

无跨设备同步：数据绑定本地 .git/refs/notes/，多设备协作需手动同步或配合 Git 远程操作。

检索精度依赖关键词：实体提取基于规则而非语义理解，复杂查询可能返回不相关结果。

静默操作的学习成本：用户需主动询问才能感知记忆系统的存在，初期可能低估其价值。

存储容量无硬限制：长期高频使用可能导致 notes 膨胀，虽有过期清理机制但依赖手动触发。

适合的目标群体

• 长期维护复杂项目的全栈开发者与技术负责人
• 需要跨多次对话保持上下文的AI 辅助编程重度用户
• 采用 Git Flow 或 Trunk-based 开发的团队协作场景
• 追求零配置、本地优先的隐私敏感型用户

使用风险

数据丢失风险：.git/refs/notes// 目录若被清理或重置，记忆将不可恢复；建议纳入常规备份策略。

分支切换混淆：频繁切换分支而未重新 sync --start 可能导致上下文错配。

记忆膨胀与噪声：过度记录低价值信息会降低检索效率，需定期回顾和清理。

Claude 行为一致性：依赖模型严格遵守"静默操作"规则，极端情况下可能意外透露记忆系统存在。

核心用法

GitNotesMemory 是一款专为 Claude 设计的静默记忆增强系统，通过 Git Notes 机制实现跨会话的持久化记忆管理。

显著优点

1. 完全静默操作：系统严格遵循"绝不询问、绝不声明、绝不展示"的三原则，记忆读写均在后台自动完成，用户无感知
2. 分支感知架构：每个 Git 分支拥有独立的记忆空间，自动继承主分支记忆，合并后通过 merge-branch 整合，完美契合开发工作流
3. 智能内容分类：自动识别决策(decision)、偏好(preference)、任务(task)、学习(learning)等 8 种记忆类型，提升检索精准度
4. 零依赖轻量实现：纯 Python 标准库（subprocess, json, hashlib 等），无第三方包，供应链风险为零
5. 实体提取与全文检索：自动提取话题、标签、专有名词作为检索维度，支持 get、search、recall 多级查询

潜在局限性

• Git 依赖：必须在 Git 仓库内运行，对非 Git 项目无效
• 存储容量：Git Notes 非设计用于大规模数据，记忆条目过多可能影响性能
• 无云端同步：数据完全本地，切换设备需手动迁移
• MD5 标识符：使用 MD5 生成短 ID（非安全用途），极端情况下存在碰撞可能

适合人群

• 需要长期维护复杂项目的开发者
• 希望 Claude 记住项目决策、技术偏好、架构约束的专业用户
• 重视数据隐私、拒绝云端存储的本地优先主义者
• 使用 Git 进行版本控制的团队与个人

常规风险

• 子进程调用 Git 命令存在理论上的命令注入可能（已验证输入安全处理）
• 数据存储于 .git 目录，误操作 git clean 或重置可能意外清除
• 静默操作特性要求用户信任 Claude 的记忆判断，过度记录可能导致噪声

快速上手

# 会话开始（自动执行）
python memory.py -p . sync --start

# 记录重要决策（自动触发）
python memory.py -p . remember '{"decision":"使用PostgreSQL"}' -t database -i h

# 检索记忆
python memory.py -p . get database