README.md

Readme

Aegis-Terminal

Local-first Q&A terminal with web ingest, live-data handlers (stock/weather/currency/timezone), and a teach/feedback loop.

Setup

python3 -m venv .venv .venv/bin/pip install -r requirements.txt cp .env.example .env # edit with your keys

Run

.venv/bin/python main.py --no-browser # health: curl -sf http://127.0.0.1:8000/health

Clients (3.2 GB host)

./aegis-lite # terminal REPL — safe with Cursor open ./aegis-lite "what is X" # one-shot query ./aegis-lite --soz # SOZ trainer TUI (curses) ./aegis # GTK desktop (slower while Cursor is open)

Terminal training (facts + corrections)

AEGIS_SPEAK=0 .venv/bin/python train_terminal.py AEGIS_SPEAK=0 .venv/bin/python train_5w.py # train_5w.py covers who/what/where/why/when with phrase variants # so paraphrases hit user_corrections + trained docs.

Query

curl -s -X POST http://127.0.0.1:8000/query \ -H 'Content-Type: application/json' \ -d '{"prompt":"what is hydrogen"}'

Key modules

main.py FastAPI entrypoint, routing, nonsense gate synthesis.py Answer synthesis teach.py Learning / feedback loop web_ingest.py Web fetch & ingest stock.py weather.py currency.py time_zone.py Live-data handlers disambiguate.py disambiguation_route.py Query disambiguation local_search.py indexer.py DuckDB local search

Data

data/aegis.duckdb DuckDB store logs/, data/*.log Runtime logs .aegis-doctor/backups/<feature>-<timestamp>/ Timestamped backups

Working with an outside AI (DeepSeek, etc.)

./aegis-handoff # builds handoff-out/ (redacted, leak-checked) # then upload handoff-out/aegis-handoff-latest.txt to the AI, or paste # the parts in order: part 1 is on the clipboard; ./aegis-handoff copy 2 ... ./aegis-handoff help # show/grep/logs/status helpers the AI will ask for # AI_PROMPT.md tells the AI how to work (one command block at a time, # backups, verification, RAM safety). HANDOFF.md is the system doc.

See HANDOFF.md (system doc), BUGS.md (changelog), OPEN_ITEMS.md.