@booklib/core
Advanced tools
Knowledge bookkeeping for AI agents — expert skills, hybrid search, knowledge graph, MCP tools
English · 中文 · 日本語 · 한국어 · Português · Українська
A knowledge platform for AI agents.
Expert knowledge, personal insights, and project context —
searchable, structured, and delivered via MCP to any AI tool.
13 AI tools supported · 10 MCP-compatible · Hybrid search engine · Knowledge graph · Zero cloud dependencies
AI agents are powerful — but they only know what's in their training data. They don't know your team's conventions, your architecture decisions, or the specific expert frameworks you follow. Every new session starts from zero.
Research from ETH Zurich confirms this is a real problem — giving agents unstructured context files actually reduces task success rates while increasing costs by 20%+. More context doesn't help. Structured, relevant context does.
BookLib is a local knowledge platform built on this principle. It gives your AI agent persistent, structured knowledge that it can search and apply across every session.
| What it does | |
|---|---|
| Knowledge engine | Index any structured knowledge — expert frameworks, team conventions, architecture decisions, research findings. Search it with natural language via a hybrid pipeline (BM25 + vector + cross-encoder reranking). |
| MCP integration | 8 tools your agent calls directly: search, audit, capture, build context. Works in Claude Code, Cursor, Copilot, Gemini, Codex, Windsurf, Roo Code, Goose, Zed, and Continue. |
| Knowledge graph | Capture insights as you work. Link them to each other and to your project components. Your agent finds related knowledge automatically through graph traversal. |
| Multi-tool support | One booklib init detects and configures all your AI tools. MCP for 10 tools, config files for 3 more. Switch tools, keep your knowledge. |
| Health system | booklib doctor diagnoses problems — too many skills, stale knowledge, oversized configs — and --cure fixes them. |
| Runs locally | Everything on your machine. No cloud, no API keys, no data leaving your laptop. Embedding model (~25 MB) runs on CPU. |
Programming, product management, UI design, data visualization, system architecture, technical writing, research — any field where structured expert knowledge improves your agent's output.
npm install -g booklib
booklib init
The wizard handles everything — detecting your project, configuring your AI tools, building the search index, and recommending relevant knowledge. After that, just work. Your agent uses BookLib automatically.
You don't type BookLib commands. Your agent does.
You: "Review this authentication module"
Agent: searches BookLib for auth patterns, finds relevant principles, applies them to the review with citations
You: "Remember that we decided to use event sourcing for orders"
Agent: captures the insight into the knowledge graph, links it to your project
You: "Something feels off about our code quality lately"
Agent: runs diagnostics, suggests which knowledge areas need attention
BookLib becomes part of how your agent thinks — not a tool you have to remember to use.
BookLib ships with 24 curated knowledge sets covering programming, architecture, design, product, and more. Browse them in the skills/ directory or search with booklib search.
BookLib can find and index skills beyond the bundled set. Configure sources in booklib.config.json:
{
"sources": [
{ "type": "registry", "trusted": true },
{ "type": "manifest", "url": "./community/registry.json", "trusted": true },
{ "type": "github-skills-dir", "repo": "obra/superpowers", "dir": "skills", "branch": "main", "trusted": true },
{ "type": "github-skills-dir", "repo": "ruvnet/ruflo", "dir": ".claude/skills", "branch": "main", "trusted": true },
{ "type": "github-org", "org": "your-org" },
{ "type": "npm-scope", "scope": "@your-scope" }
]
}
booklib discover # list available skills from all sources
booklib discover --refresh # force re-scan (bypass 24h cache)
booklib install naming-cheatsheet # download and index a specific skill
booklib setup # fetch all trusted skills at once
Source types: registry (bundled), manifest (JSON list at URL or local path), github-skills-dir (any repo with a skills/ subdirectory), github-org, npm-scope.
"trusted": true marks a source as auto-installable by booklib setup. Untrusted sources are discoverable but require explicit booklib fetch <name> with a confirmation prompt.
Set
GITHUB_TOKENto raise the GitHub API limit from 60 to 5000 req/hr:GITHUB_TOKEN=$(gh auth token) booklib discover --refresh
After booklib sync, every fetched skill lives at ~/.claude/skills/<name>/SKILL.md — the path Claude Code's native Skill tool reads from. No extra configuration needed.
booklib sync # write all fetched skills to ~/.claude/skills/
| Orchestrator | Install | Skills surface via |
|---|---|---|
| obra/superpowers | /plugin install superpowers | Skill tool — available in every session |
| ruflo | npm install -g ruflo | Skill tool — available in every session |
BookLib uses a .booklib marker file to track directories it manages and never overwrites skills you placed there manually.
Equip agents in a swarm with the right skills for their role:
booklib profile reviewer # skills for a code reviewer agent
booklib profile security # skills for a security auditor
booklib profile architect # skills for a system design agent
Roles: architect · coder · reviewer · tester · security · frontend · optimizer · devops · ai-engineer · manager · product · writer · strategist · designer · legal
Get a full skill map for a swarm trigger pipeline:
booklib swarm-config audit # security → tester agent roles + their skills
booklib swarm-config feature # architect → coder → reviewer → tester
booklib swarm-config # list all configured triggers
Scaffold context files for every AI tool in the project from a single command:
booklib init # Phase 1: .cursor/rules, CLAUDE.md, copilot-instructions, .gemini/context.md
# Phase 2: MCP server config for Claude Code, Cursor, Gemini, Codex, Zed, Continue
booklib init --orchestrator=obra # also shows superpowers install instructions
booklib init --orchestrator=ruflo # also shows ruflo install instructions
booklib init --mcp-tool=claude,zed # non-interactive MCP setup for specific tools
booklib init runs in two phases: first it writes AI tool standards files, then it interactively offers to wire up the MCP server so your tools can call booklib search and context directly. Re-run after adding new skills — it updates all files in place without overwriting your existing configs.
| Agent | Model | Skills applied |
|---|---|---|
@booklib-reviewer | sonnet | Auto-routes to the best skill |
@python-reviewer | sonnet | effective-python · asyncio · web-scraping |
@ts-reviewer | sonnet | effective-typescript · clean-code-reviewer |
@jvm-reviewer | sonnet | effective-java · effective-kotlin · kotlin-in-action · spring-boot |
@rust-reviewer | sonnet | programming-with-rust · rust-in-action |
@architecture-reviewer | opus | domain-driven-design · microservices-patterns · system-design · data-intensive |
@data-reviewer | sonnet | data-intensive-patterns · data-pipelines |
@ui-reviewer | sonnet | refactoring-ui · storytelling-with-data · animation-at-work |
BookLib can capture knowledge from your actual work and link it to your project's own topology — forming a unified graph where book skills, research notes, and architectural decisions all live together.
Every piece of knowledge is a plain Markdown file in .booklib/knowledge/nodes/ with YAML frontmatter. Node types: research · note · decision · fact · component · feature · skill.
# Capture a note (opens $EDITOR, or pipe content in)
booklib note "JWT refresh token patterns"
echo "Short expiry + rotation" | booklib note "JWT refresh token patterns"
# Type or dictate — AI structures it, fixes grammar, extracts title + tags
booklib dictate
booklib dictate --raw # verbatim, no AI processing
booklib dictate --title "auth idea"
# Save the current agent conversation as a knowledge node
booklib save-chat --title "Auth redesign decisions"
booklib save-chat --summarize # AI extracts key decisions, attaches transcript
# Create a research stub (saves as a node for you to fill in)
booklib research "JWT refresh token patterns"
Define which parts of your project map to which components. When you edit a file, BookLib finds the owning component and injects all knowledge attached to it:
booklib component add auth "src/auth/**"
booklib component add payments "src/payments/**" "src/billing/**"
Components are just component nodes in .booklib/knowledge/nodes/ — same format, no separate config file.
Connect nodes with typed relationships:
# Link by title — no need to look up IDs
booklib link "JWT strategy" "auth" --type applies-to
booklib link "auth" "payments" --type depends-on
booklib link "JWT strategy" "RFC 7519 notes" --type see-also
# Exact IDs still work if you prefer
booklib link node_abc123 comp_auth456 --type applies-to
Edge types: implements · contradicts · extends · applies-to · see-also · inspired-by · supersedes · depends-on
All edges live in .booklib/knowledge/graph.jsonl — append-only, git-trackable.
booklib nodes list # list all nodes
booklib nodes show node_abc123 # view a specific node
booklib context automatically incorporates the knowledge graph alongside book skills when you pass a file path:
booklib context "implement jwt auth" --file src/auth/middleware.js
This finds the owning component (comp_auth), traverses its edges, runs semantic search, and injects the most relevant book wisdom + your own captured knowledge together.
booklib context is the most powerful way to use BookLib before starting a task. It searches across all indexed skills simultaneously, extracts the most relevant passage from each matched book, and surfaces every decision it makes — including the quiet ones:
booklib context "implement a payment service in Kotlin with async error handling"
booklib context "implement jwt auth" --file src/auth/middleware.js # also injects graph context
Output:
[a/b] prompt with passage previews so you can make an informed choiceWorks for any domain, not just code:
booklib context "design a rate limiter for a distributed API"
booklib context "refactor a God class in Python" --prompt-only # just the prompt, no report
booklib context "add streaming to a Next.js chat UI" --prompt-only | pbcopy
booklib context "write a compelling investor update email"
booklib context "design a landing page for a SaaS product"
booklib context "structure a product requirements document for checkout"
booklib search "how to handle null values in Kotlin"
booklib search "event sourcing vs CQRS" --role=architect # filter to skills tagged for that role
booklib audit effective-kotlin src/PaymentService.kt # systematic review of a file
booklib scan # wisdom heatmap — violations per skill across the whole project (code)
booklib scan --docs # prose quality scan — passive voice, placeholders, hedge words in .md/.txt files
Preserves full context when switching agents or hitting rate limits:
booklib save-state --goal="..." --next="..." --progress="..."
booklib resume
booklib recover-auto # auto-recover from last session or git history
Multi-agent coordination:
booklib sessions-list
booklib sessions-merge auth-session,payment-session combined
booklib sessions-lineage main feature-x "branched for auth work"
booklib sessions-compare python-audit,kotlin-audit src/auth.ts comparison
All session data lives in .booklib/ (gitignored). Nothing sent to any server.
BookLib ships a local MCP server that gives any MCP-compatible AI agent access to both the skill library and the knowledge graph.
# Automatic setup (recommended) — run once, picks up all your tools:
booklib init
# Manual setup if needed:
# Claude Code
claude mcp add booklib -- booklib-mcp
# Cursor / Gemini / Codex / Zed / Continue — booklib init writes the right file for each
Available tools:
| Tool | What it does |
|---|---|
get_context | Full context builder — returns compiled book wisdom + knowledge graph for a task |
get_context (with file) | Graph-aware context: also injects knowledge linked to the file's component |
create_note | Create a knowledge node and index it immediately |
search_knowledge | Semantic search across skills + knowledge nodes (filterable by source) |
list_nodes | List all knowledge graph nodes with id, title, type |
link_nodes | Create a typed edge between two nodes (by title or ID) |
audit_content | Systematic file audit against a specific skill |
save_session_state | Save agent progress for handoff to another agent |
Agent compatibility:
| Claude Code | Cursor | Windsurf | Zed | Continue.dev | Copilot | |
|---|---|---|---|---|---|---|
| Skills (auto-inject) | ✅ hook | via MCP | via MCP | via MCP | via MCP | ❌ |
| Context builder | ✅ | ✅ MCP | ✅ MCP | ✅ MCP | ✅ MCP | ❌ |
| Knowledge graph | ✅ | ✅ MCP | ✅ MCP | ✅ MCP | ✅ MCP | ❌ |
Each bundled skill is evaluated by asking a model to review code with and without the skill active. Delta = pass rate with skill minus pass rate without — it measures how much the skill actually changes model behaviour. A delta of +0pp means the model already knew it; a high delta means the skill is genuinely teaching it something new.
Thresholds: pass rate ≥ 80% · delta ≥ 20pp · baseline < 70%
| Skill | Pass Rate | Baseline | Delta | Evals | Last Run |
|---|---|---|---|---|---|
| animation-at-work | 96% | 64% | +32pp | 3 | 2026-03-28 |
| clean-code-reviewer | 91% | 59% | +33pp | 15 | 2026-03-28 |
| data-intensive-patterns | 91% | 62% | +29pp | 3 | 2026-03-28 |
| data-pipelines | 96% | 30% | +65pp | 3 | 2026-03-28 |
| design-patterns | 100% | 67% | +33pp | 3 | 2026-03-28 |
| domain-driven-design | 100% | 65% | +35pp | 3 | 2026-03-28 |
| effective-java | 92% | 67% | +25pp | 3 | 2026-03-28 |
| effective-kotlin | 100% | 56% | +44pp | 3 | 2026-03-28 |
| effective-python | 91% | 50% | +41pp | 3 | 2026-03-28 |
| effective-typescript | 93% | 27% | +67pp | 3 | 2026-03-28 |
| kotlin-in-action | 95% | 57% | +38pp | 3 | 2026-03-28 |
| lean-startup | 100% | 52% | +48pp | 3 | 2026-03-28 |
| microservices-patterns | 100% | 70% | +30pp | 3 | 2026-03-28 |
| programming-with-rust | 100% | 73% | +27pp | 3 | 2026-03-28 |
| refactoring-ui | 91% | 39% | +52pp | 3 | 2026-03-28 |
| rust-in-action | 94% | 63% | +31pp | 3 | 2026-03-28 |
| skill-router | 94% | 69% | +25pp | 3 | 2026-03-28 |
| spring-boot-in-action | 100% | 65% | +35pp | 3 | 2026-03-28 |
| storytelling-with-data | 100% | 100% | +0pp | 3 | 2026-03-28 |
| system-design-interview | 100% | 52% | +48pp | 3 | 2026-03-28 |
| using-asyncio-python | 91% | 67% | +24pp | 3 | 2026-03-28 |
| web-scraping-python | 96% | 38% | +58pp | 3 | 2026-03-28 |
Run evals: ANTHROPIC_API_KEY=... npx booklib eval <name>
booklib-ai/booklib/
├── skills/ 22 bundled skills (SKILL.md + examples + evals)
├── community/ community skill registry (registry.json)
├── agents/ 8 autonomous reviewer agents
├── commands/ slash commands, one per skill
├── rules/ always-on language standards
├── hooks/ Claude Code hooks (PreToolUse + PostToolUse)
├── booklib.config.json discovery source configuration
└── lib/
├── engine/ indexer, searcher, auditor, scanner, handoff, sessions
│ ├── graph.js knowledge graph: node CRUD, edge append, BFS traversal
│ ├── capture.js node creation: editor, stdin, AI structuring, dictation
│ └── graph-injector.js injection pipeline: semantic + graph traversal combined
├── context-builder.js cross-skill context builder (+ graph-aware buildWithGraph)
├── skill-fetcher.js fetch skills from GitHub/npm, sync to ~/.claude/skills/
├── discovery-engine.js scan configured sources for available skills
├── project-initializer.js generate context files for all AI tools
└── ...
bin/
├── booklib.js CLI (registered as `booklib`)
└── booklib-mcp.js MCP server
.booklib/(gitignored) — local state:sessions/for handoffs,index/for search index,skills/for fetched community skills,knowledge/for graph nodes and edges.
.booklib marker tracks which ~/.claude/skills/ dirs BookLib manages; never overwrites yours@xenova/transformers, vectra, gray-matter, @modelcontextprotocol/sdk, minimatchTo add a bundled skill:
cp -r skills/clean-code-reviewer skills/your-book-name
# Edit SKILL.md, examples/before.md, examples/after.md, evals/evals.json
npx booklib check your-book-name
To add a community skill, edit community/registry.json and open a PR.
To add an external source, edit booklib.config.json.
See CONTRIBUTING.md for the full guide.
Open requests: The Pragmatic Programmer · Clean Architecture · A Philosophy of Software Design · more →
| Milestone | Date |
|---|---|
First commit (clean-code-reviewer skill) | Feb 11, 2026 |
First npm publish (@booklib/skills v1.0.0) | Feb 17, 2026 |
| v1.10.0 — 22 skills, 8 agents, profiles, rules | Mar 28, 2026 |
| BookLib Engine — semantic search, session handoff, multi-agent coordination | Mar 29, 2026 |
| Discovery engine — GitHub, npm, community registry, obra/superpowers, ruflo compatibility | Mar 29, 2026 |
v1.11.0 — Non-code domain support (product, writing, strategy, design), scan --docs mode | Mar 30, 2026 |
| v1.12.0 — Knowledge Graph: nodes, edges, components, dictation, save-chat, graph-aware context injection | Mar 30, 2026 |
Full commit history at github.com/booklib-ai/booklib.
Found a bug? Have a suggestion? Open an issue — all feedback welcome.
If BookLib has helped you write better code, a ⭐ on GitHub helps me know people are using it — and helps others discover it.
Thanks to everyone who supports BookLib on Ko-fi ☕
Be the first — your name here.
MIT
FAQs
Detects AI knowledge gaps in your codebase and fixes them — post-training API detection, team knowledge, and runtime context injection via MCP for Claude, Cursor, Copilot, and 10+ AI coding tools
The npm package @booklib/core receives a total of 5 weekly downloads. As such, @booklib/core popularity was classified as not popular.
We found that @booklib/core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
arXiv now limits authors to two submissions a month as AI slop overwhelms moderators, delays good papers, and sparks debate over applying the limit to everyone.
Research
/Security News
A new GhostAction wave hits hundreds of GitHub repos, expanding CI/CD secret theft to cloud and AI credentials in source code and git history.
Research
/Security News
Tensorlake npm SDK version 0.5.144 was compromised in a ChainDrop / Shai-Hulud attack, delivering credential-stealing malware.