Shadow

A Discord roleplay bot portraying Shadow the Hedgehog. Note: If you use this, edit the prompt.ts file to fit what you want. Because this is geared to my own ocs and worlds xd.

Features

• Immersive scene narration with locations, movement, body language, and action
• Story continuity across messages
• Combat choreography and competitive banter
• Persistent memories for relationship and roleplay details
• In-character Japanese tutoring and correction
• Optional proactive away messages
• OpenRouter free-model routing
• Optional Tavily web search with source links

Environment

Create .env:

DISCORD_TOKEN=your_discord_bot_token
OPENROUTER_API_KEY=sk-or-v1-your_openrouter_key
OPENROUTER_MODEL=openrouter/free

DATABASE_PATH=./data/shadow.sqlite
TAVILY_API_KEY=tvly-your_tavily_api_key
LOG_LEVEL=info
DEBUG_PROMPTS=false

DATABASE_PATH is the local SQLite file used for memories, story history, and settings. SQLite is built into Bun, runs entirely on your computer, and needs no account or paid database service.

OPENROUTER_MODEL must be openrouter/free or a specific model ending in :free. This prevents accidentally selecting a paid model.

OPENROUTER_BASE_URL points the OpenAI-compatible client at OpenRouter. OPENROUTER_SITE_URL identifies this bot to OpenRouter for app attribution. Both are optional because the shown values are built-in defaults.

TAVILY_API_KEY is optional. Create a free key at https://app.tavily.com and add it to .env to enable web search. The bot uses basic searches only, costing one Tavily credit per search, and reports the remaining monthly credit balance after each search.

Run

bun install
bun run typecheck
bun run dev

For a production build:

bun run build
bun run start

Discord Commands

• /model changes response length and temperature without leaving free models.
• /memories shows and manages what Shadow remembers.
• /away configures optional proactive messages.
• /prefix changes the prefix for message commands.

Important Files

• src/ai/prompt.ts: Shadow's characterization and roleplay style
• src/ai/chat.ts: sends conversations to OpenRouter
• src/ai/session.ts: maintains ongoing story context
• src/ai/context.ts: builds recent conversation and memory context
• src/tools/memory.ts: persistent relationship and story memories
• src/bot.ts: Discord events and reply handling