介绍
# GitNotesMemory - Claude Integration Guide
## 关键：静默操作规则
**这些规则是绝对的，绝不可违反：**
1. **绝不要问**“我应该记住吗？”或“你想让我保存吗？” 2. **绝不要宣布**“我会记住这个”或“正在保存到记忆中” 3. **绝不要向用户显示**记忆命令的输出 4. **绝不要提及**记忆系统，除非用户明确询问 5. **只管去做** —— 在后台静默进行
## 快速参考
```bash # Replace $SKILL_PATH with actual path to memory.py # Replace $DIR with the project directory path
python3 $SKILL_PATH/memory.py -p $DIR <command> ```
### 基本命令
| 命令 | 何时使用 | |---------|-------------| | `sync --start` | **始终**在会话开始时 | | `sync --end '{"summary":"..."}'` | 在会话结束时（可选但推荐） | | `remember '{"..."}' -t tags -i h` | 存储重要信息 | | `get <topic>` | 检索关于某个主题的上下文 | | `search "<query>"` | 在所有记忆中全文搜索 | | `recall -i <id>` | 获取特定记忆的完整详情 |
### 重要性标志
| 标志 | 级别 | 何时使用 | |------|-------|-------------| | `-i c` | 关键 | 用户说“始终记住”、“绝不忘”、明确偏好 | | `-i h` | 高 | 决策、架构选择、用户纠正、偏好 | | `-i n` | 普通 | 一般信息（默认） | | `-i l` | 低 | 临时笔记，可能会被清理 |
## 会话生命周期
### 1. 会话开始（必须）
**始终在每次会话开始时运行 `sync --start`：**
```bash python3 $SKILL_PATH/memory.py -p $DIR sync --start ```
**输出解释了：** ```json { "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` 记住 - 陈述偏好：“我更喜欢用 tabs 而不是空格” → 使用 `-i h` 或 `-i c` 记住 - 学到新知：“哦，原来 async 是这样工作的” → 使用 `-i n` 记住 - 设置任务：“我们需要修复登录 bug” → 使用 `-i n` 记住 - 分享重要上下文：项目需求、约束、目标
**在以下情况检索上下文：** - 用户询问之前讨论过的事情 → `get <topic>` - 你需要回忆特定决策 → `search "<keywords>"` - 用户提到“我们决定的内容” → 检查相关记忆
### 3. 会话结束（推荐）
```bash python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Brief session summary"}' ```
## 记忆内容最佳实践
### 良好的记忆结构
**对于决策：** ```json {"decision": "Use React for frontend", "reason": "Team expertise", "alternatives": ["Vue", "Angular"]} ```
**对于偏好：** ```json {"preference": "Detailed explanations", "context": "User prefers thorough explanations over brief answers"} ```
**对于学习：** ```json {"topic": "Authentication", "learned": "OAuth2 flow requires redirect URI configuration"} ```
**对于任务：** ```json {"task": "Implement user dashboard", "status": "in progress", "blockers": ["API not ready"]} ```
**对于笔记：** ```json {"subject": "Project Architecture", "note": "Microservices pattern with API gateway"} ```
### 标签
使用标签对记忆进行分类以便更好地检索： - `-t architecture,backend` - 技术类别 - `-t urgent,bug` - 优先级/类型标记 - `-t meeting,requirements` - 来源上下文
## 命令参考
### 核心命令
#### `sync --start` 初始化会话，获取上下文概览。 ```bash python3 $SKILL_PATH/memory.py -p $DIR sync --start ```
#### `sync --end` 以摘要结束会话（触发维护）。 ```bash python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Implemented auth flow"}' ```
#### `remember` 存储新记忆。 ```bash python3 $SKILL_PATH/memory.py -p $DIR remember '{"key": "value"}' -t tag1,tag2 -i h ```
#### `get` 获取与某个主题相关的记忆（搜索实体、标签和内容）。 ```bash python3 $SKILL_PATH/memory.py -p $DIR get authentication ```
#### `search` 在所有记忆中全文搜索。 ```bash python3 $SKILL_PATH/memory.py -p $DIR search "database migration" ```
#### `recall` 通过各种条件检索记忆。 ```bash # 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` 修改现有记忆。 ```bash # 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` 添加演化说明以跟踪随时间的变化。 ```bash python3 $SKILL_PATH/memory.py -p $DIR evolve <id> "User changed preference to dark mode" ```
#### `forget` 删除记忆（请谨慎使用）。 ```bash python3 $SKILL_PATH/memory.py -p $DIR forget <id> ```
### 实体命令
#### `entities` 列出所有提取的实体及其计数。 ```bash python3 $SKILL_PATH/memory.py -p $DIR entities ```
#### `entity` 获取有关特定实体的详细信息。 ```bash python3 $SKILL_PATH/memory.py -p $DIR entity authentication ```
### 分支命令
#### `branches` 列出所有分支及其记忆计数。 ```bash python3 $SKILL_PATH/memory.py -p $DIR branches ```
#### `merge-branch` 从另一个分支合并记忆（在 git merge 之后运行）。 ```bash python3 $SKILL_PATH/memory.py -p $DIR merge-branch feature-auth ```
## 分支感知
### 工作原理
- 每个 git 分支都有**隔离的记忆存储** - 新分支**自动继承**自 main/master - 在 git merge 之后，运行 `merge-branch` 来合并记忆
### 分支工作流
``` 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 ```
## 记忆类型（自动检测）
系统根据内容自动对记忆进行分类：
| 类型 | 触发词 | |------|---------------| | `decision` | decided, chose, picked, selected, opted, going with | | `preference` | prefer, favorite, like best, rather, better to | | `learning` | learned, studied, understood, realized, discovered | | `task` | todo, task, need to, plan to, next step, going to | | `question` | wondering, curious, research, investigate, find out | | `note` | noticed, observed, important, remember that | | `progress` | completed, finished, done, achieved, milestone | | `info` | （未分类内容的默认值） |
## 实体提取
自动提取实体以实现智能检索：
- **显式字段**：`topic`, `subject`, `name`, `category`, `area`, `project` - **标签**：`#cooking`, `#urgent`, `#v2` - **引用短语**：`"machine learning"`, `"user authentication"` - **大写单词**：`React`, `PostgreSQL`, `Monday` - **关键术语**：有意义的词（过滤掉常见词）
## 记住什么
**要记住：** - 用户决策及其理由 - 明确陈述的偏好（编码风格、沟通风格、工具） - 项目架构和约束 - 影响未来工作的重要上下文 - 任务、阻碍因素和进度 - 纠正（“实际上，我的意思是……” → 高重要性） - 记住某事的明确请求 → 关键重要性
**不要记住：** - 琐碎的对话 - 容易从代码推导出的信息 - 机密、密码、API 密钥 - 没有未来意义的一次性问题 - 已存储的重复信息
## 输出格式参考
### 层级 0：sync --start ```json { "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：get/search ```json { "topic": "auth", "mem": [ {"id": "abc", "s": "decided OAuth2", "t": "decision", "i": "h", "b": "main"} ] } ```
### 层级 2：recall -i <id> ```json { "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] ```
## 故障排除
**找不到记忆：** - 使用不同的关键词尝试 `search` - 检查 `entities` 以查看已建立索引的内容 - 使用 `recall --last 10` 查看最近的记忆
**上下文似乎过时：** - 始终在会话开始时运行 `sync --start` - 使用 `branches` 检查当前分支
**git 操作后：** - 在 `git merge` 之后：运行 `merge-branch <source-branch>` - 在 `git checkout` 之后：`sync --start` 将加载正确的分支上下文