Knowledge capture for Claude Code and MCP clients
npm install @telvok/librarian


A knowledge management MCP server for AI coding assistants. Capture insights, search with semantic understanding, and access a library of developer knowledge.
Claude Code (Recommended)
#### Plugin (full experience)
Includes MCP tools, slash commands, and hooks.
```
/plugin marketplace add telvokdev/librarian
/plugin install librarian@librarian
#### MCP only
`bash`
claude mcp add librarian -- npx @telvok/librarian-mcp
Cursor
Add to .cursor/mcp.json:
`json`
{
"mcpServers": {
"librarian": {
"command": "npx",
"args": ["@telvok/librarian-mcp"]
}
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
`json`
{
"mcpServers": {
"librarian": {
"command": "npx",
"args": ["@telvok/librarian-mcp"]
}
}
}
Any MCP Client
Add to your MCP config:
`json`
{
"mcpServers": {
"librarian": {
"command": "npx",
"args": ["@telvok/librarian-mcp"]
}
}
}
Or install globally:
`bash`
npm install -g @telvok/librarian-mcp
`javascript
// Search before making decisions
brief({ query: "stripe webhook handling" })
// Capture what you learned
record({
insight: "Stripe retries webhooks but doesn't dedupe - always check idempotency key",
context: "payments, webhooks"
})
// Mark helpful entries to boost their ranking
mark_hit({ path: "local/stripe-webhooks-need-idempotency.md" })
// Browse the library
library_search({ query: "react patterns" })
`
| Tool | Purpose |
|------|---------|
| brief(query?, limit?) | Semantic search across your library |record(insight, ...)
| | Capture knowledge worth keeping |adopt(path, title?)
| | Copy imported entry to local library |mark_hit(path)
| | Mark an entry as helpful (increases ranking) |import_memories(format, path)
| | Import from other AI tools |rebuild_index(force?)
| | Rebuild semantic search embeddings |delete(path?, query?, confirm?)
| | Delete entries from local library |
Browse and publish books at telvok.com. Free and paid content supported.
| Tool | Purpose |
|------|---------|
| library_search(query, filters?) | Search Telvok library |library_download(slug)
| | Download a free book locally |library_publish(name, attestation, ...)
| | Publish entries as a book |my_books(filter?)
| | View published and downloaded books |sync(slug?, force?)
| | Check for updates to owned books |rate_book(slug, rating, ...)
| | Rate a book (1-5 stars) |seller_analytics()
| | View download stats for your books |
| Tool | Purpose |
|------|---------|
| bounty_create(title, ...) | Post a knowledge request |bounty_list(query?, tags?, status?)
| | Browse available bounties |bounty_claim(bounty_id)
| | Claim a bounty to fulfill |bounty_submit(bounty_id, book_slug)
| | Submit fulfillment |my_bounties(role?)
| | View your bounties |
| Tool | Purpose |
|------|---------|
| auth(action) | Login, logout, status, complete |help(topic?)
| | Get help on any tool |feedback(message, type?)
| | Send feedback |
Librarian uses local AI embeddings for semantic search:
``
You saved: "Stripe webhooks need idempotency checks"
You search: "handling duplicate payment events"
→ It finds it.
- all-MiniLM-L6-v2 model (384-dim embeddings)
- ~30MB download on first run, cached locally
- No API calls — fully offline
Results ranked by semantic similarity, recency (60%), and hit count (40%).
| Format | Sources |
|--------|---------|
| jsonl | Anthropic MCP Memory, mcp-knowledge-graph |markdown
| | Obsidian, Basic Memory MCP |cursor
| | Cursor Memory Bank |json
| | Simple memory servers |sqlite
| | mcp-memory-service, SQLite-vec |
1. auth({ action: "login" }) — returns code + URLtelvok.com/device
2. Visit , enter the codeauth({ action: "complete" })
3. — saves API key locally
Keys stored in .librarian/.auth, expire after 90 days.
``
.librarian/
├── local/ # Your entries
├── imported/ # Downloaded books
├── packages/ # Purchased content
├── archived/ # Stale but searchable
├── index.json # Semantic embeddings
├── models/ # Cached embedding model
└── .auth # API key (git-ignored)
1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)git commit -m 'Add my feature'
3. Commit changes ()git push origin feature/my-feature`)
4. Push (
5. Open a Pull Request
MIT - Telvok