SPEC.md

# MM1 Specification

## Goal

Build a local Gradio prototype that demonstrates a privacy boundary between a small personal agent and internet-facing agents.

## Requirements

- Runs with `python app.py`.
- No local GPU required.
- In default live mode, does not use mock data. If a live tool is unavailable, it reports that explicitly.
- Stores memory locally in JSON files.
- Extracts candidate memory from chat.
- Lets the user accept, edit, reject, or delete memory.
- Routes tasks to `local_answer`, `direct_search`, or `codex_big_agent`.
- Writes an engineering trace with private memory, sanitized outbound task, route, result summary, and final private synthesis.
- Tests fail if accepted memory leaks into outbound payloads.

## Runtime Modes

- `MOCK_MODE=false`: live mode; no fixture/mock result is used.
- `MOCK_MODE=true`: optional deterministic development fixtures.
- `DIRECT_SEARCH_ENABLED=true`: try live search when mock mode is off.
- `CODEX_RUNTIME_MODE=true`: allow Codex runtime when available.
- `HACKATHON_COMPLIANT_MODE=false`: concept demo mode where Codex backend usage is allowed.

## Data

Local runtime data is stored under project-local `data/`:

- `memory.json`
- `memory_events.jsonl`
- `engineering_events.jsonl`
- `fixtures/`
- `runs/<run_id>/trace.json`
- `runs/<run_id>/codex_workspace/`