Librarium sends one research question to the search and AI sources you choose, then saves each answer, citation and cost in a Run you can resume.
Website · Docs · Agent setup · Laravel package
- Node.js 22.12 or newer for the npm package. Homebrew and the standalone binaries include their own runtime.
- An API key for at least one source, for example
EXA_API_KEY. Research calls the providers you select, and those calls can cost money.
npm install -g librarium
# or
brew install jkudish/tap/librariumStandalone macOS and Linux binaries install with
curl -fsSL https://raw.githubusercontent.com/jkudish/librarium/main/scripts/install.sh | sh.
Check the result with librarium --version; it prints a 2.x version.
librarium setup
librarium setup --check
librarium research "Compare managed PostgreSQL services" --only exa --dry-runsetup is an interactive wizard for keys, source options and a default cost
cap. Keys can be literal values or references such as env:EXA_API_KEY, and
environment variables work without a config file. setup --check reads local
configuration only and makes no provider calls.
The dry run plans the request without calling a provider or saving a Run. Your Run id will differ:
run_01M5ZQD37CXSGVA07PVQZ93MB5 planned (quick)
Compare managed PostgreSQL services
exa: queued, 0 citations, reported USD unknown
Remove --dry-run to run it. Librarium saves the Run before the first
provider call, then prints each source's status, citation count and reported
cost. Runs go to ./agents/librarium under the current directory unless
runs.path is set. librarium show --source exa prints that source's answer
and citations from the latest Run.
librarium research "Compare managed PostgreSQL services" --deep --only exa,openai --max-cost 1 --no-wait
librarium show <run-id> --wait --json
librarium summarize <run-id> --verify--deep submits durable research tasks. --no-wait returns after submission
and requires --deep, because quick work runs inside the calling process.
show resumes the saved task handles; it never submits the work again. Ctrl-C
detaches and prints the show command to use later. summarize writes a
separate, budgeted Run linked to the original by summary_of.
Without --only, Librarium uses every research source you have set up, at
quick depth. --only and --skip take comma-separated source, engine or
saved group names. Naming a source without credentials is an error.
There are 16 research sources: brave, claude, exa, firecrawl,
gemini, google, grok, jina, kagi, openai, openrouter,
parallel, perplexity, tavily, valyu and you.
There are 5 engines: chatgpt, gemini-app, google-ai-mode,
google-ai-overview and copilot. Engines record what a consumer AI product
showed, collected through SearchAPI. They run only when named, and their
results carry observation: "surface".
Groups are lists you save yourself with groups add; none are built in:
librarium groups add visibility chatgpt gemini-app google-ai-mode
librarium research "How do AI products describe Acme?" --only visibility
librarium groups remove visibilityThe sources command (librarium sources --json) shows what your
installation can use, with options and price hints. The
provider reference describes each
source's quick and deep variants. Source keys
lists the environment variable each source reads.
The mcp command (librarium mcp) runs a stdio MCP server with three tools:
researchstarts a Run and returns a summary with statuses, citation counts and costs.get_runresumes a Run or pages through one source's answer and citations.list_sourceslists sources, engines, saved groups and price hints.
research and get_run wait 45 seconds by default and at most 50
(wait_seconds). An MCP max_cost can only lower the configured cap.
The install guide has registration steps for each agent host. For Claude Code:
claude mcp add --scope user librarium -- librarium mcplibrarium install-skill installs the bundled SKILL.md into
~/.claude/skills/librarium.
npm install librariumimport { createLibrarium } from 'librarium';
const librarium = createLibrarium();
const run = await librarium.research('Compare managed PostgreSQL services', {
only: ['exa'],
maxCost: '0.50',
});
for (const result of run.results)
console.log(result.source, result.status, result.citations.length, result.cost.reported);research resolves when the Run finishes. It prints one line per source;
cost.reported is null when the provider did not report a charge. The
root import reads ~/.config/librarium/config.json and stores Runs on disk.
librarium/core runs in Workers and browsers with a memory store by default.
See the library docs for get,
sources, summarize, imports and custom RunStores.
browse lists saved Runs. html and jsonl export a Run. usage totals
reported spend. cleanup prunes finished Runs older than runs.keep_days.
config reads and edits the config file. completions prints bash, zsh or
fish completions. upgrade updates an npm, pnpm, yarn or Homebrew install, and
install-skill installs the agent skill. The
command reference has flags and examples.
- A cost cap (
--max-costormax_cost) skips sources without a price estimate, then admits each source, in catalog order, whose estimate fits the remaining budget. It stops unstarted work, but calls already in flight can finish above the cap. - Reported cost comes from the provider only. Unknown cost is
null, never"0". A failed call may still be billed, and Librarium never substitutes another source after a failure. - Provider answers and citations are untrusted evidence. Credentials are redacted before storage, but questions and cited pages can still contain private information.
- 2.0 migrates a 1.x config to version 3 after writing a backup.
showcannot read 1.x run directories. Read the upgrade guide before upgrading.
- Configuration and source options
- Custom sources and RunStores
- Costs and limits
- Laravel package
(
jkudish/laravel-ai-librarium), which shares the Run format throughlibrarium-spec - Changelog
Ask questions in GitHub Discussions and report bugs in issues.
- Laravel AI Librarium: the Laravel package (
composer require jkudish/laravel-ai-librarium). - Laravel AI Librarium: Firecrawl: collects AI answer engine results for the Laravel package through Firecrawl browser sessions.
- librarium-spec: the shared Run schemas, source catalog and conformance fixtures.
- librarium.si: documentation for all of them.
If you find Librarium useful, consider becoming a sponsor or donating.
See CONTRIBUTING.md to work on the code. To report a vulnerability, see SECURITY.md.