git-notes-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitNotesMemory - Claude Integration Guide

GitNotesMemory - Claude 集成指南

CRITICAL: SILENT OPERATION RULES

重要：静默操作规则

These rules are ABSOLUTE and must NEVER be violated:

NEVER ask "should I remember?" or "want me to save?"
NEVER announce "I'll remember this" or "saving to memory"
NEVER show memory command output to users
NEVER mention memory system unless user explicitly asks about it
JUST DO IT - silently in the background

以下规则为绝对要求，绝不能违反：

绝不要询问“是否需要我记住？”或“要我保存吗？”
绝不要告知“我会记住这个”或“正在保存到记忆中”
绝不要向用户展示记忆命令的输出
除非用户明确询问，否则绝不要提及该记忆系统
直接执行——在后台静默操作

Quick Reference

快速参考

bash

undefined

bash

undefined

Replace $SKILL_PATH with actual path to memory.py

将 $SKILL_PATH 替换为 memory.py 的实际路径

Replace $DIR with the project directory path

将 $DIR 替换为项目目录路径

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

undefined

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

undefined

Essential Commands

核心命令

Command	When to Use
`sync --start`	ALWAYS at session start
`sync --end '{"summary":"..."}'`	At session end (optional but recommended)
`remember '{"..."}' -t tags -i h`	Store important information
`get <topic>`	Retrieve context about a topic
`search "<query>"`	Full-text search across all memories
`recall -i <id>`	Get full details of a specific memory

命令	使用场景
`sync --start`	每次会话开始时必须执行
`sync --end '{"summary":"..."}'`	会话结束时执行（可选但推荐）
`remember '{"..."}' -t tags -i h`	存储重要信息
`get <topic>`	检索与某主题相关的上下文
`search "<query>"`	对所有记忆内容进行全文检索
`recall -i <id>`	获取特定记忆的完整详情

Importance Flags

重要性标识

Flag	Level	When to Use
`-i c`	Critical	User says "always remember", "never forget", explicit preferences
`-i h`	High	Decisions, architecture choices, user corrections, preferences
`-i n`	Normal	General information (default)
`-i l`	Low	Temporary notes, might be pruned

标识	级别	使用场景
`-i c`	关键	用户提到“永远记住”、“绝不要忘记”、明确偏好时
`-i h`	高	决策、架构选择、用户纠正、偏好设置
`-i n`	普通	一般信息（默认级别）
`-i l`	低	临时笔记，可能会被清理

Session Lifecycle

会话生命周期

1. Session Start (MANDATORY)

1. 会话开始（必须执行）

Always run
sync --start
at the beginning of every session:

bash

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

Output explains:

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
}

Use this context to:

Understand what the user has been working on
Reference previous decisions
Maintain continuity across sessions

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

bash

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

输出说明：

json

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

可利用此上下文：

了解用户当前的工作内容
参考之前的决策
保持跨会话的连续性

2. During Session

2. 会话进行中

Silently remember when user:

Makes a decision: "Let's use PostgreSQL" → remember with
```
-i h
```
States a preference: "I prefer tabs over spaces" → remember with
```
-i h
```
or
```
-i c
```
Learns something: "Oh, so that's how async works" → remember with
```
-i n
```
Sets a task: "We need to fix the login bug" → remember with
```
-i n
```
Shares important context: Project requirements, constraints, goals

Retrieve context when:

User asks about something previously discussed →
```
get <topic>
```
You need to recall a specific decision →
```
search "<keywords>"
```
User references "what we decided" → check relevant memories

当用户出现以下行为时，静默执行记忆操作：

做出决策：“我们使用PostgreSQL吧” → 用
```
-i h
```
标识存储
表达偏好：“我更喜欢用制表符而非空格” → 用
```
-i h
```
或
```
-i c
```
标识存储
获得新知识：“哦，原来异步是这样工作的” → 用
```
-i n
```
标识存储
设置任务：“我们需要修复登录bug” → 用
```
-i n
```
标识存储
分享重要上下文：项目需求、约束条件、目标

在以下场景检索上下文：

用户询问之前讨论过的内容 → 执行
```
get <topic>
```
需要回忆特定决策 → 执行
```
search "<keywords>"
```
用户提到“我们之前的决定” → 检查相关记忆

3. Session End (Recommended)

3. 会话结束（推荐执行）

bash

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

bash

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

Memory Content Best Practices

记忆内容最佳实践

Good Memory Structure

良好的记忆结构

For decisions:

json

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

For preferences:

json

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

For learnings:

json

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

For tasks:

json

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

For notes:

json

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

决策类：

json

{"decision": "使用React开发前端", "reason": "团队有相关经验", "alternatives": ["Vue", "Angular"]}

偏好类：

json

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

学习类：

json

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

任务类：

json

{"task": "实现用户仪表盘", "status": "进行中", "blockers": ["API尚未准备好"]}

笔记类：

json

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

Command Reference

命令参考

Core Commands

核心命令

sync --start

sync --start

Initialize session, get context overview.

bash

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

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

bash

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

sync --end

sync --end

End session with summary (triggers maintenance).

bash

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

以总结内容结束会话（触发维护操作）。

bash

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

remember

remember

Store a new memory.

bash

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

存储新的记忆内容。

bash

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

get

get

Get memories related to a topic (searches entities, tags, and content).

bash

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

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

bash

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

search

search

Full-text search across all memories.

bash

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

对所有记忆内容进行全文检索。

bash

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

recall

recall

Retrieve memories by various criteria.

bash

undefined

通过多种条件检索记忆。

bash

undefined

Get full memory by ID

通过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

获取最近N条记忆

python3 $SKILL_PATH/memory.py -p $DIR recall --last 5

Overview of all memories

获取所有记忆的概览

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

undefined

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

undefined

Update Commands

更新命令

update

update

Modify an existing memory.

bash

undefined

修改已有的记忆内容。

bash

undefined

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

undefined

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

undefined

evolve

evolve

Add an evolution note to track changes over time.

bash

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

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

bash

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

forget

forget

Delete a memory (use sparingly).

bash

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

删除记忆内容（谨慎使用）。

bash

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

Entity Commands

实体命令

entities

entities

List all extracted entities with counts.

bash

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

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

bash

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

entity

entity

Get details about a specific entity.

bash

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

获取特定实体的详情。

bash

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

Branch Commands

分支命令

branches

branches

List all branches with memory counts.

bash

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

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

bash

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

merge-branch

merge-branch

Merge memories from another branch (run after git merge).

bash

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

合并来自其他分支的记忆内容（在git merge后执行）。

bash

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

Branch Awareness

分支感知机制

How It Works

工作原理

Each git branch has isolated memory storage
New branches automatically inherit from main/master
After git merge, run
```
merge-branch
```
to combine memories

每个git分支都有独立的记忆存储
新分支会自动继承main/master分支的记忆
git merge后，运行
```
merge-branch
```
合并记忆内容

Branch Workflow

分支工作流程

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

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

Memory Types (Auto-Detected)

记忆类型（自动检测）

The system automatically classifies memories based on content:

Type	Trigger Words
`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`	(default for unclassified content)

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

类型	触发关键词
`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`	（未分类内容的默认类型）

Entity Extraction

实体提取

Entities are automatically extracted for intelligent retrieval:

Explicit fields:
```
topic
```
,
```
subject
```
,
```
name
```
,
```
category
```
,
```
area
```
,
```
project
```
Hashtags:
```
#cooking
```
,
```
#urgent
```
,
```
#v2
```
Quoted phrases:
```
"machine learning"
```
,
```
"user authentication"
```
Capitalized words:
```
React
```
,
```
PostgreSQL
```
,
```
Monday
```
Key terms: Meaningful words (common words filtered out)

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

显式字段：
```
topic
```
,
```
subject
```
,
```
name
```
,
```
category
```
,
```
area
```
,
```
project
```
话题标签：
```
#cooking
```
,
```
#urgent
```
,
```
#v2
```
引用短语：
```
"machine learning"
```
,
```
"user authentication"
```
大写单词：
```
React
```
,
```
PostgreSQL
```
,
```
Monday
```
关键术语：有意义的词汇（过滤掉常用词）

What to Remember

记忆内容选择

DO remember:

User decisions and their rationale
Stated preferences (coding style, communication style, tools)
Project architecture and constraints
Important context that affects future work
Tasks, blockers, and progress
Corrections ("actually, I meant..." → high importance)
Explicit requests to remember something → critical importance

DON'T remember:

Trivial conversation
Information easily derivable from code
Secrets, passwords, API keys
One-time questions with no future relevance
Duplicate information already stored

需要记住的内容：

用户的决策及其理由
用户明确表达的偏好（编码风格、沟通风格、工具选择）
项目架构和约束条件
对未来工作有影响的重要上下文
任务、障碍和进展
用户的纠正内容（“实际上，我指的是...” → 高重要性）
用户明确要求记住的内容 → 关键重要性

无需记住的内容：

无关紧要的对话
可从代码中轻松获取的信息
机密信息、密码、API密钥
无未来参考价值的一次性问题
已存储的重复信息

Output Format Reference

输出格式参考

Tier 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
}

json

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

Tier 1: get/search

json

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

json

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

Tier 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)
}

json

{
  "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": "..."}] // 演进记录（如有）
}

Example Silent Flow

静默流程示例

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]

用户: "我们用Python构建一个REST API吧"
Claude: [静默执行: remember '{"decision": "REST API", "language": "Python"}' -t architecture -i h]
        [回复关于REST API搭建的内容，绝口不提记忆系统]

用户: "比起Flask我更喜欢FastAPI"
Claude: [静默执行: remember '{"preference": "FastAPI over Flask", "reason": "user preference"}' -i h]
        [继续讨论FastAPI相关内容，不说“我会记住”]

用户: "我们之前关于API的决定是什么？"
Claude: [静默执行: get api]
        [利用检索到的上下文准确回答]

用户: "实际上，我们还是用Flask吧"
Claude: [静默执行: remember '{"decision": "Changed to Flask", "previous": "FastAPI"}' -i h]
        [静默执行: evolve <fastapi-memory-id> "User changed preference to Flask"]
        [确认用户的变更，绝口不提记忆更新]

Troubleshooting

故障排除

Memory not found:

Use
```
search
```
with different keywords
Check
```
entities
```
to see what's indexed
Use
```
recall --last 10
```
to see recent memories

Context seems stale:

Always run
```
sync --start
```
at session beginning
Check current branch with
```
branches
```

After git operations:

After
```
git merge
```
: run
```
merge-branch <source-branch>
```
After
```
git checkout
```
:
```
sync --start
```
will load correct branch context

找不到记忆内容：

使用
```
search
```
尝试不同关键词
查看
```
entities
```
了解已索引的内容
使用
```
recall --last 10
```
查看最近的记忆

上下文内容过时：

务必在会话开始时运行
```
sync --start
```
使用
```
branches
```
检查当前分支

git操作后：

执行
```
git merge
```
后：运行
```
merge-branch <source-branch>
```
执行
```
git checkout
```
后：
```
sync --start
```
会加载对应分支的上下文