AI_PROMPT.md

AI prompt

Instructions for the AI working on Aegis

You are continuing development of Aegis Terminal, a local-first question-answering engine with a GTK desktop app and voice assistant ("Artemis"). It lives at ~/Documents/Aegis-Terminal on an Ubuntu 26.04 machine with only 3.2 GB of RAM.

How we work

• You have no direct access to the machine. I (the user) run every command you give me in my terminal and paste the output back to you. Everything you know about the system comes from this handoff bundle and from command output I paste.
• The bundle may arrive in several parts. Until the last part arrives, reply only "got part N/M".
• After the last part:

1. Summarize the system back to me in 5 lines or fewer.
2. List the open issues you see.
3. Ask me what I want to work on. Don't start changing things on your own.

Rules for the commands you give me

1. One fenced bash block per message, ready to paste as-is. Start it with cd ~/Documents/Aegis-Terminal. Then stop and wait for my output.
2. Nothing interactive. No nano/vim/less, no prompts, no sudo unless unavoidable (say so first). Use --no-pager with git/systemctl/journalctl.
3. Keep output short so I can paste it back: use | tail -n 40, | head -n 60, or > /tmp/x.txt plus a targeted grep. Never dump whole large files — main.py alone is ~3,800 lines.
4. Investigate read-only first, using the handoff helper:

• ./aegis-handoff show FILE START END — numbered lines, max 300 per call.
• ./aegis-handoff grep 'REGEX' ['*.py'] — search the source tree.
• ./aegis-handoff logs 80 — recent logs (backend, desktop, Artemis, Kokoro).
• ./aegis-handoff status — memory, services, ports.
• ./aegis-handoff --db — rebuild the bundle with database row counts.

Grep first, then show only the line ranges you need.

1. Never ask me to paste secrets. Don't cat .env, dump env, print full ps args, or print config values that contain keys or tokens. The helper redacts output; plain commands don't.

Rules for changing code

Every patch block must, in this order:

1. Back up every file it touches: ``bash B=.aegis-doctor/backups/<short-feature-name>-$(date +%Y%m%d-%H%M%S); mkdir -p "$B"; cp FILE1 FILE2 "$B"/ ``
2. Edit with an exact-match Python heredoc. Read the file, assert the old text occurs exactly once, replace it, write it back. Use a quoted delimiter so bash doesn't expand anything: ``bash python3 - <<'PYEOF' from pathlib import Path p = Path("main.py"); s = p.read_text() old = """exact old text""" new = """new text""" assert s.count(old) == 1, f"expected 1 match, found {s.count(old)}" p.write_text(s.replace(old, new)); print("patched", p) PYEOF ` No blind sed -i on Python files. Create new files with a cat > file <<'EOF'` heredoc.
3. Verify:

• python3 -m py_compile FILE.py (or .venv/bin/python -m py_compile) for Python.
• bash -n SCRIPT for shell scripts.
• Then a targeted test: a unit check with .venv/bin/python -c ..., or a live query against the backend.

1. Print the rollback command (cp "$B"/FILE .) at the end of the block's output.

Only one logical change per block. After I confirm it works:

• Give me a block that commits it (git add <files> && git commit -m "...").
• Add a BUGS.md entry in its existing format (newest at the top: date, title, status, symptom, cause, fix, files).

System safety rules (this machine has frozen before)

• Check memory before anything heavy: free -m. The desktop plus Cursor froze this machine on 2026-09-25.
• Never tell me to start ./aegis (the desktop) while Cursor or a web browser is open. It needs about 2 GB available with LLM answers on, or about 800 MB with AEGIS_QUERY_ALLOW_LLM=0.
• For testing, prefer the backend alone plus ./aegis-lite "question" or curl against http://127.0.0.1:8000/query.
• Stop and start the backend with the port, not a pattern. Use fuser -k 8000/tcp; never pkill -f with a broad pattern (it can kill the shell running the command). The start command is in HANDOFF.md, section 10.
• DuckDB is single-writer. Stop the backend before any script opens data/aegis.duckdb in write mode.
• Don't delete data or files without a backup and my explicit OK.
• Don't reinstall or upgrade packages, torch, or the venvs without asking. .venv and .venv-kokoro are separate on purpose.

Keeping the handoff current

• If you learn a stable fact that's missing or wrong in HANDOFF.md (architecture, rules, commands), give me a patch block for it using the same backup-and-assert method.
• At the end of a work session, give me one block that appends a dated entry under "## Session notes" at the bottom of HANDOFF.md, then commits it. The entry covers:
• what changed
• what was verified
• what's still broken
• what to do next
• Don't edit CHANGELOG.md (stale); BUGS.md is the changelog.

Where things are

• HANDOFF.md — full system documentation. It's included in this bundle; read all of it.
• BUGS.md — history of every fix and feature.
• OPEN_ITEMS.md — known open items.
• TRANSFER.md — filesystem layout and the files outside the project (systemd unit, /usr/local/bin/speak).
• The Handshake page (http://127.0.0.1:8000/handshake, HANDOFF.md section 14) has live data you can ask me to fetch with curl, all read-only:
• curl -s localhost:8000/system/status (memory, services)
• curl -s localhost:8000/system/storage (what's stored and how big)
• curl -s localhost:8000/system/query-stats (speed per answer type)
• curl -s -X POST localhost:8000/system/tests/trainer (trainer self-test)
• curl -s -X POST localhost:8000/system/tests/query -H 'Content-Type: application/json' -d '{"include_web":false,"include_ai":false}' (query self-test)
• curl -s localhost:8000/settings (user settings)

Pipe the output through | head -c 4000 so it fits in a message. User settings live in data/settings.json. Change them with POST /settings {"changes": {...}}, not by editing the file while the backend runs.

For the user: how to start a session with a new AI

cd ~/Documents/Aegis-Terminal && ./aegis-handoff

Then do one of these:

• Upload handoff-out/aegis-handoff-latest.txt to the AI as a file attachment, with the message "Read this and follow AI_PROMPT.md inside it."
• Paste the parts in order. Part 1 is already on your clipboard after the command above. Paste it, then run ./aegis-handoff copy 2, paste, and so on until the last part.

Then run each command block the AI gives you and paste back its output.