BrainMarks

Agentic RAG for your browser bookmarks — local-first, BYOM, privacy-focused. Turn your browser bookmarks into a private, queryable knowledge base — ask a natural-language question and get a cited, synthesized answer from your own saved pages.

❯ what was that article about local-first architecture?

  Three bookmarks in your index cover local-first architecture:
  - The Local-First Software Manifesto argues apps work offline first... [1]
  - Embedded RAG comparison shows local vector stores remove servers... [2]

  [tool] search_bookmarks · [tool] fetch_page

Install

Prerequisite: install uv (the Python package/venv manager) once:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install BrainMarks (any platform — Linux / macOS / Windows):

uv tool install brainmarks-agent
brainmarks          # starts server on :8008 + opens the webapp

The wheel bundles the webapp UI and the CLI — one artifact, no build step. brainmarks runs the guided setup (provider, model, autostart) and prints your webapp URL, extension store links, and access token.

Quick Start

1. Install (above), run brainmarks
2. Install the browser extension (below), toggle sync ON, import your bookmarks (full or pick folders)
3. Configure your model: Admin → provider (e.g. OpenRouter) + model + API key, or leave the local default
4. Ask in Chat or the side panel: "what was that article about local-first architecture?"

Desktop captures, everywhere reads: the extension (bookmark capture) is desktop-only — mobile browsers have no extension API. The webapp is the read/search surface, reachable remotely via token auth.

Command Line

The brainmarks CLI is bundled with the wheel. Lightweight commands run instantly (no model load); only start / mcp / eval build the backend stack.

brainmarks                          # shortcut for: brainmarks start
brainmarks --help                   # top-level help
brainmarks -v / --version           # print version

Common keys for config set/get: PROVIDER, LLM_MODEL, LLM_BASE_URL, LLM_API_KEY, EMBEDDING_MODEL, EMBEDDING_PROVIDER, PRIVACY_MODE, MEMORY_BACKEND, PORT, HOST.

Browser Extension

The extension imports/syncs your browser bookmarks into BrainMarks and adds a side-panel chat you can use while browsing.

Chrome Web Store (Chrome / Edge / Brave / Opera): install BrainMarks from the Chrome Web Store, then open the popup and toggle Auto-sync ON to import your bookmarks.

Manual load (development / self-hosted):

1. Build or download the packaged zip: ./scripts/package_extension.sh → dist/brainmarks-extension-<version>.zip
2. Open chrome://extensions → enable Developer mode
3. Click Load unpacked → select the extension/ folder (or drag in the zip)
4. Open the popup → toggle Auto-sync ON → import bookmarks (one-click or selective tree)

The extension connects to the local backend at 127.0.0.1:8008 (host permission). If the backend isn't running, the popup shows the install command for your OS.

Features

• Agentic chat — a LangGraph agent with tool calling (search bookmarks, fetch pages, web search, memory), SSE streaming, session memory, and named sessions.
• Hybrid retrieval — LlamaIndex QueryFusionRetriever: vector (ChromaDB + sentence-transformers) fused with BM25 (Reciprocal Rank Fusion), deduplicated by source.
• RAG over everything you save — bookmarks, web sources, and uploaded documents (PDF, Markdown, TXT, DOCX, HTML with OCR-aware scanning) all become queryable knowledge.
• Browser extension (Chrome / Brave / Edge / Opera) — one-click full import, selective tree picker, save current page, opt-in background sync, side-panel chat with markdown, citations, and inline approval prompts.
• Webapp — chat, library (bookmarks + web sources + documents), knowledge-graph view, a full Admin panel, and a rich dashboard.
• BYOM — bring your own model: Ollama, OpenAI, Groq, Anthropic, OpenRouter, or any OpenAI-compatible endpoint. Provider presets in Admin, no raw URLs.
• Observability — every agent run is traced locally: what it did, tool calls, tokens, cost, latency; raw per-run traceability is one click away.
• Evaluation — a golden-set harness plus optional DeepEval metrics and LLM-as-judge, with sampled live auto-eval of real chat responses.
• Guardrails — prompt-injection defense (retrieved content is structurally delimited as untrusted data), tool-permission interrupts for mutating actions, and a privacy-mode gate. A Guardrails dashboard shows what's active and what's been approved.
• Memory — the agent remembers conversational facts (never bookmark content) and recalls them across sessions.
• Agent-side caching — embedding, retrieval, and exact-answer caches (incl. live-tool answers with a short TTL) keep repeated questions fast and cheap; a Cache dashboard shows hits.
• MCP dual-role — expose BrainMarks tools to other AI apps (stdio / Streamable HTTP), or add external MCP tools to the agent loop.
• Dead-link detection, duplicates, and recommendations — probe stored sources, merge near-dup groups, and surface "you might also like" suggestions.
• Scheduled digests — periodic local summaries of your saved topics, viewable in the dashboard.
• Privacy-first — no telemetry, local SQLite + ChromaDB, air-gapped capable (Ollama + local embeddings). PRIVACY_MODE=strict blocks non-localhost models by default.

Configuration

Config precedence: environment vars > YAML (--config) > CWD .env > ~/.brainmarks/.env > defaults.

Set them in the Admin panel (persists across restarts) or .env.

Architecture

API: the stable, third-party-consumable REST surface (auth, curl quickstart, endpoint reference) is documented in docs/api.md. Interactive docs at /docs (Swagger) and /openapi.json.

Browser Extension (vanilla MV3)  ─┐
Webapp (React + Vite + shadcn + motion) ─┤── HTTP :8008
                                         ▼
                    FastAPI backend
                      LangGraph agent (LiteLLM router, MemorySaver checkpointer)
                        Tools: search_bookmarks · fetch_page · web_search · remember · MCP
                      LlamaIndex QueryFusionRetriever (vector + BM25, RRF)
                      Ingestion: fetch → extract → chunk → embed → tag
                      Stores: SQLite (metadata) · ChromaDB (vectors) · ~/.brainmarks

Development

git clone https://github.com/Akshxdev/BrainMarks.git && cd BrainMarks
uv sync                          # backend deps + dev group
uv run brainmarks                # backend on :8008
cd webapp && npm install && npm run dev   # webapp on :5173 (CORS configured)

uv run pytest                    # backend test suite
cd webapp && npm run build       # type-check + bundle
python scripts/generate_openapi.py  # regenerate frontend API types from the contract

Extension: chrome://extensions → Developer mode → Load unpacked → extension/.

License

MIT. Dependencies MIT / Apache-2.0 compatible.