memory-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Memory Search

<identity> Memory Search is the live recall layer for all agents in the ecosystem. It performs semantic search over the global memory corpus (learnings, decisions, issues, gotchas, patterns) using vector similarity. Every agent must use this skill to avoid working from stale or contradictory context — especially in long sessions where in-conversation memory has been compressed or reset. </identity> <capabilities> - Semantic similarity search over all memory files (learnings.md, decisions.md, issues.md, gotchas.json, patterns.json) - Returns up to 10 results ranked by similarity score - Output includes: source file, similarity percentage, and 200-character content preview - Supports natural language queries — no keyword matching required - Cross-agent knowledge retrieval: surfaces knowledge from previous agents in the same or prior sessions </capabilities> <instructions> <execution_process>

<identity> Memory Search是生态系统中所有Agent的实时召回层，它使用向量相似度对全局内存语料库（学习成果、决策、问题、常见陷阱、模式）执行语义搜索。所有Agent都必须使用该技能，避免基于过时或矛盾的上下文开展工作，尤其是在会话内内存已被压缩或重置的长时间会话场景下。 </identity> <capabilities> - 对所有内存文件（learnings.md、decisions.md、issues.md、gotchas.json、patterns.json）执行语义相似度搜索 - 最多返回10条按相似度评分排序的结果 - 输出包含：源文件、相似度百分比、200字内容预览 - 支持自然语言查询，无需关键词匹配 - 跨Agent知识检索：可展示同一会话或先前会话中其他Agent生成的知识 </capabilities> <instructions> <execution_process>

Step 1: Formulate a Focused Query

步骤1：制定精准查询

Identify the specific knowledge gap before invoking. Good queries target a concrete decision, pattern, or error — not a broad topic.

Good queries:

```
"JWT refresh token rotation pattern"
```
```
"Windows path normalization in hooks"
```
```
"BM25 index rebuild performance"
```
```
"agent spawning without task_id error"
```

Bad queries (too broad):

```
"authentication"
```
— too generic, returns noise
```
"everything about routing"
```
— unfocused
```
"what have we done before"
```
— meaningless for semantic search

调用前先明确具体的知识缺口，好的查询会针对具体的决策、模式或错误，而非宽泛的主题。

好的查询示例：

```
"JWT refresh token rotation pattern"
```
```
"Windows path normalization in hooks"
```
```
"BM25 index rebuild performance"
```
```
"agent spawning without task_id error"
```

不好的查询示例（过于宽泛）：

```
"authentication"
```
— 太通用，会返回无效内容
```
"everything about routing"
```
— 不聚焦
```
"what have we done before"
```
— 对语义搜索无意义

Step 2: Run the Search

步骤2：执行搜索

Invoke via the

Bash

tool:

bash

node .claude/lib/memory/memory-search.cjs "your focused search query"

Full invocation:

bash

node .claude/lib/memory/memory-search.cjs "JWT refresh token rotation pattern"

通过

Bash

工具调用：

bash

node .claude/lib/memory/memory-search.cjs "your focused search query"

完整调用示例：

bash

node .claude/lib/memory/memory-search.cjs "JWT refresh token rotation pattern"

Step 3: Parse the Output

步骤3：解析输出

The output format is:

Found N results for: "<query>"

[<source-file>] Similarity: XX.X%
<200-character content preview>...

[<source-file>] Similarity: YY.Y%
<200-character content preview>...

Example real output:

Found 3 results for: "JWT refresh token rotation pattern"

[learnings.md] Similarity: 87.3%
JWT refresh tokens must be stored in httpOnly cookies to prevent XSS. See ADR-045 for detailed rationale and trade-offs vs localStorage approach...

[decisions.md] Similarity: 74.1%
ADR-045: JWT over sessions chosen for stateless architecture. Refresh token rotation every 15 minutes. Invalidate on logout via token blocklist...

[issues.md] Similarity: 61.2%
Known issue: JWT expiry not propagated to frontend — workaround in auth.middleware.ts line 47 until ADR-045 Phase 2 is implemented...

输出格式如下：

Found N results for: "<query>"

[<source-file>] Similarity: XX.X%
<200-character content preview>...

[<source-file>] Similarity: YY.Y%
<200-character content preview>...

真实输出示例：

Found 3 results for: "JWT refresh token rotation pattern"

[learnings.md] Similarity: 87.3%
JWT refresh tokens must be stored in httpOnly cookies to prevent XSS. See ADR-045 for detailed rationale and trade-offs vs localStorage approach...

[decisions.md] Similarity: 74.1%
ADR-045: JWT over sessions chosen for stateless architecture. Refresh token rotation every 15 minutes. Invalidate on logout via token blocklist...

[issues.md] Similarity: 61.2%
Known issue: JWT expiry not propagated to frontend — workaround in auth.middleware.ts line 47 until ADR-045 Phase 2 is implemented...

Step 4: Interpret Similarity Scores

步骤4：解读相似度评分

Similarity	Interpretation	Action
>80%	Highly relevant — directly matches the query	Read the full source file for complete context
60–80%	Likely relevant — related topic or adjacent pattern	Skim and use if applicable
40–60%	Possibly relevant — tangentially related	Use judgment, may be noise
<40%	Probably not relevant	Discard unless nothing better exists

相似度	解读	操作建议
>80%	高度相关 — 与查询直接匹配	阅读完整源文件获取全部上下文
60–80%	大概率相关 — 相关主题或邻近模式	略读，适用的话可使用
40–60%	可能相关 — 间接相关	自行判断，可能是无效内容
<40%	大概率不相关	除非没有更好的结果否则直接忽略

Step 5: Follow Up on High-Similarity Results

步骤5：跟进高相似度结果

For results with similarity >60%, read the full source file to get untruncated content:

bash

undefined

对于相似度>60%的结果，阅读完整源文件获取未截断的内容：

bash

undefined

Results showed [decisions.md] Similarity: 87.3%

结果显示 [decisions.md] 相似度: 87.3%

Follow up with:

跟进操作：

Read({ file_path: '.claude/context/memory/decisions.md' })


Or search for the specific ADR/pattern by keyword:

```bash
node .claude/lib/memory/memory-search.cjs "ADR-045 JWT"

Read({ file_path: '.claude/context/memory/decisions.md' })


或者按关键词搜索特定的ADR/模式：

```bash
node .claude/lib/memory/memory-search.cjs "ADR-045 JWT"

Step 6: Handle Zero Results

步骤6：处理零结果情况

Found 0 results

, try:

Rephrase the query using synonyms or the actual error message text

Broaden slightly — e.g.,

"JWT authentication"

instead of

"JWT RS256 key rotation"

Check memory files directly if the topic is recent and may not yet be indexed

Zero results means the knowledge is either not yet documented or the query was too specific.

如果返回

Found 0 results

，可以尝试：

改写查询：使用同义词或实际错误信息文本

适当放宽范围 — 比如用

"JWT authentication"

替代

"JWT RS256 key rotation"

直接检查内存文件：如果主题是近期内容，可能还未被索引

零结果意味着相关知识要么尚未被记录，要么查询过于具体。

Step 7: Apply or Document Findings

步骤7：应用或记录查询结果

If result confirms known approach: proceed with confidence; cite the source in your reasoning.
If result reveals a better approach: update your plan to align with the documented pattern.
If result reveals a known issue/workaround: apply the workaround immediately rather than discovering it yourself.
If nothing useful found: continue with your best judgment; document your decision afterward to Memory Protocol.

</execution_process>

<best_practices>

Run early, not late: Memory search at the START of a task prevents wasted effort. Running it after you have already made decisions is too late to benefit.
One query per knowledge gap: Don't batch all your unknowns into one query. Run targeted queries for each specific gap.
Use the actual error message as the query: If you hit an error, search for the error message text verbatim — it often finds a documented workaround.
Results are pointers, not canonical sources: Always follow up by reading the full source file when similarity is >70%. The 200-char preview is not the complete record.
After a session gap or context compression: Always run memory-search to re-establish current state before proceeding. Context may have been lost.
Cross-agent knowledge sync: Before duplicating an analysis another agent might have done, search memory. The result may already be documented.

</best_practices> </instructions>

At the start of a long task or after a context compression event:

bash

undefined

如果结果确认了已知方案：放心推进，在你的推理过程中标注来源
如果结果展示了更好的方案：更新你的计划，与已记录的模式对齐
如果结果披露了已知问题/解决方案：直接应用解决方案，无需自行排查
如果没有找到有用内容：按照你的最佳判断继续推进，之后将你的决策记录到内存协议中

</execution_process>

<best_practices>

尽早执行，不要延后：在任务开始时执行内存搜索可以避免无用功，在你已经做出决策后再搜索就来不及发挥价值了。
每个知识缺口对应一个查询：不要把所有未知项合并到一个查询中，针对每个具体缺口执行定向查询。
用实际错误信息作为查询内容：如果你遇到了错误，直接逐字搜索错误信息，通常能找到已记录的解决方案。
结果只是指向标，不是权威来源：当相似度>70%时一定要跟进阅读完整源文件，200字的预览不是完整记录。
会话中断或上下文压缩后：继续推进前一定要执行内存搜索重建当前状态，上下文可能已经丢失。
跨Agent知识同步：在重复其他Agent可能已经做过的分析前，先搜索内存，结果可能已经被记录了。

</best_practices> </instructions>

在长任务开始时或上下文压缩事件后：

bash

undefined

What are the current known issues in this area?

该领域当前已知的问题有哪些？

node .claude/lib/memory/memory-search.cjs "hook execution errors"

What patterns have been established for this domain?

这个领域已经建立了哪些模式？

node .claude/lib/memory/memory-search.cjs "routing table keyword patterns"

Any decisions I should be aware of?

有哪些我需要了解的决策？

node .claude/lib/memory/memory-search.cjs "agent model selection ADR"


</usage_example>

<usage_example title="Debugging — check for known workarounds">

When stuck on an error:

```bash

node .claude/lib/memory/memory-search.cjs "agent model selection ADR"


</usage_example>

<usage_example title="调试 — 检查已知解决方案">

遇到错误卡壳时：

```bash

Search for the exact error message

搜索准确的错误信息

node .claude/lib/memory/memory-search.cjs "Unable to locate module.exports insertion point"

Or describe the symptom

或者描述症状

node .claude/lib/memory/memory-search.cjs "routing table update fails silently"


If a result appears with >70% similarity, the error has been seen before and may have a documented fix.
</usage_example>

<usage_example title="Before making an architectural decision">

Before choosing between two approaches:

```bash

node .claude/lib/memory/memory-search.cjs "routing table update fails silently"


如果出现相似度>70%的结果，说明这个错误之前出现过，可能有已记录的修复方案。
</usage_example>

<usage_example title="做出架构决策前">

在两个方案间做选择前：

```bash

What was decided previously about this tradeoff?

关于这个权衡之前有过什么决策？

node .claude/lib/memory/memory-search.cjs "ESM vs CJS module format decision"

Are there ADRs for this pattern?

这个模式有没有对应的ADR？

node .claude/lib/memory/memory-search.cjs "async hook pattern ADR"


If a relevant ADR is found, follow it rather than re-litigating the decision.
</usage_example>

<usage_example title="Cross-agent knowledge retrieval">

When you need to know what another agent discovered:

```bash

node .claude/lib/memory/memory-search.cjs "async hook pattern ADR"


如果找到相关的ADR，遵循该决策，无需重新讨论。
</usage_example>

<usage_example title="跨Agent知识检索">

当你需要了解其他Agent的发现时：

```bash

What did the reflection agent find recently?

反思Agent最近发现了什么？

node .claude/lib/memory/memory-search.cjs "reflection agent findings skills gap"

What did the security audit reveal?

安全审计披露了什么问题？

node .claude/lib/memory/memory-search.cjs "security audit prompt injection findings"


</usage_example>
</examples>

node .claude/lib/memory/memory-search.cjs "security audit prompt injection findings"


</usage_example>
</examples>

Iron Laws

铁律

ALWAYS run memory-search before assuming no prior context exists. Never claim "there's no documented pattern for this" without first running a targeted search.
NEVER use memory-search results as canonical ground truth. They are summaries and previews. Always read the full source for decisions with material consequences.
NEVER skip memory-search because "I already know about this." Stale in-session assumptions are the primary cause of inconsistent multi-agent behavior.
ALWAYS run multiple targeted queries, not one broad one. A single broad query misses specific matches. Two or three focused queries are more effective.
NEVER run memory-search with a query longer than ~10 words. Over-specified queries degrade similarity matching. Extract the key concept.

在假设没有先前上下文之前，一定要先执行内存搜索。 没有先执行定向搜索，永远不要声称「这个场景没有已记录的模式」。
永远不要把内存搜索结果当作权威事实。 它们只是摘要和预览，对于有重大影响的决策，一定要阅读完整源文件。
永远不要因为「我已经了解这个内容」就跳过内存搜索。 会话内的过时假设是多Agent行为不一致的主要原因。
一定要执行多个定向查询，而不是一个宽泛的查询。 单个宽泛查询会漏掉特定匹配，2-3个聚焦的查询效率更高。
永远不要用超过10个词的查询执行内存搜索。 过度限定的查询会降低相似度匹配效果，提取核心概念即可。

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Correct Approach
`"everything about auth"` broad query	Too generic — returns unrelated noise	`"JWT refresh token rotation"`
Skipping search because "context is fresh"	In-session context is NOT the same as memory	Always search at task start
Treating 200-char preview as full record	Preview truncates at 200 chars — critical detail may be cut	Follow up with `Read` on the source file
Running search AFTER making the decision	Memory lookup must happen before your design choice	Search first, decide second
Single query for multiple unknowns	One query can't cover multiple semantic dimensions	Run one query per knowledge gap
Ignoring <60% results entirely	Sometimes tangential info is still actionable	Skim low-similarity results before discarding

反模式	失效原因	正确做法
`"everything about auth"` 这类宽泛查询	太通用，会返回无关的无效内容	`"JWT refresh token rotation"`
因为「上下文是新的」就跳过搜索	会话内上下文不等于内存存储的内容	任务启动时一定要搜索
把200字预览当作完整记录	预览只截断到200字，关键细节可能被切掉	对源文件执行 `Read` 操作跟进查看
做出决策后才执行搜索	内存查询必须在你做出设计选择之前进行	先搜索，再决策
单个查询对应多个未知项	一个查询无法覆盖多个语义维度	每个知识缺口对应一个查询
完全忽略相似度<60%的结果	有时间接相关的信息仍然可用	丢弃低相似度结果前先略读

Error Handling

错误处理

Error	Cause	Resolution
`Usage: node .claude/lib/memory/memory-search.cjs "search query"`	Query argument missing	Always pass a quoted query string
`Search failed: <error message>`	Memory manager unavailable or index not built	Check `.claude/lib/memory/memory-manager.cjs` and ensure memory system is initialized
`Found 0 results`	Query too specific or topic not yet documented	Rephrase query; fall back to direct file search
Very slow response (>3s)	Vector similarity computation on cold index	Expected on first call; subsequent calls are faster

错误	原因	解决方案
`Usage: node .claude/lib/memory/memory-search.cjs "search query"`	缺少查询参数	一定要传入带引号的查询字符串
`Search failed: <error message>`	内存管理器不可用或索引未构建	检查 `.claude/lib/memory/memory-manager.cjs` ，确保内存系统已初始化
`Found 0 results`	查询过于具体或主题尚未被记录	改写查询；降级为直接文件搜索
响应非常慢（>3秒）	冷索引上的向量相似度计算	首次调用属于正常现象，后续调用会更快

Integration Patterns

集成模式

Mandatory Pre-Task Pattern (All Agents)

强制前置任务模式（所有Agent适用）

Every agent should run memory-search at task start for any non-trivial work:

bash

undefined

所有Agent执行非 trivial 工作前都应该在任务启动时执行内存搜索：

bash

undefined

Pattern: topic-scoped recall before starting

模式：开始前先召回主题相关内容

node .claude/lib/memory/memory-search.cjs "known patterns for <your task domain>" node .claude/lib/memory/memory-search.cjs "known issues in <your task area>"

undefined

node .claude/lib/memory/memory-search.cjs "known patterns for <your task domain>" node .claude/lib/memory/memory-search.cjs "known issues in <your task area>"

undefined

Error Recovery Pattern

错误恢复模式

When any tool or command fails unexpectedly:

bash

undefined

任何工具或命令意外失败时：

bash

undefined

Paste the error message directly as the query

直接粘贴错误信息作为查询内容

node .claude/lib/memory/memory-search.cjs "<exact error text>"

undefined

node .claude/lib/memory/memory-search.cjs "<exact error text>"

undefined

Decision Gate Pattern

决策门槛模式

Before any architectural decision:

bash

undefined

做出任何架构决策前：

bash

undefined

Check for existing ADRs on this topic

检查该主题是否有现存的ADR

node .claude/lib/memory/memory-search.cjs "ADR <decision topic>"

undefined

node .claude/lib/memory/memory-search.cjs "ADR <decision topic>"

undefined

Cross-Session Continuity Pattern

跨会话连续性模式

At the start of any continued session (especially after context compression):

bash

node .claude/lib/memory/memory-search.cjs "recent decisions <project area>"
node .claude/lib/memory/memory-search.cjs "current known issues"
node .claude/lib/memory/memory-search.cjs "last session learnings"

任何续会开始时（尤其是上下文压缩后）：

bash

node .claude/lib/memory/memory-search.cjs "recent decisions <project area>"
node .claude/lib/memory/memory-search.cjs "current known issues"
node .claude/lib/memory/memory-search.cjs "last session learnings"

When to Use

适用场景

Trigger	Query Strategy	Expected Benefit
Long-running session — context may be stale	`"<domain> recent decisions"`	Re-sync with documented state
New error encountered	`"<exact error message>"`	Find documented workaround
Before architectural decision	`"ADR <topic>"` or `"<decision> trade-off"`	Avoid re-litigating settled decisions
After context compression	`"<current task domain>"`	Restore working context
Cross-agent handoff	`"<previous agent task> findings"`	Continue from where other agent left off
Before writing a new pattern	`"<pattern name> existing"`	Avoid duplicating documented guidance

触发条件	查询策略	预期收益
长时间运行的会话 — 上下文可能过时	`"<domain> recent decisions"`	与已记录的状态重新同步
遇到新错误	`"<exact error message>"`	找到已记录的解决方案
架构决策前	`"ADR <topic>"` 或 `"<decision> trade-off"`	避免重新讨论已确定的决策
上下文压缩后	`"<current task domain>"`	恢复工作上下文
跨Agent交接	`"<previous agent task> findings"`	从其他Agent停止的地方继续推进
编写新模式前	`"<pattern name> existing"`	避免重复编写已记录的指引

Memory Protocol (MANDATORY)

内存协议（强制要求）

Before starting:

bash

node .claude/lib/memory/memory-search.cjs "memory-search usage patterns"

After completing:

New search pattern discovered →
```
.claude/context/memory/learnings.md
```
Memory index issue found →
```
.claude/context/memory/issues.md
```
Decision about when to use memory-search →
```
.claude/context/memory/decisions.md
```

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen. This skill exists to recover from exactly that situation.

开始前：

bash

node .claude/lib/memory/memory-search.cjs "memory-search usage patterns"

完成后：

发现新的搜索模式 → 写入
```
.claude/context/memory/learnings.md
```
发现内存索引问题 → 写入
```
.claude/context/memory/issues.md
```
关于何时使用内存搜索的决策 → 写入
```
.claude/context/memory/decisions.md
```

假设会发生中断：你的上下文可能会重置。如果内容没有存在内存中，就等于没有发生过。这个技能就是为了应对这种情况而存在的。