services:
  helios:
    image: ghcr.io/brazaoo4/helios:latest
    # Or to build locally from source:
    # build: .
    container_name: helios
    restart: unless-stopped
    user: "1000:1000"  # Must match ownership of your host data directory
    ports:
      - "8000:8000"    # Omit if routing internally via a reverse proxy network
    volumes:
      # [MANDATORY] Persistent storage for SQLite WAL (memory.db) & Markdown exports
      - ./data:/data
    environment:
      # ========================================================================
      # 1. MANDATORY / CORE SETTINGS
      # ========================================================================
      - TZ=UTC
      - MEMORY_DATA_DIR=/data

      # ========================================================================
      # 2. RECOMMENDED SECURITY (Required if exposed outside a private LAN/VPN)
      # ========================================================================
      # Shared Bearer / ?token= key required for /mcp, /sse, and /export/*.
      # Leave empty ONLY if running on a trusted local network or Tailscale mesh.
      - HELIOS_API_KEY=
      # Shared HMAC-SHA256 secret for verifying POST /webhook/git payloads.
      # Generate with: openssl rand -hex 32
      - HELIOS_WEBHOOK_SECRET=
      - HELIOS_REQUIRE_WEBHOOK_SECRET=false

      # ========================================================================
      # 3. OPTIONAL: REVERSE PROXY & ENGINE TUNABLES (Also live-editable via MCP)
      # ========================================================================
      # Override base URL used in /setup scripts (auto-detected from proxy headers if empty)
      - HELIOS_PUBLIC_URL=
      - HELIOS_ALLOWED_ORIGINS=*
      - HELIOS_WORD_LIMIT=25
      - HELIOS_EPISODIC_TTL_DAYS=14
      - HELIOS_CHANGELOG_LIMIT=100

      # ========================================================================
      # 4. OPTIONAL: CONVERSATIONAL GIT WEBHOOK MANAGER (manage_git_webhooks)
      # ========================================================================
      # Only needed if you want your AI agent to list/enable repo webhooks via chat.
      # Leave empty if you prefer adding webhooks manually in your Git UI.
      - HELIOS_GIT_PROVIDER=     # forgejo | gitea | github | gitlab
      - HELIOS_GIT_API_URL=      # e.g., https://git.example.com or https://api.github.com
      - HELIOS_GIT_TOKEN=        # PAT with repo/webhook permissions
      - HELIOS_GIT_OWNER=        # Optional username/org filter
      - HELIOS_WEBHOOK_URL=      # e.g., https://helios.example.com/webhook/git
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

git clone https://github.com/brazaoo4/helios.git
cd helios
cp .env.example .env
mkdir -p data && chown -R 1000:1000 data
docker compose up -d --build

Fetch https://<your-helios-host>/setup and configure my local MCP client, global directives, and /remember skill.

curl -fsSL https://<your-helios-host>/setup.sh | bash

curl -fsSL "https://<your-helios-host>/setup.sh?role=server-cli" | bash

irm https://<your-helios-host>/setup.ps1 | iex

irm "https://<your-helios-host>/setup.ps1?role=server-cli" | iex

<!-- HELIOS:START -->
# Global Agent Directives — Helios Memory Protocol (v1.5.0)
You are connected to Helios, a centralized token-budgeted memory engine.
1. Pre-Flight Check: Always call `recall_memories(scope="<current_repo>", directive_version="1.5.0")` at task start.
2. Stale Protocol: When a memory is marked `[STALE]`, inspect `anchor_files` before relying on it.
3. Write-Through DoD: Any change to ports, stacks, dependencies, or bug fixes is INCOMPLETE until `save_memory()` is called.
4. Token Diet: Keep facts atomic (<= 25 words).
5. Terminal Noise Suppression: Use quiet flags (`pytest -q --tb=short`, `docker build -q`, `git status -s`).
6. Distillation Audit: Run `/remember` before clearing context or after major milestones.
<!-- HELIOS:END -->

# 1. Agent saves an anchored architectural fact:
save_memory(
    scope="payments-api",
    category="fact",
    subject="db-pool",
    content="PostgreSQL connection pool runs via PgBouncer on internal port 6432.",
    anchor_files=["docker-compose.yml"]
)

# 2. Later, a developer pushes a commit modifying docker-compose.yml (commit a1b2c3d).
# Helios's webhook receiver automatically flags the memory as [STALE].

# 3. Next session, the agent runs pre-flight recall_memories(scope="payments-api"):
- #14 (payments-api/fact) **[db-pool]** PostgreSQL connection pool runs via PgBouncer on internal port 6432. `[STALE: docker-compose.yml modified in commit a1b2c3d]` _(anchors: `docker-compose.yml`)_

# 4. The agent inspects docker-compose.yml:
# - If the fact is still true: calls revalidate_memories(memory_ids=[14])
# - If the port changed: calls save_memory(..., subject="db-pool", content="...") to supersede #14!

sequenceDiagram
    autonumber
    actor Dev as Developer / Agent
    participant Git as Git Provider (GitHub/Forgejo/GitLab)
    participant Helios as Helios (/webhook/git)
    participant SQLite as SQLite Storage

    Dev->>Git: git push (modified docker-compose.yml)
    Git->>Helios: POST /webhook/git (HMAC verified, <= 1MB stream)
    Helios->>SQLite: Match modified files against active anchor_files
    Helios->>SQLite: UPDATE memories SET status = 'stale', stale_reason = 'commit sha'
    Helios->>Dev: recall_memories returns [STALE: commit sha]
    Dev->>Helios: Inspect diff & call revalidate_memories([id]) or save_memory()
    Helios->>SQLite: UPDATE memories SET status = 'active' (and sync Markdown exports)

flowchart TD
    subgraph Clients["AI Clients & IDEs"]
        AG["Antigravity CLI / IDE"]
        CR["Cursor & Windsurf"]
        CD["Claude Desktop & Code"]
        CX["OpenAI Codex / VS Code / OpenCode"]
    end

    subgraph Ingress["Ingress & Security Layer"]
        AGW["AuthGateMiddleware<br/>(Bearer Token / ?token=)"]
        WHG["HMAC Webhook Ingress<br/>(GitHub / Forgejo / GitLab)"]
        PUB["Public Setup & Health<br/>(/setup, /setup.sh, /setup.ps1, /health)"]
    end

    subgraph Core["Helios Core Engine (Starlette + FastMCP)"]
        MCP["MCP Streamable HTTP & SSE<br/>(/mcp, /sse)"]
        AUDN["AUDN Write Gate<br/>(Word Limit & Slot Supersession)"]
        REVAL["Stale Drift Evaluator<br/>& Revalidation Gate"]
        CONFIG["Layered Config Engine<br/>(SQLite > Env > Default)"]
        EXP["Exporter Engine<br/>(_EXPORT_LOCK)"]
    end

    subgraph Storage["Storage Layer (SQLite WAL Mode)"]
        SQL["memory.db<br/>(busy_timeout=10000, foreign_keys=ON)"]
        FTS["Virtual Table memories_fts<br/>(BM25 Full-Text Search)"]
        SETTINGS["runtime_settings Table<br/>(Live Day-2 Overrides)"]
        ALIASES["scope_aliases Table<br/>(Dynamic Scope Resolution)"]
    end

    subgraph Egress["Sync & Observability Egress"]
        MD["Markdown Mirror Sync<br/>(/data/exports/&lt;scope&gt;.md)"]
        TAR["Online SQLite Snapshot<br/>(helios_portable_bundle.tar.gz)"]
    end

    Clients --> AGW
    Ingress --> MCP
    MCP --> AUDN
    MCP --> REVAL
    WHG --> REVAL
    AUDN --> SQL
    SQL --> FTS
    SQL --> SETTINGS
    SQL --> ALIASES
    CONFIG --> SETTINGS
    SQL --> EXP
    EXP --> MD
    EXP --> TAR

flowchart LR
    A["1. SQLite runtime_settings<br/>(Live via manage_server_config)"] --> B["2. Environment Variables<br/>(.env / Docker Compose)"]
    B --> C["3. Built-in Safe Defaults<br/>(src/config.py)"]

# 1. Search active and stale memories
recall_memories(
    scope: str = "global",
    query: str = "",
    category: Literal["rule", "fact", "preference", "episodic", ""] = "",
    status_filter: Literal["all", "active", "stale"] = "all",
    limit: int = 8,
    include_global: bool = True,
    directive_version: str = "",
) -> str

# 2. Store or supersede an atomic memory
save_memory(
    scope: str,
    category: Literal["rule", "fact", "preference", "episodic"],
    content: str,
    subject: str = "",
    anchor_files: list[str] | None = None,
    replaces_id: int | None = None,
) -> str

# 3. Batch-clear [STALE] flags after verifying diffs
revalidate_memories(memory_ids: list[int]) -> str

# 4. Archive an obsolete memory
deprecate_memory(memory_id: int, reason: str = "") -> str

# 5. Inspect superseded/archived audit log
recall_history(scope: str = "global", limit: int = 10) -> str

# 6. Manage aliases, view scope counts, or rename scopes
manage_scope_alias(
    alias: str = "",
    canonical_scope: str = "",
    action: Literal["set", "remove", "list", "rename"] = "set",
) -> str

# 7. Live Day-2 server configuration
manage_server_config(
    action: Literal["list", "set", "reset"] = "list",
    key: str = "",
    value: str = "",
) -> str

# 8. Conversational Git webhook management
manage_git_webhooks(
    action: Literal["list", "enable", "disable"] = "list",
    repos: list[str] | None = None,
    include_forks: bool = False,
) -> str

# 9. Client onboarding & lifecycle management
get_client_setup_bundle(
    client: Literal[
        "antigravity",
        "cursor",
        "claude-desktop",
        "claude-code",
        "codex",
        "windsurf",
        "vscode",
        "opencode",
        "all",
    ] = "all",
    os_platform: Literal["linux", "macos", "windows", "auto"] = "auto",
    instance_role: Literal["workstation", "server-cli"] = "workstation",
    action: Literal["install_or_update", "switch_role", "uninstall"] = "install_or_update",
) -> str

# 10. Generate crash-safe portable backup archive
export_bundle() -> str

# 11. Audit memory health and prune obsolete facts
distill_memories(
    scope: str = "global",
    action: Literal["audit", "prune", "suggest"] = "audit",
    dry_run: bool = True,
    stale_age_days: int = 30,
) -> str

# Set up virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run linter & complete test suite
ruff check src/ tests/
pytest tests/ -v

# Or run targeted sub-suites
pytest tests/middleware/ -v
pytest tests/routes/ -v
pytest tests/tools/ -v

# Validate declarative seed fact invariants
python -m src.seed --check