Librarian

Persistent memory with semantic search, hit-based ranking, universal import, and a knowledge marketplace

GitHub

Librarian

npm version License: MIT Downloads

A knowledge management MCP server for AI coding assistants. Capture insights, search with semantic understanding, and access a library of developer knowledge.

Installation

Claude Code (Recommended)

Plugin (full experience)

Includes MCP tools, slash commands, and hooks.

/plugin marketplace add telvokdev/librarian
/plugin install librarian@librarian

MCP only

claude mcp add librarian -- npx @telvok/librarian-mcp
Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}
Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}
Any MCP Client

Add to your MCP config:

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}

Or install globally:

npm install -g @telvok/librarian-mcp

Quick Start

// 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" })

API Reference (Beta)

Local Knowledge

ToolPurpose
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

Library

Browse and publish books at telvok.com. Free and paid content supported.

ToolPurpose
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

Bounties

ToolPurpose
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

Account

ToolPurpose
auth(action)Login, logout, status, complete
help(topic?)Get help on any tool
feedback(message, type?)Send feedback

How Search Works

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%).

Import Formats

FormatSources
jsonlAnthropic MCP Memory, mcp-knowledge-graph
markdownObsidian, Basic Memory MCP
cursorCursor Memory Bank
jsonSimple memory servers
sqlitemcp-memory-service, SQLite-vec

Authentication

  1. auth({ action: "login" }) — returns code + URL
  2. Visit telvok.com/device, enter the code
  3. auth({ action: "complete" }) — saves API key locally

Keys stored in .librarian/.auth, expire after 90 days.

Library Structure

.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)

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Commit changes (git commit -m 'Add my feature')
  4. Push (git push origin feature/my-feature)
  5. Open a Pull Request

License

MIT - Telvok

İlgili Sunucular