BrainMarks

Local-first, agentic bookmark RAG. Turn your browser bookmarks into a queryable knowledge base — ask a natural-language question and get a cited, synthesized answer from your own saved pages. Nothing leaves your machine.

❯ 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

Features (Phase 1 — shipped)

• Agentic chat — LangGraph agent with tool calling (search bookmarks, fetch pages, web search). SSE streaming, live RAG pipeline visualization, session memory.
• Hybrid retrieval — LlamaIndex QueryFusionRetriever: vector (ChromaDB + sentence-transformers) fused with BM25 (Reciprocal Rank Fusion), deduplicated by source.
• Browser extension (Chrome / Brave / Edge / Firefox) — one-click full import, selective tree picker, save current page, opt-in background sync, side-panel chat.
• Webapp — chat, library (bookmarks + web sources), dashboard, admin. Hacker-terminal design.
• BYOM — bring your own model: Ollama, OpenAI, Groq, Anthropic, OpenRouter, or any OpenAI-compatible endpoint. Provider presets in Admin, no raw URLs.
• Privacy-first — zero telemetry, local SQLite + ChromaDB, air-gapped capable (Ollama + local embeddings). PRIVACY_MODE=strict blocks non-localhost models by default.
• Prompt-injection guardrail — retrieved content is structurally delimited as untrusted data; the agent can't be redirected by page contents.

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. brainmarks sets up autostart and prints your webapp URL, extension store links, and access token.

Then install the extension (Chrome Web Store / Firefox Add-ons) — enable sync in the popup and import your bookmarks.

Quick Start

1. Install (above), run brainmarks
2. Install the extension, toggle sync ON, import bookmarks (full or pick folders)
3. Configure your model: Admin → provider (e.g. OpenRouter) + model + API key, or leave default Ollama
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 a read/search surface; remote mode (Phase 2) makes your index reachable from anywhere.

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
                      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                    # 56 tests
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/.

Full project docs live in the Obsidian vault (see AGENTS.md for the path).

Roadmap

• Phase 1 ✅ — core RAG, agent, extension, webapp, shipping
• Phase 2 (next) — LLM categorization (real topic tags), web sources lifecycle, MCP server/client, Mem0 memory, document upload, remote mode + token auth
• Phase 3 — dead-link detection, duplicates, recommendations, graph memory (Cognee opt-in)
• Phase 4 — web archiving, history indexing, knowledge graph viz, scheduled digests, multi-user
• Phase 5 — REST API, collaborative annotations, mobile companion

License

MIT. Dependencies MIT / Apache-2.0 compatible.