| name | save-to-kb |
| description | Personal knowledge base manager for LLM-Brain-Bases. Four modes: (1) AUTO-SAVE — automatically called at end of significant conversations to save reusable knowledge as Cards; (2) INIT — run "save-to-kb init" on first install to create directory structure and configure KB path; (3) CHECK — run "save-to-kb check" to scan the entire knowledge base for broken links, inconsistencies, and missing data, then fix with user confirmation; (4) REPLAY — run "save-to-kb replay" to retroactively process historical sessions that were never saved. Config path: ~/.claude/skills/save-to-kb/.config |
save-to-kb
Route: Which Procedure to Run
Read the invocation context first:
- Invoked with argument
init → run [INIT PROCEDURE]
- Invoked with argument
check → run [CHECK PROCEDURE]
- Invoked with argument
replay → run [REPLAY PROCEDURE]
- Invoked with argument
save → run [AUTO-INIT CHECK] then [SAVE PROCEDURE]
- Invoked with argument
file <path> → run [FILE PROCEDURE] with the given path
- Invoked without arguments → run [MENU]
[MENU]
Present a two-level menu using AskUserQuestion (max 4 options per question).
Level 1 — main actions:
- save — 从当前对话提取知识并保存到知识库
- file — 分析指定文件并提取知识（PDF / MD / txt）
- check — 健康检查，扫描断链和不一致
- 管理知识库… — 进入二级菜单（init / replay）
If user selects "管理知识库…", show Level 2:
- init — 初始化知识库或更改路径
- replay — 回溯历史 session，补录遗漏的知识
Route based on final selection:
- save → [AUTO-INIT CHECK] then [SAVE PROCEDURE]
- file → [FILE PROCEDURE]
- check → [CHECK PROCEDURE]
- init → [INIT PROCEDURE]
- replay → [REPLAY PROCEDURE]
[AUTO-INIT CHECK]
Before running the save procedure, verify the KB is initialized:
- Check if
~/.claude/skills/save-to-kb/.config exists and contains a path
- If missing or empty → run [INIT PROCEDURE] first, then continue with save
[INIT PROCEDURE]
Two scenarios: first-time setup and change path. Both follow the same steps but with different prompts and behaviors.
Step I-1: Detect Scenario
Read ~/.claude/skills/save-to-kb/.config:
Step I-2: Ask for Path
Ask the user:
"Enter the full path for the knowledge base (e.g. ~/Documents/LLM-Brain-Bases or /Users/you/Obsidian/Work/LLM-Brain-Bases):"
Expand ~ to the actual absolute home directory path. Show the resolved path and ask: "Confirm: create knowledge base at {resolved-path}? (yes/no)"
If no → ask again for a new path.
Step I-3: Create Directory Structure
Create the following directories (skip any that already exist):
{KB}/
{KB}/Bases/
{KB}/Cards/
{KB}/Wiki/
Step I-3b: Migrate Files (path change + migrate: true only)
Skip this step for first-time setup or if user chose not to migrate.
Copy all contents from {old-KB}/ to {new-KB}/:
{old-KB}/Bases/ → {new-KB}/Bases/{old-KB}/Cards/ → {new-KB}/Cards/{old-KB}/Wiki/ → {new-KB}/Wiki/{old-KB}/Claude.md → {new-KB}/Claude.md
Rules:
- Copy, do not move. Old files remain untouched.
- Do not overwrite files that already exist at the new location.
- Wikilinks inside the files are relative (
[[Cards/slug]]), so they require no modification.
- After copying, report:
Migrated {N} files to {new-KB}.
Step I-4: Write Master Index
First-time setup: Write {KB}/Claude.md only if it does not exist (never overwrite an existing index).
Path change: Write {KB}/Claude.md only if it does not exist at the new location.
# LLM-Brain-Bases — Master Knowledge Index
*Auto-maintained by Claude. Last updated: {YYYY-MM-DD}.*
## How to Use This Index
Before starting any non-trivial task:
1. Check the **Scenario Quick-Lookup** table below for the task type
2. If found, read the linked Cards directly
3. If not found, identify the relevant category in **Knowledge Map** and open the Wiki file
To save new knowledge: invoke `save-to-kb` at conversation end.
To health-check the KB: invoke `save-to-kb check`.
---
## Knowledge Map
| Wiki | Cards | Focus | Key Tags |
|------|-------|-------|----------|
| [[Wiki/ai-tools]] | 0 | Claude Code, LLM tools, prompting, skills | claude, hooks, skills, llm |
| [[Wiki/workflow]] | 0 | Development process, tooling, automation | git, ci, planning |
| [[Wiki/debugging]] | 0 | Systematic diagnosis patterns | debugging, logging, tracing |
| [[Wiki/architecture]] | 0 | System design, decisions, tradeoffs | design, patterns, architecture |
| [[Wiki/knowledge-management]] | 0 | Knowledge base, Obsidian, PKM | obsidian, pkm |
| [[Wiki/frontend]] | 0 | Vue3, Nuxt, React, SSR, UI | vue3, nuxt, react, ssr |
| [[Wiki/backend]] | 0 | APIs, databases, server logic | postgres, redis, api |
| [[Wiki/infra]] | 0 | Deployment, CI/CD, cloud | docker, vercel, github-actions |
| [[Wiki/business]] | 0 | Non-technical context, decisions | client, scope, product |
---
## Scenario Quick-Lookup
| Scenario | Start Here |
|----------|-----------|
| *(empty — populated after first save)* | — |
---
## Cross-Domain Cards
*(empty — populated after first save)*
---
## Recently Added
*(empty — populated after first save)*
---
## Stats
- Total cards: 0
- Total bases (sessions): 0
- Wiki categories: 0
- Last save: —
Step I-5: Write Config File
Write the confirmed KB path (single line) to ~/.claude/skills/save-to-kb/.config:
/full/expanded/path/to/KB
Step I-6: Update Global CLAUDE.md
Read ~/.claude/CLAUDE.md. Find the <!-- LLM_BRAIN_BASES_BLOCK:BEGIN --> marker.
First-time setup — block does not exist: Append the following block at the end of the file:
<!-- LLM_BRAIN_BASES_BLOCK:BEGIN -->
## LLM-Brain-Bases 个人知识库
知识库路径：`{KB}`
（路径配置文件：`~/.claude/skills/save-to-kb/.config`）
### 规则 1：任务前查库
在开始以下类型的非平凡任务前，先查询知识库：
- 调试不熟悉的错误或行为
- 集成特定的库、API 或服务
- 系统设计或架构决策
- 涉及之前接触过的代码库或技术栈
操作步骤：
1. 读取 `{KB}/Claude.md`（主索引）
2. 从"场景快查"或"知识地图"定位相关 Wiki 和 Cards
3. 读取相关 Cards 后再开始工作
以下情况可跳过：纯机械操作、纯写作任务、与已有知识库完全无关的领域。
### 规则 2：对话结束自动保存
对话产出以下任何一项时，在对话末尾主动调用 `save-to-kb`：
- 调试发现了非显而易见的根因
- 发现了某 API/库/工具的文档未记录的行为
- 做出了有明确推理的架构或设计决策
- 总结出让重复任务明显更高效的工作流模式
- 验证了某种不该重蹈的失败路径
**判断标准**：刚加入项目的工程师在做类似任务前读到这张卡片会有收益吗？有则保存。
以下情况不保存：纯机械任务输出、标准教科书知识、一次性交付物、结论未明确的探索。
保存操作静默执行，无需向用户宣告（除非被问及）。
<!-- LLM_BRAIN_BASES_BLOCK:END -->
Path change — block already exists: Find the line starting with 知识库路径： inside the block and update the path value to the new {KB} path. Leave all other content unchanged.
Step I-7: Confirm
Report to user:
✓ Knowledge base initialized at: {KB}
✓ Directory structure created: Bases/ Cards/ Wiki/
✓ Master index written: Claude.md
✓ Config saved: ~/.claude/skills/save-to-kb/.config
✓ CLAUDE.md rules updated
Run `save-to-kb check` at any time to audit the knowledge base.
[REPLAY PROCEDURE]
Retroactively process historical session files that were never saved to the knowledge base.
Step R-1: Load Config
Read KB path from ~/.claude/skills/save-to-kb/.config. If missing → report "Not initialized. Run save-to-kb init first." and stop.
Step R-2: Locate Session Files
Claude Code stores session logs as JSONL files. Find the directory for the current working directory:
ls ~/.claude/projects/{project-dir}/*.jsonl
Run this bash command to list all session files with their dates:
for f in ~/.claude/projects/{project-dir}/*.jsonl; do
ts=$(grep -m1 '"timestamp"' "$f" | grep -o '"timestamp":"[^"]*"' | cut -d'"' -f4)
echo "$ts $f"
done | sort
Step R-3: Identify Unprocessed Sessions
Read all files in $KB/Bases/ and extract the session-id: field from each frontmatter.
Build a set of already-processed session IDs. A session is already processed if its JSONL filename (without .jsonl) matches any session-id in Bases/.
Sessions with no matching ID are candidates, regardless of date.
Report to user:
Found {N} session files. {M} already have Base records.
{K} unprocessed sessions:
[1] 2026-04-07 abc123.jsonl (~42 messages)
[2] 2026-04-06 def456.jsonl (~18 messages)
...
Process all? Or enter numbers to select (e.g. "1 3"):
Step R-4: Extract Conversation Content
For each selected session file, parse the JSONL to reconstruct the conversation:
jq -r 'select(.type == "user" or .type == "assistant")
| "\(.type | ascii_upcase): \(.message.content // "" | if type == "array" then .[0].text else . end)"' \
{session-file}.jsonl
Each message should be extracted with its role (user/assistant) and content text. Ignore metadata entries (permission-mode, file-history-snapshot, tool results, etc.).
Step R-5: Process Each Session
For each selected session, treat the extracted conversation as if it were the current session context and run the full [SAVE PROCEDURE] (Steps S-1 through S-6).
Key differences from normal save:
- The Base
date: should use the session's actual date (from timestamp), not today
- The Base
slug: should include the session date
- Check for duplicates against all existing Cards (not just today's)
Step R-6: Report
After processing all selected sessions:
Replay complete.
Sessions processed: {K}
Cards created: {N}
Cards updated: {M}
Bases written: {K}
[CHECK PROCEDURE]
Audit the entire knowledge base for broken links, inconsistencies, and data quality issues. Present findings and fix with user confirmation.
Step C-1: Load Config
Read ~/.claude/skills/save-to-kb/.config to get KB path.
If missing → report "Knowledge base not initialized. Run save-to-kb init first." and stop.
Step C-2: Scan Cards/
List all .md files in {KB}/Cards/. For each card, check:
| Check | Issue Type |
|---|
Required frontmatter fields present: title, slug, category, tags, scenario, created, updated, confidence | MISSING_FIELD |
slug matches the filename (without .md) | SLUG_MISMATCH |
category value corresponds to an existing Wiki/{category}.md file | BROKEN_CATEGORY |
Each entry in related: has a matching Cards/{slug}.md file | BROKEN_RELATED |
Each entry in sources: has a matching Bases/ file | BROKEN_SOURCE |
Required body sections present: ## What, ## Why It Matters, ## How | MISSING_SECTION |
confidence value is one of: high, medium, low | INVALID_CONFIDENCE |
Step C-3: Scan Bases/
List all .md files in {KB}/Bases/. For each base, check:
| Check | Issue Type |
|---|
Required frontmatter fields: date, session-title, slug | MISSING_FIELD |
Each entry in cards-created and cards-updated has matching Cards/ file | BROKEN_CARD_REF |
Step C-4: Scan Wiki/
List all .md files in {KB}/Wiki/. For each Wiki file, check:
| Check | Issue Type |
|---|
All [[Cards/slug]] wikilinks have matching files in Cards/ | BROKEN_WIKILINK |
All [[Wiki/category]] wikilinks have matching files in Wiki/ | BROKEN_WIKILINK |
card-count in frontmatter matches the actual number of [[Cards/ entries in the file | COUNT_MISMATCH |
Step C-5: Scan Claude.md
Read {KB}/Claude.md. Check:
| Check | Issue Type |
|---|
All [[Cards/slug]] references have matching files in Cards/ | BROKEN_WIKILINK |
All [[Wiki/category]] references have matching files in Wiki/ | BROKEN_WIKILINK |
Stats Total cards matches actual file count in Cards/ | STATS_MISMATCH |
Stats Total bases matches actual file count in Bases/ | STATS_MISMATCH |
Step C-6: Report Issues
Present a structured report:
Health Check Report — {YYYY-MM-DD}
====================================
Cards/ ({N} files scanned)
✓ card-a.md
⚠ [#1] card-b.md — BROKEN_RELATED: slug 'missing-card' not found in Cards/
⚠ [#2] card-c.md — MISSING_SECTION: '## Why It Matters' not found
Bases/ ({N} files scanned)
✓ 2026-04-09-session.md
⚠ [#3] 2026-04-08-old.md — BROKEN_CARD_REF: 'Cards/deleted-card' not found
Wiki/ ({N} files scanned)
✓ ai-tools.md
⚠ [#4] frontend.md — COUNT_MISMATCH: card-count=5 but 3 actual entries found
Claude.md
⚠ [#5] Stats: Total cards=10, actual=8
Found 5 issues.
Fix all? Enter "yes" to fix all, or "skip 2,4" to fix all except those numbered.
If no issues found:
✓ Health check passed — {N} cards, {N} bases, {N} wiki files. No issues found.
Step C-7: Apply Fixes
If user confirms, apply the following repair actions per issue type:
| Issue Type | Repair Action |
|---|
BROKEN_RELATED | Remove the broken slug from related: list |
BROKEN_SOURCE | Remove the broken entry from sources: list |
BROKEN_CARD_REF | Remove the broken entry from cards-created/cards-updated |
BROKEN_WIKILINK | Remove the broken [[link]] entry from the file |
BROKEN_CATEGORY | Ask user: create the missing Wiki file, or reassign card to existing category? |
SLUG_MISMATCH | Update slug: in frontmatter to match the filename |
MISSING_FIELD | Report field as missing, ask user what value to set, then write it |
MISSING_SECTION | Add the missing section with placeholder text: *(to be filled)* |
INVALID_CONFIDENCE | Set confidence: medium as default |
COUNT_MISMATCH | Recount actual [[Cards/ entries and update card-count |
STATS_MISMATCH | Recount actual files and update Stats numbers in Claude.md |
After fixes, report:
Fixed 4 of 5 issues. Skipped: #2 (manual action required).
Run `save-to-kb check` again to verify.
[SAVE PROCEDURE]
Save reusable knowledge from the current conversation into LLM-Brain-Bases.
Step S-0: Load Config
Read KB path from ~/.claude/skills/save-to-kb/.config.
Step S-1: Extract Knowledge Points
Review the full conversation. A card must be non-obvious and transferable — meaning someone encountering a similar situation in the future would genuinely benefit from reading it.
Knowledge falls into these saveable categories:
Technical
- A bug's non-obvious root cause and fix
- Undocumented or surprising API / library behavior
- Integration constraints between two systems or tools
- Non-obvious performance characteristics
Architecture & Design
- A design decision with clear reasoning that generalizes beyond this project
- A tradeoff conclusion worth remembering (why X was chosen over Y)
Product & Requirements
- A non-obvious insight about user behavior or intent revealed during development
- A requirement that turned out to mean something different than assumed — and why
- A product decision pattern that resolved ambiguity in a generalizable way
AI & Vibe Coding
- Non-obvious Claude / LLM behavior (prompt patterns, context limits, model quirks)
- Effective Skill, Hook, or tool configuration patterns for Claude Code
- Vibe coding workflow patterns that meaningfully improve AI-assisted development
- Lessons from AI agent coordination (task splitting, context management, handoff)
Hard rejections — do NOT save:
- Generic process templates or documentation structures
- Decisions or bugs entirely specific to one project with zero generalizable signal
- Mainstream best practices any competent engineer already knows
- Anything that belongs in CLAUDE.md rather than a reusable card
- Unresolved explorations with no confirmed conclusion
Judgment test: "Would someone hitting a similar situation in the future — whether a bug, a decision, a product question, or an AI interaction — be better equipped after reading this card?" If yes, save it.
Step S-2: Check for Duplicates
Before writing any card:
- Read
$KB/Claude.md — scan Knowledge Map and Scenario Quick-Lookup
- Check the relevant Wiki file for existing entries
- Search
$KB/Cards/ for files with similar slugs or title keywords
If a close match exists: update the existing card (add content, update updated: date, add new Base to sources:). Never create two cards for the same concept.
Step S-3: Write Cards
For each knowledge point, write $KB/Cards/{slug}.md.
Slug rules: lowercase, hyphens only, no special chars, ≤60 chars.
---
title: "{Title}"
slug: {slug}
category: {category}
tags: [{tag1}, {tag2}]
scenario: [{scenario1}, {scenario2}]
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
confidence: {high|medium|low}
related:
- {slug-of-related-card}
sources:
- "[[Bases/{YYYY-MM-DD}-{session-slug}]]"
---
## What
One sentence. What is this knowledge point. No hedging.
## Why It Matters
When does this matter. What breaks without it.
## How
Concrete procedure, pattern, command, or code.
## Gotchas
Edge cases, common mistakes. Omit section if none.
## Connections
Prose explaining how this relates to other concepts. Use [[wikilinks]] inline.
## References
- [[Bases/{YYYY-MM-DD}-{session-slug}]] — {one-line session description}
Category options (create new Wiki file if none fit):
frontend | backend | infra | ai-tools | workflow | debugging | architecture | knowledge-management | business
Confidence: high = confirmed; medium = partially tested; low = speculative.
Step S-4: Write the Base
First, get the current session ID by running:
ls -t ~/.claude/projects/$(echo $PWD | sed 's|/|-|g' | sed 's|^-||')/*.jsonl 2>/dev/null | head -1 | xargs basename | sed 's/.jsonl//'
If this fails or returns empty, use "unknown" as the session-id.
Write one Base file at $KB/Bases/{YYYY-MM-DD}-{session-slug}.md. Append-only — never edit after creation.
---
date: {YYYY-MM-DD}
session-id: {session-id-from-jsonl-filename}
session-title: "{Brief title}"
slug: {YYYY-MM-DD}-{session-slug}
project: "{Project name, or 'General'}"
tech: [{tech1}]
scenario: [{scenario1}]
cards-created:
- "[[Cards/{slug}]]"
cards-updated:
- "[[Cards/{slug}]]"
---
## Session Summary
2–4 sentences.
## Key Discoveries
- {Discovery} — why it matters
## Cards Written
- [[Cards/{slug}]] — description
Step S-5: Update Wiki Files
For each card's category, update $KB/Wiki/{category}.md:
- Add card under the correct tech-stack and scenario sections
- Add to Cross-Wiki Connections table if it bridges categories
- Increment
card-count in frontmatter
- Append to Recent Additions (keep last 20)
If the Wiki file doesn't exist, create it using references/wiki-template.md.
Step S-6: Update Master Index
Edit $KB/Claude.md:
- Update
Cards count in Knowledge Map for affected categories
- Add scenario entry-points to Scenario Quick-Lookup
- Add cross-domain cards to Cross-Domain Cards
- Prepend to Recently Added (keep last 10)
- Update Stats (total cards, bases, last save date)
What NOT to Save
- Task-specific outputs (delivered code, one-time reports)
- Preferences already in CLAUDE.md
- Pure reference facts (version numbers, general documentation)
- Incomplete explorations with no resolved conclusions
[FILE PROCEDURE]
Extract reusable knowledge cards from a file (PDF, Markdown, txt, or any readable format).
Step F-1: Load Config
Read KB path from ~/.claude/skills/save-to-kb/.config.
If missing → report "Not initialized. Run save-to-kb init first." and stop.
Step F-2: Get File Path
If invoked from menu selection: ask the user with AskUserQuestion:
"请输入文件路径（支持 PDF / Markdown / txt）："
If invoked with argument (save-to-kb file <path>): use the provided path directly.
Expand ~ to the absolute home directory. Verify the file exists before proceeding.
If file not found → report the resolved path and stop.
Step F-2b: Copy File to Knowledge Base
Copy the source file into {KB}/Sources/ to preserve a local reference:
mkdir -p "{KB}/Sources"
cp "{source-path}" "{KB}/Sources/{filename}"
If the file already exists at the destination, skip copying (do not overwrite).
Report: Source file copied to: {KB}/Sources/{filename}
Step F-3: Read File
Use the Read tool to read the file.
- For PDF: read all pages. If the PDF has more than 20 pages, read in batches of 20 pages.
- For text/markdown: read the full file.
Step F-4: Extract Knowledge Points
Analyze the file content. Apply the same filter as [SAVE PROCEDURE] Step S-1 — same categories (Technical, Architecture & Design, Product & Requirements, AI & Vibe Coding), same hard rejections, same judgment test.
Before extracting, report a summary to the user:
File: {filename}
Pages/size: {N} pages / {size}
Candidate knowledge areas identified:
- {area 1}
- {area 2}
...
Proceed to extract cards? (yes/no)
Step F-5: Check for Duplicates
Same as [SAVE PROCEDURE] Step S-2 — check Claude.md and existing Cards before writing.
Step F-6: Write Cards
Same format as [SAVE PROCEDURE] Step S-3.
In the sources: field, reference the Base written in Step F-7 (use the slug you plan to write).
Step F-7: Write the Base
Write one Base file at $KB/Bases/{YYYY-MM-DD}-{file-slug}.md.
Use session-id: file:{filename} to distinguish file-sourced bases from session-sourced bases.
Reference the local copy (Sources/{filename}) as the source, not the original path.
---
date: {YYYY-MM-DD}
session-id: "file:{filename}"
session-title: "{Brief description of file content}"
slug: {YYYY-MM-DD}-{file-slug}
project: "General"
tech: [{tech1}]
scenario: [{scenario1}]
cards-created:
- "[[Cards/{slug}]]"
cards-updated: []
---
## Source
File: `[[Sources/{filename}]]`
Original path: `{original-source-path}`
{2–4 sentences describing what the file covers and why it was imported.}
## Key Discoveries
- {Discovery} — why it matters
## Cards Written
- [[Cards/{slug}]] — description
Step F-8: Update Wiki and Master Index
Same as [SAVE PROCEDURE] Steps S-5 and S-6.
Step F-9: Report
File analysis complete.
Source: {filename}
Cards created: {N}
Cards updated: {M}
Base written: {slug}
