mirror of
https://github.com/Zetaphor/browser-recall.git
synced 2025-12-06 02:19:37 +00:00
Update readme
This commit is contained in:
159
README.md
159
README.md
@@ -1,160 +1,3 @@
|
||||
# Browser Recall
|
||||
|
||||
Browser Recall is a browser history and bookmark management system that captures, processes, and stores web page content in a searchable format. It consists of a browser extension and a FastAPI backend server that work together to provide the ability to search your the content of your browsing history and bookmarks.
|
||||
|
||||
## Features
|
||||
|
||||
- 🔍 Full-text search across browsing history and bookmarks
|
||||
- 📝 Automatic conversion of web pages to markdown format
|
||||
- 🔄 Real-time page content capture via WebSocket
|
||||
- ⚡ Optimized SQLite database with FTS5 search
|
||||
- 🛡️ Configurable domain exclusions
|
||||
- 📊 Efficient content processing and storage
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Backend Components
|
||||
|
||||
- **FastAPI Server**: Main application server handling WebSocket connections and HTTP endpoints
|
||||
- **SQLite Database**: Stores history and bookmarks with full-text search capabilities
|
||||
- **Page Reader**: Converts HTML content to markdown format
|
||||
- **History Scheduler**: Background task for updating browser history
|
||||
- **Configuration System**: Manages domain exclusions and reader settings
|
||||
|
||||
### Browser Extension
|
||||
|
||||
- **Content Script**: Captures page content and sends to backend
|
||||
- **Background Script**: Manages WebSocket connection and message handling
|
||||
- **Manifest**: Extension configuration and permissions
|
||||
|
||||
## Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.8+
|
||||
- Firefox Browser (for the extension)
|
||||
- SQLite3
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd browser-recall
|
||||
```
|
||||
|
||||
2. Create and activate a virtual environment:
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
3. Install dependencies:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. Install the browser extension:
|
||||
|
||||
Option A - Install from signed XPI file:
|
||||
- Download the latest `.xpi` file from the releases page
|
||||
- In Firefox, go to `about:addons`
|
||||
- Click the gear icon and select "Install Add-on From File"
|
||||
- Select the downloaded `.xpi` file
|
||||
- Click "Add" when prompted
|
||||
|
||||
Option B - Install temporarily for development:
|
||||
- Open Firefox
|
||||
- Navigate to `about:debugging`
|
||||
- Click "This Firefox"
|
||||
- Click "Load Temporary Add-on"
|
||||
- Select the `manifest.json` file from the `extension` directory
|
||||
|
||||
### Configuration
|
||||
|
||||
1. Configure domain exclusions in `app/config.yaml`:
|
||||
```yaml
|
||||
ignored_domains:
|
||||
- "localhost"
|
||||
- "127.0.0.1"
|
||||
- "*.local"
|
||||
# Add more patterns as needed
|
||||
```
|
||||
|
||||
2. Configure the server port in `main.py` (default: 8523)
|
||||
|
||||
## Usage
|
||||
|
||||
1. Start the server:
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
2. The extension will automatically:
|
||||
- Capture page content as you browse
|
||||
- Send content to the backend server
|
||||
- Update history and bookmarks
|
||||
|
||||
3. Access the web interface:
|
||||
- Home page: `http://localhost:8523/`
|
||||
- Search interface: `http://localhost:8523/search`
|
||||
- Bookmarks page: `http://localhost:8523/bookmarks`
|
||||
|
||||
4. Access the API endpoints:
|
||||
- Search history: `GET /history/search`
|
||||
- Search bookmarks: `GET /bookmarks/search`
|
||||
- Advanced search: `GET /history/search/advanced`
|
||||
- Manage ignored domains: `GET/POST/DELETE /config/ignored-domains`
|
||||
|
||||
## Web Interface
|
||||
|
||||
Browser Recall includes a basic web interface for viewing and searching your browsing history and bookmarks:
|
||||
|
||||
- **Home Page**: Displays recent browsing history
|
||||
- **Search Page**: Provides a form interface for searching history with filters
|
||||
- **Bookmarks Page**: Shows your browser bookmarks
|
||||
|
||||
The interface is built with:
|
||||
- Tailwind CSS for styling
|
||||
- Responsive design for mobile and desktop
|
||||
- Dark mode for comfortable viewing
|
||||
|
||||
## API Documentation
|
||||
|
||||
The API documentation is available through FastAPI's interactive interface at `http://localhost:8523/docs`. This provides a complete API reference with:
|
||||
- Interactive endpoint testing
|
||||
- Request/response examples
|
||||
- Schema documentation
|
||||
|
||||
### History Endpoints
|
||||
|
||||
- `GET /history/search`
|
||||
- Query parameters:
|
||||
- `domain`: Filter by domain
|
||||
- `start_date`: Filter by start date
|
||||
- `end_date`: Filter by end date
|
||||
- `search_term`: Full-text search
|
||||
- `include_content`: Include markdown content
|
||||
|
||||
- `GET /history/search/advanced`
|
||||
- Advanced full-text search using SQLite FTS5 syntax
|
||||
|
||||
### Bookmark Endpoints
|
||||
|
||||
- `GET /bookmarks/search`
|
||||
- Query parameters:
|
||||
- `domain`: Filter by domain
|
||||
- `folder`: Filter by folder
|
||||
- `search_term`: Search in titles
|
||||
|
||||
### Configuration Endpoints
|
||||
|
||||
- `GET /config/ignored-domains`: List ignored domains
|
||||
- `POST /config/ignored-domains`: Add domain pattern
|
||||
- `DELETE /config/ignored-domains/{pattern}`: Remove domain pattern
|
||||
|
||||
## Development
|
||||
|
||||
- Logs are stored in the `logs` directory
|
||||
- Database file: `browser_history.db`
|
||||
- WebSocket endpoint: `ws://localhost:8523/ws`
|
||||
WIP Redux
|
||||
Reference in New Issue
Block a user