Saki
Permission-Aware AI Agent for Discord
Saki is a private, single-guild Discord assistant built as a persistent Gateway service. It combines a structured tool-calling LLM agent with deterministic moderation, persistent memory, scheduled reminders, server administration, image understanding, and music playback.
A private, single-guild Discord assistant combining structured tool execution, deterministic moderation, persistent memory, scheduled workflows, multimodal input, and Lavalink music.
- Role
- Sole Designer and Engineer
- Type
- Independent Production Project
- Status
- Live
- Runtime
- Persistent Discord Gateway Service
- Repository
- Private
Technologies
- TypeScript
- Node.js
- discord.js
- Groq
- SQLite
- FTS5
- Lavalink
- Docker
- Railway
Overview
Saki is designed for one private Discord community rather than as a multi-tenant SaaS product. A guild allowlist rejects requests from every server except its configured home guild.
Unlike a traditional command bot, Saki can interpret natural-language requests and take controlled actions through structured tools. Depending on the requesting user's authorization level, the agent can search server knowledge, summarize conversations, create reminders and events, manage music, perform moderation, or operate Discord resources.
AI is invoked only during explicit interactions such as mentions, replies, /ask, and summarization flows. Fast moderation, member onboarding, reminders, and command handling remain deterministic application services.
Discord acts as the user interface, while the bot process owns command handling, authorization, agent orchestration, moderation, persistence, music, and service integration.
The Problem
Traditional Discord bots are reliable but limited to predefined commands. General-purpose AI chatbots understand natural language but should not receive unrestricted access to moderation tools or server infrastructure.
The engineering question behind Saki was:
“How can an LLM understand natural-language requests and take useful actions inside Discord without receiving uncontrolled administrative authority?”
The Solution
- 01
Discord Gateway Interface
A persistent discord.js process receives messages, slash commands, button interactions, member events, voice-state updates, and raw gateway events required by Lavalink.
- 02
Explicit AI Invocation
The LLM runs only when a user directly mentions Saki, replies to Saki, invokes /ask, or uses another AI-specific flow. It does not process every server message.
- 03
Permission-Aware Agent
The agent receives only the tool schemas available to the requesting user. Public, moderator, and owner tools are exposed separately.
- 04
Defense-in-Depth Execution
Permissions are checked when tools are exposed to the model and checked again when a tool executes.
- 05
Persistent Memory and Knowledge
SQLite stores guild settings, reminders, learned server facts, user memories, and searchable conversation history.
- 06
Deterministic Moderation
Spam bursts and malicious links are handled outside the model for predictable latency, cost, and enforcement.
- 07
Independent Music Service
Music playback runs through a separate Lavalink service so chat, commands, memory, and moderation remain available if music is offline.
Architecture
A persistent Gateway process routes Discord events into deterministic services, a permission-aware AI agent, and an independent music subsystem, with SQLite persistence and external model and Lavalink services.
Discord Gateway
- Messages
- Slash commands
- Buttons
- Member events
- Voice events
Event Router
- Route by event type
- Guild allowlist
- Cooldownowns
Deterministic Services
- Spam filter
- Link filter
- Welcome workflow
- Slash commands
- Reminder scheduler
- Action logging
AI Agent
- Context builder
- Permission-filtered tools
- Model router
- Skills
- Knowledge
- Vision
- Web research
- Tool loop
Music System
- Queue manager
- Player locks
- Voice-state handling
- Lavalink client
Discord Tool Layer
- Public tools
- Moderator tools
- Owner tools
Persistence
- SQLite
- Settings
- User memories
- Server FAQ
- Chat history
- FTS5
- Reminders
Groq / OpenAI-compatible API
- Language models
- Vision models
- Model fallback chain
Lavalink 4
- Voice playback
- Search and source plugins
- Queue state
Core Capabilities
Structured Tool Agent
Executes Discord actions through typed function tools instead of giving the model unrestricted API access.
Permission-Aware Operations
Filters tools according to public, moderator, and owner authorization levels.
Persistent Memory
Stores personal facts, guild knowledge, reminders, and searchable conversation history.
Deterministic Moderation
Handles malicious links and message-burst spam without calling an LLM.
Scheduled Workflows
Creates reminders, polls, and Discord scheduled events.
Multimodal Input
Uses a separate vision-model path for image understanding and comparison requests.
Model Resilience
Supports model fallback, per-model cooldowns, rate-limit handling, and oversized-request recovery.
Music Infrastructure
Uses Lavalink for playback, queue controls, loop modes, shuffle, volume, empty-channel cleanup, and source resolution.
Skills and Knowledge
Loads Markdown playbooks and static guild documentation when relevant.
Graceful Degradation
Keeps moderation and normal commands available if the AI provider or music service is temporarily unavailable.
Agent Runtime
These controls reduce runaway tool loops and unsafe execution. They do not imply that LLM behavior is perfectly predictable or impossible to exploit.
- Maximum five tool rounds per request
- Recent history trimmed for token safety
- User payloads and tool results bounded before entering model context
- Tool schemas filtered before model inference
- Tool permissions checked again during execution
- Malformed tool arguments fail closed
- Leaked tool markup removed from user-facing responses
- Personality instructions reinforced after tool output
- Provider and model fallback logic
- Different handling for rate limits and oversized requests
Permission Model
Public
Can use approved knowledge, reminders, polls, personal memory, music, channel discovery, social interactions, and self-service tools.
Moderator
Can use moderation, message cleanup, slowmode, channel and role operations, voice moderation, event management, and server-fact tools.
Owner
Can access invites, emoji management, webhooks, AutoMod operations, and higher-risk administrative capabilities.
- Tool definitions are filtered before the LLM sees them, but authorization is also checked when the requested operation executes.
- The bot's own Discord role still requires the corresponding API permissions and sufficient role hierarchy.
End-to-End Request Flow
- 01A user mentions Saki, replies to Saki, or invokes an AI command.
- 02The guild allowlist and per-user cooldown are checked.
- 03Deterministic spam and malicious-link controls run when applicable.
- 04Recent channel messages, reply context, user memories, and optional image input are collected.
- 05The speaker's authorization level determines which tool schemas are available.
- 06The model generates prose or structured tool calls.
- 07Tool arguments are parsed and validated.
- 08Permissions are checked again during execution.
- 09The operation runs through Discord.js or an internal service.
- 10Bounded tool results return to the agent.
- 11The loop repeats until complete or the five-round limit is reached.
- 12The final response is sanitized and sent to Discord.
- 13Conversation turns are stored for short-term and searchable long-term recall.
Memory Architecture
Short-Term Conversation Memory
Recent in-process turns scoped by channel and user. This memory is lost on process restart.
Long-Term User Memory
Structured personal facts stored in SQLite with limits on fact count and size. Facts are grouped into preference, identity, event, and general categories.
Searchable Conversation Recall
Persisted chat turns indexed with FTS5, pruned by age and per-channel limits.
Server Knowledge
Static Markdown documentation plus moderator-managed learned facts stored in SQLite.
Reminder Persistence
Scheduled reminders are stored in SQLite and atomically claimed by a polling service.
Deterministic Moderation
Moderation controls run before the AI path. The LLM is not responsible for deciding whether the fast spam or link rules trigger.
- Discord invite filtering
- Known tracking and IP-logging links
- Common credential-theft and fake-gift patterns
- Message-burst spam detection
- Moderator bypass behavior
- Configurable action logging
- Slash-command moderation operations
- Discord bulk-delete limitations for older messages
Music Infrastructure
- Lavalink 4 runs as a separate Railway service
- The bot connects over Railway's private network
- One voice connection is maintained per guild
- Queue mutations are serialized through a guild music lock
- Supports play, pause, resume, skip, stop, queue, loop, shuffle, and volume
- Interactive queue controls use Discord buttons
- Empty channels trigger pause and eventual player cleanup
- Music failures do not disable moderation or AI chat
- Lavalink plugins resolve supported sources and mirror Spotify or Apple Music links through playable providers
Skills and Server Knowledge
Markdown skills provide reusable playbooks for workflows such as music, memory, web research, onboarding, game nights, movie nights, moderation cleanup, and personality behavior.
Static server knowledge contains rules, channels, roles, and operational information. Learned server facts are stored separately in SQLite.
The rules section is intentionally not injected into every personality prompt, but remains available through explicit rules and knowledge tools.
Key Engineering Decisions
Run as a persistent Discord Gateway process.
Rationale: Message events, member events, voice state, moderation, and Lavalink integration require a long-running connection rather than an interaction-only webhook architecture.
Invoke AI only during explicit interactions.
Rationale: This reduces cost, unnecessary message processing, context noise, accidental responses, and privacy concerns.
Keep moderation deterministic.
Rationale: Spam and malicious-link enforcement need predictable behavior independent of model availability or interpretation.
Filter tools before inference.
Rationale: A user cannot persuade the model to call a capability it was never given.
Re-check permissions during execution.
Rationale: Tool visibility is not a replacement for deterministic server-side authorization.
Fail closed on malformed arguments.
Rationale: Invalid model-generated JSON must not silently become empty or default arguments for destructive operations.
Use SQLite for a single-guild deployment.
Rationale: SQLite with WAL mode provides sufficient durable persistence without unnecessary distributed database infrastructure.
Separate Lavalink from the bot process.
Rationale: Music failures should not bring down commands, moderation, memory, reminders, or AI interactions.
Bound agent rounds and context.
Rationale: Tool-loop and context limits reduce duplicate actions, runaway requests, and provider token-limit failures.
Restrict allowed mentions.
Rationale: AI-generated responses must not be able to mass-ping roles or @everyone.
Technical Highlights
- TypeScript ESM runtime
- Node.js 22+
- discord.js v14
- Single allowed guild
- Approximately 29 slash commands
- Three authorization levels
- Maximum five agent tool rounds
- Three memory tiers
- SQLite WAL mode
- FTS5-backed search
- 15-second reminder polling
- Maximum two images per applicable vision request
- Separate bot and Lavalink services
- Optional Message Content and Guild Members intents
- Model fallback and cooldown handling
- Graceful shutdown for reminders, Lavalink, Discord, and SQLite
Technology
Runtime
- TypeScript
- Node.js 22
- tsx
- pnpm
Discord
- discord.js v14
- Discord Gateway
- Slash commands
- Interactive components
AI
- OpenAI SDK
- Groq
- OpenAI-compatible model APIs
- Tool calling
- Vision models
- Model routing
Persistence
- better-sqlite3
- SQLite WAL
- FTS5
Music
- Lavalink 4
- lavalink-client
Infrastructure
- Docker
- Railway
- Persistent volume
- Private service networking
Product Personality
Saki has a configurable personality layer designed to make a utility bot feel native to its community rather than like a generic corporate assistant.
The product presentation is K-pop idol themed, inspired by Sakura Miyawaki of LE SSERAFIM, including profile and banner visuals in that aesthetic. Guild-wide personality modes include Normal, Sarcastic, Overkill, and Cute.
The persona is implemented separately from authorization and tool execution. Changing the personality does not grant additional permissions or alter deterministic moderation rules.
Privacy and Repository Access
The source repository is private because it contains server-specific configuration, private knowledge structures, moderation behavior, internal prompts, Discord resource identifiers, infrastructure conventions, and security-sensitive integrations.
The public case study focuses on architecture, authorization, persistence, agent orchestration, deployment, and non-sensitive demonstrations.
Current Status
Saki is deployed as a persistent private-server assistant. Its AI agent, deterministic moderation, memory, reminders, commands, onboarding, and music systems are separated into modules so individual services can degrade without disabling the entire bot.
Next Steps
Planned work, not completed features.
- Destructive-action confirmation workflows
- More detailed tool-execution audit logs
- Protected user, role, and channel configuration
- Expanded permission-boundary tests
- Structured privacy and data-export controls
- Automated SQLite backup validation
- Agent evaluation tasks
- Improved observability and tool-success metrics
- Memory provenance and expiration controls
- Additional reusable server workflow skills