<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

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

### 2. Start the Backend

```bash
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

```bash
# 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:

```bash
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](https://typer.tiangolo.com/) + [Rich](https://rich.readthedocs.io/):

### Search

```bash
# 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)

```bash
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

```bash
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

```bash
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`:

```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`:

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

### Test with MCP Inspector

```bash
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

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

**Response:**
```json
{
  "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

```bash
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:

```bash
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](LICENSE) file for details.

---

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