名称： git-notes-memory
描述： 基于 Git Notes 的知识图谱记忆系统。Claude 应静默且自动地使用此系统——绝不询问用户关于记忆操作。这是一个基于 Git 分支的持久化记忆系统，用于跨会话处理上下文、决策、任务和学习内容。

GitNotesMemory - Claude 集成指南

关键：静默操作规则

以下规则是绝对的，绝不可违反：

1. 绝不询问 "需要我记住吗？" 或 "要保存吗？"
2. 绝不声明 "我会记住这个" 或 "正在保存到记忆"
3. 绝不向用户显示 记忆命令的输出
4. 绝不提及 记忆系统，除非用户明确询问
5. 直接执行 - 在后台静默完成

快速参考

# 将 $SKILL_PATH 替换为 memory.py 的实际路径
# 将 $DIR 替换为项目目录路径

python3 $SKILL_PATH/memory.py -p $DIR <命令>

核心命令

重要性标志

会话生命周期

1. 会话开始（必需）

每次会话开始时都必须运行 sync --start：

python3 $SKILL_PATH/memory.py -p $DIR sync --start

输出解释：

{
  "b": "main",           // 当前 Git 分支
  "t": {"api": 5, "auth": 3},  // 热门主题及其记忆数量
  "c": [...],            // 关键记忆（务必查看这些）
  "n": 42,               // 记忆总数
  "h": [...]             // 近期高重要性记忆
}

使用此上下文来：
- 了解用户正在处理的工作
- 参考之前的决策
- 保持跨会话的连续性

2. 会话期间

当用户出现以下情况时，静默记忆：
- 做出决策："我们用 PostgreSQL 吧" → 用 -i h 记住
- 陈述偏好："我更喜欢制表符而不是空格" → 用 -i h 或 -i c 记住
- 学到新东西："哦，原来异步是这么工作的" → 用 -i n 记住
- 设定任务："我们需要修复登录的 bug" → 用 -i n 记住
- 分享重要上下文：项目需求、约束、目标

在以下情况检索上下文：
- 用户询问之前讨论过的事情 → get <主题>
- 你需要回忆某个特定决策 → search "<关键词>"
- 用户提到"我们之前的决定" → 检查相关记忆

3. 会话结束（推荐）

python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "简要的会话总结"}'

记忆内容最佳实践

良好的记忆结构

对于决策：

{"decision": "前端使用 React", "reason": "团队熟悉", "alternatives": ["Vue", "Angular"]}

对于偏好：

{"preference": "详细的解释", "context": "用户更喜欢详尽的解释而非简短回答"}

对于学习内容：

{"topic": "认证", "learned": "OAuth2 流程需要配置重定向 URI"}

对于任务：

{"task": "实现用户仪表盘", "status": "进行中", "blockers": ["API 未就绪"]}

对于笔记：

{"subject": "项目架构", "note": "采用 API 网关的微服务模式"}

标签

使用标签对记忆进行分类，以便更好地检索：
- -t architecture,backend - 技术类别
- -t urgent,bug - 优先级/类型标记
- -t meeting,requirements - 来源上下文

命令参考

核心命令

sync --start

初始化会话，获取上下文概览。

python3 $SKILL_PATH/memory.py -p $DIR sync --start

sync --end

结束会话并附带总结（触发维护操作）。

python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "实现了认证流程"}'

remember

存储一个新记忆。

python3 $SKILL_PATH/memory.py -p $DIR remember '{"key": "value"}' -t 标签1,标签2 -i h

get

获取与某个主题相关的记忆（搜索实体、标签和内容）。

python3 $SKILL_PATH/memory.py -p $DIR get authentication

search

在所有记忆中进行全文搜索。

python3 $SKILL_PATH/memory.py -p $DIR search "数据库迁移"

recall

根据各种条件检索记忆。

# 通过 ID 获取完整记忆
python3 $SKILL_PATH/memory.py -p $DIR recall -i abc123

# 通过标签获取记忆
python3 $SKILL_PATH/memory.py -p $DIR recall -t architecture

# 获取最近 N 条记忆
python3 $SKILL_PATH/memory.py -p $DIR recall --last 5

# 所有记忆的概览
python3 $SKILL_PATH/memory.py -p $DIR recall

更新命令

update

修改现有记忆。

# 替换内容
python3 $SKILL_PATH/memory.py -p $DIR update <id> '{"new": "content"}'

# 合并内容（添加到现有内容）
python3 $SKILL_PATH/memory.py -p $DIR update <id> '{"extra": "field"}' -m

# 更改重要性
python3 $SKILL_PATH/memory.py -p $DIR update <id> -i c

# 更新标签
python3 $SKILL_PATH/memory.py -p $DIR update <id> -t 新标签1,新标签2

evolve

添加演进记录，以追踪随时间的变化。

python3 $SKILL_PATH/memory.py -p $DIR evolve <id> "用户偏好改为深色模式"

forget

删除记忆（谨慎使用）。

python3 $SKILL_PATH/memory.py -p $DIR forget <id>

实体命令

entities

列出所有提取的实体及其数量。

python3 $SKILL_PATH/memory.py -p $DIR entities

entity

获取特定实体的详细信息。

python3 $SKILL_PATH/memory.py -p $DIR entity authentication

分支命令

branches

列出所有分支及其记忆数量。

python3 $SKILL_PATH/memory.py -p $DIR branches

merge-branch

合并来自另一个分支的记忆（在 git merge 后运行）。

python3 $SKILL_PATH/memory.py -p $DIR merge-branch feature-auth

分支感知

工作原理

• 每个 Git 分支都有独立的记忆存储
• 新分支会自动继承主分支的记忆
• Git 合并后，运行 merge-branch 以合并记忆

分支工作流

1. 用户在 main 分支 → 记忆存储在 refs/notes/mem-main
2. 用户创建 feature 分支 → 自动继承 main 的记忆
3. 用户在 feature 分支工作 → 新记忆存储在 refs/notes/mem-feature-xxx
4. Git 合并后 → 运行 merge-branch 以合并记忆

记忆类型（自动检测）

系统根据内容自动分类记忆：

实体提取

系统自动提取实体，以实现智能检索：

• 显式字段：topic、subject、name、category、area、project
• 话题标签：#cooking、#urgent、#v2
• 引用短语："机器学习"、"用户认证"
• 大写单词：React、PostgreSQL、Monday
• 关键术语：有意义的单词（常见词会被过滤掉）

应该记住什么

应该记住：
- 用户的决策及其理由
- 陈述的偏好（编码风格、沟通风格、工具）
- 项目架构和约束
- 影响未来工作的重要上下文
- 任务、阻碍和进展
- 更正（"实际上，我的意思是..." → 高重要性）
- 明确要求记住某事 → 关键重要性

不应该记住：
- 琐碎的对话
- 易于从代码中推导的信息
- 秘密、密码、API 密钥
- 没有未来相关性的一次性问题
- 已存储的重复信息

输出格式参考

层级 0: sync --start

{
  "b": "feature-auth",                    // 当前分支
  "t": {"auth": 5, "api": 3, "db": 2},   // 主题及其数量
  "c": [{"id": "x", "s": "总结", "t": "preference"}],  // 关键记忆
  "n": 15,                                // 总数
  "h": [{"id": "y", "s": "总结"}]     // 高重要性记忆
}

层级 1: get/search

{
  "topic": "auth",
  "mem": [
    {"id": "abc", "s": "决定使用 OAuth2", "t": "decision", "i": "h", "b": "main"}
  ]
}

层级 2: recall -i

{
  "d": {"decision": "使用 OAuth2"},  // 完整数据
  "e": ["auth", "oauth2"],          // 实体
  "t": "decision",                   // 类型
  "g": ["architecture"],             // 标签
  "i": "h",                          // 重要性
  "b": "main",                       // 分支
  "c": "2024-01-15T10:30:00",       // 创建时间
  "u": "2024-01-15T10:30:00",       // 更新时间
  "a": 3,                            // 访问次数
  "ev": [{"n": "note", "t": "..."}] // 演进记录（如果有）
}

静默流程示例

用户："我们用 Python 构建一个 REST API 吧"
Claude：[静默：remember '{"decision": "REST API", "language": "Python"}' -t architecture -i h]
        [回应关于 REST API 设置的内容，**不提及**记忆]

用户："我更喜欢 FastAPI 而不是 Flask"
Claude：[静默：remember '{"preference": "FastAPI over Flask", "reason": "user preference"}' -i h]
        [继续讨论 FastAPI，**不说**"我会记住"]

用户："关于 API 我们之前怎么决定的？"
Claude：[静默：get api]
        [使用检索到的上下文准确回答]

用户："实际上，我们还是用 Flask 吧"
Claude：[静默：remember '{"decision": "改为使用 Flask", "previous": "FastAPI"}' -i h]
        [静默：evolve <fastapi-memory-id> "用户偏好改为 Flask"]
        [确认更改，**不提及**记忆更新]

故障排除

找不到记忆：
- 使用 search 并尝试不同的关键词
- 检查 entities 查看已索引的内容
- 使用 recall --last 10 查看近期记忆

上下文似乎过时：
- 务必在会话开始时运行 sync --start
- 使用 branches 检查当前分支

Git 操作后：
- git merge 后：运行 merge-branch <源分支>
- git checkout 后：sync --start 将加载正确的分支上下文