/librarian
Orchestrate high-level knowledge workflows using Librarian MCP tools.
Prerequisites
Librarian MCP server must be configured and running. Verify by checking that library_stats responds. If it fails, tell the user to run librarian-mcp --setup /path/to/vault and restart Claude.
Commands
/librarian ingest [path] Ingest a solution doc into the vault
/librarian import <file> Convert local document (PDF, DOCX, image) to vault markdown
/librarian from gmail <query> Import Gmail threads matching a search into the vault
/librarian from web <url> Import any web page into the vault as markdown
/librarian from twitter <url> Import an X/Twitter thread into the vault
/librarian from calendar [query] Import calendar events/meeting notes into the vault
/librarian from claude [session] Extract learnings from a Claude Code session into the vault
/librarian search <query> Deep search vault for prior art
/librarian connect [path] Find and apply missing wikilinks
/librarian daily [text] Append a learning to today's daily note
/librarian graph [note] Explore vault structure or a note's neighborhood
/librarian analyze Full vault analysis: god nodes, communities, viz, report
/librarian daydream [focus] Discover non-obvious connections across vault notes
/librarian status Vault health overview
If no command is given, show the usage summary above.
ingest
Purpose: Import a docs/solutions/ file (or any local markdown) into the vault, gaining auto-wikilinks and knowledge graph integration. This is the bridge between per-project documentation (like ce:compound output) and the persistent vault.
Behavior
Locate the source file:
- If
[path] is provided, use it directly
- If no path, scan
docs/solutions/ for the most recently modified .md file
- If
docs/solutions/ doesn't exist or is empty, tell the user and stop
Read the source file using the Read tool (local filesystem)
Determine vault destination:
- Parse the source file's YAML frontmatter for
category (or infer from parent directory name)
- Map to vault path:
Solutions/<category>/<filename>.md
- Categories map directly:
build-errors/ -> Solutions/build-errors/, etc.
Write to vault using library_write with the file content
library_write auto-links mentions of existing vault notes as [[wikilinks]]
- Report what links were auto-added
Run library_suggest_links on the newly written file
- Report any additional link suggestions found
- If suggestions exist, ask user if they want to apply them (re-write with links)
Report:
Ingested: docs/solutions/build-errors/vite-hmr-timeout.md
-> Solutions/build-errors/vite-hmr-timeout.md
Auto-linked: [[Vite]], [[HMR]], [[SvelteKit]]
Suggestions: 2 additional links available
The solution is now searchable and connected to your knowledge graph.
Batch mode
If the user says /librarian ingest all or /librarian ingest docs/solutions/:
- Find all
.md files in docs/solutions/ recursively
- Ingest each one, reporting progress
- Summarize: total ingested, total links added, any failures
import
Purpose: Convert any non-markdown document into markdown and store it in the vault. Uses Microsoft's MarkItDown for conversion, then auto-wikilinks the content.
Supported formats
PDF, DOCX, XLSX, PPTX, images (OCR), audio (transcription), HTML, CSV, JSON, XML, ZIP — anything MarkItDown supports.
Prerequisites
MarkItDown must be installed: pip install markitdown
If the user hasn't installed it, tell them and stop. Don't try to work around it.
Behavior
Determine source and destination:
<file> is the local filesystem path to the document
- If the user provides a vault destination path, use it
- Otherwise, infer from the file:
Imports/<filename-stem>.md
Call library_import with:
source_path: the local file path
library_path: the vault destination
title: filename stem or user-provided title
Report:
Imported: quarterly-report.pdf
-> Imports/quarterly-report.md (12,847 bytes, 2,103 words)
Auto-linked: [[Q1 Revenue]], [[Product Roadmap]]
Batch mode
If the user provides a directory path:
- List all non-markdown files in the directory
- Confirm with the user before proceeding
- Import each file, reporting progress
- Summarize: total imported, total words, failures
from
Purpose: Import content from external connectors (Gmail, web, Twitter/X, Google Calendar) into the vault. Each connector extracts content, converts it to a structured markdown note with frontmatter, writes it via library_write for auto-wikilinks, and integrates it into the knowledge graph.
All from subcommands follow the same output pattern:
- YAML frontmatter with
source, imported, type, and tags
- Structured markdown body
- Key takeaways or summary section
- Written via
library_write for auto-wikilinks
from gmail
Purpose: Import Gmail threads into the vault as structured notes. Useful for preserving important email conversations, research threads, or decisions.
Connector: Claude.ai Gmail MCP (search_threads, get_thread)
Behavior:
Search for threads:
- Call
search_threads with the user's query (same syntax as Gmail search bar)
- Examples:
"from:editor@publisher.com", "subject:manuscript feedback", "has:attachment newer_than:7d"
- Display results (subject, from, date, snippet) and let user pick which to import
- If only one result, proceed directly
Extract full thread:
- Call
get_thread with messageFormat: "FULL_CONTENT" for each selected thread
- Extract: participants, dates, subject, full message bodies
Build the vault note:
---
title: "<subject line>"
participants: ["sender@email.com", "recipient@email.com"]
source: gmail
thread_id: "<thread_id>"
imported: YYYY-MM-DD
type: email
tags:
- source/gmail
- <topic tags inferred from content>
---
# <subject line>
**Participants:** sender, recipient | **Date range:** YYYY-MM-DD to YYYY-MM-DD
---
## Message 1 — From: sender@email.com (YYYY-MM-DD HH:MM)
<message body>
## Message 2 — From: recipient@email.com (YYYY-MM-DD HH:MM)
<message body>
---
## Key points
<3-5 bullet point summary of the thread's decisions, action items, or key information>
Vault path: Emails/<YYYY>/<slugified-subject>.md
Write via library_write, report auto-linked notes.
Report:
Imported: "Re: Manuscript feedback round 2" (5 messages)
-> Emails/2026/manuscript-feedback-round-2.md
Auto-linked: [[Publishing]], [[Draft Review]]
Key points: 3 action items extracted
from web
Purpose: Import any web page into the vault as clean markdown. Uses Exa or Tavily for extraction.
Connectors: Exa (web_fetch_exa) preferred, Tavily (tavily_extract) as fallback.
Behavior:
Extract the page:
- Try
web_fetch_exa with the URL first (returns clean markdown)
- If Exa fails or returns insufficient content, fall back to
tavily_extract with extract_depth: "advanced"
- If both fail, tell the user and stop
Build the vault note:
---
title: "<page title>"
url: "<source URL>"
author: "<author if detectable>"
imported: YYYY-MM-DD
type: article
tags:
- source/web
- <topic tags inferred from content>
---
# <page title>
**Source:** [<domain>](<url>) | **Imported:** YYYY-MM-DD
---
<cleaned markdown content>
---
## Key takeaways
<3-5 bullet point summary>
Vault path: Web/<YYYY>/<slugified-title>.md
Write via library_write, report auto-linked notes.
Batch mode: If given multiple URLs, process each sequentially.
from twitter
Purpose: Import an X/Twitter thread into the vault.
Connector: bird CLI via Bash (from agent-reach tooling).
Behavior:
Extract the thread:
- Run:
bird thread <url> via Bash
- If URL is a single tweet (not a thread), run:
bird read <url>
- If
bird fails, fall back: try tavily_extract on the URL, or ask user to paste text
Parse the output:
- Extract: author handle, date, individual tweets
- Identify the thread topic from the first tweet
Build the vault note:
---
title: "<thread topic summary>"
author: "@handle"
source: "<original URL>"
imported: YYYY-MM-DD
type: thread
tags:
- source/twitter
- <topic tags inferred from content>
---
# <thread topic summary>
**Author:** [@handle](<profile url>) | **Date:** YYYY-MM-DD | **[Original thread](<url>)**
---
<thread content, preserving tweet boundaries with --- separators>
---
## Key takeaways
<3-5 bullet point summary of the thread's main points>
Vault path: Threads/<YYYY>/<slugified-topic>.md
Write via library_write, report auto-linked notes.
Batch mode: If given multiple URLs, process each sequentially.
from calendar
Purpose: Import calendar events into the vault, useful for meeting notes, event context, or archiving.
Connector: Claude.ai Google Calendar MCP (gcal_list_events, gcal_get_event)
Behavior:
Find events:
- If
[query] is provided, use it as a search term via gcal_list_events with q parameter
- If no query, list today's events via
gcal_list_events with timeMin/timeMax set to today
- Display results and let user pick which to import
Get full event details:
- Call
gcal_get_event for each selected event
- Extract: title, date/time, attendees, description, location, attachments
Build the vault note:
---
title: "<event summary>"
date: YYYY-MM-DD
attendees: ["person1@email.com", "person2@email.com"]
source: google-calendar
event_id: "<event_id>"
imported: YYYY-MM-DD
type: meeting
tags:
- source/calendar
- <topic tags inferred from content>
---
# <event summary>
**Date:** YYYY-MM-DD HH:MM - HH:MM | **Location:** <location>
**Attendees:** person1, person2
---
## Event description
<description from the calendar event>
---
## Notes
<placeholder for user to fill in meeting notes>
Vault path: Meetings/<YYYY>/<YYYY-MM-DD>-<slugified-title>.md
Write via library_write, report auto-linked notes.
Batch mode: If importing a date range, ask user: /librarian from calendar --week imports all events from the current week.
from claude
Purpose: Extract key learnings, decisions, and solutions from a Claude Code session transcript and archive them in the vault. Closes the knowledge loop — your conversations become searchable vault knowledge.
Data source: Local JSONL files at ~/.claude/projects/<project>/<session-id>.jsonl
Behavior:
Find the session:
- If
[session] is a UUID, use it directly
- If
[session] is a project name or path fragment, find matching project directory under ~/.claude/projects/
- If no argument, list the 10 most recent sessions across all projects with date, size, project, and first user message as topic hint. Let the user pick.
- To list sessions: use Bash to scan
~/.claude/projects/*/ for .jsonl files, sort by mtime descending
Parse the JSONL transcript:
- Read the file using the Read tool (it's local plaintext)
- Each line is a JSON object with a
type field: user, assistant, system, file-history-snapshot, permission-mode, attachment
- Focus on
user and assistant messages:
user messages have message.content (string or array of {type: "text", text: "..."} blocks)
assistant messages have message.content as array of blocks: thinking, text, tool_use
- Extract only
text blocks from assistant messages (skip thinking and tool_use)
- Skip
system, file-history-snapshot, permission-mode, and attachment types
Synthesize the session into a vault note:
- Read through the conversation and extract:
- Topic: What was the session about? (infer from first user message and overall flow)
- Decisions made: Architecture choices, approach selections, trade-offs resolved
- Problems solved: Bugs fixed, issues resolved, with root causes
- Key artifacts: Files created/modified, commands established
- Open items: Things deferred, noted for future, or left incomplete
- Be selective — not every message is worth archiving. Focus on knowledge that compounds.
Build the vault note:
---
title: "<session topic summary>"
project: "<project path>"
session_id: "<uuid>"
date: YYYY-MM-DD
source: claude-code
imported: YYYY-MM-DD
type: session
tags:
- source/claude-code
- <project tag>
- <topic tags inferred from content>
---
# <session topic summary>
**Project:** <project path> | **Date:** YYYY-MM-DD | **Messages:** N
---
## Decisions
- <decision 1 — what was chosen and why>
- <decision 2>
## Solutions
### <problem 1 title>
**Problem:** <what was wrong>
**Root cause:** <why>
**Fix:** <what was done>
## Artifacts
- Created: `path/to/file.md`
- Modified: `src/main.rs` — added skill installation to --setup
## Open items
- <anything deferred or left for future sessions>
Vault path: Sessions/<YYYY>/<YYYY-MM-DD>-<slugified-topic>.md
Write via library_write, report auto-linked notes.
Report:
Imported session: "Librarian skill + MCP connector integration"
-> Sessions/2026/2026-04-11-librarian-skill-mcp-connectors.md
Auto-linked: [[librarian-mcp]], [[ce-compound]], [[Obsidian]]
Extracted: 4 decisions, 2 solutions, 1 open item
Tips for from claude
- Current session: You can import the current session — just use the session ID from the JSONL filename. The transcript is written incrementally, so it includes everything up to now.
- Pairs with session-close: Run
/session-close to update project memory, then /librarian from claude to archive the knowledge in the vault.
- Large sessions: For sessions with 100+ messages, focus extraction on the second half where solutions typically land. Skip early exploration/dead-ends unless they contain useful "what didn't work" context.
- Privacy: Session transcripts may contain API keys, passwords, or sensitive data that was read by tools. The synthesis step should never copy raw credentials — only extract the conceptual knowledge.
search
Purpose: Deep search across the vault for prior art on a topic. More than a raw search -- synthesizes results into actionable context.
Behavior
Call library_search with the query (limit: 10)
For the top 3-5 results, call library_read to get full content
Synthesize a brief summary:
- What the vault knows about this topic
- Which notes are most relevant (with paths)
- Key insights or solutions found
- Related tags discovered
Call library_traverse from the most relevant result (depth: 1) to find connected notes the search might have missed
Report:
Vault knowledge on "<query>":
Direct matches (N files):
- Solutions/build-errors/vite-hmr-timeout.md — HMR fix for Tauri apps
- Research/Deep Dives/vite-internals.md — Vite architecture notes
Key insights:
- [synthesized takeaways from the matched content]
Connected notes (via graph):
- [[SvelteKit]] (1 hop from vite-hmr-timeout)
Tags: #build, #vite, #frontend
connect
Purpose: Find unlinked mentions across the vault and optionally apply them. Strengthens the knowledge graph.
Behavior
If [path] is provided:
- Run
library_suggest_links on that specific file
- Show suggestions
- Ask user to confirm before applying
If no path (vault-wide scan):
- Call
library_stats to get orphan notes
- For each orphan (up to 10), run
library_suggest_links
- Report which orphans could be connected and how
- Ask user before applying any changes
Applying links:
- Read the file via
library_read
- Write it back via
library_write (which auto-links on write)
- Report the links that were added
daily
Purpose: Append a learning, note, or reflection to today's daily note.
Behavior
If [text] is provided:
- Call
library_daily with append: <text>
- Done
If no text:
- Summarize the current conversation's key outcomes (what was solved, what was learned, what decisions were made)
- Format as a bullet list under a
## Learnings section
- Call
library_daily with the formatted summary
- Show what was appended
Always report the daily note path (e.g., Journal/2026/2026-04-11.md)
graph
Purpose: Explore vault structure or a specific note's neighborhood in the knowledge graph.
Behavior
If [note] is provided:
- Call
library_traverse with start: <note>, depth: 2
- Call
library_links on the note for backlinks/outgoing detail
- Render a text-based neighborhood map:
Topic Neighborhood: "Vite"
[[SvelteKit]] ---> [[Vite]] <--- [[HMR]]
|
v
[[Tauri Build]]
Backlinks (3): SvelteKit, HMR, Frontend Tooling
Outgoing (2): Tauri Build, ESBuild
2 hops: 8 notes reachable
If no note (vault-wide):
- Call
library_stats for overview
- Call
library_graph_analysis for structure
- Report: file count, word count, connected components, hub notes, bridge notes, orphan count
- Highlight the top 5 hub notes (most connected)
- Flag orphans that might need linking
analyze
Purpose: Run full vault intelligence analysis — community detection, structural importance ranking (god nodes), cross-community bridge detection, and interactive visualization. Generates two artifacts in the vault root.
Behavior
Call library_report (no params, uses default output path)
- Runs the full pipeline: graph build → community detection → betweenness centrality → PageRank → surprising connections
- Writes
GRAPH_REPORT.md to vault root
- Report includes: god nodes table, community breakdown, surprising cross-topic connections, suggested questions
Call library_visualize (no params, uses default output path)
- Generates self-contained interactive HTML with force-directed graph layout
- Nodes colored by community, sized by structural importance
- Click to inspect, search to filter
- Writes
GRAPH_VIZ.html to vault root
Report:
Vault analysis complete.
Report: GRAPH_REPORT.md
- 847 notes, 2,341 links, 12 communities, 43 orphans
- God nodes: [[Claude]], [[Obsidian]], [[Knowledge Management]]
- 8 surprising cross-community connections found
Visualization: GRAPH_VIZ.html
- Open in browser to explore the interactive graph
Next steps:
- /librarian connect — link orphan notes into the graph
- /librarian from claude — archive this session's learnings
What the report contains
| Section |
Content |
| God Nodes |
Top 10 structurally important notes ranked by composite score (degree + betweenness centrality + PageRank) |
| Communities |
Topic clusters with member lists, detected by modularity optimization |
| Surprising Connections |
High-betweenness edges that bridge different communities — the cross-topic links |
| Suggested Questions |
5 questions the graph is uniquely positioned to answer |
daydream
Purpose: Discover non-obvious connections between vault notes using multi-agent combinatorial exploration. Inspired by Gwern's LLM Daydreaming essay and glebis's Daydream skill — implements the brain's "default mode network" for your vault.
How it works
The command pairs random notes and asks parallel sub-agents to find surprising connections, then filters with critics. Only genuinely novel, coherent, and useful insights survive.
Behavior
Sample notes from the vault:
- Call
library_list to get all note paths
- Call
library_read on a random sample of 50 notes
- Weight toward recent notes (by date frontmatter or filename)
- If
[focus] provided: use library_search to find focus-relevant notes, pair them with random notes from outside that cluster
Generate random pairs:
- Create 50 unique note pairs from the sample
- Check
Daydreams/history.json (via library_read) for already-processed pairs
- Skip duplicates, proceed with remaining pairs
Synthesize connections (parallel sub-agents):
- Launch 10 parallel sub-agents (Sonnet model), each processing 5 pairs
- Each agent reads both notes and explores:
- Abstract analogies between concepts
- Similar problems or solutions in different domains
- Potential combinations or hybrid ideas
- Revealing contradictions or tensions
- Each agent returns structured results: title, connection description, source notes, reasoning
Critique and filter (parallel sub-agents):
- Launch 10 parallel critic sub-agents (Haiku model)
- Each critic scores connections on three dimensions (1-10 each):
- Novelty: Is this surprising and non-obvious?
- Coherence: Is the reasoning logical and well-grounded?
- Usefulness: Could this lead to new work, insights, or decisions?
- Accept only connections with average score >= 7.0
Write accepted insights to vault:
- For each accepted insight, call
library_write to create Daydreams/<YYYYMMDD>-<slug>.md
- Frontmatter includes: title, source_notes (paths), scores (novelty/coherence/usefulness), date, tags (daydream, source topics)
- Body includes: the connection description, reasoning, and source note excerpts
library_write auto-wikilinks the insight into the knowledge graph
Update history:
- Read or create
Daydreams/history.json via library_read/library_write
- Add all processed pairs (accepted or rejected) to prevent re-processing
- Track: pair hashes, dates, accept/reject status
Report:
Daydream complete.
Processed: 42 pairs (8 skipped as duplicates)
Accepted: 7 insights (17% acceptance rate)
Insights written:
- Daydreams/20260411-authentication-as-trust-boundary.md
"Authentication patterns in the auth module mirror trust boundary
concepts from the game theory notes — both define threshold functions."
- Daydreams/20260411-vite-hmr-and-neural-plasticity.md
...
Run /librarian analyze to see how these integrate into the knowledge graph.
Cost
Approximately $0.40-0.50 per run (50 pairs) using Sonnet for synthesis and Haiku for critique.
Tips
- Run weekly or after adding substantial new content to the vault
- Use
[focus] to explore connections around a specific topic: /librarian daydream authentication
- Daydream insights compound — they become seeds for future runs, creating a discovery flywheel
- Run
/librarian analyze after daydream to see how insights integrate into the graph
status
Purpose: Quick vault health check.
Behavior
- Call
library_stats
- Report in compact format:
Vault: The Labyrinth
Files: 1,247 | Words: 389,102 | Links: 3,891 | Tags: 156
Orphans: 23 (run /librarian connect to fix)
Solutions: 45 ingested
Last daily: 2026-04-11
Tool Reference
This skill orchestrates these Librarian MCP tools:
| Tool |
Used by |
library_search |
search, daydream (focus mode) |
library_read |
search, ingest, connect, daydream |
library_write |
ingest, from *, connect, daydream |
library_list |
ingest (scan docs/solutions/), import (batch), daydream |
library_links |
graph |
library_tags |
search |
library_metadata |
ingest (read frontmatter) |
library_daily |
daily |
library_stats |
status, graph |
library_suggest_links |
ingest, connect |
library_traverse |
search, graph |
library_shortest_path |
graph (on request) |
library_graph_analysis |
graph (vault-wide) |
library_cluster |
analyze, graph |
library_visualize |
analyze |
library_report |
analyze |
library_import |
import (MarkItDown conversion) |
Claude.ai MCP connectors
| Connector |
Tools used |
Used by |
| Gmail |
search_threads, get_thread |
from gmail |
| Exa |
web_fetch_exa |
from web |
| Tavily |
tavily_extract |
from web (fallback), from twitter (fallback) |
| Google Calendar |
gcal_list_events, gcal_get_event |
from calendar |
Local data sources
| Source |
Location |
Used by |
| Claude Code sessions |
~/.claude/projects/<project>/<session>.jsonl |
from claude |
External CLI tools
| Tool |
Used by |
Install |
markitdown |
import |
pip install markitdown |
bird |
from twitter |
Via agent-reach / bird CLI |
Integration with ce:compound
The primary integration pattern:
/ce:compound # Documents a solution in docs/solutions/
/librarian ingest # Imports latest solution into vault (auto-wikilinked)
This bridges project-scoped documentation into the persistent, cross-project knowledge graph. The next time you /librarian search for a similar problem, the solution surfaces with full graph context.
1---2name: librarian3description: Orchestrate vault knowledge workflows using the Librarian MCP server. Ingest solutions, search prior art, explore the knowledge graph, log daily learnings.4argument-hint: "<command> [args]"5metadata:6 source: https://skillmd.com/skills/ngmeyer/librarian7---89# /librarian1011Orchestrate high-level knowledge workflows using Librarian MCP tools.1213## Prerequisites1415Librarian MCP server must be configured and running. Verify by checking that `library_stats` responds. If it fails, tell the user to run `librarian-mcp --setup /path/to/vault` and restart Claude.1617## Commands1819```20/librarian ingest [path] Ingest a solution doc into the vault21/librarian import <file> Convert local document (PDF, DOCX, image) to vault markdown22/librarian from gmail <query> Import Gmail threads matching a search into the vault23/librarian from web <url> Import any web page into the vault as markdown24/librarian from twitter <url> Import an X/Twitter thread into the vault25/librarian from calendar [query] Import calendar events/meeting notes into the vault26/librarian from claude [session] Extract learnings from a Claude Code session into the vault27/librarian search <query> Deep search vault for prior art28/librarian connect [path] Find and apply missing wikilinks29/librarian daily [text] Append a learning to today's daily note30/librarian graph [note] Explore vault structure or a note's neighborhood31/librarian analyze Full vault analysis: god nodes, communities, viz, report32/librarian daydream [focus] Discover non-obvious connections across vault notes33/librarian status Vault health overview34```3536If no command is given, show the usage summary above.3738---3940## ingest4142**Purpose:** Import a `docs/solutions/` file (or any local markdown) into the vault, gaining auto-wikilinks and knowledge graph integration. This is the bridge between per-project documentation (like ce:compound output) and the persistent vault.4344### Behavior45461. **Locate the source file:**47 - If `[path]` is provided, use it directly48 - If no path, scan `docs/solutions/` for the most recently modified `.md` file49 - If `docs/solutions/` doesn't exist or is empty, tell the user and stop50512. **Read the source file** using the Read tool (local filesystem)52533. **Determine vault destination:**54 - Parse the source file's YAML frontmatter for `category` (or infer from parent directory name)55 - Map to vault path: `Solutions/<category>/<filename>.md`56 - Categories map directly: `build-errors/` -> `Solutions/build-errors/`, etc.57584. **Write to vault** using `library_write` with the file content59 - `library_write` auto-links mentions of existing vault notes as `[[wikilinks]]`60 - Report what links were auto-added61625. **Run `library_suggest_links`** on the newly written file63 - Report any additional link suggestions found64 - If suggestions exist, ask user if they want to apply them (re-write with links)65666. **Report:**67 ```68 Ingested: docs/solutions/build-errors/vite-hmr-timeout.md69 -> Solutions/build-errors/vite-hmr-timeout.md7071 Auto-linked: [[Vite]], [[HMR]], [[SvelteKit]]72 Suggestions: 2 additional links available7374 The solution is now searchable and connected to your knowledge graph.75 ```7677### Batch mode7879If the user says `/librarian ingest all` or `/librarian ingest docs/solutions/`:80- Find all `.md` files in `docs/solutions/` recursively81- Ingest each one, reporting progress82- Summarize: total ingested, total links added, any failures8384---8586## import8788**Purpose:** Convert any non-markdown document into markdown and store it in the vault. Uses Microsoft's MarkItDown for conversion, then auto-wikilinks the content.8990### Supported formats9192PDF, DOCX, XLSX, PPTX, images (OCR), audio (transcription), HTML, CSV, JSON, XML, ZIP — anything MarkItDown supports.9394### Prerequisites9596MarkItDown must be installed: `pip install markitdown`9798If the user hasn't installed it, tell them and stop. Don't try to work around it.99100### Behavior1011021. **Determine source and destination:**103 - `<file>` is the local filesystem path to the document104 - If the user provides a vault destination path, use it105 - Otherwise, infer from the file: `Imports/<filename-stem>.md`1061072. **Call `library_import`** with:108 - `source_path`: the local file path109 - `library_path`: the vault destination110 - `title`: filename stem or user-provided title1111123. **Report:**113 ```114 Imported: quarterly-report.pdf115 -> Imports/quarterly-report.md (12,847 bytes, 2,103 words)116117 Auto-linked: [[Q1 Revenue]], [[Product Roadmap]]118 ```119120### Batch mode121122If the user provides a directory path:123- List all non-markdown files in the directory124- Confirm with the user before proceeding125- Import each file, reporting progress126- Summarize: total imported, total words, failures127128---129130## from131132**Purpose:** Import content from external connectors (Gmail, web, Twitter/X, Google Calendar) into the vault. Each connector extracts content, converts it to a structured markdown note with frontmatter, writes it via `library_write` for auto-wikilinks, and integrates it into the knowledge graph.133134All `from` subcommands follow the same output pattern:135- YAML frontmatter with `source`, `imported`, `type`, and `tags`136- Structured markdown body137- Key takeaways or summary section138- Written via `library_write` for auto-wikilinks139140### from gmail141142**Purpose:** Import Gmail threads into the vault as structured notes. Useful for preserving important email conversations, research threads, or decisions.143144**Connector:** Claude.ai Gmail MCP (`search_threads`, `get_thread`)145146**Behavior:**1471481. **Search for threads:**149 - Call `search_threads` with the user's query (same syntax as Gmail search bar)150 - Examples: `"from:editor@publisher.com"`, `"subject:manuscript feedback"`, `"has:attachment newer_than:7d"`151 - Display results (subject, from, date, snippet) and let user pick which to import152 - If only one result, proceed directly1531542. **Extract full thread:**155 - Call `get_thread` with `messageFormat: "FULL_CONTENT"` for each selected thread156 - Extract: participants, dates, subject, full message bodies1571583. **Build the vault note:**159 ```markdown160 ---161 title: "<subject line>"162 participants: ["sender@email.com", "recipient@email.com"]163 source: gmail164 thread_id: "<thread_id>"165 imported: YYYY-MM-DD166 type: email167 tags:168 - source/gmail169 - <topic tags inferred from content>170 ---171172 # <subject line>173174 **Participants:** sender, recipient | **Date range:** YYYY-MM-DD to YYYY-MM-DD175176 ---177178 ## Message 1 — From: sender@email.com (YYYY-MM-DD HH:MM)179180 <message body>181182 ## Message 2 — From: recipient@email.com (YYYY-MM-DD HH:MM)183184 <message body>185186 ---187188 ## Key points189190 <3-5 bullet point summary of the thread's decisions, action items, or key information>191 ```1921934. **Vault path:** `Emails/<YYYY>/<slugified-subject>.md`1941955. **Write via `library_write`**, report auto-linked notes.1961976. **Report:**198 ```199 Imported: "Re: Manuscript feedback round 2" (5 messages)200 -> Emails/2026/manuscript-feedback-round-2.md201202 Auto-linked: [[Publishing]], [[Draft Review]]203 Key points: 3 action items extracted204 ```205206### from web207208**Purpose:** Import any web page into the vault as clean markdown. Uses Exa or Tavily for extraction.209210**Connectors:** Exa (`web_fetch_exa`) preferred, Tavily (`tavily_extract`) as fallback.211212**Behavior:**2132141. **Extract the page:**215 - Try `web_fetch_exa` with the URL first (returns clean markdown)216 - If Exa fails or returns insufficient content, fall back to `tavily_extract` with `extract_depth: "advanced"`217 - If both fail, tell the user and stop2182192. **Build the vault note:**220 ```markdown221 ---222 title: "<page title>"223 url: "<source URL>"224 author: "<author if detectable>"225 imported: YYYY-MM-DD226 type: article227 tags:228 - source/web229 - <topic tags inferred from content>230 ---231232 # <page title>233234 **Source:** [<domain>](<url>) | **Imported:** YYYY-MM-DD235236 ---237238 <cleaned markdown content>239240 ---241242 ## Key takeaways243244 <3-5 bullet point summary>245 ```2462473. **Vault path:** `Web/<YYYY>/<slugified-title>.md`2482494. **Write via `library_write`**, report auto-linked notes.2502515. **Batch mode:** If given multiple URLs, process each sequentially.252253### from twitter254255**Purpose:** Import an X/Twitter thread into the vault.256257**Connector:** `bird` CLI via Bash (from agent-reach tooling).258259**Behavior:**2602611. **Extract the thread:**262 - Run: `bird thread <url>` via Bash263 - If URL is a single tweet (not a thread), run: `bird read <url>`264 - If `bird` fails, fall back: try `tavily_extract` on the URL, or ask user to paste text2652662. **Parse the output:**267 - Extract: author handle, date, individual tweets268 - Identify the thread topic from the first tweet2692703. **Build the vault note:**271 ```markdown272 ---273 title: "<thread topic summary>"274 author: "@handle"275 source: "<original URL>"276 imported: YYYY-MM-DD277 type: thread278 tags:279 - source/twitter280 - <topic tags inferred from content>281 ---282283 # <thread topic summary>284285 **Author:** [@handle](<profile url>) | **Date:** YYYY-MM-DD | **[Original thread](<url>)**286287 ---288289 <thread content, preserving tweet boundaries with --- separators>290291 ---292293 ## Key takeaways294295 <3-5 bullet point summary of the thread's main points>296 ```2972984. **Vault path:** `Threads/<YYYY>/<slugified-topic>.md`2993005. **Write via `library_write`**, report auto-linked notes.3013026. **Batch mode:** If given multiple URLs, process each sequentially.303304### from calendar305306**Purpose:** Import calendar events into the vault, useful for meeting notes, event context, or archiving.307308**Connector:** Claude.ai Google Calendar MCP (`gcal_list_events`, `gcal_get_event`)309310**Behavior:**3113121. **Find events:**313 - If `[query]` is provided, use it as a search term via `gcal_list_events` with `q` parameter314 - If no query, list today's events via `gcal_list_events` with `timeMin`/`timeMax` set to today315 - Display results and let user pick which to import3163172. **Get full event details:**318 - Call `gcal_get_event` for each selected event319 - Extract: title, date/time, attendees, description, location, attachments3203213. **Build the vault note:**322 ```markdown323 ---324 title: "<event summary>"325 date: YYYY-MM-DD326 attendees: ["person1@email.com", "person2@email.com"]327 source: google-calendar328 event_id: "<event_id>"329 imported: YYYY-MM-DD330 type: meeting331 tags:332 - source/calendar333 - <topic tags inferred from content>334 ---335336 # <event summary>337338 **Date:** YYYY-MM-DD HH:MM - HH:MM | **Location:** <location>339 **Attendees:** person1, person2340341 ---342343 ## Event description344345 <description from the calendar event>346347 ---348349 ## Notes350351 <placeholder for user to fill in meeting notes>352 ```3533544. **Vault path:** `Meetings/<YYYY>/<YYYY-MM-DD>-<slugified-title>.md`3553565. **Write via `library_write`**, report auto-linked notes.3573586. **Batch mode:** If importing a date range, ask user: `/librarian from calendar --week` imports all events from the current week.359360### from claude361362**Purpose:** Extract key learnings, decisions, and solutions from a Claude Code session transcript and archive them in the vault. Closes the knowledge loop — your conversations become searchable vault knowledge.363364**Data source:** Local JSONL files at `~/.claude/projects/<project>/<session-id>.jsonl`365366**Behavior:**3673681. **Find the session:**369 - If `[session]` is a UUID, use it directly370 - If `[session]` is a project name or path fragment, find matching project directory under `~/.claude/projects/`371 - If no argument, list the 10 most recent sessions across all projects with date, size, project, and first user message as topic hint. Let the user pick.372 - To list sessions: use Bash to scan `~/.claude/projects/*/` for `.jsonl` files, sort by mtime descending3733742. **Parse the JSONL transcript:**375 - Read the file using the Read tool (it's local plaintext)376 - Each line is a JSON object with a `type` field: `user`, `assistant`, `system`, `file-history-snapshot`, `permission-mode`, `attachment`377 - Focus on `user` and `assistant` messages:378 - `user` messages have `message.content` (string or array of `{type: "text", text: "..."}` blocks)379 - `assistant` messages have `message.content` as array of blocks: `thinking`, `text`, `tool_use`380 - Extract only `text` blocks from assistant messages (skip `thinking` and `tool_use`)381 - Skip `system`, `file-history-snapshot`, `permission-mode`, and `attachment` types3823833. **Synthesize the session into a vault note:**384 - Read through the conversation and extract:385 - **Topic:** What was the session about? (infer from first user message and overall flow)386 - **Decisions made:** Architecture choices, approach selections, trade-offs resolved387 - **Problems solved:** Bugs fixed, issues resolved, with root causes388 - **Key artifacts:** Files created/modified, commands established389 - **Open items:** Things deferred, noted for future, or left incomplete390 - Be selective — not every message is worth archiving. Focus on knowledge that compounds.3913924. **Build the vault note:**393 ```markdown394 ---395 title: "<session topic summary>"396 project: "<project path>"397 session_id: "<uuid>"398 date: YYYY-MM-DD399 source: claude-code400 imported: YYYY-MM-DD401 type: session402 tags:403 - source/claude-code404 - <project tag>405 - <topic tags inferred from content>406 ---407408 # <session topic summary>409410 **Project:** <project path> | **Date:** YYYY-MM-DD | **Messages:** N411412 ---413414 ## Decisions415416 - <decision 1 — what was chosen and why>417 - <decision 2>418419 ## Solutions420421 ### <problem 1 title>422 **Problem:** <what was wrong>423 **Root cause:** <why>424 **Fix:** <what was done>425426 ## Artifacts427428 - Created: `path/to/file.md`429 - Modified: `src/main.rs` — added skill installation to --setup430431 ## Open items432433 - <anything deferred or left for future sessions>434 ```4354365. **Vault path:** `Sessions/<YYYY>/<YYYY-MM-DD>-<slugified-topic>.md`4374386. **Write via `library_write`**, report auto-linked notes.4394407. **Report:**441 ```442 Imported session: "Librarian skill + MCP connector integration"443 -> Sessions/2026/2026-04-11-librarian-skill-mcp-connectors.md444445 Auto-linked: [[librarian-mcp]], [[ce-compound]], [[Obsidian]]446 Extracted: 4 decisions, 2 solutions, 1 open item447 ```448449### Tips for from claude450451- **Current session:** You can import the current session — just use the session ID from the JSONL filename. The transcript is written incrementally, so it includes everything up to now.452- **Pairs with session-close:** Run `/session-close` to update project memory, then `/librarian from claude` to archive the knowledge in the vault.453- **Large sessions:** For sessions with 100+ messages, focus extraction on the second half where solutions typically land. Skip early exploration/dead-ends unless they contain useful "what didn't work" context.454- **Privacy:** Session transcripts may contain API keys, passwords, or sensitive data that was read by tools. The synthesis step should never copy raw credentials — only extract the conceptual knowledge.455456---457458## search459460**Purpose:** Deep search across the vault for prior art on a topic. More than a raw search -- synthesizes results into actionable context.461462### Behavior4634641. **Call `library_search`** with the query (limit: 10)4654662. **For the top 3-5 results**, call `library_read` to get full content4674683. **Synthesize** a brief summary:469 - What the vault knows about this topic470 - Which notes are most relevant (with paths)471 - Key insights or solutions found472 - Related tags discovered4734744. **Call `library_traverse`** from the most relevant result (depth: 1) to find connected notes the search might have missed4754765. **Report:**477 ```478 Vault knowledge on "<query>":479480 Direct matches (N files):481 - Solutions/build-errors/vite-hmr-timeout.md — HMR fix for Tauri apps482 - Research/Deep Dives/vite-internals.md — Vite architecture notes483484 Key insights:485 - [synthesized takeaways from the matched content]486487 Connected notes (via graph):488 - [[SvelteKit]] (1 hop from vite-hmr-timeout)489490 Tags: #build, #vite, #frontend491 ```492493---494495## connect496497**Purpose:** Find unlinked mentions across the vault and optionally apply them. Strengthens the knowledge graph.498499### Behavior5005011. **If `[path]` is provided:**502 - Run `library_suggest_links` on that specific file503 - Show suggestions504 - Ask user to confirm before applying5055062. **If no path (vault-wide scan):**507 - Call `library_stats` to get orphan notes508 - For each orphan (up to 10), run `library_suggest_links`509 - Report which orphans could be connected and how510 - Ask user before applying any changes5115123. **Applying links:**513 - Read the file via `library_read`514 - Write it back via `library_write` (which auto-links on write)515 - Report the links that were added516517---518519## daily520521**Purpose:** Append a learning, note, or reflection to today's daily note.522523### Behavior5245251. **If `[text]` is provided:**526 - Call `library_daily` with `append: <text>`527 - Done5285292. **If no text:**530 - Summarize the current conversation's key outcomes (what was solved, what was learned, what decisions were made)531 - Format as a bullet list under a `## Learnings` section532 - Call `library_daily` with the formatted summary533 - Show what was appended5345353. **Always report** the daily note path (e.g., `Journal/2026/2026-04-11.md`)536537---538539## graph540541**Purpose:** Explore vault structure or a specific note's neighborhood in the knowledge graph.542543### Behavior5445451. **If `[note]` is provided:**546 - Call `library_traverse` with `start: <note>`, `depth: 2`547 - Call `library_links` on the note for backlinks/outgoing detail548 - Render a text-based neighborhood map:549 ```550 Topic Neighborhood: "Vite"551552 [[SvelteKit]] ---> [[Vite]] <--- [[HMR]]553 |554 v555 [[Tauri Build]]556557 Backlinks (3): SvelteKit, HMR, Frontend Tooling558 Outgoing (2): Tauri Build, ESBuild559 2 hops: 8 notes reachable560 ```5615622. **If no note (vault-wide):**563 - Call `library_stats` for overview564 - Call `library_graph_analysis` for structure565 - Report: file count, word count, connected components, hub notes, bridge notes, orphan count566 - Highlight the top 5 hub notes (most connected)567 - Flag orphans that might need linking568569---570571## analyze572573**Purpose:** Run full vault intelligence analysis — community detection, structural importance ranking (god nodes), cross-community bridge detection, and interactive visualization. Generates two artifacts in the vault root.574575### Behavior5765771. **Call `library_report`** (no params, uses default output path)578 - Runs the full pipeline: graph build → community detection → betweenness centrality → PageRank → surprising connections579 - Writes `GRAPH_REPORT.md` to vault root580 - Report includes: god nodes table, community breakdown, surprising cross-topic connections, suggested questions5815822. **Call `library_visualize`** (no params, uses default output path)583 - Generates self-contained interactive HTML with force-directed graph layout584 - Nodes colored by community, sized by structural importance585 - Click to inspect, search to filter586 - Writes `GRAPH_VIZ.html` to vault root5875883. **Report:**589 ```590 Vault analysis complete.591592 Report: GRAPH_REPORT.md593 - 847 notes, 2,341 links, 12 communities, 43 orphans594 - God nodes: [[Claude]], [[Obsidian]], [[Knowledge Management]]595 - 8 surprising cross-community connections found596597 Visualization: GRAPH_VIZ.html598 - Open in browser to explore the interactive graph599600 Next steps:601 - /librarian connect — link orphan notes into the graph602 - /librarian from claude — archive this session's learnings603 ```604605### What the report contains606607| Section | Content |608|---------|---------|609| **God Nodes** | Top 10 structurally important notes ranked by composite score (degree + betweenness centrality + PageRank) |610| **Communities** | Topic clusters with member lists, detected by modularity optimization |611| **Surprising Connections** | High-betweenness edges that bridge different communities — the cross-topic links |612| **Suggested Questions** | 5 questions the graph is uniquely positioned to answer |613614---615616## daydream617618**Purpose:** Discover non-obvious connections between vault notes using multi-agent combinatorial exploration. Inspired by Gwern's LLM Daydreaming essay and glebis's Daydream skill — implements the brain's "default mode network" for your vault.619620### How it works621622The command pairs random notes and asks parallel sub-agents to find surprising connections, then filters with critics. Only genuinely novel, coherent, and useful insights survive.623624### Behavior6256261. **Sample notes from the vault:**627 - Call `library_list` to get all note paths628 - Call `library_read` on a random sample of 50 notes629 - Weight toward recent notes (by date frontmatter or filename)630 - If `[focus]` provided: use `library_search` to find focus-relevant notes, pair them with random notes from outside that cluster6316322. **Generate random pairs:**633 - Create 50 unique note pairs from the sample634 - Check `Daydreams/history.json` (via `library_read`) for already-processed pairs635 - Skip duplicates, proceed with remaining pairs6366373. **Synthesize connections (parallel sub-agents):**638 - Launch 10 parallel sub-agents (Sonnet model), each processing 5 pairs639 - Each agent reads both notes and explores:640 - Abstract analogies between concepts641 - Similar problems or solutions in different domains642 - Potential combinations or hybrid ideas643 - Revealing contradictions or tensions644 - Each agent returns structured results: title, connection description, source notes, reasoning6456464. **Critique and filter (parallel sub-agents):**647 - Launch 10 parallel critic sub-agents (Haiku model)648 - Each critic scores connections on three dimensions (1-10 each):649 - **Novelty:** Is this surprising and non-obvious?650 - **Coherence:** Is the reasoning logical and well-grounded?651 - **Usefulness:** Could this lead to new work, insights, or decisions?652 - Accept only connections with average score >= 7.06536545. **Write accepted insights to vault:**655 - For each accepted insight, call `library_write` to create `Daydreams/<YYYYMMDD>-<slug>.md`656 - Frontmatter includes: title, source_notes (paths), scores (novelty/coherence/usefulness), date, tags (daydream, source topics)657 - Body includes: the connection description, reasoning, and source note excerpts658 - `library_write` auto-wikilinks the insight into the knowledge graph6596606. **Update history:**661 - Read or create `Daydreams/history.json` via `library_read`/`library_write`662 - Add all processed pairs (accepted or rejected) to prevent re-processing663 - Track: pair hashes, dates, accept/reject status6646657. **Report:**666 ```667 Daydream complete.668669 Processed: 42 pairs (8 skipped as duplicates)670 Accepted: 7 insights (17% acceptance rate)671672 Insights written:673 - Daydreams/20260411-authentication-as-trust-boundary.md674 "Authentication patterns in the auth module mirror trust boundary675 concepts from the game theory notes — both define threshold functions."676 - Daydreams/20260411-vite-hmr-and-neural-plasticity.md677 ...678679 Run /librarian analyze to see how these integrate into the knowledge graph.680 ```681682### Cost683684Approximately $0.40-0.50 per run (50 pairs) using Sonnet for synthesis and Haiku for critique.685686### Tips687688- Run weekly or after adding substantial new content to the vault689- Use `[focus]` to explore connections around a specific topic: `/librarian daydream authentication`690- Daydream insights compound — they become seeds for future runs, creating a discovery flywheel691- Run `/librarian analyze` after daydream to see how insights integrate into the graph692693---694695## status696697**Purpose:** Quick vault health check.698699### Behavior7007011. Call `library_stats`7022. Report in compact format:703 ```704 Vault: The Labyrinth705 Files: 1,247 | Words: 389,102 | Links: 3,891 | Tags: 156706 Orphans: 23 (run /librarian connect to fix)707 Solutions: 45 ingested708 Last daily: 2026-04-11709 ```710711---712713## Tool Reference714715This skill orchestrates these Librarian MCP tools:716717| Tool | Used by |718|------|---------|719| `library_search` | search, daydream (focus mode) |720| `library_read` | search, ingest, connect, daydream |721| `library_write` | ingest, from *, connect, daydream |722| `library_list` | ingest (scan docs/solutions/), import (batch), daydream |723| `library_links` | graph |724| `library_tags` | search |725| `library_metadata` | ingest (read frontmatter) |726| `library_daily` | daily |727| `library_stats` | status, graph |728| `library_suggest_links` | ingest, connect |729| `library_traverse` | search, graph |730| `library_shortest_path` | graph (on request) |731| `library_graph_analysis` | graph (vault-wide) |732| `library_cluster` | analyze, graph |733| `library_visualize` | analyze |734| `library_report` | analyze |735| `library_import` | import (MarkItDown conversion) |736737### Claude.ai MCP connectors738739| Connector | Tools used | Used by |740|-----------|-----------|---------|741| Gmail | `search_threads`, `get_thread` | from gmail |742| Exa | `web_fetch_exa` | from web |743| Tavily | `tavily_extract` | from web (fallback), from twitter (fallback) |744| Google Calendar | `gcal_list_events`, `gcal_get_event` | from calendar |745746### Local data sources747748| Source | Location | Used by |749|--------|----------|---------|750| Claude Code sessions | `~/.claude/projects/<project>/<session>.jsonl` | from claude |751752### External CLI tools753754| Tool | Used by | Install |755|------|---------|---------|756| `markitdown` | import | `pip install markitdown` |757| `bird` | from twitter | Via agent-reach / bird CLI |758759## Integration with ce:compound760761The primary integration pattern:762763```764/ce:compound # Documents a solution in docs/solutions/765/librarian ingest # Imports latest solution into vault (auto-wikilinked)766```767768This bridges project-scoped documentation into the persistent, cross-project knowledge graph. The next time you `/librarian search` for a similar problem, the solution surfaces with full graph context.