goodvibes-memory

资源

scripts/
  validate-memory-usage.sh
references/
  schemas.md

GoodVibes 记忆协议

记忆系统通过将决策、模式、失败和偏好记录到结构化 JSON 文件中，实现跨会话学习。每个 Agent 都必须在开始工作前读取记忆，并在完成工作后写入记忆。

为什么这很重要

没有记忆：

• Agent 会重复已知的失败
• 已验证的模式会在每个会话中重新发现
• 架构决策会被遗忘或违背
• 不会应用项目特定的偏好

有记忆：

• 失败会连同预防策略一起记录
• 模式会得到一致复用
• 决策会指导后续工作
• 偏好有助于保持一致性

文件结构

.goodvibes/
|-- memory/           # Structured JSON (machine-readable)
|   |-- decisions.json    # Architectural decisions
|   |-- patterns.json     # Proven approaches
|   |-- failures.json     # Past errors + resolutions
|   |-- preferences.json  # Project conventions
|   +-- index.json        # Index file (optional)
+-- logs/             # Markdown logs (human-readable)
    |-- activity.md       # Completed work log
    |-- decisions.md      # Decision log with context
    +-- errors.md         # Error log with resolution

---

开始工作前（读取阶段）

在实现任何任务之前，务必检查记忆文件。使用基于关键词的搜索查找相关条目。

1. 检查 failures.json

目的：避免重复已知的失败。

方法：

# Use precision_read to read the file
precision_read:
  files:
    - path: .goodvibes/memory/failures.json
  verbosity: standard

# Search for keywords matching your task
# Example keywords: "precision_fetch", "config", "auth", "API", "build"

查找内容：

• keywords 字段与任务匹配（例如，搜索「auth」会找到身份验证相关的失败）
• error 字段描述了类似的问题
• context 字段与当前情况匹配

如果找到：

• 阅读 resolution —— 了解如何修复
• 阅读 prevention —— 了解如何避免
• 应用预防策略

2. 检查 patterns.json

目的：采用经过验证的方法，而不是另起炉灶。

方法：

precision_read:
  files:
    - path: .goodvibes/memory/patterns.json
  verbosity: standard

查找内容：

• keywords 与任务类型匹配
• when_to_use 描述了当前情况
• name 表明这是相关模式

如果找到：

• 阅读 description —— 了解该模式
• 检查 example_files —— 查看该模式的使用位置
• 遵循该模式，除非有充分理由不这样做

3. 检查 decisions.json

目的：遵循先前的架构决策。

方法：

precision_read:
  files:
    - path: .goodvibes/memory/decisions.json
  verbosity: standard

查找内容：

• scope 包含你将修改的文件
• category 与你的领域匹配（例如，「architecture」「pattern」「library」）
• status 为「active」（而非「superseded」或「reverted」）

如果找到：

• 阅读 what 和 why —— 理解决策内容及原因
• 如果任务与决策冲突：继续之前向协调器报告
• 如果任务与决策一致：遵循该决策

4. 检查 preferences.json

目的：应用项目特定的规范。

方法：

precision_read:
  files:
    - path: .goodvibes/memory/preferences.json
  verbosity: standard

查找内容：

• key 与你的领域匹配（例如，「category.preference_name」）

如果找到：

• 应用 value 中的偏好
• 遵循 reason 中的理由

搜索策略

手动关键词匹配：阅读文件，并查找与任务相关的关键词。

示例：

• 任务：「使用 Clerk 添加身份验证」
• 要搜索的关键词：auth、clerk、authentication、login、session
• 在 failures.json 中检查过往的身份验证失败
• 在 patterns.json 中检查身份验证模式
• 在 decisions.json 中检查身份验证库相关决策

范围筛选：重点查看 scope 包含你将修改的文件的条目。

---

完成工作后（写入阶段）

完成任务、解决错误或做出决策后，将其记录到记忆中。务必同时写入 JSON（机器可读）和 Markdown（人类可读）。

何时写入

情况	写入到
任务通过审查	activity.md + 可选的 patterns.json/decisions.json
错误已解决	errors.md + failures.json
做出决策	decisions.md + decisions.json
不要写入	简单修复、没有新模式、没有决策

任务通过审核后

1. 始终记录到 activity.md

格式：

## YYYY-MM-DD: [Brief Title]

**Task**: [What was the goal?]

**Plan**: [Approach taken, or N/A]

**Status**: COMPLETE

**Completed Items**:
- [List of what was accomplished]

**Files Modified**:
- [List of changed files with brief description]

**Review Score**: [X/10]

**Commit**: [commit SHA]

---

2. 可选：添加到 patterns.json（如果出现了可复用的模式）

仅在以下情况下添加：

• 该方法可在多个文件或任务中复用
• 该方法并非显而易见（不是标准做法）
• 该方法能有效解决特定问题

架构：

{
  "id": "pat_YYYYMMDD_HHMMSS",
  "name": "PatternNameInPascalCase",
  "description": "What the pattern does and why it works",
  "when_to_use": "Situation where this pattern applies",
  "example_files": ["path/to/file.ts", "another/example.ts"],
  "keywords": ["searchable", "terms"]
}

3. 可选：添加到 decisions.json（如果做出了架构决策）

仅在以下情况下添加：

• 在多种方案之间做出了选择
• 该决策会影响后续工作
• 该决策的适用范围超出当前单个任务

架构：

{
  "id": "dec_YYYYMMDD_HHMMSS",
  "date": "YYYY-MM-DDTHH:MM:SSZ",
  "category": "library|architecture|pattern|convention",
  "what": "What was decided",
  "why": "Rationale for the decision",
  "scope": ["files/directories affected"],
  "confidence": "high | medium | low",
  "status": "active|superseded|reverted"
}

错误解决后

1. 始终记录到 errors.md

格式：

## YYYY-MM-DD HH:MM - [ERROR_CATEGORY]

**Error**: [Brief description]

**Context**:
- Task: [What were you doing?]
- Agent: [Which agent encountered it?]
- File(s): [Affected files]

**Root Cause**: [Why did it happen?]

**Resolution**: [How was it fixed? Or UNRESOLVED]

**Prevention**: [How to avoid it in the future?]

**Status**: RESOLVED | UNRESOLVED

---

2. 始终添加到 failures.json（包含完整上下文）

架构：

{
  "id": "fail_YYYYMMDD_HHMMSS",
  "date": "YYYY-MM-DDTHH:MM:SSZ",
  "error": "Brief error description",
  "context": "What task was being performed",
  "root_cause": "Technical explanation of why it failed",
  "resolution": "How it was fixed (or UNRESOLVED)",
  "prevention": "How to avoid this failure in the future",
  "keywords": ["searchable", "error-related", "terms"]
}

错误类别（用于 errors.md）：

• TOOL_FAILURE -- 精密工具或原生工具失败
• AGENT_FAILURE -- Agent 崩溃或未能完成任务
• BUILD_ERROR -- TypeScript 编译或构建步骤失败
• TEST_FAILURE -- 测试套件失败
• VALIDATION_ERROR -- 验证、lint 或格式检查失败
• EXTERNAL_ERROR -- API、网络或依赖项问题
• UNKNOWN -- 无法确定错误类别

做出决策后

1. 始终记录到 decisions.md

格式：

## YYYY-MM-DD: [Decision Title]

**Context**: [What situation required a decision?]

**Options Considered**:
1. **[Option A]**: [Description + trade-offs]
2. **[Option B]**: [Description + trade-offs]

**Decision**: [What was chosen]

**Rationale**: [Why this option was best]

**Implications**: [What this means for future work]

---

2. 始终添加到 decisions.json

请参阅上文“任务通过审核后”部分中的架构。

---

ID 格式

使用基于时间戳的 ID，避免写入前读取现有条目：

dec_YYYYMMDD_HHMMSS   # Decisions
pat_YYYYMMDD_HHMMSS   # Patterns
fail_YYYYMMDD_HHMMSS  # Failures
pref_YYYYMMDD_HHMMSS  # Preferences

示例：dec_20260215_143022 表示在 2026-02-15 14:30:22 做出的决策

冲突风险：除非两个 Agent 在同一秒写入同一个文件，否则风险可以忽略不计。时间戳足以确保唯一性。

---

首次写入检查

首次写入任何记忆或日志文件前，检查文件是否存在：

对于 JSON 文件

如果文件不存在，则创建一个空数组：

[]

对于 Markdown 文件

如果文件不存在，则创建并添加标题：

# [File Name]

Log of [description].

---

首先使用 precision_read：

precision_read:
  files:
    - path: .goodvibes/memory/decisions.json
  verbosity: count_only  # Just check existence

如果 exists: false，请先创建文件，再追加内容。

---

常见错误

不要这样做

• 不要跳过读取记忆 -- 否则会重复犯错并违反决策
• 不要为琐碎工作写日志 -- 仅记录有意义的模式、决策或失败
• 不要使用随机 ID -- 使用基于时间戳的 ID（无需读取现有条目）
• 不要忘记 prevention 字段 -- 没有预防策略的失败记录没有用处
• 不要只记录到 JSON -- 始终同时写入 JSON 和 Markdown
• 不要创建重复条目 -- 先搜索关键词，检查模式或失败是否已存在

应该这样做

• 先读取 failures.json -- 开始前检查已知问题
• 按关键词搜索 -- 手动匹配关键词快速且有效
• 包含完整上下文 -- 失败记录应包含根本原因、解决方法和预防措施
• 使用时间戳 ID -- 无冲突风险，无需读取现有条目
• 同时记录两种格式 -- JSON 供机器使用，Markdown 供人阅读
• 更新 last_updated -- 修改 index.json 时更新时间戳

---

验证

使用 scripts/validate-memory-usage.sh 脚本检查是否符合要求：

# Validate memory protocol usage
bash plugins/goodvibes/skills/protocol/goodvibes-memory/scripts/validate-memory-usage.sh \
  session-transcript.jsonl \
  .goodvibes/memory/

# Exit code 0 = compliant
# Exit code 1 = violations found

脚本会检查：

• 任务开始时是否读取了记忆文件
• 任务完成后是否记录了活动
• 错误解决后是否记录了失败
• 发现可复用方法时是否记录了模式

---

快速参考

读取阶段检查清单

• 读取 failures.json -- 按关键词搜索类似错误
• 读取 patterns.json -- 按关键词搜索已验证的方法
• 读取 decisions.json -- 按范围搜索相关决策
• 读取 preferences.json -- 遵循项目约定

编写阶段检查清单

• 任务完成后记录到 activity.md
• 发现可复用模式时添加到 patterns.json
• 做出架构决策时添加到 decisions.json
• 解决错误后记录到 errors.md + failures.json
• 做出选择时记录到 decisions.md + decisions.json
• 更新 JSON 文件中的 last_updated 时间戳
• 使用基于时间戳的 ID（避免冲突）

---

示例

示例：开始身份验证任务前读取失败记录

# Step 1: Read failures.json
precision_read:
  files:
    - path: .goodvibes/memory/failures.json
  verbosity: standard

# Step 2: Manually search for keywords
# Keywords: "auth", "authentication", "clerk", "oauth", "token"
# Found: fail_20260210_160000 - "Service registry reads empty services"
# Context: OAuth token configuration issue
# Prevention: "Always use nested config format for services"

# Step 3: Apply prevention strategy
# Use nested format when configuring auth service

示例：实现功能后编写模式记录

# Step 1: Check if file exists
precision_read:
  files:
    - path: .goodvibes/memory/patterns.json
  verbosity: count_only

# Step 2: Read existing patterns to avoid duplicates
precision_read:
  files:
    - path: .goodvibes/memory/patterns.json
  verbosity: standard

# Step 3: Add new pattern (if not duplicate)
precision_edit:
  files:
    - path: .goodvibes/memory/patterns.json
      operations:
        - type: insert
          search: '"patterns": ['
          content: |
            {
              "id": "pat_20260215_143022",
              "name": "AuthServiceNesting",
              "description": "Auth services require nested config structure",
              "when_to_use": "When configuring auth providers in goodvibes.json",
              "example_files": [".goodvibes/goodvibes.json"],
              "keywords": ["auth", "config", "nested", "services"]
            },

示例：记录错误解决过程

# Step 1: Log to errors.md
precision_edit:
  files:
    - path: .goodvibes/logs/errors.md
      operations:
        - type: insert_at_line
          line: 1
          content: |
            ## 2026-02-15 14:30 - BUILD_ERROR
            
            **Error**: TypeScript compilation failed with "Cannot find module 'clerk'"
            
            **Context**:
            - Task: Add Clerk authentication
            - Agent: Engineer
            - File(s): src/auth/clerk.ts
            
            **Root Cause**: Missing @clerk/nextjs package in dependencies
            
            **Resolution**: RESOLVED - Added package with `npm install @clerk/nextjs`
            
            **Prevention**: Always check package.json before importing new libraries
            
            **Status**: RESOLVED
            
            ---
            

# Step 2: Add to failures.json
precision_edit:
  files:
    - path: .goodvibes/memory/failures.json
      operations:
        - type: insert
          search: '['
          content: |
            {
              "id": "fail_20260215_143022",
              "date": "2026-02-15T14:30:22Z",
              "error": "TypeScript compilation failed - Cannot find module 'clerk'",
              "context": "Adding Clerk authentication to Next.js app",
              "root_cause": "Missing @clerk/nextjs package in package.json dependencies",
              "resolution": "RESOLVED - Installed package with npm install @clerk/nextjs",
              "prevention": "Before importing from a new package, verify it exists in package.json. Use precision_read to check package.json before adding imports.",
              "keywords": ["typescript", "clerk", "module", "dependency", "package.json", "build-error"]
            },

---

与其他技能的集成

• precision-mastery：使用 precision_read/precision_edit 操作记忆文件
• error-recovery：错误恢复的第一步是检查 failures.json
• gather-plan-apply：在发现阶段纳入记忆读取
• review-scoring：审查者会检查工作开始前是否查阅了记忆

---

文件位置

所有记忆文件均相对于项目根目录：

.goodvibes/
|-- memory/
|   |-- decisions.json
|   |-- patterns.json
|   |-- failures.json
|   +-- preferences.json
+-- logs/
    |-- activity.md
    |-- decisions.md
    +-- errors.md

始终使用 .goodvibes/memory/ 和 .goodvibes/logs/ 作为路径（相对于项目根目录）。