digital-brain

<p align="center"> <h1 align="center">🧠 Digital Brain</h1> <p align="center"> <strong>AI-powered personal browsing history assistant that lives locally on your machine.</strong> </p> <p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-features">Features</a> • <a href="#-architecture">Architecture</a> • <a href="#-cli-usage">CLI</a> • <a href="#-mcp-server">MCP</a> • <a href="#-api-reference">API</a> </p> </p>

<br/>

What was I working on yesterday related to RAG?
Which website did I spend the most time on last week?
What was that command I copied to clear the terminal?

Digital Brain captures your Chrome browsing activity — page visits, text selections, copy/paste events, page content, and time spent — stores it 100% locally, and lets you search and ask questions using AI. It combines keyword search (SQLite FTS5) with semantic search (ChromaDB vectors) through a RAG pipeline powered by a local LLM.

<br/>

✨ Features

Feature	Description
🧩 Chrome Extension	Captures page visits, selections, copy/paste, page content, and tab focus time
⚡ FastAPI Backend	Receives, stores, and indexes events locally on localhost:8420
🔍 Full-Text Search	SQLite FTS5 keyword search with highlighted snippets and filters
🧬 Vector Search	ChromaDB semantic indexing for meaning-based recall
🤖 RAG Q&A	Ask questions in plain English — uses local LLM to generate answers
📊 Activity Stats	Top domains by time spent, daily breakdowns, and event timelines
💻 CLI Tool	Rich terminal interface with brain search, brain ask, brain stats
🔌 MCP Server	Query your history from Claude Desktop, VS Code, or any MCP client
🛡️ Privacy-First	All data stays on your machine — no cloud, no tracking

<br/>

📐 Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         Chrome Browser                               │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │  Chrome Extension (Manifest V3)                                │  │
│  │  ┌─────────────┐  ┌────────────────┐  ┌───────────────────┐   │  │
│  │  │ Content.js  │  │ Background.js  │  │   Popup UI        │   │  │
│  │  │ • Selections│  │ • Tab tracking │  │ • Toggle on/off   │   │  │
│  │  │ • Copy/Paste│  │ • Event queue  │  │ • View stats      │   │  │
│  │  │ • Page text │  │ • Batch flush  │  │ • Sync now        │   │  │
│  │  └──────┬──────┘  └───────┬────────┘  └───────────────────┘   │  │
│  └─────────┼─────────────────┼───────────────────────────────────┘  │
└────────────┼─────────────────┼──────────────────────────────────────┘
             │  chrome.runtime │
             └────────┬────────┘
                      │ POST /api/events (batch every 30s)
                      ▼
┌──────────────────────────────────────────────────────────────────────┐
│                    Local Backend (Python)                             │
│                                                                      │
│  ┌──────────┐   ┌──────────────┐   ┌──────────────┐                │
│  │ FastAPI   │──▶│ Event        │──▶│ SQLite+FTS5  │                │
│  │ Server    │   │ Processor    │   │ (structured) │                │
│  │ :8420     │   │ dedup+domain │   └──────────────┘                │
│  └──────────┘   └──────┬───────┘                                    │
│       │                │          ┌──────────────┐                   │
│       │                └─────────▶│ ChromaDB     │                   │
│       │                           │ (semantic)   │                   │
│       ▼                           └──────┬───────┘                   │
│  ┌──────────┐                            │                           │
│  │ RAG      │◀───── vector search ───────┘                           │
│  │ Pipeline  │◀───── FTS5 search ────────┘                           │
│  └────┬─────┘                                                        │
│       │                                                              │
│       ▼                                                              │
│  ┌──────────┐                                                        │
│  │ LLM      │  Ollama (local, free) or OpenRouter (cloud)            │
│  └──────────┘                                                        │
└──────────────────────────────────────────────────────────────────────┘
        ▲               ▲               ▲
        │               │               │
   ┌────┴────┐    ┌─────┴─────┐   ┌─────┴─────┐
   │   CLI   │    │ MCP Server│   │ REST API  │
   │ $ brain │    │ Claude/   │   │ curl/apps │
   │  search │    │ VS Code   │   │           │
   └─────────┘    └───────────┘   └───────────┘

<br/>

🚀 Quick Start

Prerequisites

• Python 3.10+
• Google Chrome (latest)
• Ollama (optional — for AI-powered answers)

1. Clone & Install

git clone https://github.com/ArpitaSethi-12/digital-brain.git
cd digital-brain
pip install -e .

2. Start the Backend

python -m backend.main

Digital Brain backend is ready  🧠
Server running at http://localhost:8420

3. Install the Chrome Extension

1. Open chrome://extensions/ in Chrome
2. Enable Developer mode (top-right toggle)
3. Click Load unpacked → select the extension/ directory
4. The 🧠 icon appears in your toolbar

4. (Optional) Install Ollama for AI Answers

# Install Ollama from https://ollama.com
ollama serve
ollama pull llama3.2

Without Ollama, Digital Brain still works — it returns retrieved results instead of generated answers.

5. Start Browsing!

Open any website. The extension captures your activity in the background. Then query it:

brain search "python tutorial"
brain ask "What was I reading about yesterday?"
brain stats

<br/>

💻 CLI Usage

Digital Brain ships with a CLI built on Typer + Rich:

Search

# Basic search
brain search "RAG pipeline"

# Filter by event type
brain search "terminal command" --type copy

# Filter by domain
brain search "react hooks" --domain github.com

# Filter by time window
brain search "python" --last 7d        # last 7 days
brain search "docker" --last 24h       # last 24 hours
brain search "AI paper" --last 2w      # last 2 weeks

Ask (RAG Q&A)

brain ask "What was I working on yesterday related to RAG?"
brain ask "What command did I copy to clear the terminal?" --type copy
brain ask "Which website did I spend the most time on?" --last 7d
brain ask "Summarize what I read about transformers" --no-llm  # skip LLM

Stats & Activity

brain stats                    # top domains + weekly activity
brain stats --period month     # monthly breakdown
brain activity                 # today's timeline
brain activity --date yesterday
brain activity --date 2026-06-01

System

brain status     # backend health + LLM availability
brain reindex    # rebuild vector index from SQLite

<br/>

🔌 MCP Server

Digital Brain includes an MCP (Model Context Protocol) server that lets AI assistants query your browsing history directly.

How It Works

You:    "What was I working on yesterday related to RAG?"
Claude: → calls search_history("RAG", last="1d")
        → Digital Brain searches local SQLite + ChromaDB
Claude: "Yesterday you visited 3 pages about RAG pipelines..."

Available Tools

Tool	Description
search_history	Keyword search with type/domain/time filters
ask_brain	RAG-powered natural language Q&A
get_stats	Top domains and activity breakdown
get_activity	Day's chronological timeline
get_timeline	Detailed event feed with full content
check_status	Backend health + LLM status

Setup with Claude Desktop

1. Start the backend: python -m backend.main

2. Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "digital-brain": {
      "command": "python3",
      "args": ["/absolute/path/to/digital-brain/mcp_server.py"]
    }
  }
}

3. Restart Claude Desktop — the 🧠 tools appear automatically.

Setup with VS Code

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "digital-brain": {
        "command": "python3",
        "args": ["/absolute/path/to/digital-brain/mcp_server.py"]
      }
    }
  }
}

Test with MCP Inspector

npx -y @modelcontextprotocol/inspector python3 mcp_server.py

<br/>

📡 API Reference

The backend exposes a REST API at http://localhost:8420:

Method	Endpoint	Description
GET	/api/health	Backend health status
POST	/api/events	Ingest event batch from extension
GET	/api/search?q=...	Full-text search with filters
POST	/api/ask	RAG question answering
GET	/api/ask?q=...	RAG via query string
GET	/api/stats/domains	Top domains by time spent
GET	/api/stats/activity?period=week	Daily event breakdown
GET	/api/stats/timeline?date=2026-06-01	Event timeline for a date
POST	/api/index/rebuild	Rebuild vector index
GET	/api/llm/status	Check LLM availability

Example: Ask a Question

curl -X POST http://localhost:8420/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What did I copy about clearing the terminal?"}'

Response:

{
  "answer": "You copied the command 'clear && printf ...' from Stack Overflow.",
  "sources": [
    {
      "event_type": "copy",
      "domain": "stackoverflow.com",
      "content": "clear && printf '\\e[3J'"
    }
  ],
  "llm_used": true,
  "retrieval_count": 3
}

Example: Search History

curl "http://localhost:8420/api/search?q=RAG&event_type=page_visit&limit=5"

<br/>

📁 Project Structure

digital-brain/
├── extension/                  # Chrome Extension (Manifest V3)
│   ├── manifest.json           # Permissions & config
│   ├── background.js           # Service worker — event batching, tab tracking
│   ├── content.js              # Content script — selections, copy/paste, page text
│   ├── popup.html/js/css       # Extension popup UI
│   └── icons/                  # Extension icons
│
├── backend/                    # Python FastAPI Backend
│   ├── main.py                 # App entry point with CORS & lifespan
│   ├── config.py               # Environment-based configuration
│   ├── models.py               # 13 Pydantic models (API contract)
│   ├── database.py             # SQLite + FTS5 (schema, CRUD, search)
│   ├── routers/
│   │   ├── events.py           # POST /api/events
│   │   ├── search.py           # GET /api/search
│   │   ├── stats.py            # GET /api/stats/*
│   │   └── ask.py              # POST /api/ask + index rebuild
│   └── services/
│       ├── event_processor.py  # Validate, dedup, extract domains
│       ├── vector_store.py     # ChromaDB operations
│       ├── rag.py              # RAG pipeline (vector + FTS → LLM)
│       ├── llm.py              # Ollama / OpenRouter client
│       └── indexer.py          # Vector index rebuild
│
├── cli/
│   └── brain.py                # Typer + Rich CLI (6 commands)
│
├── mcp_server.py               # MCP server (6 tools for AI assistants)
│
├── data/                       # Local storage (auto-created, gitignored)
│   ├── brain.db                # SQLite database + FTS5 index
│   └── chroma/                 # ChromaDB vector store
│
├── .env.example                # Environment variable template
├── pyproject.toml              # Project config & dependencies
└── README.md

<br/>

⚙️ Configuration

Copy the example and customize:

cp .env.example .env

Variable	Default	Description
BRAIN_HOST	127.0.0.1	Backend host
BRAIN_PORT	8420	Backend port
BRAIN_DATA_DIR	./data	Storage directory
BRAIN_LLM_PROVIDER	ollama	ollama or openrouter
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
OLLAMA_MODEL	llama3.2	Ollama model name
OPENROUTER_API_KEY	—	OpenRouter API key (optional)
BRAIN_RAG_TOP_K	8	Number of results for RAG context

<br/>

🧬 How RAG Works

User: "What command did I copy to clear the terminal?"
 │
 ├──▶ ChromaDB Semantic Search
 │    Finds events with similar meaning
 │    (e.g., "bash clear screen" matches "terminal command")
 │
 ├──▶ SQLite FTS5 Keyword Search
 │    Finds events containing exact words
 │    (e.g., "clear" AND "terminal")
 │
 ├──▶ Merge & Deduplicate
 │    Combines both result sets by event ID
 │
 ├──▶ Format Context Block
 │    Prepares retrieved events as LLM context
 │
 └──▶ LLM Generation (Ollama)
      Generates natural language answer
      grounded in your actual browsing data

Result: "You copied 'clear && printf \\e[3J' from stackoverflow.com on June 8th."

<br/>

🛡️ Privacy

Digital Brain is privacy-first by design:

• ✅ All data stored locally in data/ directory
• ✅ Chrome extension only communicates with localhost:8420
• ✅ MCP server runs locally via stdio — no network requests
• ✅ LLM runs locally via Ollama — your data never leaves your machine
• ✅ No analytics, no telemetry, no cloud sync
• ⚠️ OpenRouter is optional and only used if you explicitly set OPENROUTER_API_KEY

<br/>

🛠️ Tech Stack

Layer	Technology
Data Capture	Chrome Extension (Manifest V3)
Backend	Python 3.10+ · FastAPI · Uvicorn
Structured DB	SQLite 3 + FTS5
Vector DB	ChromaDB (all-MiniLM-L6-v2 embeddings)
Local LLM	Ollama (llama3.2)
Cloud LLM	OpenRouter (optional)
CLI	Typer + Rich
MCP	FastMCP (mcp SDK)
Validation	Pydantic v2
HTTP Client	httpx (async)

<br/>

📊 Project Stats

Metric	Value
Total Lines of Code	~3,800
Python Files	18
JavaScript Files	3
API Endpoints	10
CLI Commands	6
MCP Tools	6
Pydantic Models	13
Event Types Captured	6
Dependencies	10

<br/>

🗺️ Roadmap

• [ ] 🌐 Web chat UI with streaming responses
• [ ] 📅 Smarter date parsing ("yesterday", "last week") in RAG
• [ ] 🔒 Optional encryption at rest for data/
• [ ] 🔌 MCP Registry listing
• [ ] 📱 Firefox extension
• [ ] 🧠 Multi-turn conversation memory
• [ ] 📦 PyPI package (pip install digital-brain)

<br/>

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

<br/>

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

<p align="center"> Built with ❤️ as a BTech Major Project </p>