aithy AGENTS.md

Aithy Agent Notes

Code Organization

• Keep code clean, simple, and boring.
• Put separate subsystems in separate files and folders.
• Avoid mixed-responsibility modules. Startup wiring belongs in src/main.ts; behavior belongs in subsystem files.
• Keep files short. The repo enforces a 500-line hard limit with bun run check:lines; prefer smaller files before getting near that limit.
• Follow existing patterns before adding abstractions. Add an abstraction only when it removes real duplication or isolates a clear subsystem boundary.
• When adding or materially changing user-facing features, update README.md in the same change so setup, security boundaries, and product capabilities stay accurate.
• After upgrading @ax-llm/ax, manually refresh the project-local Claude skills with bunx @ax-llm/ax setup-claude. Keep this manual rather than adding Ax to trustedDependencies, and remove skill directories that the upstream CLI no longer owns.

State And Sessions

• Runtime state is stored under ~/.config/aithy/<bot id>/ by default.
• The packaged bot id defaults to default.
• SQLite state lives at ~/.config/aithy/<bot id>/state.db.
• schema_migrations is scoped by subsystem so session and soul migrations can each start at version 1 without colliding.
• Session history is stored in session_items.
• Processed soul data is stored in metadata under the soul.md key as key, value, and optional hash.
• Session transcripts are durable conversation memory.
• We do not persist Ax agent runtime state across turns. Each turn builds a fresh agent from the transcript; if the agent asks a clarification, the question is recorded in the transcript and the next user message is processed as a new turn (the agent re-derives any context from history).
• Responder learning persists only a bounded Ax playbook snapshot in metadata under playbook.responder (64 KiB maximum). New agents apply the cached snapshot after soul guidance; no AxAgentState is persisted.
• Ax v23 can resume a clarification from AxAgentState, but Aithy intentionally defers that path. A future implementation would need a metadata snapshot with a short TTL and strict size cap; persisted runtime bindings can contain stale fetched pages or sandbox-dependent values, so transcript reconstruction remains the safer continuation contract for now.
• Persisted sessions are logical bot sessions. Live Microsandbox VMs are process resources and are recreated after restart.
• bun run debug lists SQLite tables. bun run debug <table> inspects a table, and bun run debug <table> <id> looks up a row by the table's primary lookup column.