GitNotesMemory - Claude集成指南

关键：静默操作规则

这些规则是绝对的，绝不可违反：

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

快速参考

# Replace $SKILL_PATH with actual path to memory.py
# Replace $DIR with the project directory path

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

基本命令

重要性标志

会话生命周期

1. 会话开始（必需）

务必在每次会话开始时运行：sync --start输出解释：

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

利用此上下文来：

{
  "b": "main",           // Current git branch
  "t": {"api": 5, "auth": 3},  // Top topics with memory counts
  "c": [...],            // Critical memories (always review these)
  "n": 42,               // Total memory count
  "h": [...]             // High-importance recent memories
}

了解用户之前的工作内容

• 参考之前的决定
• 保持跨会话的连续性
• 2. 会话期间

当用户出现以下情况时，请默默记住：

做出决定："我们使用PostgreSQL吧" → 使用以下方式记住：

• -i h陈述偏好："我更喜欢用制表符而非空格" → 使用以下方式记住：
• -i h或-i c学到新知识："哦，原来异步是这么工作的" → 使用以下方式记住：
• -i n设定任务："我们需要修复登录漏洞" → 使用以下方式记住：
• -i n-i n
• 分享重要背景信息：项目需求、约束条件、目标

在以下情况检索背景信息：

• 用户询问先前讨论过的事项 →获取 <主题>
• 您需要回忆特定决策 →搜索“<关键词>”
• 用户提及“我们决定的事项” → 检查相关记忆

3. 会话结束（推荐）

python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Brief session summary"}'

记忆内容最佳实践

优质记忆结构

针对决策：

{"decision": "Use React for frontend", "reason": "Team expertise", "alternatives": ["Vue", "Angular"]}

针对偏好：

{"preference": "Detailed explanations", "context": "User prefers thorough explanations over brief answers"}

针对经验总结：

{"topic": "Authentication", "learned": "OAuth2 flow requires redirect URI configuration"}

针对任务：

{"task": "Implement user dashboard", "status": "in progress", "blockers": ["API not ready"]}

针对笔记：

{"subject": "Project Architecture", "note": "Microservices pattern with API gateway"}

标签

使用标签分类记忆以优化检索：

• -t 架构,后端- 技术类别
• -t 紧急,缺陷- 优先级/类型标记
• -t 会议,需求- 源上下文

命令参考

核心命令

sync --start

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

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

sync --end

结束会话并生成摘要（触发维护操作）。

python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Implemented auth flow"}'

remember

存储新的记忆。

python3 $SKILL_PATH/memory.py -p $DIR remember '{"key": "value"}' -t tag1,tag2 -i h

get

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

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

search

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

python3 $SKILL_PATH/memory.py -p $DIR search "database migration"

recall

根据各种条件检索记忆。

# Get full memory by ID
python3 $SKILL_PATH/memory.py -p $DIR recall -i abc123

# Get memories by tag
python3 $SKILL_PATH/memory.py -p $DIR recall -t architecture

# Get last N memories
python3 $SKILL_PATH/memory.py -p $DIR recall --last 5

# Overview of all memories
python3 $SKILL_PATH/memory.py -p $DIR recall

更新命令

update

修改现有记忆。

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

# Merge content (add to existing)
python3 $SKILL_PATH/memory.py -p $DIR update <id> '{"extra": "field"}' -m

# Change importance
python3 $SKILL_PATH/memory.py -p $DIR update <id> -i c

# Update tags
python3 $SKILL_PATH/memory.py -p $DIR update <id> -t newtag1,newtag2

evolve

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

python3 $SKILL_PATH/memory.py -p $DIR evolve <id> "User changed preference to dark mode"

forget

删除一条记忆（请谨慎使用）。

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

实体命令

实体

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

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

实体详情

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

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

分支命令

分支列表

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

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

合并分支

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

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

分支感知

工作原理

• 每个 git 分支都拥有独立的记忆存储
• 新分支会自动继承来自主分支/主分支的记忆
• 在 git merge 后，运行合并分支命令以合并记忆

分支工作流程

1. User on main branch → memories stored in refs/notes/mem-main
2. User creates feature branch → auto-inherits main's memories
3. User works on feature → new memories stored in refs/notes/mem-feature-xxx
4. After git merge → run merge-branch to combine memories

记忆类型（自动检测）

系统会根据内容自动对记忆进行分类：

实体提取

实体将被自动提取，用于智能检索：

• 显式字段：主题,主题,名称,类别,区域,项目
• 话题标签：#烹饪,#紧急,#第二版
• 引用短语：“机器学习”,“用户认证”
• 大写单词：React,PostgreSQL,星期一
• 关键术语: 有意义的词汇（已过滤掉常见词汇）

需要记住的内容

请务必记住：

• 用户的决策及其理由
• 明确表达的偏好（编码风格、沟通风格、工具）
• 项目架构和约束条件
• 影响未来工作的重要上下文信息
• 任务、阻碍和进展
• 更正内容（例如“实际上，我的意思是...” → 高重要性）
• 明确要求记住某事 → 至关重要

无需记住的内容：

• 琐碎的对话
• 易于从代码中推导出的信息
• 机密信息、密码、API密钥
• 无未来相关性的一次性问题
• 已存储的重复信息

输出格式参考

层级 0：同步 --开始

{
  "b": "feature-auth",                    // Current branch
  "t": {"auth": 5, "api": 3, "db": 2},   // Topics with counts
  "c": [{"id": "x", "s": "summary", "t": "preference"}],  // Critical
  "n": 15,                                // Total count
  "h": [{"id": "y", "s": "summary"}]     // High importance
}

层级 1：获取/搜索

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

层级 2：回忆 -i<id>

{
  "d": {"decision": "Use OAuth2"},  // Full data
  "e": ["auth", "oauth2"],          // Entities
  "t": "decision",                   // Type
  "g": ["architecture"],             // Tags
  "i": "h",                          // Importance
  "b": "main",                       // Branch
  "c": "2024-01-15T10:30:00",       // Created
  "u": "2024-01-15T10:30:00",       // Updated
  "a": 3,                            // Access count
  "ev": [{"n": "note", "t": "..."}] // Evolution notes (if any)
}

示例静默流程

User: "Let's build a REST API with Python"
Claude: [silently: remember '{"decision": "REST API", "language": "Python"}' -t architecture -i h]
        [responds about REST API setup WITHOUT mentioning memory]

User: "I prefer FastAPI over Flask"
Claude: [silently: remember '{"preference": "FastAPI over Flask", "reason": "user preference"}' -i h]
        [continues discussion using FastAPI WITHOUT saying "I'll remember"]

User: "What did we decide about the API?"
Claude: [silently: get api]
        [uses retrieved context to answer accurately]

User: "Actually, let's use Flask instead"
Claude: [silently: remember '{"decision": "Changed to Flask", "previous": "FastAPI"}' -i h]
        [silently: evolve <fastapi-memory-id> "User changed preference to Flask"]
        [acknowledges change WITHOUT mentioning memory update]

故障排除

未找到记忆：

• 使用搜索使用不同的关键词
• 检查实体查看已索引的内容
• 使用recall --last 10查看最近的记忆

上下文似乎过时：

• 始终在会话开始时运行sync --start在会话开始时
• 使用以下命令检查当前分支：branches

Git 操作后：

• 在git merge之后：运行merge-branch <source-branch>
• 在git checkout:同步 --开始将加载正确的分支上下文