Saki
The server assistant that became the server infrastructure.
Saki combines a permission-aware AI agent, deterministic moderation, Lavalink music, social automation, persistent memory, and a custom K-pop community engine inside one private Discord guild.
- Agentic AI
- Moderation
- Music
- Social Automation
- K-System
- Role
- Sole Designer and Engineer
- Type
- Independent Production Project
- Status
- Live
- Scope
- Single Guild · By Design
- Repository
- Private
Technologies
- TypeScript
- Node.js
- discord.js
- Groq
- SQLite
- Lavalink
- Tailscale
- Railway
Example
@Saki make a movie-night poll for Saturday and remind us two hours before
Poll created · reminder scheduled · permission: public
What Saki Became
Saki began as a private Discord assistant for one server. Over time, it grew into the system behind much of the community itself.
Today, Saki handles natural-language assistance, moderation, music, reminders, onboarding, social embeds, Reddit feeds, server statistics, and a custom K-pop subsystem with profiles, birthdays, elections, Elo-based battles, and community analytics.
Discord remains the interface. Behind it is a long-running event-driven application with its own agent runtime, schedulers, persistent state, permission model, media infrastructure, and failure boundaries.
It is intentionally built for one guild rather than generalized into a multi-tenant product.
Five Systems, One Bot
Modern Saki is not a command list. It is five cooperating systems behind one Discord presence.
Agent Runtime
Natural-language interaction with tool calling, vision, web research, memories, skills, knowledge, and model fallbacks — invoked only on explicit mentions, replies, and AI commands.
- Tool calling
- Vision
- Web research
- Memories
- Skills
- Knowledge
- Model fallbacks
Server Operations
Deterministic infrastructure for moderation, permissions, roles, scheduled events, onboarding, stats, and context menus — independent of model availability.
- Moderation
- Permissions
- Roles
- Scheduled events
- Onboarding
- Stats
- Context menus
Music
Real voice infrastructure with Lavalink, radio and playlists, queue state, preferred home-node + Railway fallback, and empty-VC presence handling.
- Lavalink
- Radio / playlists
- Queue state
- Node failover
- VC presence
Social Layer
Automation outside the agent: Twitter/X, Instagram, TikTok, Reddit, YouTube embed rewriting, and Reddit feed polling with dedupe and media normalization.
- Twitter / X
- TikTok
- Reddit feeds
- YouTube embeds
Delulu Engine
The custom community product: K-Profiles, birthdays, Supremacy elections, Bias Wars, idol analytics, name history, and hall of fame — all with persistent state and scheduled jobs.
- K-Profiles
- Birthdays
- Supremacy
- Bias Wars
- Idol analytics
- Hall of fame
Showcase feature
The Delulu Engine
Custom community mechanics with persistent state, scheduled jobs, and consequences.
There are thousands of Discord bots with an LLM and moderation. Far fewer run server-wide monthly K-pop elections that rename the guild, maintain a hall of fame, track dynasties and landslides, plus Elo-based idol wars and persistent bias profiles.
K-Profile
@estebanech
- Ult
- Gaeul
- Biases
- Haneul · Athena
- Groups
- IVE · KISS OF LIFE
- Obsession index
84%
Derived from profile state, bias records, ult history, idol mention analytics, and search relationships.
Supremacy
- Birthday claim
- Nominations
- Voting
- Crowned
- Server renamed
A monthly server-wide election where members nominate idols, vote on a theme, and the winning result becomes the server name. Saki persists election state, resumes unfinished cycles after restart, tracks historical renames, and maintains hall-of-fame statistics.
Bias Wars
Gaeul
1512 ELO
VS
Haneul
1487 ELO
Voting closes 22:14
Time-boxed idol-vs-idol battles update persistent Elo ratings and head-to-head history after voting closes.
Agent Runtime & Permissions
From message to action — visually compressed, permission-aware, and bounded.
@Saki move John to AFK and remind me in 20 minutes
- 01Discord message
- 02Context builder
- recent messages
- user memory
- permission level
- reply context
- 03Tool filter
- 04Groq
- 05move_voice_member()
- 06permission check
- 07Discord API
- 08create_reminder()
- 09SQLite
- 10final reply
- speaker
- mod
- tools seen
- filtered set
- rounds
- 2 / 5
- memory
- enabled
- result
- success
Permission ladder
Public
Knowledge, memory, music, polls, reminders, events, and self-service tools.
- knowledge
- memory
- music
- polls
- reminders
- events
Moderator
Timeout, kick, ban, purge, channels, roles, voice controls, and locks.
- timeout
- kick
- ban
- purge
- channels
- roles
- voice controls
- locks
Owner
Invites, webhooks, emoji, and AutoMod — higher-risk administrative surface.
- invites
- webhooks
- emoji
- AutoMod
Two checks, not one
Model tool exposure + execution-time authorization
- Tool definitions are filtered before the LLM sees them.
- Authorization is checked again when the requested operation executes.
- The model cannot request a tool it was never given, and being given a tool does not bypass the execution check.
Runtime controls
- 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
- Provider and model fallback logic
Music & Service Resilience
Music is real voice infrastructure with a preferred home node over Tailscale and a Railway fallback — not a single cloud Lavalink box.
saki-home
Preferred · healthy
Home PC · Tailscale · latency ~18ms
saki-railway
Fallback · healthy
Railway · cloud failover
- Preferred home node with Tailscale connectivity
- Railway fallback when the home node is unreachable
- Queue mutations serialized through a guild music lock
- Empty VC pause and resume when humans return
- YouTube / SoundCloud resolution plus Spotify / Apple metadata mapping
- Music failures do not disable moderation, commands, or the agent
AI is not the control plane
Saki works even when the LLM doesn’t.
Without Groq — still works
- Moderation
- Music
- Welcome roles
- Server stats
- Reddit feeds
- Social embeds
- Reminders
- K-System jobs
- Slash commands
Unavailable
- Natural-language agent
Architecture & Persistence
One Gateway process fans out into agent, ops, and K-System planes — sharing SQLite state and a dual-node Lavalink topology.
Discord Gateway
- Messages
- Slash commands
- Context menus
- Buttons
- Member events
- Voice / presence
- Guild state
AI Agent
- Tools / vision
- Memory / web
- Knowledge
- Skills
- Tool loop
Server Ops
- Moderation
- Embeds
- Reddit feeds
- Stats
- Onboarding
- Reminders
K-System
- Profiles
- Birthdays
- Supremacy
- Bias Wars
- Analytics
- Hall of fame
SQLite WAL
- Core state
- Social
- Jobs
- K-System
- FTS5 history
- Memories
Lavalink Client
- Queue
- Locks
- Node manager
Home Node
- Tailscale
- Preferred
Railway
- Fallback
- Cloud
External
- Groq
- Reddit OAuth
- Embed hosts
- Discord APIs
System facts
- 01 guild — by design, not an unfinished SaaS
- 03 authority tiers — Public · Mod · Owner
- 05 max agent rounds — bounded tool execution
- 02 Lavalink nodes — preferred home + cloud fallback
- 01 SQLite database — core, social, jobs, and K-System state
- Multiple event planes — Gateway · schedulers · voice · presence · guild state
Technology
Runtime
- TypeScript
- Node.js 22
- tsx
- pnpm
Discord
- discord.js v14
- Discord Gateway
- Slash commands
- Context menus
- Interactive components
AI
- Groq
- OpenAI-compatible APIs
- Tool calling
- Vision models
- Model routing / fallback
Persistence
- better-sqlite3
- SQLite WAL
- FTS5
Music
- Lavalink 4
- Home node + Railway
- Tailscale
Infrastructure
- Docker
- Railway
- Persistent volume
- Dual-node failover
Engineering Decisions
Run as a persistent Discord Gateway process.
Rationale: Message events, member events, voice state, moderation, K-System jobs, and Lavalink require a long-running connection — not an interaction-only webhook architecture.
Keep AI off the control plane.
Rationale: Moderation, music, feeds, embeds, reminders, and K-System schedulers must keep working when Groq is unavailable.
Filter tools before inference, re-check at execution.
Rationale: A user cannot persuade the model to call a capability it was never given, and visibility is never a substitute for server-side authorization.
Build for one guild on purpose.
Rationale: Single-guild scope keeps SQLite, allowlists, and community mechanics honest instead of pretending to be unfinished multi-tenant SaaS.
Prefer a home Lavalink node with cloud fallback.
Rationale: Tailscale-connected home audio with Railway failover improves latency and resilience without coupling music to the bot process.
Give community mechanics real state machines.
Rationale: Supremacy, Bias Wars, and profiles persist, resume after restart, and mutate Discord — they are product systems, not slash-command toys.
Bound agent rounds and fail closed on bad tool args.
Rationale: Limits reduce runaway loops; invalid JSON must not become empty defaults for destructive operations.
Restrict allowed mentions in AI replies.
Rationale: Model-generated responses must not mass-ping roles or @everyone.
Status & Next
Saki is live as a persistent private-server platform. Agent, moderation, music, social automation, and K-System modules are separated so individual services can degrade without taking down the guild.
The source repository is private because it contains server-specific configuration, private knowledge, moderation behavior, internal prompts, Discord resource identifiers, infrastructure conventions, and security-sensitive integrations.
This case study focuses on architecture, authorization, persistence, agent orchestration, community systems, and non-sensitive demonstrations.
Planned work, not completed features.
- Sanitized demo capture for the public case study
- Destructive-action confirmation workflows
- Richer 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 and tool-success metrics
Social content, automatically normalized
Non-agent messages can still trigger deterministic transformations — embed fixers and feed pipelines that keep working when Groq is down.
Embed rewrite
Before
https://x.com/…
After
Embedded media card via configured fixer
Reddit feed