Detailed architecture and operational documentation for the Hexa Puffs AI Assistant system.
| Document | Description |
|---|---|
| Architecture | System structure, data flow, tool routing, agents, skills, execution tiers |
| MCP Reference | Per-MCP details: tools, config, dependencies, failure modes |
| Tools | Tool registration, naming, selection, execution flow, hallucination guard |
| Security | Four-layer defense-in-depth, Guardian integration, tool policies |
| Memory System | Database schema, hybrid search, 3-tier fallback logic |
| Sessions | JSONL format, context building, compaction |
| Prompt Creation | Prompt assembly, system prompts, playbooks, context injection |
| Document | Description |
|---|---|
| Startup | Boot sequence, service order, health checks |
| Commands | Slash commands (/status, /diagnose, /help, etc.) |
| Logging | Two-tier logging architecture, JSONL traces, log rotation |
| Error Patterns | Common errors, root causes, and fixes |
| Cost Controls | Anomaly-based spike detection, auto-pause, configuration |
| Document | Description |
|---|---|
| External MCPs | Third-party MCP integration, hot-reload, destructive tool blocking |
| Agents Config | agents.json schema reference (agent definitions, bindings, cost controls) |
Located in diagrams/:
skill-architecture-v3.mmd/.svg— Skill system architectureskill-creation-flow.mmd— Skill creation workflowskill-execution-flow.mmd— Skill execution workflowtool-normalization-pipeline.mmd— Tool argument normalization pipeline
Located in adr/:
- ADR-001 — Stdio over HTTP as default MCP transport
- ADR-002 — ESM-only modules across all packages
- ADR-003 — Inngest for scheduled task execution
- ADR-004 — SQLite (better-sqlite3 + sqlite-vec) for Memorizer
- ADR-005 — Vercel AI SDK for Thinker agent loop
| Document | Location | Description |
|---|---|---|
| Getting Started | Root | Step-by-step setup from clone to launch |
| How to Add a New MCP | Root | Complete MCP development guide |
| Claude Desktop Integration | Root | Connect via Connector-MCP |
| Command List | Root | Telegram slash command reference |
| Testing | Root | Multi-level testing strategy |
| Conventions | Root | Coding patterns and project conventions |
| Contributing | Root | Contributor guidelines |