Librarian

Memória persistente com busca semântica, ranqueamento por hits, importação universal e um marketplace de conhecimento.

Documentação

Librarian

Um servidor MCP de gerenciamento de conhecimento para assistentes de codificação com IA. Capture insights, pesquise com compreensão semântica e acesse uma biblioteca de conhecimento para desenvolvedores.

Instalação

Claude Code (Recomendado)

Plugin (experiência completa)

Inclui ferramentas MCP, comandos de barra e hooks.

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

Somente MCP

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

Cursor

Adicione ao .cursor/mcp.json:

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

Windsurf

Adicione ao ~/.codeium/windsurf/mcp_config.json:

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

Qualquer Cliente MCP

Adicione à sua configuração MCP:

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

Ou instale globalmente:

npm install -g @telvok/librarian-mcp

Início Rápido

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

Referência da API (Beta)

Conhecimento Local

Ferramenta	Finalidade
`brief(query?, limit?)`	Pesquisa semântica em toda a sua biblioteca
`record(insight, ...)`	Capture conhecimento que vale a pena manter
`adopt(path, title?)`	Copie uma entrada importada para a biblioteca local
`mark_hit(path)`	Marque uma entrada como útil (aumenta a classificação)
`import_memories(format, path)`	Importe de outras ferramentas de IA
`rebuild_index(force?)`	Reconstrua os embeddings da pesquisa semântica
`delete(path?, query?, confirm?)`	Exclua entradas da biblioteca local

Biblioteca

Navegue e publique livros em telvok.com. Conteúdo gratuito e pago suportado.

Ferramenta	Finalidade
`library_search(query, filters?)`	Pesquise na biblioteca Telvok
`library_download(slug)`	Baixe um livro gratuito localmente
`library_publish(name, attestation, ...)`	Publique entradas como um livro
`my_books(filter?)`	Veja livros publicados e baixados
`sync(slug?, force?)`	Verifique atualizações de livros que você possui
`rate_book(slug, rating, ...)`	Avalie um livro (1 a 5 estrelas)
`seller_analytics()`	Veja estatísticas de download dos seus livros

Recompensas

Ferramenta	Finalidade
`bounty_create(title, ...)`	Publique uma solicitação de conhecimento
`bounty_list(query?, tags?, status?)`	Navegue pelas recompensas disponíveis
`bounty_claim(bounty_id)`	Reivindique uma recompensa para cumprir
`bounty_submit(bounty_id, book_slug)`	Envie o cumprimento
`my_bounties(role?)`	Veja suas recompensas

Conta

Ferramenta	Finalidade
`auth(action)`	Login, logout, status, conclusão
`help(topic?)`	Obtenha ajuda em qualquer ferramenta
`feedback(message, type?)`	Envie feedback

Como Funciona a Pesquisa

O Librarian usa embeddings locais de IA para pesquisa semântica:

You saved:   "Stripe webhooks need idempotency checks"
You search:  "handling duplicate payment events"
→ It finds it.

Modelo all-MiniLM-L6-v2 (embeddings de 384 dimensões)
~30MB de download na primeira execução, armazenado em cache localmente
Sem chamadas de API — totalmente offline

Resultados classificados por similaridade semântica, recência (60%) e contagem de correspondências (40%).

Formatos de Importação

Formato	Fontes
`jsonl`	Anthropic MCP Memory, mcp-knowledge-graph
`markdown`	Obsidian, Basic Memory MCP
`cursor`	Cursor Memory Bank
`json`	Servidores de memória simples
`sqlite`	mcp-memory-service, SQLite-vec

Autenticação

auth({ action: "login" }) — retorna código + URL
Visite telvok.com/device, insira o código
auth({ action: "complete" }) — salva a chave da API localmente

Chaves armazenadas em .librarian/.auth, expiram após 90 dias.

Estrutura da Biblioteca

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

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/my-feature)
Faça commit das alterações (git commit -m 'Add my feature')
Envie (git push origin feature/my-feature)
Abra um Pull Request

Licença

MIT - Telvok