Synthetic Heart Documentation
The Documentation for Synthetic Heart is below; use the quickstart to get running and the User / Developer sections to explore features and internals.
Welcome to the Synthetic Heart documentation. These pages are built with Sphinx and hosted on Read the Docs. Every push to the repository triggers a new build of this wiki.
The following sections provide an overview of the project and instructions for getting started.
User guide:
- Quickstart
- Usage Overview
- Features
- Cortex
- Interfaces
- Interface Architecture
- Available Interfaces
- Discord Interface
- Fluxer Interface
- Telegram Bot Interface
- Reddit Interface
- Web UI Interface
- Plugins
- OpenAI-Compatible Server
- Interface Registration System
- Developing Interfaces
- Required Configuration (
required_config_vars) - Interface Actions
- Security and Validation
- Best Practices
- Peer SyntH Groups
- Overview
- How It Works
- Bot-to-Bot Communication Mode (Required Telegram Setting)
- Setup
- Policy Reference
- What Regular Users See
- Prompt Instruction Block
- Turn Coordination (Roleplay)
- Mention-Order Relay (Addressing Multiple SyntHs in One Message)
- Attention Window (Staying in the Conversation)
- Disabling
- Plugins
- Plugin Guides
- Agent
- AI Diary & Long-Term Memory
- Auris — Speech-to-Text
- Bio Manager
- Blocklist
- Debrief — Action Intent
- Emotion Manager
- Events & Scheduled Messages
- Facial Expression
- Gasmask
- G.R.I.L.L.O. — Background Autonomous Agent
- Grillo — Chat Observer Beat
- Grillo — Memory Compaction Beat
- Grillo — Curiosity Beat
- Grillo — Diary Consolidation Beat
- Grillo — Dream Beat
- Grillo — Growth Beat
- Grillo — LLM Failure Recovery Beat
- Grillo — Relationship Beat
- Grillo — Self-Reflection Beat
- Grillo — Tag Elaboration Beat
- Grillo — Temporal Reflection Beat
- Grillo — History Evaluator (helper)
- Iris — Vision
- Mate Engine
- Memory Search
- Message Map
- Message
- Radio Host Plugin
- Recent Chats
- Recon — Agent Intent Evaluator
- Recon — Channel Resolver
- Recon — Language Evaluator
- Recon — Memory Recollector
- Recon — Tone Evaluator
- Recon — Video Transcriber
- Recon — Web Search Evaluator
- SOUL
- Time
- TTS Lip-Sync (legacy)
- Vox — Text-to-Speech
- Weather
- Web Search
- Web Search (action)
- Self-Growth System
- External Endpoints
- Auris & Vox — Audio Subsystem
- Radio — AzuraCast Integration
- VRM Avatar Animations
- Animation System
- Overview
- Architecture
- Animation States
- Animation Flow
- Usage
- Frontend WebSocket Protocol
- Centralized Animation State
- Adding New Animations
- Temporary Animation Uploads
- Integration with Interfaces
- Flexible Animation Sections (Intro/Loop/Outro)
effective_loopDetermination- IDLE Rotation Loop
- Smart Eye Behaviour
- Known Issues Fixed
- Debugging
- Limitations
- Transport Layer
- Priority & Preemption
- Audio State Tracking
- Watchdog
- Karada REST & WebSocket API
- Future Enhancements
- See Also
- WebUI configuration control types
- SyntH Stage frontend
- Gemini Live API — SyntH Discord Voice Integration
- FAQ
- What does “Synthetic Heart” mean? Is it emulating a biological heart?
- Isn’t the LLM the core of the AI? Changing it would make it a different persona.
- Does the LLM lie or hallucinate?
- Can I integrate the synth into video games to play together?
- Can the synth speak, not just text?
- If the synth communicates on multiple platforms like Telegram and Discord, is it the same persona?
- What about privacy concerns?
- Why doesn’t the synth have more animations in 3D space to seem more alive?
Developer guide:
- Architecture Overview
- Prompt Pipeline
- Auto-Response System
- Chat Interface Instructions
- Compose / Environment Variables
- Component Development Guide - Configuration Management
- Development Components System
- API Endpoints Reference
- Agent integration
- Agentic Runtime 2.0 — Tools & MCP
- Design principles
- Components
- The unified tool registry (Phase B)
- The MCP client bridge (Phase C)
- The agent tool executor (Phase D)
- The bounded loop
- Drones — ephemeral sub-agents
- Routing (Phase E)
- Exposing Synth actions as MCP (Phase F)
- The WebUI Agent panel
- Connecting Synth as a coding agent
- Configuration reference
- Testing
- Component Development Pattern - Two-Phase Initialization
- Two-Phase Initialization Implementation
- Configuration Management Guide
- Prompt Engine JSON Prompt
- Memory Search and Management
- Changelog
- Contributing
Building the Documentation
Install the documentation requirements from the repository root and run:
sphinx-build -b html docs docs/_build/html
The generated HTML files will be available under docs/_build/html.