extract-learnings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Value Context

价值场景

Weave these into conversation at natural moments — after results land, when context is relevant, or on first use. One or two per run, not all at once.

Most users say "remember this" expecting a single note — this skill actually runs two parallel agents (auditor + discoverer) to both capture new knowledge and verify existing memories haven't gone stale.
The 5-layer memory hierarchy means the right knowledge loads at the right time — universal preferences in L0, project architecture in L1, working notes in L2 — without polluting every session with everything.
Consolidation ("dream") is the maintenance mode: it prunes outdated memories, promotes patterns that keep recurring, and keeps the memory index under 200 lines so it stays useful.
For teams: memories captured here carry forward to every future session in this project, making onboarding and context-switching dramatically faster.

在自然的对话时机融入这些内容——在结果产出后、相关语境出现时，或首次使用时。每次运行使用1-2个，不要一次性全部使用。

大多数用户说"remember this"时期望保存一条笔记——但该技能实际上会运行两个并行Agent（审计员+发现者），既能捕获新知识，又能验证现有记忆是否已失效。
5层记忆层级确保正确的知识在正确的时机加载——L0存储通用偏好，L1存储项目架构，L2存储工作笔记——避免所有内容污染每个会话。
整合（"dream"）是维护模式：它会删除过时记忆，提升重复出现的模式的优先级，并将记忆索引保持在200行以内，以确保其可用性。
对于团队而言：此处捕获的记忆会延续到该项目未来的所有会话中，大幅加快入职和上下文切换的速度。

Memory Hierarchy

记忆层级

Layer	File	Loaded	Purpose
0	`~/.claude/CLAUDE.md`	Every session, all projects	Universal behavioral preferences
1	`<repo>/CLAUDE.md`	Every session, this project	Architecture, conventions, gotchas
2	`memory/MEMORY.md` (project dir)	Every session, agent-managed	Evolving notes, working knowledge
3	`memory/*.md` topic files	On-demand	Detailed reference too long for L2
Meta	Suggest new skill/command	N/A	Repeatable workflow → automation

Placement decision: project-independent preference → L0, project-specific technical → L1, concise working note → L2, detailed reference → L3, repeatable pattern → Meta.

层级	文件	加载时机	用途
0	`~/.claude/CLAUDE.md`	所有项目的每个会话	通用行为偏好
1	`<repo>/CLAUDE.md`	当前项目的每个会话	架构、约定、注意事项
2	`memory/MEMORY.md` （项目目录）	每个会话，由Agent管理	不断演进的笔记、工作知识
3	`memory/*.md` 主题文件	按需加载	篇幅过长不适合L2的详细参考内容
元数据	建议新技能/命令	N/A	可重复工作流→自动化

放置决策：项目无关偏好→L0，项目特定技术内容→L1，简洁工作笔记→L2，详细参考内容→L3，可重复模式→元数据。

Early Exit Guard

提前退出机制

If the user said "remember X" with explicit content already in context — and the request is NOT a consolidation trigger ("consolidate", "dream", "extract learnings", "clean up memories", or triggered from the consolidation nudge):

Resolve memory path (see Phase 1 step 1)
Read existing memories to check for duplicates and pick the right layer
Skip to Phase 3 (Propose & Execute) with that content — no subagents needed

如果用户说"remember X"且上下文已包含明确内容——且请求不是整合触发词（"consolidate"、"dream"、"extract learnings"、"clean up memories"，或来自整合提示的触发）：

解析记忆路径（见阶段1步骤1）
读取现有记忆以检查重复并选择正确层级
直接跳至阶段3（提议与执行），无需子Agent

Unified Workflow

统一工作流

Phase 1: Orient (main session)

阶段1：定位（主会话）

Resolve memory path using Bash (Glob does not expand
```
~
```
):
```
Bash: find $HOME/.claude/projects -name MEMORY.md -path "*<repo-dir-name>*" 2>/dev/null | head -1
```
The result is the full path to MEMORY.md (a file). The memory directory is its parent:
```
$(dirname <find-result>)
```
. If no result, construct the project key by replacing
```
/
```
with
```
-
```
in the current working directory path (e.g.,
```
/home/user/myrepo
```
→
```
-home-user-myrepo
```
), then use
```
$HOME/.claude/projects/<project-key>/memory/MEMORY.md
```
.
- If MEMORY.md does not exist, create it with
```
# Project Memory
```
  header. Note that the Memory Auditor has nothing to audit — in Phase 2, spawn only the Signal Discoverer.

Steps 2-4 are required and run as parallel tool calls.

Read MEMORY.md + list topic files (
```
Glob memory/*.md
```
from resolved path)
Read both CLAUDE.md files (
```
~/.claude/CLAUDE.md
```
+
```
<repo>/CLAUDE.md
```
) — required for dedup quality; skipping means proposals may duplicate L0/L1 content
```
git log --oneline -20
```
Build context snapshot: summarize existing knowledge + list verification targets (file paths, functions, patterns named in memories)

使用Bash解析记忆路径（Glob不会展开
```
~
```
）：
```
Bash: find $HOME/.claude/projects -name MEMORY.md -path "*<repo-dir-name>*" 2>/dev/null | head -1
```
结果是MEMORY.md的完整路径（一个文件）。记忆目录是其父目录：
```
$(dirname <find-result>)
```
。如果没有结果，将当前工作目录路径中的
```
/
```
替换为
```
-
```
来构建项目密钥（例如，
```
/home/user/myrepo
```
→
```
-home-user-myrepo
```
），然后使用
```
$HOME/.claude/projects/<project-key>/memory/MEMORY.md
```
。
- 如果MEMORY.md不存在，创建它并添加
```
# Project Memory
```
  标题。注意此时Memory Auditor没有可审计的内容——在阶段2中，仅启动Signal Discoverer。

步骤2-4为必填项，需作为并行工具调用运行。

读取MEMORY.md并列出主题文件（从解析路径执行
```
Glob memory/*.md
```
）
读取两个CLAUDE.md文件（
```
~/.claude/CLAUDE.md
```
+
```
<repo>/CLAUDE.md
```
）——这对去重质量至关重要；跳过此步骤可能导致提议重复L0/L1内容
```
git log --oneline -20
```
构建上下文快照：总结现有知识并列出验证目标（记忆中提及的文件路径、函数、模式）

Phase 2: Gather (2 agents in parallel)

阶段2：收集（两个并行Agent）

Launch both agent calls in a single message so they run in parallel. Use the Agent tool with:

Memory Auditor:
```
subagent_type: "claude-memory:memory-auditor"
```
. In the
```
prompt
```
, include the context snapshot from Phase 1 — memory file contents, git log output, and verification targets list.
Signal Discoverer:
```
subagent_type: "claude-memory:signal-discoverer"
```
. In the
```
prompt
```
, include existing memory summaries (for dedup) and the project name.

If Phase 1 noted MEMORY.md was just created (no existing memories), skip the Memory Auditor and spawn only the Signal Discoverer.

Both agents require

maxTurns ≥ 30

— verify agent frontmatter at

plugins/claude-memory/agents/

. Agents with low maxTurns exit early and return truncated output that appears non-empty but contains no findings.

Phase 2 is complete when both agents return reports. If either returns empty or clearly truncated (one line, no structured findings), proceed with the other's results — but if the Signal Discoverer fails, also perform a manual fallback: query the 5 most recent session summaries directly from

~/.claude-memory/conversations.db

using

Bash(python3 -c "import sqlite3; ...")

and apply the signal criteria from the Content Quality Rules section below.

在一条消息中启动两个Agent调用，使其并行运行。使用Agent工具：

Memory Auditor：
```
subagent_type: "claude-memory:memory-auditor"
```
。在
```
prompt
```
中包含阶段1的上下文快照——记忆文件内容、git日志输出和验证目标列表。
Signal Discoverer：
```
subagent_type: "claude-memory:signal-discoverer"
```
。在
```
prompt
```
中包含现有记忆摘要（用于去重）和项目名称。

如果阶段1指出MEMORY.md刚创建（无现有记忆），则跳过Memory Auditor，仅启动Signal Discoverer。

两个Agent都要求

maxTurns ≥ 30

——请在

plugins/claude-memory/agents/

处验证Agent前置内容。maxTurns值较低的Agent会提前退出，返回看似非空但无有效结果的截断输出。

当两个Agent都返回报告时，阶段2完成。如果其中一个返回空内容或明显截断（仅一行，无结构化结果），则使用另一个的结果继续——但如果Signal Discoverer失败，还需执行手动回退：使用

Bash(python3 -c "import sqlite3; ...")

直接从

~/.claude-memory/conversations.db

查询最近5个会话摘要，并应用下文内容质量规则中的信号标准。

Phase 3: Synthesize & Propose (main session)

阶段3：合成与提议（主会话）

Receive agent reports
Deduplicate across reports and against existing memories
Rank by impact, limit to 3-7 candidates
For each candidate: determine target layer, target section, action (ADD / EDIT / REMOVE)
Read target files, check for duplicates

Present proposals:

### [ACTION] Learning: <summary>
**Target:** <file> → <section>
**Rationale:** <why this layer>
```diff
- <old line>
+ <new line>

MEMORY.md line check — if over 170 lines, propose specific demotions to L3 or removals
Layer 0 gate — if targeting
```
~/.claude/CLAUDE.md
```
, warn: "This modifies global instructions loaded in every session across all projects. Confirm?"
AskUserQuestion: Approve all / Approve selectively / Reject

接收Agent报告
在报告之间以及与现有记忆之间进行去重
按影响排序，限制为3-7个候选内容
针对每个候选内容：确定目标层级、目标章节、操作（ADD / EDIT / REMOVE）
读取目标文件，检查重复

呈现提议：

### [ACTION] Learning: <summary>
**Target:** <file> → <section>
**Rationale:** <why this layer>
```diff
- <old line>
+ <new line>

MEMORY.md行数检查——如果超过170行，提议将特定内容降级到L3或删除
L0限制——如果目标是
```
~/.claude/CLAUDE.md
```
，需警告："这会修改所有项目所有会话中加载的全局指令。是否确认？"
AskUserQuestion: 全部批准/选择性批准/拒绝

Phase 4: Execute

阶段4：执行

Apply approved edits. Output summary table:

| Learning | Action | Target | Status |
|----------|--------|--------|--------|

Only if Phase 2 agents ran (not an early-exit capture): write consolidation marker using Bash (Write tool requires prior Read and cannot create new files):

Bash: date -u +%Y-%m-%dT%H:%M:%SZ > <memory-dir>/.last-consolidation

Phase 4 is complete when all approved edits are applied and the summary table is presented.

应用已批准的编辑。输出摘要表格：

| Learning | Action | Target | Status |
|----------|--------|--------|--------|

仅当阶段2运行了Agent（不是提前退出捕获）时：使用Bash写入整合标记（Write工具需要先执行Read，无法创建新文件）：

Bash: date -u +%Y-%m-%dT%H:%M:%SZ > <memory-dir>/.last-consolidation

当所有已批准的编辑都已应用并呈现摘要表格时，阶段4完成。

Content Quality Rules

内容质量规则

Every candidate must pass: (1) agent would benefit from knowing this in future sessions, (2) condensed to minimum useful form, (3) placed at correct layer, (4) not already captured in target file, (5) stated as reusable principle not session-specific incident.

Pass: commands discovered through trial-and-error, non-obvious gotchas, architectural decisions with rationale, user behavioral corrections, configuration quirks, version milestones.

Fail: information readable from code, generic best practices, one-off bugs without pattern, verbose explanations, duplicates, temporary state, unverified speculation, incidents without generalizable principle.

每个候选内容必须满足：(1) Agent在未来会话中会受益于该内容，(2) 浓缩至最小有用形式，(3) 放置在正确层级，(4) 未在目标文件中捕获，(5) 表述为可复用原则而非会话特定事件。

合格内容：通过反复试验发现的命令、非显而易见的注意事项、带有理由的架构决策、用户行为修正、配置 quirks、版本里程碑。

不合格内容：可从代码中读取的信息、通用最佳实践、无模式的一次性bug、冗长解释、重复内容、临时状态、未经验证的推测、无通用原则的事件。