session-brain

Session Brain

基于 Agent 会话历史构建可搜索的主题图谱。输出位于 ~/.claude/session-brain/ 的旁路数据中，不会触碰知识库。

所有繁重的工作都由 obsidian-wiki CLI 中的确定性 Python 代码完成。你唯一要做的就是为聚类命名，这只需一轮，也不需要阅读任何会话记录。

何时使用哪个技能

目标	技能
构建或刷新图谱；浏览主题	session-brain（本技能）
查找并加载特定的过往会话	session-search
将会话提炼为永久知识库页面	wiki-history-ingest / claude-history-ingest

第 1 步：构建

obsidian-wiki sessions-build --json

在约 1000 个会话的情况下，首次运行耗时约 3 秒，增量运行则远低于 1 秒——它只会重新读取大小或修改时间发生变化的会话记录。实用标志：

标志	使用场景
--full	忽略所有缓存并重新读取全部内容
--mutual	生成更紧凑的小型聚类（仅使用 mutual-kNN 边）
--half-life N	更改近期性半衰期（默认 90 天）
--min-sim 0.15	减少边的数量并提高边的强度——如果图谱过于密集而难以阅读，请使用此选项
--skip name	排除某个项目。匹配方式为子字符串匹配；请传入不带修饰的名称，因为缓存目录以 - 开头，argparse 会将其识别为标志

报告关键数字：会话总数、有会话记录的数量与仅有历史记录的数量、边数和聚类数。

第 2 步：为未命名的聚类命名

obsidian-wiki sessions-clusters --unnamed --json

每个聚类都包含 top_terms 和 exemplars（度数最高的三个会话，其标题已在 graph.json 中）。**这些信息就足够了。**不要打开会话记录为聚类命名——整个设计目标就是无论语料库大小如何，命名都只需一轮。

为每个聚类编写一个 3–5 个词的 name 和一个单句 summary，然后：

obsidian-wiki sessions-name --from - <<'EOF'
[{"id": 3, "name": "warden telemetry pipeline", "summary": "Building and debugging the redacted telemetry chain."}]
EOF

名称以聚类的主导词汇为键，存储在 names.json 中，而非以聚类 ID 为键——因此即使聚类 ID 是位置性的、会随语料库增长而变化，这些名称在重建后仍能保留。重复运行时，--unnamed 通常为空，这一步无需操作。

如果某个聚类的词语确实毫无关联，就如实命名（"mixed — short sessions"），不要凭空编造主题。

第 3 步：报告图谱

读取 clusters.json 并告诉用户：

• 最大主题——按 size 排序
• 当前热门——momentum 最高（最近 30 天与此前 60 天的活动对比）
• 已沉寂的主题——dormant: true（近期性低，且过去 60 天内没有活动）
• 主题交汇处——bridges，即连接两个原本彼此分离主题的会话。 这些通常是图谱中最有趣的会话。

然后提供可视化：

open ~/.claude/session-brain/graph.html

节点大小表示会话长度，亮度表示近期性，空心圆环表示仅有历史记录的会话，金色边框表示已加书签的会话。时间滑块和搜索框会共同筛选。

注意事项

• **切勿通过本技能写入知识库。**如果用户想将会话知识存入知识库，请使用 wiki-history-ingest。
• **仅有历史记录的会话确实存在。**长期缓存中约有 40% 的内容仅作为提示词存在于 history.jsonl 中；这些内容会生成图谱节点，也可以搜索到，但无法加载。请明确说明这一点，不要让人误以为它们丢失了。
• 图谱属于派生数据。如果结果有误，使用 --full 从头重建；不会丢失任何内容。