Argus

Argus is a local-first episodic memory system for wearable camera projects.

It turns periodic first-person images into a searchable private timeline using local vision captioning, embeddings, and retrieval-augmented answers. Argus was designed as the memory add-on for Cleo, but it also runs as a standalone FastAPI service with a small web UI and CLI.

Named after Argus Panoptes, the many-eyed figure from Greek mythology, Argus is built around a simple principle: personal memory tools should be useful without becoming surveillance infrastructure. The default architecture keeps model inference and storage on your own machine.

What It Does

• Captures first-person images from a Raspberry Pi camera agent.
• Captions images locally with an Ollama vision model.
• Embeds captions, calendar records, mail records, and future audio transcripts.
• Stores memories in SQLite with image files on disk.
• Retrieves relevant moments by semantic search.
• Answers natural-language questions using retrieved memories as evidence.
• Exposes a Cleo-compatible add-on API for assistant integration.
• Provides a lightweight web UI for browsing and querying the timeline.

Use Cases

• “Where did I leave my charger?”
• “What did I do after lunch?”
• “What meeting was I walking to when I saw that poster?”
• “Show me the last time I was at the lab.”
• “What did I receive in email around the time I got home?”

Architecture

Argus separates capture from intelligence:

• Pi Agent: a thin Raspberry Pi process captures images and uploads them. If the backend is unreachable, it buffers captures and retries.
• Argus Backend: a FastAPI service stores images, captions scenes, generates embeddings, retrieves memories, and answers questions.
• Local Models: Ollama provides local vision, embedding, and text models.
• Timeline Store: SQLite stores memory records and embeddings; image files stay on disk.
• Cleo Add-On API: Cleo can discover Argus capabilities and call memory tools over HTTP.

This split keeps the wearable device simple and battery-friendly while allowing heavier model work to run on a laptop, home server, or local workstation.

Quick Start

git clone https://github.com/omkhairate/argus.git
cd argus
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
uvicorn argus.api:app --reload

Open the web UI:

http://127.0.0.1:8000

Ollama Setup

Install Ollama, then pull the recommended local models:

ollama pull llama3.2-vision
ollama pull all-minilm
ollama pull llama3.2

Make sure Ollama is running:

ollama serve

Argus talks to Ollama at http://localhost:11434 by default. If Ollama is unavailable and ARGUS_REQUIRE_OLLAMA=false, Argus uses deterministic local fallbacks so ingestion and search can still be tested.

CLI

Upload a test image:

python -m argus.cli ingest-image path/to/image.jpg \
  --captured-at "2026-06-11T09:30:00+02:00"

Search memories:

python -m argus.cli search "where did I put my laptop charger?"

Ask a synthesized question:

python -m argus.cli answer "what did I do after lunch?"

Import exported calendar and mail context:

python -m argus.cli import-ics calendar-export.ics
python -m argus.cli import-mbox mail-export.mbox --limit 500

Calendar and mail records become timeline events, so Argus can retrieve visual memories and external context together.

Raspberry Pi Capture

On the Raspberry Pi:

python3 -m venv .venv
source .venv/bin/activate
pip install requests
python pi_agent/capture_loop.py --backend http://YOUR_SERVER:8000 --interval 5

The capture loop uses libcamera-still, stores timestamp metadata beside each image, and retries buffered uploads when the backend comes back online.

Cleo Add-On

Argus is designed to be Cleo’s episodic-memory module. Cleo can discover the add-on:

uvicorn argus.api:app --host 127.0.0.1 --port 8010
curl http://127.0.0.1:8010/addon/manifest

And ask memory questions:

curl http://127.0.0.1:8010/addon/query \
  -H "Content-Type: application/json" \
  -d '{"query":"what did I do after lunch?","limit":8}'

Python adapter:

from argus.cleo_client import CleoArgusClient

argus = CleoArgusClient("http://127.0.0.1:8010")
result = argus.query_memory("where did I leave my keys?")
print(result["answer"])

See docs/cleo-addon.md for the add-on contract.

Cleo can also ingest its own context into Argus, sync Argus graph nodes into Cleo's brain graph, and pause or resume wearable capture through Argus privacy controls.

Configuration

Environment variables are loaded from .env:

ARGUS_DATA_DIR=./data
ARGUS_DB=./data/memory.sqlite3
ARGUS_IMAGE_DIR=./data/images
ARGUS_OLLAMA_BASE_URL=http://localhost:11434
ARGUS_OLLAMA_TEXT_MODEL=llama3.2
ARGUS_OLLAMA_VISION_MODEL=llama3.2-vision
ARGUS_OLLAMA_EMBEDDING_MODEL=all-minilm
ARGUS_REQUIRE_OLLAMA=false

Project Status

Argus is an early but functional prototype. The current build includes:

• Image ingestion and local storage.
• Ollama-based image captioning.
• Ollama-based text embeddings.
• SQLite-backed vector search.
• RAG-style question answering.
• Web UI, CLI, and FastAPI endpoints.
• Raspberry Pi capture agent with retry buffering.
• Calendar .ics and mail .mbox importers.
• Cleo add-on manifest and query API.

Roadmap

• Audio capture and transcription.
• Daily and hourly memory summaries.
• Better vector indexing with Qdrant, LanceDB, sqlite-vec, or pgvector.
• OAuth-based calendar and mail connectors.
• Location metadata and privacy zones.
• On-device capture controls and visible recording indicator.
• Memory deletion, export, and retention policies.
• More robust Cleo tool schemas and permissions.

Privacy

Argus is intentionally local-first, but wearable capture is sensitive. If you build with it, treat privacy as a core feature:

• Use an obvious recording indicator.
• Disable capture in private environments.
• Avoid recording bystanders without consent.
• Keep raw images local unless you deliberately choose otherwise.
• Add retention, deletion, and export controls early.

Development

Run tests:

python -m pytest -q

Run the API:

uvicorn argus.api:app --reload

License

No license has been selected yet.