Skip to content

README.md

Latest commit

 

History

History
183 lines (143 loc) · 7.56 KB

README.md

File metadata and controls

183 lines (143 loc) · 7.56 KB
Raw

Chronicle

Self-hostable AI system that captures audio/video data from OMI devices and other sources to generate memories, action items, and contextual insights about your conversations and daily interactions.

Quick Start

curl -fsSL https://raw.githubusercontent.com/SimpleOpenSoftware/chronicle/main/install.sh | sh

This clones the latest release, installs dependencies, and launches the interactive setup wizard.

For step-by-step instructions, see the setup guide.

Screenshots

WebUI Dashboard

WebUI Dashboard

Memory Search

Memory Search

Desktop Menu Bar Client

Menu Bar Client

What's Included

  • Mobile app for OMI devices via Bluetooth
  • Backend services (simple → advanced with full AI features)
  • Web dashboard for conversation and memory management
  • Optional services: Speaker recognition, offline ASR, wake word, TTS, screen capture

Links

Project Structure

chronicle/
├── app/                     # React Native mobile app
│   ├── app/                # App components and screens
│   └── plugins/            # Expo plugins
├── backends/
│   ├── advanced/           # Main AI backend (FastAPI)
│   │   ├── src/           # Backend source code
│   │   ├── init.py        # Interactive setup wizard
│   │   └── docker-compose.yml
│   ├── simple/            # Basic backend implementation
│   └── other-backends/    # Example implementations
├── extras/                  # Optional services (see extras/ for the full set)
│   ├── speaker-recognition/  # Voice identification service
│   ├── asr-services/        # Offline speech-to-text (Parakeet)
│   ├── wakeword-service/    # Wake-word detection
│   ├── intent-router/       # Voice command routing
│   ├── tts/                 # Text-to-speech
│   └── vault-sync/          # Markdown vault sync
├── plugins/                # Action plugins (e.g. Home Assistant)
├── docs/                   # Technical documentation
├── config/                 # Central configuration files
├── tests/                  # Integration & unit tests
├── wizard.py              # Root setup orchestrator
├── services.py            # Service lifecycle manager
└── *.sh                   # Convenience scripts (wrappers)

Service Architecture

┌─────────────────────────────────────────────────────────┐
│                    Chronicle System                      │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────────┐    ┌──────────────┐   ┌────────────┐ │
│  │ Mobile App   │◄──►│   Backend    │◄─►│  MongoDB   │ │
│  │ (React       │    │   (FastAPI)  │   │            │ │
│  │  Native)     │    │              │   └────────────┘ │
│  └──────────────┘    └──────────────┘                   │
│                            │                             │
│                            ▼                             │
│       ┌────────────────────┴────────────────┐          │
│       │                                     │          │
│  ┌────▼─────┐  ┌───────────┐  ┌──────────▼──┐        │
│  │ Deepgram │  │  OpenAI   │  │  Markdown   │        │
│  │   STT    │  │   LLM     │  │   Vault     │        │
│  │          │  │           │  │  (memory)   │        │
│  └──────────┘  └───────────┘  └─────────────┘        │
│                                                         │
│  Optional Services:                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │  Speaker     │  │  Parakeet    │  │  Ollama     │ │
│  │  Recognition │  │  (Local ASR) │  │  (Local     │ │
│  │              │  │              │  │   LLM)      │ │
│  └──────────────┘  └──────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────┘

Quick Command Reference

Setup & Configuration

# Interactive setup wizard (recommended for first-time users)
./wizard.sh

# Full command (what the script wraps)
uv run --with-requirements setup-requirements.txt python wizard.py

Note: Convenience scripts (*.sh) are wrappers around wizard.py and services.py that simplify the longer uv run commands.

Service Management

# Start all configured services
./start.sh

# Restart all services (preserves containers)
./restart.sh

# Check service status
./status.sh

# Stop all services
./stop.sh
Full commands (click to expand) 
# What the convenience scripts wrap
uv run --with-requirements setup-requirements.txt python services.py start --all --build
uv run --with-requirements setup-requirements.txt python services.py restart --all
uv run --with-requirements setup-requirements.txt python services.py status
uv run --with-requirements setup-requirements.txt python services.py stop --all

Development

# Backend development
cd backends/advanced
uv run python src/advanced_omi_backend/main.py

# Integration tests (needs a .env with API keys)
./backends/advanced/run-test.sh

# Mobile app
cd app
npm start

See docs/testing.md for the unit-test lanes and coverage.

Health Checks

# Backend health
curl http://localhost:8000/health

# Web dashboard
open http://localhost:5173

Vision

Have various sensors feed the state of your world to computers and AI, and get something useful out of it. Wearable audio devices capture personal spoken context best, so Chronicle starts there: multiple OMI-like devices feeding audio, and from it memories, action items, and home automation. Devices with a camera — or smart glasses — extend the same idea to visual context.

Roadmap

  • Visual context capture — screen capture ships today; wearable camera and smart glasses are not yet supported
  • Multi-device coordination — single-device capture works; coordinating overlapping captures across devices is not implemented