memory

Memory - 读取与访问操作

统一的只读记忆技能，包含用于搜索、加载、同步、历史记录和可视化的子命令。

跨会话读取策略（Opus 5.5 / CC 2.1.111+）： Opus 5.5 能够可靠地跨会话读取文件系统记忆。在会话开始时加载上下文，请优先采用分层读取顺序：

1. ~/.claude/projects/<slug>/memory/MEMORY.md（持久索引——始终先加载）
2. .claude/chain/state.json + 最新的 NN-*.json 交接文件（会话续接）
3. 对于文件系统索引无法回答的内容，使用 MCP mcp__memory__search_nodes（类型化图遍历）

第 1 层开销低（小型索引文件），第 2 层范围明确（特定会话），第 3 层按需选择（仅在必要时使用）。避免将完整知识图谱全部载入上下文——先用索引缩小搜索范围。

参数解析

SUBCOMMAND = "$ARGUMENTS[0]"  # First token: search, load, history, viz, status
QUERY = "$ARGUMENTS[1]"       # Second token onward: search query or flags
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

用法

memory search <query>  # Search knowledge graph
memory load             # Load context at session start
memory history          # View decision timeline
memory viz              # Visualize knowledge graph
memory status           # Show memory system health

---

重要：未指定子命令时使用 AskUserQuestion

如果调用时未指定子命令，请询问用户想要执行什么操作：

AskUserQuestion(
  questions=[{
    "question": "What memory operation do you need?",
    "header": "Operation",
    "options": [
      {"label": "search", "description": "Search decisions and patterns in knowledge graph"},
      {"label": "load", "description": "Load relevant context for this session"},
      {"label": "history", "description": "Decision timeline + knowledge-graph viz (--mermaid)"},
      {"label": "status", "description": "Check memory system health"}
    ],
    "multiSelect": false
  }]
)

---

子命令

加载详细信息：使用 Read("references/memory-commands.md") 查看各子命令的完整用法、标志、输出格式和基于上下文的结果数量限制。

子命令	用途
search	搜索过往决策、模式和实体。支持 --category（映射到 metadata.category）、--limit、--agent（按 agent_id 限定范围）和 --global 筛选标志
load	在会话开始时自动加载相关记忆。支持 --project、--global
history	以表格、Mermaid 或 JSON 格式输出决策时间线。支持 --since、--mermaid
viz	将知识图谱渲染为 Mermaid 图表。另请参阅 Read("references/mermaid-patterns.md")
status	检查记忆系统运行状况

---

定时扫描（cron）

每夜 KG 过时报告

.github/workflows/memory-staleness.yml 中的 cron 作业每天 04:00 UTC 运行。它调用 scripts/staleness_cron.py 扫描所有记忆 MCP 实体，标记最新观察时间戳超过 30 天的实体，并将 Markdown 报告写入 docs/reports/memory-staleness-YYYY-MM-DD.md。

python3 ${CLAUDE_SKILL_DIR}/scripts/staleness_cron.py docs/reports/ \
    --threshold-days 30 --limit 50

自动跳过条件（均以状态码 0 退出，并记录 WARN 日志）：

跳过原因	触发条件
yg-mcp-core not importable	未安装 yg-mcp-core>=0.3.0（orchestkit 为公开项目；yg-mcp-core 位于私有源 pypi.yonyon.ai——仅 HQ 可用）
memory MCP unreachable	memory MCP 服务已停机，或 .mcp.json 未定义 memory

报告内容：

• 实体总数 / 过时实体数 / 最新实体数
• 按过时程度排序的前 N 条过时记录（无时间戳的排在最前，然后从最早到最新）
• 每行包含：名称、entityType、天数、观察次数
• 按过时时长区间给出的建议操作（>90d 建议检查，>180d 可考虑归档）

无法解析时间戳的实体也视为过时——正确做法是由操作人员介入处理（补录 last_read 观察记录或清理实体）。

用于便于单元测试的纯函数（parse_iso_timestamp、latest_observation_timestamp、is_stale、build_report_payload、render_markdown）位于同级文件 staleness_lib.py 中。

此模式与 Yonatan-HQ/hq-ext-plugin#194（audio_podcast）以及 orchestkit#1886（post-synth podcast）+ #1887（memory writeback）保持一致。此功能因 Yonatan-HQ/core#993（yg-mcp-core 0.3.0）而解除阻塞。

---

工作流

1. 解析子命令

Extract first argument as subcommand
If no subcommand -> AskUserQuestion
Validate subcommand is one of: search, load, history, viz, status
Parse remaining flags
Check for --agent <agent-id> flag → agent_id: "ork:{agent-id}"

2. 执行子命令

根据子命令将请求路由到相应的处理程序。

3. 报告结果

根据操作类型设置合适的输出格式。

---

规则速查

规则	影响	涵盖内容
entity-extraction-patterns（加载 rules/entity-extraction-patterns.md）	高	实体类型、关系类型、图查询语义
deduplication-strategy（加载 rules/deduplication-strategy.md）	高	Edit-over-Write 模式、基于锚点的插入、验证

---

会话恢复

加载详情：对于 CC 2.1.31 的恢复提示、结束前的上下文捕获，以及 PR、议题和实现的恢复工作流，请使用 Read("references/session-resume-patterns.md")。

---

相关技能

• ork:remember - 存储决策和模式（写入端）

---

错误处理

• 如果用于可视化的图为空：显示有关使用 remember 的提示信息
• 如果子命令无效：显示用法帮助
• 如果记忆文件损坏：报告问题并提供修复选项
• 如果搜索查询为空：改为显示最近的实体
• 如果没有搜索结果：建议替代方案