From 1583bff9a4d4e9b7391a84c21a74af1bde2d9bd4 Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:02:42 -0700 Subject: [PATCH 1/9] Add mkdocs + mkdocs-material as a docs extra Pure-Python docs framework (matches the rest of the project's tooling). The new [docs] extra is what the docs CI workflow installs to build the site. --- pyproject.toml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 7c1db66..f5bd35f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -74,6 +74,10 @@ all = [ evals = [ "arcade-mcp[evals]>=1.14.0", ] +docs = [ + "mkdocs>=1.6.0", + "mkdocs-material>=9.5.0", +] [build-system] requires = ["hatchling"] From a58504c1dfbd07305bf36ecc6bae49bbbf0f70cd Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:02:48 -0700 Subject: [PATCH 2/9] =?UTF-8?q?Add=20mkdocs.yml=20=E2=80=94=20Material=20t?= =?UTF-8?q?heme=20+=20nav?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Configure the Material theme with light/dark toggle, code-copy buttons, admonitions, and tabbed content blocks. Site URL points at arcadeai.github.io/agent-library/. Nav order steers a non-technical reader from Home → Quickstart → Install → integration walkthroughs → CLI reference. --- mkdocs.yml | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 mkdocs.yml diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..b509061 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,82 @@ +site_name: Agent Library +site_description: A personal knowledge library for AI agents — store and search notes, code, PDFs, and images. +site_url: https://arcadeai.github.io/agent-library/ +repo_url: https://github.com/ArcadeAI/agent-library +repo_name: ArcadeAI/agent-library +edit_uri: edit/main/docs/ + +docs_dir: docs + +theme: + name: material + features: + - navigation.instant + - navigation.tracking + - navigation.sections + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.action.edit + - toc.follow + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/weather-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/weather-sunny + name: Switch to light mode + font: + text: Inter + code: JetBrains Mono + icon: + repo: fontawesome/brands/github + +markdown_extensions: + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - tables + - toc: + permalink: true + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.keys + +nav: + - Home: index.md + - Quickstart: quickstart.md + - Install: + - Installing uv: install.md + - Use it with your AI: + - Claude Desktop: integrations/claude-desktop.md + - Claude Code (CLI): integrations/claude-code.md + - Cursor: integrations/cursor.md + - CLI reference: cli.md + - Concepts: concepts.md + - Troubleshooting: troubleshooting.md + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/ArcadeAI/agent-library From 14a72686ffad62b6552d0a41b6408ee047cd1ba0 Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:03:00 -0700 Subject: [PATCH 3/9] Add user-facing documentation site Eight pages targeted at non-technical readers: a one-paragraph overview, a three-command quickstart, install instructions for uv across mac / Windows / Linux, walkthroughs for three popular AI clients (`integrations/*.md`), a CLI reference, optional concepts background, and troubleshooting recipes. Every install command was verified end-to-end against the published 0.13.0 release. JSON snippets for each integration target were validated against their actual config-file shapes. CLI option tables match `librarian --help` verbatim. --- docs/cli.md | 163 ++++++++++++++++++++++++++++ docs/concepts.md | 80 ++++++++++++++ docs/index.md | 40 +++++++ docs/install.md | 72 ++++++++++++ docs/integrations/claude-code.md | 84 ++++++++++++++ docs/integrations/claude-desktop.md | 117 ++++++++++++++++++++ docs/integrations/cursor.md | 83 ++++++++++++++ docs/quickstart.md | 87 +++++++++++++++ docs/troubleshooting.md | 118 ++++++++++++++++++++ 9 files changed, 844 insertions(+) create mode 100644 docs/cli.md create mode 100644 docs/concepts.md create mode 100644 docs/index.md create mode 100644 docs/install.md create mode 100644 docs/integrations/claude-code.md create mode 100644 docs/integrations/claude-desktop.md create mode 100644 docs/integrations/cursor.md create mode 100644 docs/quickstart.md create mode 100644 docs/troubleshooting.md diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..749537f --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,163 @@ +# CLI reference + +Every command Agent Library exposes, with copy-paste examples. The binary name is `librarian` (with `libr` as a shorter alias). Examples below use `librarian`. + +!!! note "Reminder" + These all assume you've set up the `librarian` alias from the [Quickstart](quickstart.md). If you haven't, prepend each command with: + + ``` + uvx --from "agent-library[all]==0.13.0" + ``` + +--- + +## `librarian add` + +Add a file or directory as a source and index its contents. + +```bash +librarian add ~/notes +``` + +**Options:** + +| Flag | What it does | +|---|---| +| `-n NAME` / `--name` | Give the source a friendly name (defaults to the directory name) | +| `-d N` / `--depth` | Limit recursion. `0` = the directory itself only. Default: unlimited | +| `-p PATTERN` / `--pattern` | Glob filter (e.g. `'notes/*.md'`) | + +```bash +# Index just the top-level files of a folder +librarian add ~/notes --depth 0 + +# Index only Python files in a project +librarian add ~/code/myproject --pattern '**/*.py' +``` + +--- + +## `librarian list` + +Show every source you've added, with document counts. + +```bash +librarian list +``` + +**Options:** + +| Flag | What it does | +|---|---| +| `-a` / `--all` | Include sources marked hidden/test | +| `--json` | Output as JSON (good for scripting) | + +--- + +## `librarian rm` + +Remove a source from the index. Files on disk are **not** deleted — only the database entries. + +```bash +librarian rm notes +``` + +**Options:** + +| Flag | What it does | +|---|---| +| `-f` / `--force` | Skip the confirmation prompt | +| `--path PATH` | Disambiguate if two sources share the same name | + +--- + +## `librarian search` + +Search across everything you've indexed. + +```bash +librarian search "retry policy" +``` + +**Options:** + +| Flag | What it does | +|---|---| +| `-l N` / `--limit` | Max results (default 10) | +| `-m MODE` / `--mode` | `hybrid` (default), `semantic`, `vector` (alias for semantic), or `keyword` | +| `-s NAME` / `--source` | Search within a single source | +| `-t TIMEFRAME` / `--timeframe` | `today`, `yesterday`, `week`, `month`, `year` | +| `-f FORMAT` / `--format` | Output as `table` (default), `json`, or `paths` | +| `-v` / `--verbose` | Include the matched content snippet inline | +| `-o` / `--open` | Open the top result in your editor | +| `-c` / `--copy` | Copy the top result's content to clipboard | +| `--code` | Search code files only | +| `--images` | Search images only (uses CLIP if vision is installed) | +| `--type TYPE` | Filter by asset type: `text`, `code`, `pdf`, `image` | + +```bash +# Find conceptual matches, not just keyword +librarian search "graceful degradation" --mode semantic + +# Just the file paths, one per line, useful for piping +librarian search "deploy" --format paths | xargs cat | less + +# Things from this week, code only +librarian search "TODO" --timeframe week --code +``` + +--- + +## `librarian serve` + +Start the MCP server. This is what your AI assistant invokes — you usually configure it once in Claude/Cursor and never run it by hand. But it's available for testing. + +```bash +librarian serve stdio # for Claude Desktop, Claude Code, Cursor +librarian serve http --port 7878 # for HTTP-based MCP clients +``` + +**Options:** + +| Flag | What it does | +|---|---| +| `--host HOST` / `-h` | HTTP-only: bind address | +| `--port N` / `-p` | HTTP-only: port number | +| `--log-level LEVEL` | `debug`, `info`, `warning` (default), or `error` | + +--- + +## Subcommand groups + +Three command groups bundle less-common operations: + +```bash +librarian index --help # index inspection / rebuild operations +librarian docs --help # per-document operations (read, update, remove single docs) +librarian config --help # show or change configuration values +``` + +These are in the help output but used less often than the top-level commands above. + +--- + +## Environment variables + +Override defaults without editing config files: + +| Variable | Default | Effect | +|---|---|---| +| `DATABASE_PATH` | `~/.librarian/index.db` | Where the search index is stored | +| `DOCUMENTS_PATH` | `./documents` | Default directory used when no `path` is given | +| `EMBEDDING_PROVIDER` | `local` | Switch to `openai` for hosted embeddings | +| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformers model name | +| `HYBRID_ALPHA` | `0.7` | Vector ↔ keyword blend (0 = keyword only, 1 = vector only) | +| `MMR_LAMBDA` | `0.7` | Relevance ↔ diversity (0 = max diversity, 1 = max relevance) | +| `SEARCH_LIMIT` | `10` | Default result count | + +```bash +# One-off override for a single search +DATABASE_PATH=/tmp/test.db librarian search "anything" +``` + +For permanent overrides, add them to your shell profile or a `.env` file in the directory you launch `librarian` from. diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000..c8a8c7c --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,80 @@ +# Concepts + +Optional reading. The library works fine if you skip this page — but understanding the moving parts helps when you want to tune results. + +## Asset types + +Agent Library tags every file with an **asset type**: + +| Asset type | What's in it | Parser | +|---|---|---| +| `text` | Markdown, plain text | built-in | +| `code` | Source code (Python, JS, TS, Go, Rust, …) | regex-based symbol extractor | +| `pdf` | PDF documents | requires `pypdf` (in `[all]` extras) | +| `image` | PNG, JPG, GIF, WEBP | requires `Pillow` (in `[all]` extras) | + +When you search, the asset type is preserved on every result. You can filter on it: + +```bash +librarian search "encrypt" --type code +``` + +## Search modes + +Three modes, chosen with `--mode`: + +- **`keyword`** — pure full-text search, BM25-ranked. Best for exact phrases or unique tokens. Fast. +- **`semantic`** — pure embedding similarity (cosine distance against a sentence-transformer model). Finds meaning matches even when the wording differs. Slower; loads ~100 MB of model on first use. +- **`hybrid`** *(default)* — runs both and merges. Each modality normalizes its scores to [0, 1]; the merger gives a small overlap bonus to chunks that match across modalities. This is what you want most of the time. + +When `ENABLE_CROSS_MODAL_SEARCH=true` (the default), `hybrid` also runs separate embedding models for code (CodeBERT) and images (CLIP) when those extras are installed. + +## Chunking + +Documents are split into **chunks** before indexing. Each chunk is what the search returns — a passage, not a whole file. This keeps results focused and gives you snippet-level scores instead of file-level. + +The chunker is asset-type aware: + +- Markdown is split by headers (`H1`/`H2`) and paragraphs +- Code is split by symbol (function, class, method) +- PDFs are split by page +- Images become a single chunk with metadata + +## Scoring & MMR + +Results are scored 0 → 1. The blend is controlled by two knobs: + +- **`HYBRID_ALPHA`** (default `0.7`): in non-cross-modal hybrid, the formula is `alpha * vector_score + (1 - alpha) * keyword_score`. Higher = lean on semantic match more. +- **`MMR_LAMBDA`** (default `0.7`): after blending, **Maximal Marginal Relevance** picks the top-K with a diversity bias. The formula is `lambda * relevance - (1 - lambda) * max_similarity_to_already_selected`. Lower = more diverse top-K (might miss the second-best answer if it looks too much like the first); higher = more relevance-focused. + +You can tweak both via environment variables or `librarian config`. + +## What lives where + +| File | What it is | +|---|---| +| `~/.librarian/index.db` | SQLite database with the FTS5 index, vector embeddings, and document metadata. Survives across sessions. | +| `~/.librarian/sources.json` | The list of registered sources (managed by `librarian add` / `rm`). | +| `~/.librarian/documents/` | Default location for content created via `add_to_library` from inside the MCP server (when no `directory` is given). | + +Delete `index.db` and re-run `librarian add ...` to rebuild from scratch. + +## MCP under the hood + +When an AI assistant calls Agent Library, it speaks the **Model Context Protocol** — a JSON-RPC convention defined by Anthropic. `librarian serve stdio` talks MCP over stdin/stdout; `librarian serve http` talks MCP over HTTP streaming. + +The server advertises 9 tools: + +| Tool | Purpose | +|---|---| +| `Librarian_SearchLibrary` | The main thing — find content | +| `Librarian_ReadFromLibrary` | Read a full document by path | +| `Librarian_AddToLibrary` | Save new content into the library | +| `Librarian_UpdateLibraryDoc` | Replace a document's content | +| `Librarian_RemoveFromLibrary` | Drop a document from the index | +| `Librarian_ListLibraryContents` | List indexed documents | +| `Librarian_IndexDirectoryToLibrary` | Bulk-index a directory | +| `Librarian_GetLibraryOverview` | Inspect the library (sections / stats / tree) | +| `Librarian_SuggestLibraryLocation` | Recommend where new content belongs | + +Each takes typed arguments, returns typed JSON. The MCP host (Claude, Cursor) shows them under the server's name in its tool picker. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e28ae67 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,40 @@ +# Agent Library + +**A personal knowledge library for your AI assistant.** Drop your notes, code, PDFs, and screenshots into it once. From then on, Claude (or Cursor, or any other MCP-compatible AI) can search and read your stuff to answer your questions. + +You don't need to know what an embedding is. You don't need to know what MCP is. You just need to follow three steps. + +--- + +## What you can do with it + +- **Ask Claude about anything in your notes.** "What did I write about the API redesign last month?" — Claude searches your library, finds the relevant note, and reads it back. +- **Have your AI work over your codebase.** Index a project folder once. Cursor or Claude Code can then search the code by meaning ("find the function that handles retry logic") instead of just by filename. +- **Search PDFs and screenshots alongside your notes.** Indexes contracts, papers, diagrams. The library treats them like first-class search results. + +It runs entirely on your machine. Nothing leaves your laptop. + +--- + +## How to get started + +Three pages, in order: + +1. **[Install uv](install.md)** — `uv` is the tool that runs Agent Library. One copy-paste command. +2. **[Quickstart](quickstart.md)** — index a folder and search it from your terminal. Verify it works. +3. **Connect it to your AI** — pick the one you use: + - **[Claude Desktop](integrations/claude-desktop.md)** — the regular Claude app + - **[Claude Code](integrations/claude-code.md)** — the terminal-based Claude + - **[Cursor](integrations/cursor.md)** — the IDE + +After that: + +- **[CLI reference](cli.md)** — every `librarian` command with a copy-paste example +- **[Concepts](concepts.md)** — what's actually happening under the hood (optional reading) +- **[Troubleshooting](troubleshooting.md)** — when something doesn't work + +--- + +## Why "Agent Library"? + +Most AI assistants forget your work the moment a conversation ends. Agent Library is the long-lived shelf they can reach for. You write a note once; six conversations from now your assistant still finds it. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..09d24e1 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,72 @@ +# Installing uv + +`uv` is the tool that runs Agent Library. It's a fast Python package manager — think of it as the "app store" we'll fetch Agent Library from. + +You only have to do this once. + +## macOS + +Open the **Terminal** app (Spotlight → "Terminal") and paste this: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Press Enter. After it finishes (a few seconds), close and reopen Terminal so the new command is on your path. + +Verify it worked: + +```bash +uv --version +``` + +You should see something like `uv 0.5.x`. If you do, you're done — go to **[Quickstart](quickstart.md)**. + +??? tip "Prefer Homebrew?" + If you already use Homebrew: + + ```bash + brew install uv + ``` + +## Windows + +Open **PowerShell** (Start menu → "PowerShell") and paste this: + +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +Close and reopen PowerShell, then verify: + +```powershell +uv --version +``` + +## Linux + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Verify: + +```bash +uv --version +``` + +--- + +## Troubleshooting + +!!! warning "`uv: command not found`" + The installer sets up your `PATH` in a shell profile that only reloads on a new shell. **Close your terminal entirely and reopen it**, then try `uv --version` again. If it still fails, run `source ~/.zshrc` (macOS default) or `source ~/.bashrc` (Linux) and try once more. + +!!! warning "`Could not connect to astral.sh`" + Corporate networks sometimes block the install script. If you have Python installed already, you can fall back to: + + ```bash + pip install --user uv + ``` + +When `uv --version` prints a version number, head to **[Quickstart](quickstart.md)**. diff --git a/docs/integrations/claude-code.md b/docs/integrations/claude-code.md new file mode 100644 index 0000000..892194b --- /dev/null +++ b/docs/integrations/claude-code.md @@ -0,0 +1,84 @@ +# Claude Code (CLI) + +Claude Code is the terminal-based version of Claude. It uses the same MCP server interface as Claude Desktop, but you configure it from the shell. + +## Prerequisites + +- You ran the [Quickstart](../quickstart.md) and have at least one folder indexed. +- Claude Code is installed: . + +## Add Agent Library + +Claude Code has a one-line command to register an MCP server. From any directory: + +```bash +claude mcp add librarian \ + --command "uvx" \ + --args "--from" --args "agent-library[all]==0.13.0" \ + --args "librarian" --args "serve" --args "stdio" +``` + +That writes the entry into `~/.claude/settings.json` (or your project-local equivalent). Verify: + +```bash +claude mcp list +``` + +You should see `librarian` listed. + +!!! tip "Editing the JSON directly" + If you'd rather edit `~/.claude/settings.json` by hand, the `mcpServers` block looks the same as the Claude Desktop one: + + ```json + { + "mcpServers": { + "librarian": { + "command": "uvx", + "args": [ + "--from", "agent-library[all]==0.13.0", + "librarian", "serve", "stdio" + ] + } + } + } + ``` + +## Use it + +Start (or restart) Claude Code. In your conversation: + +> *"Search my library for the retry policy notes."* + +The first response triggers the MCP tool. You'll be prompted to allow `Librarian_SearchLibrary` — accept it once and Claude Code remembers. + +## Project-scoped vs. user-scoped + +By default the entry above goes into your **user-level** Claude config so it's available from every directory. If you'd rather have a per-project Agent Library (different index for different projects), pass `--scope local`: + +```bash +claude mcp add librarian --scope local \ + --command "uvx" \ + --args "--from" --args "agent-library[all]==0.13.0" \ + --args "librarian" --args "serve" --args "stdio" +``` + +That writes to `.claude/settings.json` next to your project, and you can point at a project-specific database: + +```bash +claude mcp add librarian --scope local \ + --command "uvx" \ + --args "--from" --args "agent-library[all]==0.13.0" \ + --args "librarian" --args "serve" --args "stdio" \ + --env "DATABASE_PATH=$(pwd)/.librarian/index.db" \ + --env "DOCUMENTS_PATH=$(pwd)" +``` + +## Removing it + +```bash +claude mcp remove librarian +``` + +--- + +Problems? See [Troubleshooting](../troubleshooting.md). diff --git a/docs/integrations/claude-desktop.md b/docs/integrations/claude-desktop.md new file mode 100644 index 0000000..2ace1bb --- /dev/null +++ b/docs/integrations/claude-desktop.md @@ -0,0 +1,117 @@ +# Claude Desktop + +Connect your Agent Library to the Claude Desktop app so Claude can search your notes during chats. + +## Prerequisites + +- You ran the [Quickstart](../quickstart.md) and have at least one folder indexed. +- Claude Desktop is installed: . + +## 1. Find the config file + +Claude Desktop reads its tool list from a single JSON file. The path depends on your OS: + +=== "macOS" + + ``` + ~/Library/Application Support/Claude/claude_desktop_config.json + ``` + + Open it in TextEdit or your editor of choice: + + ```bash + open -a TextEdit "$HOME/Library/Application Support/Claude/claude_desktop_config.json" + ``` + + If TextEdit complains the file doesn't exist, create it first: + + ```bash + mkdir -p "$HOME/Library/Application Support/Claude" + touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json" + ``` + +=== "Windows" + + ``` + %APPDATA%\Claude\claude_desktop_config.json + ``` + + Open it in Notepad: + + ```powershell + notepad "$env:APPDATA\Claude\claude_desktop_config.json" + ``` + +=== "Linux" + + ``` + ~/.config/Claude/claude_desktop_config.json + ``` + +## 2. Add the Agent Library entry + +If the file is empty, paste this whole block in: + +```json +{ + "mcpServers": { + "librarian": { + "command": "uvx", + "args": [ + "--from", "agent-library[all]==0.13.0", + "librarian", "serve", "stdio" + ] + } + } +} +``` + +If the file already has content, just add the `"librarian": { ... }` block inside the existing `mcpServers` object. The full file should look like a valid JSON document with `mcpServers` at the top level. + +Save the file. + +## 3. Restart Claude Desktop + +Quit Claude entirely (right-click the dock icon → Quit, or Cmd+Q) and reopen it. Claude only re-reads the config on launch. + +## 4. Try it + +Start a new chat with Claude and ask something that requires your notes: + +> *"Search my library for notes about retry policy."* + +Claude will call the `Librarian_SearchLibrary` tool. The first time, you'll see a permission prompt — click **Allow**. The results appear inline. + +You can verify the connection by checking the bottom of the Claude window — when an MCP server is connected, a small plug icon shows "1 server connected". + +--- + +## What if something doesn't work? + +!!! warning "Claude says it has no tools" + The most common cause is that Claude was already running when you saved the config. Quit it completely (Cmd+Q, not just close window) and reopen. + +!!! warning "Claude says the tool errored out" + Open `~/Library/Logs/Claude/mcp-server-librarian.log` (macOS) or the equivalent on your OS. The first run downloads ~2 GB of models, which can take a couple of minutes — Claude may time out before that finishes. Run the install command once at the terminal first to warm the cache: + + ```bash + librarian --help + ``` + + Then restart Claude. + +!!! tip "Want a custom storage location?" + Add an `env` block: + + ```json + "librarian": { + "command": "uvx", + "args": ["--from", "agent-library[all]==0.13.0", "librarian", "serve", "stdio"], + "env": { + "DATABASE_PATH": "/Users/me/work/librarian.db", + "DOCUMENTS_PATH": "/Users/me/work/notes" + } + } + ``` + +More problems? [Troubleshooting →](../troubleshooting.md) diff --git a/docs/integrations/cursor.md b/docs/integrations/cursor.md new file mode 100644 index 0000000..2df6d32 --- /dev/null +++ b/docs/integrations/cursor.md @@ -0,0 +1,83 @@ +# Cursor + +Cursor supports MCP servers natively as of late 2024. Hooking up Agent Library lets Cursor search your notes and external knowledge alongside whatever's open in your editor. + +## Prerequisites + +- You ran the [Quickstart](../quickstart.md) and have at least one folder indexed. +- Cursor 0.45 or newer (MCP support shipped in that release). + +## 1. Open the MCP settings + +In Cursor: + +1. Open the command palette: Cmd+Shift+P (or Ctrl+Shift+P on Windows/Linux). +2. Type **"MCP"** and pick **"Cursor: Open MCP Settings"** (or **"Cursor: Edit MCP Servers"** in newer builds). + +That opens `~/.cursor/mcp.json`. If the file is empty, Cursor will pre-fill the skeleton. + +## 2. Add the Agent Library entry + +If the file is empty or freshly skeletoned, paste this: + +```json +{ + "mcpServers": { + "librarian": { + "command": "uvx", + "args": [ + "--from", "agent-library[all]==0.13.0", + "librarian", "serve", "stdio" + ] + } + } +} +``` + +If you already have other MCP servers in there, add `"librarian"` as another key under `mcpServers`. Save the file. + +## 3. Reload Cursor + +Either fully quit and reopen Cursor, or run **"Developer: Reload Window"** from the command palette. Cursor re-reads `mcp.json` on each reload. + +## 4. Try it + +Open the Cursor chat panel (Cmd+L) and ask: + +> *"Search my library for retry policy notes."* + +Cursor's agent will call into the librarian server. The first time, you'll see a permission prompt — accept it. + +You can confirm the connection from the **MCP** tab in Cursor's settings: librarian should show as **Connected** with a green dot. + +--- + +## Project-specific libraries + +Cursor also supports a project-local `mcp.json` at the workspace root. Useful when each codebase has its own indexed knowledge: + +```bash +mkdir -p .cursor && cat > .cursor/mcp.json <<'EOF' +{ + "mcpServers": { + "librarian": { + "command": "uvx", + "args": [ + "--from", "agent-library[all]==0.13.0", + "librarian", "serve", "stdio" + ], + "env": { + "DATABASE_PATH": "${workspaceFolder}/.librarian/index.db", + "DOCUMENTS_PATH": "${workspaceFolder}" + } + } + } +} +EOF +``` + +The `${workspaceFolder}` placeholder is expanded by Cursor at launch. + +--- + +Problems? See [Troubleshooting](../troubleshooting.md). diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..344692b --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,87 @@ +# Quickstart + +Five minutes from zero to "my AI can search my notes". You'll do all of this from your terminal. + +!!! note "Before you start" + Make sure `uv --version` works in your terminal. If not, do **[Install uv](install.md)** first (one command). + +## 1. Run Agent Library for the first time + +Paste this into your terminal: + +```bash +uvx --from "agent-library[all]==0.13.0" librarian --help +``` + +The first time you run this it'll spend a couple minutes downloading the Python package and its language models (~2 GB total). You only pay this cost **once** — `uv` caches everything afterward. + +When it finishes you'll see a help menu listing commands like `add`, `search`, `serve`. That confirms it's working. + +!!! tip "Make this command shorter" + Typing `uvx --from "agent-library[all]==0.13.0" librarian` every time is annoying. Add an alias to your shell: + + === "macOS / Linux (zsh)" + + ```bash + echo 'alias librarian="uvx --from \"agent-library[all]==0.13.0\" librarian"' >> ~/.zshrc + source ~/.zshrc + ``` + + === "macOS / Linux (bash)" + + ```bash + echo 'alias librarian="uvx --from \"agent-library[all]==0.13.0\" librarian"' >> ~/.bashrc + source ~/.bashrc + ``` + + From here on, this guide assumes you have the `librarian` alias. If you didn't set one, just substitute the long form. + +## 2. Index a folder of notes + +Pick any folder that has text-like files — notes, markdown, PDFs, code. Let's say it's `~/notes/`. + +```bash +librarian add ~/notes +``` + +Agent Library walks the folder, parses each supported file (Markdown, code in 18 languages, PDFs, images), splits the contents into searchable chunks, and stores them in `~/.librarian/index.db`. It'll print a progress summary at the end. + +!!! note "Supported file types" + Out of the box: Markdown (`.md`), text (`.txt`), 18 programming languages (`.py`, `.js`, `.ts`, `.go`, `.rs`, etc.), PDFs, and common image formats (PNG, JPG). Other file types are skipped. + +## 3. Search it + +```bash +librarian search "what was that idea about retry policy?" +``` + +Three results print, ranked by how well they match. Each has a path, a snippet, and a relevance score from 0 to 1. + +By default this is a **hybrid search** — it combines keyword matching with semantic understanding, so "retry policy" finds notes that talk about "exponential backoff" too. + +Two other modes are available when you want them: + +```bash +librarian search "exact phrase here" --mode keyword # exact-match only +librarian search "this concept" --mode semantic # meaning-based only +``` + +## 4. List what you've indexed + +```bash +librarian list +``` + +Shows every source you've added (folders or single files) with document counts. + +--- + +## You're set + +The library now has your stuff. Next: tell your AI assistant about it. + +- [Set up Claude Desktop →](integrations/claude-desktop.md) +- [Set up Claude Code →](integrations/claude-code.md) +- [Set up Cursor →](integrations/cursor.md) + +If something didn't work, head to [Troubleshooting](troubleshooting.md). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..26d190e --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,118 @@ +# Troubleshooting + +The most common things that go wrong, and how to fix them. + +## `uv: command not found` + +The installer dropped `uv` into `~/.local/bin` (Linux/macOS) or `~/.cargo/bin` (older versions), but your terminal hasn't picked up the change yet. + +**Fix:** Close your terminal completely and reopen it. If that doesn't help, manually add the install dir to your PATH: + +```bash +export PATH="$HOME/.local/bin:$PATH" +``` + +Add that line to `~/.zshrc` or `~/.bashrc` to make it stick. + +## First run is taking forever + +The first `uvx --from "agent-library[all]==0.13.0"` invocation downloads: + +- The Agent Library package +- `sentence-transformers` and `torch` (~500 MB) +- Optional vision/code models on first search (~1 GB) + +Plan on 2–5 minutes the first time. Subsequent runs use the cached install and start in under a second. + +If it seems stuck, run with verbose output: + +```bash +uv tool install --verbose "agent-library[all]==0.13.0" +``` + +## Claude says it doesn't have any tools + +Three things to check: + +1. **Did you fully quit Claude before reopening?** A cold restart is required after editing `claude_desktop_config.json`. Close menus aren't enough — use Cmd+Q on macOS. +2. **Is the JSON valid?** Paste the whole file into to confirm. A common mistake is leaving a trailing comma after the last entry. +3. **Did the MCP subprocess crash?** Check `~/Library/Logs/Claude/mcp-server-librarian.log` (macOS) for stack traces. If you see "command not found: uvx", the issue is your PATH — see the section above. + +## "First time" timeouts inside Claude + +Claude Desktop has an internal timeout for MCP server startup. If your first run hits the ~2-minute model download, Claude may give up before the server is ready. + +**Fix:** Warm the cache once at the terminal first: + +```bash +uvx --from "agent-library[all]==0.13.0" librarian --help +``` + +Then restart Claude. The next launch will reuse the cached install. + +## "ModuleNotFoundError: No module named 'pypdf'" / 'PIL' + +You installed without the `[all]` extras. PDFs and images are skipped silently when their parsers aren't available. + +**Fix:** Reinstall with all extras: + +```bash +uv tool install --reinstall "agent-library[all]==0.13.0" +``` + +Or, in your MCP config, change `"agent-library==0.13.0"` to `"agent-library[all]==0.13.0"`. + +## Search returns nothing + +A few likely causes: + +- **You haven't indexed anything yet.** Run `librarian list` — if it's empty, run `librarian add ` first. +- **Your query is too narrow.** Try `--mode hybrid` (the default — combines semantic and keyword) and a shorter query. Also try `--type text` if you're certain the content is text-based. +- **The index is stale.** Re-run `librarian add ` to refresh. New files are picked up automatically; modified ones are re-indexed. + +## Search results look weird / irrelevant + +Try a different `--mode`: + +- `keyword` is best for exact-phrase searches. +- `semantic` is best when you want meaning matches but no token overlap. +- `hybrid` (default) blends the two. + +If hybrid results feel diluted, you can also tune `MMR_LAMBDA`: + +```bash +MMR_LAMBDA=0.9 librarian search "your query" # heavily favor relevance over diversity +MMR_LAMBDA=0.3 librarian search "your query" # heavily favor diversity (different docs) +``` + +## I want to wipe everything and start over + +```bash +rm -rf ~/.librarian +uv tool uninstall agent-library +``` + +Then reinstall via Quickstart. + +## I'm hitting permission errors writing to `~/.librarian` + +Override the location with an env var: + +```bash +DATABASE_PATH="$HOME/Documents/librarian.db" librarian add ~/notes +``` + +Set it permanently in your shell profile: + +```bash +echo 'export DATABASE_PATH="$HOME/Documents/librarian.db"' >> ~/.zshrc +``` + +--- + +Still stuck? Open an issue at with: + +1. What you ran +2. What you expected +3. What happened (full error output) +4. `librarian --version` output (run after `uv tool install agent-library`) From b17c94ec9a4f9f3593537d77ac353c348963ec84 Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:03:08 -0700 Subject: [PATCH 4/9] Build and deploy docs to GitHub Pages on push to main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Workflow runs whenever docs/, mkdocs.yml, or this workflow change. Uses the modern actions/configure-pages → actions/upload-pages-artifact → actions/deploy-pages chain (no peaceiris/gh-pages branch). Concurrency group serializes deploys so a fast follow-up commit can't race the previous build. NOTE: GitHub Pages must be enabled once for the repo with "Source = GitHub Actions" before this workflow can deploy. Settings → Pages. --- .github/workflows/docs.yml | 65 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..c56639f --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,65 @@ +name: Docs + +on: + push: + branches: [main] + paths: + - "docs/**" + - "mkdocs.yml" + - ".github/workflows/docs.yml" + workflow_dispatch: + +# GITHUB_TOKEN permissions required by actions/deploy-pages. +permissions: + contents: read + pages: write + id-token: write + +# Allow only one in-flight deploy at a time so a fast follow-up commit +# doesn't race the previous build. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + name: Build site + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v7 + with: + version: latest + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install docs dependencies + run: uv sync --extra docs + + - name: Build site (strict) + run: uv run mkdocs build --strict + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + name: Deploy to GitHub Pages + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Configure Pages + uses: actions/configure-pages@v5 + + - name: Deploy + id: deployment + uses: actions/deploy-pages@v4 From 0f56a4827cba786d22088cfee16531c488faf974 Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:14:01 -0700 Subject: [PATCH 5/9] Add Configuration docs page with model tables and how-to-change guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every env var the library reads, grouped by concern (storage, text embeddings, code embeddings, vision embeddings, OCR, image captioning, chunking, search, codebase, PDF, server, advanced tool behavior). Each variable lists default + effect. Embedding model sections have explicit tables of supported choices — text (MiniLM, mpnet, BGE small/base/large, E5 small/base/large, mxbai), code (CodeBERT base, GraphCodeBERT base), vision (CLIP B-32, B-16, L-14), image captioning (BLIP base, BLIP large) — each with HuggingFace links so users can browse model cards before switching. Page opens with how-to-change patterns (one-off shell var, permanent shell var, MCP env block in the relevant integration's config file, .env file) so a non-technical reader sees how to apply a setting in their actual setup before reading the reference. Closes the gap noted in PR #19 — the docs covered install + integration but didn't tell users how to swap the embedding model or move the database somewhere other than ~/.librarian/. --- docs/configuration.md | 321 ++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 322 insertions(+) create mode 100644 docs/configuration.md diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..4c191b3 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,321 @@ +# Configuration + +Every knob Agent Library exposes, what it does, what its default is, and **how to change it**. If you only want one or two tweaks, jump straight to [How to change a setting](#how-to-change-a-setting); the rest is reference. + +--- + +## How to change a setting + +Every setting is read from an environment variable at startup. There are three common ways to set those vars: + +=== "From the terminal (one-off)" + + Prefix any `librarian` command: + + ```bash + HYBRID_ALPHA=0.5 librarian search "deploy notes" + ``` + + Useful for testing tweaks without committing to them. + +=== "From the terminal (permanent)" + + Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.): + + ```bash + export DATABASE_PATH="$HOME/Documents/librarian.db" + export EMBEDDING_MODEL="BAAI/bge-base-en-v1.5" + ``` + + `source` the file or open a new terminal for changes to take effect. + +=== "Inside Claude Desktop / Cursor / Claude Code" + + The MCP server runs in its own subprocess that doesn't see your shell's env vars. You set them in the `env` block of the MCP config: + + ```json + { + "mcpServers": { + "librarian": { + "command": "uvx", + "args": [ + "--from", "agent-library[all]==0.13.0", + "librarian", "serve", "stdio" + ], + "env": { + "EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5", + "MMR_LAMBDA": "0.5" + } + } + } + } + ``` + + Restart Claude / Cursor after editing. + +=== "From a `.env` file" + + Drop a `.env` file in the directory you launch `librarian` from: + + ``` + EMBEDDING_MODEL=BAAI/bge-base-en-v1.5 + HYBRID_ALPHA=0.6 + DATABASE_PATH=/Users/me/work/librarian.db + ``` + + Agent Library reads it automatically on startup. + +!!! warning "All values must be strings" + JSON env blocks expect `"true"` and `"0.7"`, not `true` or `0.7`. Boolean values that count as "true": `true`, `1`, `yes`, `on` (case-insensitive). Anything else is false. + +--- + +## Storage + +| Variable | Default | What it does | +|---|---|---| +| `DATABASE_PATH` | `~/.librarian/index.db` | SQLite file with the FTS index, vectors, and document metadata | +| `DOCUMENTS_PATH` | `./documents` | Default directory used when no `path` is given to a tool | +| `SOURCES_CONFIG_PATH` | `~/.librarian/sources.json` | List of registered sources (managed by `librarian add` / `rm`) | + +Set these per-project to keep work and personal libraries separate. + +--- + +## Text embeddings + +The library uses an **embedding model** to map text into vectors so semantic search can find meaning matches. The default is fast and small; bigger models give better results at the cost of disk space and CPU. + +| Variable | Default | What it does | +|---|---|---| +| `EMBEDDING_PROVIDER` | `local` | Either `local` (sentence-transformers on your machine) or `openai` (any OpenAI-compatible endpoint) | +| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | The model to load. See the supported list below | +| `EMBEDDING_DIMENSION` | `384` | Vector dimension. Must match the chosen model — see the supported list | +| `EMBEDDING_QUERY_INSTRUCTION` | `"Given a query, return relevant information from documents."` | Used by instruction-tuned models (E5, BGE) to bias the encoding toward retrieval | + +### Supported text models + +All of these are loaded via `sentence-transformers`. To switch, set `EMBEDDING_MODEL` and `EMBEDDING_DIMENSION` to the matching pair from the table. + +| Model | Dim | Size | Notes | HF link | +|---|---|---|---|---| +| `all-MiniLM-L6-v2` *(default)* | 384 | 80 MB | Fast, decent quality, ships everywhere | [→](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) | +| `all-mpnet-base-v2` | 768 | 420 MB | The classic sentence-transformers default. Higher quality, ~5× slower | [→](https://huggingface.co/sentence-transformers/all-mpnet-base-v2) | +| `BAAI/bge-small-en-v1.5` | 384 | 130 MB | BGE small — drop-in replacement for MiniLM with stronger retrieval | [→](https://huggingface.co/BAAI/bge-small-en-v1.5) | +| `BAAI/bge-base-en-v1.5` | 768 | 440 MB | BGE base — what most retrieval benchmarks use | [→](https://huggingface.co/BAAI/bge-base-en-v1.5) | +| `BAAI/bge-large-en-v1.5` | 1024 | 1.3 GB | BGE large — best quality of this family, slowest | [→](https://huggingface.co/BAAI/bge-large-en-v1.5) | +| `intfloat/e5-small-v2` | 384 | 130 MB | E5 small — strong retrieval baseline | [→](https://huggingface.co/intfloat/e5-small-v2) | +| `intfloat/e5-base-v2` | 768 | 440 MB | E5 base | [→](https://huggingface.co/intfloat/e5-base-v2) | +| `intfloat/e5-large-v2` | 1024 | 1.3 GB | E5 large | [→](https://huggingface.co/intfloat/e5-large-v2) | +| `mixedbread-ai/mxbai-embed-large-v1` | 1024 | 1.3 GB | Newer model with strong English retrieval scores | [→](https://huggingface.co/mixedbread-ai/mxbai-embed-large-v1) | + +!!! danger "Re-index when you change models" + Vectors from one model can't be searched with another. After switching `EMBEDDING_MODEL`, delete `~/.librarian/index.db` and re-run `librarian add ...` so your existing content is re-embedded. + +### Using OpenAI-compatible APIs + +If you'd rather offload embedding to a hosted service (OpenAI, vLLM, llama.cpp's server, etc.), switch the provider: + +| Variable | Default | What it does | +|---|---|---| +| `EMBEDDING_PROVIDER` | `local` | Set to `openai` | +| `OPENAI_API_BASE` | `http://localhost:7171/v1` | Endpoint URL (point at OpenAI, vLLM, llama.cpp, etc.) | +| `OPENAI_API_KEY` | `not-needed` | Your API key (or `not-needed` for local servers that don't auth) | +| `OPENAI_EMBEDDING_MODEL` | `qwen3-embedding-06b` | Model identifier the endpoint serves | +| `OPENAI_EMBEDDING_DIMENSION` | `1024` | Vector dimension for that model | +| `OPENAI_EMBEDDING_BATCH_SIZE` | `64` | How many texts to embed per API call | + +--- + +## Code embeddings + +When `ENABLE_CODE_EMBEDDINGS=true` (the default), source code files are embedded with a code-specific model in addition to the regular text embedder. This makes "find the function that handles retries" work even when "retry" isn't in the comments. + +| Variable | Default | What it does | +|---|---|---| +| `ENABLE_CODE_EMBEDDINGS` | `true` | Turn the code path on/off | +| `CODE_EMBEDDING_MODEL` | `microsoft/codebert-base` | The code embedding model | +| `CODE_EMBEDDING_DIMENSION` | `768` | Vector dimension | +| `CODE_EMBEDDING_PROVIDER` | `local` | `local` or `openai` | + +### Supported code models + +The code path activates when the model name contains `codebert` or `codellama`. Any other model falls back to the regular text path. + +| Model | Dim | Size | Notes | HF link | +|---|---|---|---|---| +| `microsoft/codebert-base` *(default)* | 768 | 500 MB | Multi-language, balanced speed/quality | [→](https://huggingface.co/microsoft/codebert-base) | +| `microsoft/graphcodebert-base` | 768 | 500 MB | Better at structural code matches (data flow / graph aware) | [→](https://huggingface.co/microsoft/graphcodebert-base) | + +!!! tip "Don't have any code in your library?" + Set `ENABLE_CODE_EMBEDDINGS=false` to skip loading the model entirely. Saves ~500 MB and a couple seconds at startup. + +--- + +## Vision embeddings + +Image files (PNG, JPG, GIF, WEBP) get a separate visual embedding so semantic search works across diagrams and screenshots. This uses CLIP — a model that maps images and text into the same vector space, so a query like "auth flow" finds matching diagrams. + +| Variable | Default | What it does | +|---|---|---| +| `ENABLE_VISION_EMBEDDINGS` | `true` | Turn the vision path on/off | +| `VISION_EMBEDDING_MODEL` | `clip-ViT-B-32` | The CLIP-family model | +| `VISION_EMBEDDING_DIMENSION` | `512` | Vector dimension | + +### Supported vision models + +The vision path activates when the model name contains `clip` or `siglip`. + +| Model | Dim | Size | Notes | HF link | +|---|---|---|---|---| +| `clip-ViT-B-32` *(default)* | 512 | 600 MB | Original CLIP base, fast | [→](https://huggingface.co/sentence-transformers/clip-ViT-B-32) | +| `clip-ViT-B-16` | 512 | 600 MB | Higher resolution patches than B-32 — slightly better, slightly slower | [→](https://huggingface.co/sentence-transformers/clip-ViT-B-16) | +| `clip-ViT-L-14` | 768 | 1.7 GB | Large CLIP — best image quality, expensive | [→](https://huggingface.co/sentence-transformers/clip-ViT-L-14) | +| `clip-ViT-L-14-336` | 768 | 1.7 GB | L-14 finetuned for higher input resolution | [→](https://huggingface.co/sentence-transformers/clip-ViT-L-14-336) | + +!!! tip "Indexing screenshots only?" + `clip-ViT-B-32` is plenty. The L-14 variants only pay off with photographic content where fine detail matters. + +--- + +## OCR (extracting text from images) + +Tesseract-based OCR runs over indexed images so the text inside a screenshot is still searchable. + +| Variable | Default | What it does | +|---|---|---| +| `ENABLE_OCR` | `true` | Toggle OCR on indexed images | +| `OCR_LANGUAGE` | `eng` | Tesseract language code(s). Multiple langs use `+` (e.g. `eng+spa`) | +| `OCR_CONFIG` | `--psm 3` | Tesseract page-segmentation mode | +| `OCR_MIN_CONFIDENCE` | `0` | Drop OCR'd text below this confidence (0–100, 0 = no filter) | + +OCR requires `tesseract` installed on the system (separate from Python deps): `brew install tesseract` on macOS, `apt install tesseract-ocr` on Debian/Ubuntu. + +--- + +## Image captioning (optional) + +When enabled, every indexed image also gets a free-text caption generated by an image-to-text model. Off by default since most users don't need it. + +| Variable | Default | What it does | +|---|---|---| +| `IMAGE_GENERATE_CAPTIONS` | `false` | Turn captioning on | +| `IMAGE_CAPTION_MODEL` | `blip-base` | The captioning model | + +| Model | Notes | HF link | +|---|---|---| +| `Salesforce/blip-image-captioning-base` *(default — `blip-base` is the short alias)* | BLIP base; fast, decent captions | [→](https://huggingface.co/Salesforce/blip-image-captioning-base) | +| `Salesforce/blip-image-captioning-large` | BLIP large; slower, better captions | [→](https://huggingface.co/Salesforce/blip-image-captioning-large) | + +--- + +## Chunking + +How documents get split into searchable chunks before indexing. + +| Variable | Default | What it does | +|---|---|---| +| `CHUNK_SIZE` | `512` | Target chunk length in tokens (≈ words) | +| `CHUNK_OVERLAP` | `50` | Tokens of overlap between adjacent chunks (preserves context across boundaries) | +| `MIN_CHUNK_SIZE` | `50` | Drop chunks shorter than this | +| `CODE_CHUNK_STRATEGY` | `code_blocks` | `code_blocks` (split by function/class) or `fixed` (fixed size) | +| `CODE_INCLUDE_CONTEXT` | `true` | Include surrounding lines as context when chunking code | +| `CODE_CONTEXT_LINES` | `5` | How many context lines on each side | +| `PDF_CHUNK_STRATEGY` | `pages` | `pages` (one chunk per page) or `sections` (split by headings) | + +!!! tip "Larger chunks = more context per result, fewer results overall" + Bumping `CHUNK_SIZE` to 1024 makes each result longer but reduces the total number of chunks. Good for technical docs where context matters; bad for short notes where you want fine-grained matching. + +--- + +## Search behavior + +| Variable | Default | What it does | +|---|---|---| +| `SEARCH_LIMIT` | `10` | Default result count | +| `HYBRID_ALPHA` | `0.7` | In hybrid mode, the blend: `alpha · vector_score + (1 - alpha) · keyword_score`. Higher = more semantic | +| `MMR_LAMBDA` | `0.7` | Maximal Marginal Relevance: `lambda · relevance - (1 - lambda) · max_similarity_to_already_picked`. Higher = relevance-focused, lower = diverse | +| `ENABLE_CROSS_MODAL_SEARCH` | `true` | Search text + code + image vectors in parallel and merge fairly | +| `CROSS_MODAL_SIMILARITY_THRESHOLD` | `0.7` | Drop cross-modal matches below this similarity | +| `MODALITY_WEIGHT_TEXT` | `1.0` | Per-modality weight in the cross-modal merge | +| `MODALITY_WEIGHT_CODE` | `1.0` | | +| `MODALITY_WEIGHT_VISION` | `1.0` | | +| `MODALITY_WEIGHT_FTS` | `1.0` | Keyword search modality weight | + +!!! tip "Tuning the search" + - **Results feel scattered?** Lower `MMR_LAMBDA` toward 0.3 to push for more diverse top-K, or raise it toward 0.9 to lock in on the most relevant. + - **Hybrid is missing exact-keyword matches?** Lower `HYBRID_ALPHA` toward 0.3 to weight keyword score higher. + - **Code matches dominating text matches?** Lower `MODALITY_WEIGHT_CODE` to 0.5. + +--- + +## Codebase indexing + +| Variable | Default | What it does | +|---|---|---| +| `CODEBASE_AUTO_DETECT` | `true` | Detect language from file extensions automatically | +| `CODEBASE_INDEX_TESTS` | `true` | Include `tests/` and `*_test.*` files | +| `CODEBASE_MAX_FILE_SIZE_KB` | `500` | Skip files larger than this | +| `DEFAULT_ASSET_TYPES` | `text,code` | Comma-separated asset types to index by default | + +--- + +## PDF processing + +| Variable | Default | What it does | +|---|---|---| +| `ENABLE_PDF_PROCESSING` | `true` | Toggle PDF parsing | +| `PDF_OCR_ENABLED` | `false` | Run OCR on PDF pages (slow; only useful for scanned PDFs without an embedded text layer) | + +--- + +## Server + +| Variable | Default | What it does | +|---|---|---| +| `LIBRARIAN_HOST` | `127.0.0.1` | HTTP transport bind address | +| `LIBRARIAN_PORT` | `8000` | HTTP transport port | +| `LIBRARIAN_ENABLE_OPTIONAL_TOOLS` | `true` | Whether `get_library_overview` and `suggest_library_location` are advertised | + +--- + +## Tool behavior (advanced) + +| Variable | Default | What it does | +|---|---|---| +| `TOOL_SEARCH_DEFAULT_LIMIT` | `10` | Default `limit` arg when the AI calls `search_library` without specifying | +| `TOOL_MAX_CONTEXT_LINES` | `10` | Max lines of context surfaced in tool output | +| `CODE_MAX_DEPENDENCY_DEPTH` | `3` | Max depth for code dependency walks | +| `CODE_MAX_REFERENCES` | `50` | Max references returned per query | +| `INDEX_POLL_INTERVAL` | `60.0` | Seconds between background re-index polls | +| `INDEX_START_DELAY` | `5.0` | Seconds before the first background poll on startup | + +--- + +## Putting it together — a real example + +Say you want a project-specific library that uses a stronger embedder, weights keyword matches higher than the default, and lives next to your code rather than in `~/.librarian/`. Add this to your Cursor `mcp.json` or Claude Desktop config: + +```json +{ + "mcpServers": { + "librarian": { + "command": "uvx", + "args": [ + "--from", "agent-library[all]==0.13.0", + "librarian", "serve", "stdio" + ], + "env": { + "DATABASE_PATH": "${workspaceFolder}/.librarian/index.db", + "DOCUMENTS_PATH": "${workspaceFolder}", + "EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5", + "EMBEDDING_DIMENSION": "768", + "HYBRID_ALPHA": "0.5", + "ENABLE_VISION_EMBEDDINGS": "false" + } + } + } +} +``` + +After saving, reload Cursor (or restart Claude). Index once with `librarian add .` — and your AI now searches that project's content with the stronger model. diff --git a/mkdocs.yml b/mkdocs.yml index b509061..c392ef7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,6 +73,7 @@ nav: - Claude Code (CLI): integrations/claude-code.md - Cursor: integrations/cursor.md - CLI reference: cli.md + - Configuration: configuration.md - Concepts: concepts.md - Troubleshooting: troubleshooting.md From 1d215dd405613814236f0f0516a1e00f8712ad05 Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:22:48 -0700 Subject: [PATCH 6/9] Use `uv tool install` for terminal usage; keep `uvx` for MCP configs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Quickstart was suggesting users add a shell alias to shorten `uvx --from "agent-library[all]==0.13.0" librarian`. `uv tool install` is cleaner: one command and `librarian` is on PATH like any other CLI tool. Verified end-to-end: the binary lands at ~/.local/bin/librarian and runs. Integration pages keep `uvx --from ...` as the default MCP `command` because GUI desktop apps don't inherit shell PATH on macOS (launchd strips it). Each page now has an "Already ran `uv tool install`?" tip showing the simpler form — absolute path for GUI desktop hosts, plain `librarian` for terminal-launched hosts that inherit PATH. Troubleshooting page references switched from the alias-style invocation to the new install command for the warm-the-cache step. --- docs/integrations/claude-code.md | 12 ++++++++++ docs/integrations/claude-desktop.md | 12 ++++++++++ docs/integrations/cursor.md | 12 ++++++++++ docs/quickstart.md | 34 ++++++++++++++--------------- docs/troubleshooting.md | 5 +++-- 5 files changed, 56 insertions(+), 19 deletions(-) diff --git a/docs/integrations/claude-code.md b/docs/integrations/claude-code.md index 892194b..97d4bc3 100644 --- a/docs/integrations/claude-code.md +++ b/docs/integrations/claude-code.md @@ -43,6 +43,18 @@ You should see `librarian` listed. } ``` +??? tip "Already ran `uv tool install`?" + Claude Code is a terminal app, so it inherits your shell `PATH`. That means once you've done `uv tool install`, the simpler form works too: + + ```json + "librarian": { + "command": "librarian", + "args": ["serve", "stdio"] + } + ``` + + `uvx` is still our default in the docs because it's hermetic and doesn't depend on the install state. + ## Use it Start (or restart) Claude Code. In your conversation: diff --git a/docs/integrations/claude-desktop.md b/docs/integrations/claude-desktop.md index 2ace1bb..8a04e6e 100644 --- a/docs/integrations/claude-desktop.md +++ b/docs/integrations/claude-desktop.md @@ -70,6 +70,18 @@ If the file already has content, just add the `"librarian": { ... }` block insid Save the file. +??? tip "Already ran `uv tool install`?" + If you went through the [Quickstart](../quickstart.md) and installed Agent Library globally with `uv tool install`, you can swap the `uvx` form for the installed binary directly. **You'll need to use the absolute path** because Claude Desktop is launched by macOS's `launchd` and doesn't inherit your terminal's `PATH`: + + ```json + "librarian": { + "command": "/Users/YOUR-USERNAME/.local/bin/librarian", + "args": ["serve", "stdio"] + } + ``` + + Find your absolute path with `which librarian` in the terminal. The `uvx` form doesn't have this caveat, which is why we recommend it as the default. + ## 3. Restart Claude Desktop Quit Claude entirely (right-click the dock icon → Quit, or Cmd+Q) and reopen it. Claude only re-reads the config on launch. diff --git a/docs/integrations/cursor.md b/docs/integrations/cursor.md index 2df6d32..6599b93 100644 --- a/docs/integrations/cursor.md +++ b/docs/integrations/cursor.md @@ -36,6 +36,18 @@ If the file is empty or freshly skeletoned, paste this: If you already have other MCP servers in there, add `"librarian"` as another key under `mcpServers`. Save the file. +??? tip "Already ran `uv tool install`?" + Cursor inherits more of your environment than Claude Desktop, so the simpler form usually works once you've installed the binary globally: + + ```json + "librarian": { + "command": "librarian", + "args": ["serve", "stdio"] + } + ``` + + If Cursor reports "command not found", switch back to the `uvx` form above (or use the absolute path from `which librarian`). + ## 3. Reload Cursor Either fully quit and reopen Cursor, or run **"Developer: Reload Window"** from the command palette. Cursor re-reads `mcp.json` on each reload. diff --git a/docs/quickstart.md b/docs/quickstart.md index 344692b..5a6938d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -5,36 +5,36 @@ Five minutes from zero to "my AI can search my notes". You'll do all of this fro !!! note "Before you start" Make sure `uv --version` works in your terminal. If not, do **[Install uv](install.md)** first (one command). -## 1. Run Agent Library for the first time +## 1. Install Agent Library Paste this into your terminal: ```bash -uvx --from "agent-library[all]==0.13.0" librarian --help +uv tool install "agent-library[all]==0.13.0" ``` -The first time you run this it'll spend a couple minutes downloading the Python package and its language models (~2 GB total). You only pay this cost **once** — `uv` caches everything afterward. +This installs Agent Library as a regular command on your machine — like installing any other CLI tool. The first run downloads the Python package and its language models (~2 GB total). You only pay this cost **once**; `uv` caches everything afterward. -When it finishes you'll see a help menu listing commands like `add`, `search`, `serve`. That confirms it's working. +Verify it worked: -!!! tip "Make this command shorter" - Typing `uvx --from "agent-library[all]==0.13.0" librarian` every time is annoying. Add an alias to your shell: +```bash +librarian --help +``` - === "macOS / Linux (zsh)" +You should see a help menu listing commands like `add`, `search`, `serve`. From here on, you just type `librarian ...` like any other terminal tool. - ```bash - echo 'alias librarian="uvx --from \"agent-library[all]==0.13.0\" librarian"' >> ~/.zshrc - source ~/.zshrc - ``` +!!! tip "Updating later" + To pick up a new release: - === "macOS / Linux (bash)" + ```bash + uv tool upgrade agent-library + ``` - ```bash - echo 'alias librarian="uvx --from \"agent-library[all]==0.13.0\" librarian"' >> ~/.bashrc - source ~/.bashrc - ``` + To remove it: - From here on, this guide assumes you have the `librarian` alias. If you didn't set one, just substitute the long form. + ```bash + uv tool uninstall agent-library + ``` ## 2. Index a folder of notes diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 26d190e..58c98e1 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -16,7 +16,7 @@ Add that line to `~/.zshrc` or `~/.bashrc` to make it stick. ## First run is taking forever -The first `uvx --from "agent-library[all]==0.13.0"` invocation downloads: +The first `uv tool install "agent-library[all]==0.13.0"` (or `uvx ...` invocation) downloads: - The Agent Library package - `sentence-transformers` and `torch` (~500 MB) @@ -45,7 +45,8 @@ Claude Desktop has an internal timeout for MCP server startup. If your first run **Fix:** Warm the cache once at the terminal first: ```bash -uvx --from "agent-library[all]==0.13.0" librarian --help +uv tool install "agent-library[all]==0.13.0" +librarian --help ``` Then restart Claude. The next launch will reuse the cached install. From 7f89a798b9018050aa86422569b906bb07c7ed13 Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:31:58 -0700 Subject: [PATCH 7/9] Audit fixes: verified every doc claim against source and live binary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each issue below was caught by running the actual command, parsing config.py / types.py for ground truth, or curl-checking external links. The PR previously contained user-facing inaccuracies; this commit corrects them. cli.md - librarian add: documented missing flags --exclude / --dry-run / --verbose (verified against `librarian add --help`) - New sections enumerating `librarian config`, `librarian index`, and `librarian docs` subcommand groups (all verified via --help) configuration.md - Added `librarian config set/get/edit/show/path/reset/models` flow as the recommended way to persist config changes — settings.json was a major missing piece. Includes precedence ordering. - Removed the `clip-ViT-L-14-336` row — the model doesn't exist under sentence-transformers/ (returns 401). Every other HF link verified with `curl -I` -> 200. terminal AI client integration page - Replaced fictional `--command/--args` flags for the `mcp add` subcommand with the real form: `mcp add NAME -- COMMAND ARGS...` using the `--` separator. Verified end-to-end: the subcommand registered the server, the host reported "✓ Connected", removal worked. - Default scope is `local` (not `user`); choices are local|user|project (3, not 2). Documented all three with their on-disk locations. - Env-var flag is `-e KEY=VALUE` (single equals, not `--env "K=V"`). IDE AI client integration page - Softened the unverifiable IDE-version claim to "a version with built-in MCP support". concepts.md - AssetType list now includes the 5th value (multimodal) with a note that no parser currently emits it but it's accepted as a filter. troubleshooting.md - "Wipe and start over" now mentions settings.json gets cleared too. - Added `librarian config reset` as the lighter alternative. --- docs/cli.md | 45 +++++++++++++++++++++++---- docs/concepts.md | 1 + docs/configuration.md | 52 +++++++++++++++++++++++--------- docs/integrations/claude-code.md | 40 ++++++++++++------------ docs/integrations/cursor.md | 2 +- docs/troubleshooting.md | 10 ++++-- 6 files changed, 108 insertions(+), 42 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 749537f..8348be9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -26,13 +26,19 @@ librarian add ~/notes | `-n NAME` / `--name` | Give the source a friendly name (defaults to the directory name) | | `-d N` / `--depth` | Limit recursion. `0` = the directory itself only. Default: unlimited | | `-p PATTERN` / `--pattern` | Glob filter (e.g. `'notes/*.md'`) | +| `-e PATTERN` / `--exclude` | Glob to skip. Can be passed multiple times | +| `--dry-run` | Show what would be indexed without doing anything | +| `-v` / `--verbose` | Print every file as it's indexed | ```bash # Index just the top-level files of a folder librarian add ~/notes --depth 0 -# Index only Python files in a project -librarian add ~/code/myproject --pattern '**/*.py' +# Index only Python files in a project, excluding tests +librarian add ~/code/myproject --pattern '**/*.py' --exclude '**/tests/**' + +# Preview without writing +librarian add ~/notes --dry-run ``` --- @@ -131,13 +137,40 @@ librarian serve http --port 7878 # for HTTP-based MCP clients Three command groups bundle less-common operations: +### `librarian config` + +The most useful of the three. **Persist config changes** to `~/.librarian/settings.json` so they survive across sessions: + ```bash -librarian index --help # index inspection / rebuild operations -librarian docs --help # per-document operations (read, update, remove single docs) -librarian config --help # show or change configuration values +librarian config show # table of every setting with source attribution +librarian config get HYBRID_ALPHA # one value +librarian config set HYBRID_ALPHA 0.5 +librarian config path # show the four config-file locations +librarian config edit # open settings.json in your editor +librarian config models # check / download embedding models +librarian config reset # back to defaults ``` -These are in the help output but used less often than the top-level commands above. +See [Configuration](configuration.md) for the full list of settable keys. + +### `librarian index` + +Lower-level index operations: + +```bash +librarian index build # rebuild the entire index from scratch +librarian index clean # remove all indexed data (keeps sources list) +librarian index clobber # remove everything and reinitialize the database +``` + +### `librarian docs` + +Per-document operations: + +```bash +librarian docs list # list every indexed document +librarian docs search "title text" # search by title only (not contents) +``` --- diff --git a/docs/concepts.md b/docs/concepts.md index c8a8c7c..a4e0dd9 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -12,6 +12,7 @@ Agent Library tags every file with an **asset type**: | `code` | Source code (Python, JS, TS, Go, Rust, …) | regex-based symbol extractor | | `pdf` | PDF documents | requires `pypdf` (in `[all]` extras) | | `image` | PNG, JPG, GIF, WEBP | requires `Pillow` (in `[all]` extras) | +| `multimodal` | Reserved for documents that mix modalities (none of today's parsers emit this — but the enum value exists for forward compatibility, and `--asset_type=multimodal` is accepted as a filter) | — | When you search, the asset type is preserved on every result. You can filter on it: diff --git a/docs/configuration.md b/docs/configuration.md index 4c191b3..fc86fc9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -6,32 +6,41 @@ Every knob Agent Library exposes, what it does, what its default is, and **how t ## How to change a setting -Every setting is read from an environment variable at startup. There are three common ways to set those vars: +There are four ways to apply a setting. Pick the one that matches your situation. -=== "From the terminal (one-off)" +=== "`librarian config set` (recommended)" - Prefix any `librarian` command: + The simplest path. Settings are persisted to `~/.librarian/settings.json` and survive across sessions: ```bash - HYBRID_ALPHA=0.5 librarian search "deploy notes" + librarian config set EMBEDDING_MODEL "BAAI/bge-base-en-v1.5" + librarian config set EMBEDDING_DIMENSION 768 + librarian config set HYBRID_ALPHA 0.5 + ``` + + Inspect the current state: + + ```bash + librarian config show # table of every setting + where each came from + librarian config get HYBRID_ALPHA + librarian config path # show the four config-file paths + librarian config edit # open settings.json in your editor + librarian config reset # back to defaults ``` - Useful for testing tweaks without committing to them. + Restart `librarian serve` (or your AI client) after changing anything. -=== "From the terminal (permanent)" +=== "From the terminal (one-off)" - Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.): + Prefix any `librarian` command with an env var. Useful for trying a setting without committing to it: ```bash - export DATABASE_PATH="$HOME/Documents/librarian.db" - export EMBEDDING_MODEL="BAAI/bge-base-en-v1.5" + HYBRID_ALPHA=0.5 librarian search "deploy notes" ``` - `source` the file or open a new terminal for changes to take effect. - === "Inside Claude Desktop / Cursor / Claude Code" - The MCP server runs in its own subprocess that doesn't see your shell's env vars. You set them in the `env` block of the MCP config: + The MCP server is a subprocess, so settings the AI host should know about live in the `env` block of the MCP config: ```json { @@ -44,6 +53,7 @@ Every setting is read from an environment variable at startup. There are three c ], "env": { "EMBEDDING_MODEL": "BAAI/bge-base-en-v1.5", + "EMBEDDING_DIMENSION": "768", "MMR_LAMBDA": "0.5" } } @@ -65,7 +75,22 @@ Every setting is read from an environment variable at startup. There are three c Agent Library reads it automatically on startup. -!!! warning "All values must be strings" +=== "Permanent shell var" + + Less recommended (env is invisible to GUI apps), but works if everything you care about is terminal-only. Add to `~/.zshrc` or `~/.bashrc`: + + ```bash + export DATABASE_PATH="$HOME/Documents/librarian.db" + export EMBEDDING_MODEL="BAAI/bge-base-en-v1.5" + ``` + +!!! info "Precedence (highest wins)" + 1. Process env vars (`HYBRID_ALPHA=0.5 librarian ...`) + 2. `.env` file in CWD + 3. `librarian config set` (in `~/.librarian/settings.json`) + 4. Built-in defaults + +!!! warning "All values must be strings inside JSON" JSON env blocks expect `"true"` and `"0.7"`, not `true` or `0.7`. Boolean values that count as "true": `true`, `1`, `yes`, `on` (case-insensitive). Anything else is false. --- @@ -171,7 +196,6 @@ The vision path activates when the model name contains `clip` or `siglip`. | `clip-ViT-B-32` *(default)* | 512 | 600 MB | Original CLIP base, fast | [→](https://huggingface.co/sentence-transformers/clip-ViT-B-32) | | `clip-ViT-B-16` | 512 | 600 MB | Higher resolution patches than B-32 — slightly better, slightly slower | [→](https://huggingface.co/sentence-transformers/clip-ViT-B-16) | | `clip-ViT-L-14` | 768 | 1.7 GB | Large CLIP — best image quality, expensive | [→](https://huggingface.co/sentence-transformers/clip-ViT-L-14) | -| `clip-ViT-L-14-336` | 768 | 1.7 GB | L-14 finetuned for higher input resolution | [→](https://huggingface.co/sentence-transformers/clip-ViT-L-14-336) | !!! tip "Indexing screenshots only?" `clip-ViT-B-32` is plenty. The L-14 variants only pay off with photographic content where fine detail matters. diff --git a/docs/integrations/claude-code.md b/docs/integrations/claude-code.md index 97d4bc3..732a788 100644 --- a/docs/integrations/claude-code.md +++ b/docs/integrations/claude-code.md @@ -9,16 +9,13 @@ Claude Code is the terminal-based version of Claude. It uses the same MCP server ## Add Agent Library -Claude Code has a one-line command to register an MCP server. From any directory: +Claude Code has a one-line command to register an MCP server. The `--` separator tells Claude where the command-and-args to invoke begin: ```bash -claude mcp add librarian \ - --command "uvx" \ - --args "--from" --args "agent-library[all]==0.13.0" \ - --args "librarian" --args "serve" --args "stdio" +claude mcp add librarian -- uvx --from "agent-library[all]==0.13.0" librarian serve stdio ``` -That writes the entry into `~/.claude/settings.json` (or your project-local equivalent). Verify: +That writes the entry into `~/.claude.json` (or your project-local equivalent depending on `--scope`). Verify: ```bash claude mcp list @@ -63,28 +60,33 @@ Start (or restart) Claude Code. In your conversation: The first response triggers the MCP tool. You'll be prompted to allow `Librarian_SearchLibrary` — accept it once and Claude Code remembers. -## Project-scoped vs. user-scoped +## Scope: local, project, or user + +`claude mcp add` accepts a `--scope` flag (default: `local`): + +| Scope | Where it's stored | When you'd use it | +|---|---|---| +| `local` *(default)* | `.claude.json` for the current project — only you see it | Trying things out, personal experiments | +| `project` | `.mcp.json` at the repo root, checked into git | Sharing a server config with the whole team | +| `user` | `~/.claude.json` — visible from every directory | One library you use across all your projects | -By default the entry above goes into your **user-level** Claude config so it's available from every directory. If you'd rather have a per-project Agent Library (different index for different projects), pass `--scope local`: +For a personal library available everywhere: ```bash -claude mcp add librarian --scope local \ - --command "uvx" \ - --args "--from" --args "agent-library[all]==0.13.0" \ - --args "librarian" --args "serve" --args "stdio" +claude mcp add librarian --scope user -- uvx --from "agent-library[all]==0.13.0" librarian serve stdio ``` -That writes to `.claude/settings.json` next to your project, and you can point at a project-specific database: +For a project-specific library with its own database: ```bash -claude mcp add librarian --scope local \ - --command "uvx" \ - --args "--from" --args "agent-library[all]==0.13.0" \ - --args "librarian" --args "serve" --args "stdio" \ - --env "DATABASE_PATH=$(pwd)/.librarian/index.db" \ - --env "DOCUMENTS_PATH=$(pwd)" +claude mcp add librarian \ + -e "DATABASE_PATH=$(pwd)/.librarian/index.db" \ + -e "DOCUMENTS_PATH=$(pwd)" \ + -- uvx --from "agent-library[all]==0.13.0" librarian serve stdio ``` +Pass `-e KEY=VALUE` once per env var (it can be repeated). + ## Removing it ```bash diff --git a/docs/integrations/cursor.md b/docs/integrations/cursor.md index 6599b93..a8cc4c0 100644 --- a/docs/integrations/cursor.md +++ b/docs/integrations/cursor.md @@ -5,7 +5,7 @@ Cursor supports MCP servers natively as of late 2024. Hooking up Agent Library l ## Prerequisites - You ran the [Quickstart](../quickstart.md) and have at least one folder indexed. -- Cursor 0.45 or newer (MCP support shipped in that release). +- A version of Cursor with built-in MCP support (visible as a **MCP** tab in Settings). ## 1. Open the MCP settings diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 58c98e1..7d2d375 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -89,11 +89,17 @@ MMR_LAMBDA=0.3 librarian search "your query" # heavily favor diversity (differ ## I want to wipe everything and start over ```bash -rm -rf ~/.librarian +rm -rf ~/.librarian # database, sources list, settings.json uv tool uninstall agent-library ``` -Then reinstall via Quickstart. +Then reinstall via [Quickstart](quickstart.md). + +To reset just configuration (keeping your indexed content): + +```bash +librarian config reset +``` ## I'm hitting permission errors writing to `~/.librarian` From 57960a65a1506e76d532b5888b494f46566cb7cb Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:42:54 -0700 Subject: [PATCH 8/9] =?UTF-8?q?Brand=20the=20docs=20site=20to=20match=20ar?= =?UTF-8?q?cade.dev=20=E2=80=94=20dark=20theme=20+=20cyan=20accent?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pulled the actual brand colors and the wordmark logo from arcade.dev itself so the docs site visually fits the rest of the product. Theme defaults flipped: dark slate is now the primary experience (matches arcade.dev's dark-first aesthetic), with a sun-icon toggle to switch to a light scheme that keeps the same accent. Material's built-in palettes (`primary: black`, `accent: cyan`) handle the high- level scheme; the exact hex values come from a custom stylesheet at docs/assets/extra.css that targets the per-scheme CSS variables. Brand tokens applied: - background #0f0f0f (page) - raised surface #1a1a2e (code blocks, search bar) - accent #00e0e0 (links, hover, code spans, focus rings) - foreground #ffffff Logo (white SVG wordmark) and favicon (32x32 JPEG) are copied directly from arcade.dev's CDN paths so they always match what marketing ships. Custom CSS rules also retint admonitions (note/tip/info → cyan border + tinted title bar) and code spans (cyan-on-navy) so the brand color shows up in the most-read parts of the docs. Strict build still clean; no broken links or missing references. --- docs/assets/extra.css | 130 ++++++++++++++++++++++++++++++++++++++++ docs/assets/favicon.jpg | Bin 0 -> 2873 bytes docs/assets/logo.svg | 15 +++++ mkdocs.yml | 27 ++++++--- 4 files changed, 163 insertions(+), 9 deletions(-) create mode 100644 docs/assets/extra.css create mode 100644 docs/assets/favicon.jpg create mode 100644 docs/assets/logo.svg diff --git a/docs/assets/extra.css b/docs/assets/extra.css new file mode 100644 index 0000000..23f5507 --- /dev/null +++ b/docs/assets/extra.css @@ -0,0 +1,130 @@ +/* + * Agent Library docs — Arcade brand overrides. + * + * Brand palette pulled directly from arcade.dev: + * - background: #0f0f0f (near-black, primary) + * - surface: #1a1a2e (dark navy, raised) + * - accent: #00e0e0 (signature cyan) + * - foreground: #ffffff + */ + +:root { + --arcade-cyan: #00e0e0; + --arcade-cyan-dim: #00b0b0; + --arcade-bg: #0f0f0f; + --arcade-surface: #1a1a2e; + --arcade-surface-2: #232342; + --arcade-fg: #ffffff; + --arcade-fg-muted: #c8c8d4; +} + +/* Dark scheme — primary brand experience. */ +[data-md-color-scheme="slate"] { + --md-default-bg-color: var(--arcade-bg); + --md-default-bg-color--light: var(--arcade-surface); + --md-default-fg-color: var(--arcade-fg); + --md-default-fg-color--light: var(--arcade-fg-muted); + --md-default-fg-color--lighter: rgba(255, 255, 255, 0.6); + --md-default-fg-color--lightest: rgba(255, 255, 255, 0.07); + + --md-primary-fg-color: var(--arcade-bg); + --md-primary-fg-color--light: var(--arcade-surface); + --md-primary-fg-color--dark: #050505; + --md-primary-bg-color: var(--arcade-fg); + --md-primary-bg-color--light: var(--arcade-fg-muted); + + --md-accent-fg-color: var(--arcade-cyan); + --md-accent-fg-color--transparent: rgba(0, 224, 224, 0.12); + --md-accent-bg-color: var(--arcade-bg); + + --md-code-bg-color: var(--arcade-surface); + --md-code-fg-color: var(--arcade-fg); + --md-code-hl-color: rgba(0, 224, 224, 0.18); + --md-code-hl-keyword-color: var(--arcade-cyan); + --md-code-hl-string-color: #c4ff8a; + + --md-typeset-a-color: var(--arcade-cyan); + + --md-footer-bg-color: var(--arcade-bg); + --md-footer-bg-color--dark: #050505; +} + +/* Light scheme — keep the cyan accent, white background, near-black text. */ +[data-md-color-scheme="default"] { + --md-primary-fg-color: var(--arcade-bg); + --md-primary-fg-color--light: var(--arcade-surface); + --md-primary-fg-color--dark: #050505; + --md-primary-bg-color: var(--arcade-fg); + + --md-accent-fg-color: var(--arcade-cyan-dim); + --md-accent-fg-color--transparent: rgba(0, 176, 176, 0.12); + + --md-typeset-a-color: var(--arcade-cyan-dim); + + --md-footer-bg-color: var(--arcade-bg); + --md-footer-bg-color--dark: #050505; +} + +/* Header tweaks: slightly darker than page background, hairline accent border. */ +.md-header { + background-color: var(--arcade-bg); + border-bottom: 1px solid rgba(0, 224, 224, 0.18); +} + +/* Logo: enforce a fixed height so the SVG wordmark doesn't dominate. */ +.md-header__button.md-logo img, +.md-header__button.md-logo svg { + height: 1.5rem; + width: auto; +} + +/* Brighter cyan on hover for nav links + table-of-contents items. */ +[data-md-color-scheme="slate"] .md-nav__link:hover, +[data-md-color-scheme="slate"] .md-nav__link.md-nav__link--active { + color: var(--arcade-cyan); +} + +/* Code blocks: match the navy surface tone. */ +[data-md-color-scheme="slate"] .md-typeset code { + background-color: var(--arcade-surface-2); + color: var(--arcade-cyan); + border-radius: 3px; +} +[data-md-color-scheme="slate"] .md-typeset pre > code { + background-color: var(--arcade-surface); + color: var(--arcade-fg); +} + +/* Admonitions: tint the title bar with cyan for note/tip; keep warning/danger. */ +[data-md-color-scheme="slate"] .md-typeset .admonition.note, +[data-md-color-scheme="slate"] .md-typeset .admonition.tip, +[data-md-color-scheme="slate"] .md-typeset .admonition.info { + border-color: var(--arcade-cyan); +} +[data-md-color-scheme="slate"] .md-typeset .admonition.note > .admonition-title, +[data-md-color-scheme="slate"] .md-typeset .admonition.tip > .admonition-title, +[data-md-color-scheme="slate"] .md-typeset .admonition.info > .admonition-title { + background-color: rgba(0, 224, 224, 0.15); +} + +/* Buttons: cyan accent, dark text. */ +[data-md-color-scheme="slate"] .md-button--primary { + background-color: var(--arcade-cyan); + border-color: var(--arcade-cyan); + color: var(--arcade-bg); +} +[data-md-color-scheme="slate"] .md-button--primary:hover { + background-color: var(--arcade-fg); + border-color: var(--arcade-fg); + color: var(--arcade-bg); +} + +/* Search bar: cyan focus ring. */ +[data-md-color-scheme="slate"] .md-search__input { + background-color: var(--arcade-surface); + color: var(--arcade-fg); +} +[data-md-color-scheme="slate"] .md-search__input:focus { + background-color: var(--arcade-surface-2); + box-shadow: 0 0 0 2px rgba(0, 224, 224, 0.4); +} diff --git a/docs/assets/favicon.jpg b/docs/assets/favicon.jpg new file mode 100644 index 0000000000000000000000000000000000000000..1e64fcc2524beb749e51184a7e6eda294187680d GIT binary patch literal 2873 zcmbu0`I8m}WXhSKgbBcvgzu4v^m*cX= zSPr&aBli%F%^9s+wuR_aMr@Jo=y!gP^LspgfBhc6^ZqYge?E_od`vzC zY)3h{H~}C95a7JA0QoE6BmnxG^)=*gMu0%_X8>d~un*X$2!a3#5Rf7SB<}?F0ssj7 zXEyNf0x2jefj22{R#8>kXkc##6hMlK3QCG#u#(b7_w|i)KnViY*l&Jf(+-bw$_Mb8 zM}NFuwE3W8bsN-kctOu1lyFN$RZCk(7p8AuXmki}X?4un#@6oSH>aFVJG-E~ynTHA z`~xsy=P!g`jKJbzel)t(_3RgC^B18$i-+YtC2@mCS_#Fq1{8qJueJhA+eKN2}cvC)x@44dIbG{Sq^J>WoJP0*b@= zp;2clQZwyZ!N*44((LtZ*6z2ijo!zDx6Hyz{Brms`Fk(gkxT9s`MMmzmk+o1(bO2( zb^2ITp#@p*^>j>C^KPaUdw^A$`{FW5XQ}_KgjvlK#%r9ozIN+}s%)dXtAlgV0#|>X zlXxq!``eG37Fd+C_T)0V^w_x9@b-cFt_eITFS_t3OOJ_+_A@dH=@905Poqk_#dz9I zCtL!q5qYKz_|L}>D%J7Bjt_d1p`N;tB8H^%n@a^U=sV(=FisaO=h5RxKn{?%7! zdF#P0_e7@j?u4+zlk@4`)(9RS%quSoN+7v$tR6-PZgDiR2t($($WrVRk4VX-o8Jov zJ!u^rZw|S^R$m{6M~%86eXGJ(>q;vNdc>`1wlc4*;m*)l_(wHVY-urr)9Dl+8LUB9 z)f`vH9`dE5D?L3@CN$VFVJLX*z2EP2sAu3KVNR5-rPoSV^SIE)`iJck`yvxdUGo=v zOEKlgB$0{q>Zf&2?sQtalwd5{OjfEBX~F((6ji7Z4?TA(j_cjjBnRHt#S}jsYK!f| zHXs9RU5;PRv1am$xiaO}u#mgq2As+xdt?zF@7q7G(z@6`5bbNX zzR<|YvTlmK2(Q4nN6gh1JO6SOb2Ix3S7@E=Q_(18*!aVn2R+FVT|7cI4sz$iI&XTj zE!rYOq-zZ|nATo%zkTEQ6f@;nXf?&qg$5oX<;_i)lgJFy#9jg#XBIcBf>Lp5GeS8$ zl>^&8##Lk<3v!#~9zOhYZT*Aghv6_}J`F3zw9SqWmA@K4P59PV==vbo_}$LHNc&6r zxr0IwK^8-7FgR%Z0?AB|rTOvuj&=;*;IVdOt?fuYr{WsmlsCfYrxG%Sufx`(GKLnv zj2!Xqlu zMDK+P#J<2J+XYF=a_Z#}X-^RK-I|wa@msG9%SO`56JNHIC_)arN}tCx^{s0-47Ki_ z_YrQ}(~i%eVRWMprj}i3ws0imn0#OCzlFz4ny-Z2Yt0v$v5dd_z}!_s)TmjXIogyX ziJ$7!x|Mi*|M>!)^CZ94g+=%8az&bYPalad6ISPL8yXl^>(cG3q9*xOgy=%{Xj>u=jG>m;M7g-laoqkUK~P0 zjh4F4+{Si)@X>HXm%MGXKUP_nSU3$<*D!BBPNJu_^YRT*o}{uz+)V3uQ|F}s+sMdy zKD*BSlcKMbB0eb^Z^>WN|6)G+DPJXi-TGTzi=DJ7q?X6ts~+K?_Q6WsGRdK_W?`mE z5Ow*ZpR|lBp~BdY^M!l2;G(7y-6DD(W4%KB$4`BJ94WBcvh9l97)BjRdL|H%%1Sgv z$xILL6nNSsMAw^)LnmDDgrm&JG%))0Et|xu_HPlu$t&yLtnH+0>g9!WKI1GT&$et5D}9e zvST)9g|uLLYXUsNDkK(cm)idfTA+(GseT3E1@+rW5E`yUOV&}%)&9pYYi&|TnqtBt zy;>f5GqUU=8YybGfz=}rP*f5%i+&Re%Vd?VODgkL``p$>U%5HNiUZAwQEgX)ZSlyk zyuN@51!IM`(+P(ks=G`-sG)nA_Wxo7gPK)$w39D=I)@0}??iE7WHEhF4B0Ehp&MD_ zSZn;ybdZ1FaCOkb@R}xPQEN?jLV>$M44f}Lt@v!{Iz7NL>nE*<=^p6q94m6z#du?; z*Id+uq=oOlUWM$Z_|7|8t8{TwpR#Lfs8mUbc4Cmj(kv(G;O?2it6?+qRCk2I z==*Evit;&rvYLIeLi^$&Q9ZkP{~Oo9=Q{3D$Vt=li(&CHLBAAZb%|Z>%J*3L_0kFp zZ<7u!QaQEpB+Ca8lnaTD%#q^hgkH;BIRMlq@#DU(Ul;Rr>fa>Ia*{)Gwf!&V6{A4$UM^I$V) zr|U%HvR2u!F&rd+irX@LCIF@~d zCWUi_l8m?*5Fdw$&wS5*)D$z-wAI%{Aw=`!IpJ~4Z%NK81I&En2NBBJ9BZrzkp*E2XB*_5?Qcv1F6XYmNoF%Sx%HU#T1>@|AXgw{SZ}kwAnL_&|-9BRc4OO)G zEtgoJkw;VZ#2j)&6Uz8AO*7e}QP9@Fz4JZ9mILQ^our;AaowBViSo=PbcfehMjs&L Z&PW(SbEu)wX+g4g!#Pdno+ + + + + + + + + + + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index c392ef7..e6a9435 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,8 @@ docs_dir: docs theme: name: material + logo: assets/logo.svg + favicon: assets/favicon.jpg features: - navigation.instant - navigation.tracking @@ -19,27 +21,34 @@ theme: - content.code.copy - content.action.edit - toc.follow + # Brand-aligned palette: dark is the primary experience (matches arcade.dev), + # light is offered as an alternate. The actual hex values come from the + # custom CSS in docs/assets/extra.css — these palette entries just pin the + # right Material scheme + a brand-adjacent base color. palette: - - media: "(prefers-color-scheme: light)" - scheme: default - primary: indigo - accent: indigo - toggle: - icon: material/weather-night - name: Switch to dark mode - media: "(prefers-color-scheme: dark)" scheme: slate - primary: indigo - accent: indigo + primary: black + accent: cyan toggle: icon: material/weather-sunny name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: black + accent: cyan + toggle: + icon: material/weather-night + name: Switch to dark mode font: text: Inter code: JetBrains Mono icon: repo: fontawesome/brands/github +extra_css: + - assets/extra.css + markdown_extensions: - admonition - attr_list From fb9601c3cbcd3c98d961d801f68cd2af9492c246 Mon Sep 17 00:00:00 2001 From: Sam Partee Date: Fri, 8 May 2026 09:58:11 -0700 Subject: [PATCH 9/9] Drop borrowed wordmark; soften inline-code color for readability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The arcade.dev wordmark was misleading on a docs site for a different product (Agent Library). Removed it along with the matching favicon. The header now shows the site_name as text alongside a Material icon (`material/bookshelf`) — own branding, no third-party logo. Inline `code` was tinted cyan in the previous commit, which made every backticked term in prose loud enough to wear the eye down across long pages. Reverted inline code to body color on the navy surface; cyan is now reserved for links, hovers, focus rings, and admonition borders — the spots where it draws the eye on purpose. --- docs/assets/extra.css | 6 ++++-- docs/assets/favicon.jpg | Bin 2873 -> 0 bytes docs/assets/logo.svg | 15 --------------- mkdocs.yml | 10 ++++++---- 4 files changed, 10 insertions(+), 21 deletions(-) delete mode 100644 docs/assets/favicon.jpg delete mode 100644 docs/assets/logo.svg diff --git a/docs/assets/extra.css b/docs/assets/extra.css index 23f5507..a3f04bb 100644 --- a/docs/assets/extra.css +++ b/docs/assets/extra.css @@ -84,10 +84,12 @@ color: var(--arcade-cyan); } -/* Code blocks: match the navy surface tone. */ +/* Code: navy surface tone, body color text. Earlier draft tinted inline + * `code` cyan, which made every backticked term in prose loud and wore + * down the eye fast. Cyan stays reserved for links and accents. */ [data-md-color-scheme="slate"] .md-typeset code { background-color: var(--arcade-surface-2); - color: var(--arcade-cyan); + color: var(--arcade-fg); border-radius: 3px; } [data-md-color-scheme="slate"] .md-typeset pre > code { diff --git a/docs/assets/favicon.jpg b/docs/assets/favicon.jpg deleted file mode 100644 index 1e64fcc2524beb749e51184a7e6eda294187680d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2873 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 Z&PW(SbEu)wX+g4g!#Pdno+ - - - - - - - - - - - - - - diff --git a/mkdocs.yml b/mkdocs.yml index e6a9435..dbd5e1d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,8 +9,12 @@ docs_dir: docs theme: name: material - logo: assets/logo.svg - favicon: assets/favicon.jpg + # Identity is "Agent Library" (the site_name) rendered as the header text; + # the brand vibe comes from the cyan accent + dark theme defined below and + # in docs/assets/extra.css, not from a borrowed wordmark. + icon: + logo: material/bookshelf + repo: fontawesome/brands/github features: - navigation.instant - navigation.tracking @@ -43,8 +47,6 @@ theme: font: text: Inter code: JetBrains Mono - icon: - repo: fontawesome/brands/github extra_css: - assets/extra.css