Librarian

Bộ nhớ bền vững với tìm kiếm ngữ nghĩa, xếp hạng dựa trên lượt truy cập, nhập liệu phổ quát và một chợ tri thức.

Bạn có thể làm gì với Librarian?

Search your personal knowledge library — Use brief to run a semantic search across saved insights before making decisions.
Capture and store insights — Save developer knowledge with record, including optional context tags for later retrieval.
Boost useful entries — Mark helpful library entries with mark_hit to increase their ranking in future searches.
Browse and download shared books — Search the Telvok library with library_search and download free books via library_download.
Import from other memory tools — Bring in existing knowledge using import_memories, with support for JSONL, Markdown, Cursor, and SQLite formats.

Tài liệu

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

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

License

MIT - Telvok