Second Brain - Local-First Browser RAG Chrome Extension

Second Brain is a Manifest V3 Chrome Extension that quietly indexes the text content of web pages you visit, chunks it, generates vector embeddings, and stores them in a local vector database (IndexedDB) inside your browser. It provides a natural-language Q&A interface inside the browser SidePanel, answering questions using strict citations and a zero-hallucination grounding policy.

---

Technical Stack & Constraints

• Extension Framework: Manifest V3 (MV3)
• Local Storage: IndexedDB (vector arrays and metadata stores)
• Embeddings & LLM Backend: Local Ollama (nomic-embed-text & llama3.2)
• Styling: Modern Vanilla CSS (classy minimal light theme, deep navy & white panels)
• Automation Suite: Puppeteer automated test runner

---

Repository Structure

├── manifest.json              # Extension Manifest V3 configuration
├── package.json               # dependencies (puppeteer)
├── src/
│   ├── background/
│   │   └── background.js      # Passive capture orchestrator & privacy filters
│   ├── content/
│   │   └── extractor.js       # DOM extraction script with SPA MutationObserver
│   ├── clean/
│   │   └── parser.js          # Boilerplate HTML stripper (nav/footer/cookie banners)
│   ├── dedup/
│   │   └── dedup.js           # Jaccard similarity content deduplication
│   ├── indexing/
│   │   └── db.js              # IndexedDB vector store manager & embedding fetch
│   ├── query/
│   │   └── search.js          # Cosine similarity and strict RAG synthesizers
│   └── ui/
│       ├── shared.css         # Styling system tokens
│       ├── popup.html/js      # Quick action dashboard controls
│       ├── sidepanel.html/js  # Main search assistant interface
│       └── eval.html/js       # Extension-side test harness environment
├── eval/
│   ├── questions.json         # 30-question validation suite
│   ├── runner.js              # Puppeteer script to execute the tests and write logs
│   └── logs/                  # Output execution logs per test run
├── FINDINGS.md                # System analysis, thread model, and fallback details
└── README.md                  # Quickstart, setup, and instructions

---

Setup & Quickstart

1. Prerequisites (Ollama Install)

To run fully offline vector embeddings and LLM generations:

1. Download and install Ollama.
2. Pull the required models from your terminal:

   ollama pull nomic-embed-text
   ollama pull llama3.2

Important

CORS Configuration (Origins): Chrome security policies restrict cross-origin requests from extension scripts (chrome-extension://...). To allow Chrome to talk to local Ollama, you must set the environment variable OLLAMA_ORIGINS="*" (or "chrome-extension://*") when starting Ollama.

On macOS: Launch Ollama from your terminal with:

OLLAMA_ORIGINS="*" ollama serve

If Ollama is already running in your menubar, quit it first.

---

2. Install Dependencies

In the project root directory, download the test automation dependencies:

npm install

If the Chrome browser binary for Puppeteer fails to download or throws execution errors on macOS, run the clean installer:

npx puppeteer browsers install chrome
xattr -cr ~/.cache/puppeteer

---

3. Load the Extension in Chrome

1. Open Google Chrome and navigate to chrome://extensions/.
2. Enable Developer mode using the toggle switch in the top-right corner.
3. Click the Load unpacked button in the top-left.
4. Select the project root directory (untitled folder 5).
5. Pin the Second Brain icon to your toolbar. Click it to open the controls or trigger the SidePanel Search Workspace.

---

Running the Evaluation Suite

We have built an automated test runner (eval/runner.js) that launches a sandboxed browser profile, seeds the vector database with the extension's own codebase, runs 30 questions, programmatically validates them, and writes results to eval/logs/.

To run the automated evaluation harness:

node eval/runner.js

The script will:

1. Verify the local Ollama connection.
2. Launch a clean browser instance preloaded with the extension at a locked extension ID (fgegfoleeaekcpfenpjkfeeoopcoffge).
3. Open the evaluation panel and seed the IndexedDB.
4. Run 30 questions (factual, multi-hop, time-scoped, and negative cases).
5. Save per-question execution logs to eval/logs/question_<id>.json.
6. Write a full run summary report to eval/logs/summary.json.
7. Display accuracy metrics in the terminal.

---

Offline Fallback Execution

To guarantee system stability on machines with slow networks or where local Ollama is busy/misconfigured, Second Brain implements local client-side fallback engines:

1. Bag-of-Words Embedding Fallback: If Ollama embeddings fail, the indexer generates deterministic Float32 vectors via term hashing and falls back to a sparse keyword search inside IndexedDB.
2. Extractive Answer Fallback: If Ollama text synthesis fails, the RAG search synthesizes responses by extracting sentences matching the query and compiling citations in the exact same format.
3. Source-Citation Grading Fallback: If the LLM judge fails to grade responses, the test console grades factual accuracy by verifying if the generated answer correctly cited the required source files.