session-brain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session Brain

Builds a searchable topic graph over your agent session history. The output is a sidecar at

~/.claude/session-brain/

— the vault is never touched.

All the heavy lifting is deterministic Python in the

obsidian-wiki

CLI. Your only job is to name the clusters, which takes exactly one turn and requires reading no transcripts.

基于你的Agent会话历史构建可搜索的主题图谱。输出结果为位于

~/.claude/session-brain/

的附属文件——绝不会触碰vault。

所有核心逻辑由

obsidian-wiki

CLI中的确定性Python代码实现。你只需为聚类命名，这一步仅需一轮操作，无需阅读任何会话记录。

When to use which skill

技能适用场景对比

Goal	Skill
Build or refresh the graph; survey topics	`session-brain` (this one)
Find and load a specific past session	`session-search`
Distil sessions into permanent vault pages	`wiki-history-ingest` / `claude-history-ingest`

目标	技能
构建或刷新图谱；概览主题	`session-brain` （本技能）
查找并加载特定历史会话	`session-search`
将会话提炼为永久vault页面	`wiki-history-ingest` / `claude-history-ingest`

Step 1: Build

步骤1：构建图谱

bash

obsidian-wiki sessions-build --json

Roughly 3 seconds cold on ~1000 sessions, well under a second incrementally — it re-reads only transcripts whose size or mtime changed. Useful flags:

Flag	When
`--full`	Ignore all caches and re-read everything
`--mutual`	Tighter, smaller clusters (mutual-kNN edges only)
`--half-life N`	Change the recency half-life (default 90 days)
`--min-sim 0.15`	Fewer, stronger edges — use if the graph is too dense to read
`--skip name`	Exclude a project. Match is substring-based; pass the bare name, because cache dirs start with `-` and argparse reads that as a flag

Report the headline numbers: total sessions, how many have transcripts vs. are history-only, edges, and cluster count.

bash

obsidian-wiki sessions-build --json

处理约1000个会话时，冷启动耗时约3秒，增量更新耗时不到1秒——它仅重新读取大小或修改时间发生变化的会话记录。实用参数：

参数	适用场景
`--full`	忽略所有缓存，重新读取全部内容
`--mutual`	生成更紧凑、规模更小的聚类（仅保留mutual-kNN边）
`--half-life N`	修改新鲜度半衰期（默认90天）
`--min-sim 0.15`	生成更少、更强的边——若图谱过于密集难以阅读时使用
`--skip name`	排除某个项目。匹配基于子字符串；只需传入项目名称，因为缓存目录以 `-` 开头，argparse会将其识别为参数

执行后会返回关键数据：会话总数、带记录的会话数与仅存于历史的会话数、边数以及聚类数量。

Step 2: Name the unnamed clusters

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

bash

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

Each cluster comes with

top_terms

and

exemplars

(its three highest-degree sessions, whose titles are already in

graph.json

). That is all you need. Do not open transcripts to name a cluster — the whole design goal is that naming costs one turn regardless of corpus size.

Write a 3–5 word

name

and a one-sentence

summary

per cluster, then:

bash

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

Names are stored in

names.json

keyed by the cluster's dominant vocabulary, not its id — so they survive rebuilds even though cluster ids are positional and shift as the corpus grows. On repeat runs

--unnamed

is usually empty and this step is free.

If a cluster's terms are genuinely incoherent, name it honestly (

"mixed — short sessions"

) rather than inventing a theme.

bash

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

每个聚类会附带

top_terms

（核心术语）和

exemplars

（三个关联度最高的会话，其标题已存入

graph.json

）。这些信息足够命名。无需打开会话记录来命名聚类——本工具的设计目标就是无论语料规模多大，命名仅需一轮操作。

为每个聚类编写3-5个词的

name

（名称）和一句

summary

（摘要），然后执行：

bash

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"

），而非强行编造主题。

Step 3: Report the map

步骤3：展示图谱报告

Read

clusters.json

and tell the user:

Biggest topics — by
```
size
```
What's hot — highest
```
momentum
```
(activity in the last 30 days vs. the 60 before it)
What's gone quiet —
```
dormant: true
```
(low recency and nothing in 60 days)
Where topics meet —
```
bridges
```
, the sessions that connect two otherwise separate topics. These are often the most interesting sessions in the graph.

Then offer the visualisation:

bash

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

Node size is session length, brightness is recency, hollow rings are history-only sessions, and gold borders are bookmarked ones. The time slider and search box filter together.

读取

clusters.json

并向用户展示：

最大主题——按
```
size
```
（规模）排序
热门主题——
```
momentum
```
（动量）最高的主题（过去30天与之前60天的活跃度对比）
沉寂主题——标记为
```
dormant: true
```
的主题（新鲜度低且过去60天无活动）
主题关联点——
```
bridges
```
（桥接会话），即连接两个原本独立主题的会话。这些通常是图谱中最有价值的会话。

然后提供可视化方式：

bash

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

节点大小代表会话长度，亮度代表新鲜度，空心环代表仅存于历史的会话，金色边框代表已收藏的会话。时间滑块和搜索框可配合使用进行筛选。

Notes

注意事项

Never write to the vault from this skill. If the user wants session knowledge in the vault, that is
```
wiki-history-ingest
```
.
History-only sessions are real. Roughly 40% of a long-lived cache exists only as prompts in
```
history.jsonl
```
; those get graph nodes and are findable, but can never be loaded. Say so plainly rather than implying they are missing.
The graph is derived data. If it looks wrong,
```
--full
```
rebuilds from scratch; nothing is lost.

本技能绝不会写入vault。若用户希望将会话知识存入vault，请使用
```
wiki-history-ingest
```
。
仅存于历史的会话是真实存在的。对于长期使用的缓存，约40%仅以提示形式存在于
```
history.jsonl
```
中；这些会话会生成图谱节点且可被查找，但无法加载。请如实告知用户，而非暗示这些会话缺失。
图谱是衍生数据。若显示异常，使用
```
--full
```
参数可从头重建；不会丢失任何数据。