Librarian

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

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

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

Bounties

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

Account

Tool	Purpose
`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

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

Authentication

auth({ action: "login" }) — returns code + URL
Visit telvok.com/device, enter the code
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

Librarian

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

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

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

Bounties

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

Account

Tool	Purpose
`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

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

Authentication

auth({ action: "login" }) — returns code + URL
Visit telvok.com/device, enter the code
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)

Help us improve

Find plugins for your project

Help us improve

librarian

Popularity

Health & Quality

Confidence

What's Inside

Help us improve

README

Librarian

Installation

Plugin (full experience)

MCP only

Quick Start

API Reference (Beta)

Local Knowledge

Library

Bounties

Account

How Search Works

Import Formats

Authentication

Library Structure

Contributing

Similar Plugins

ai-knowledge

autology

brain-os

domain-memory-agent

spine

secondbrain

Librarian

Installation

Plugin (full experience)

MCP only

Quick Start

API Reference (Beta)

Local Knowledge

Library

Bounties

Account

How Search Works

Import Formats

Authentication

Library Structure

Contributing