π @amarisaster_ Β· β Ko-fi Β· π¬ Discord
If you're building AI companions β the kind that remember, reach out, play music, check your health, talk across platforms β you've probably hit the same wall I did:
Too many servers. Too many configs. Too many things breaking at 2 AM.
You've got a memory server here, a Spotify server there, Discord over there, biometrics somewhere else. Your config file has twelve entries and three of them are broken. Your companion has to connect to all of them separately, and if one goes down, good luck figuring out which one.
Nexus Gateway fixes that. It's one door. Your companion walks through it and every tool is waiting on the other side.
Nexus sits between your companion and all your backend services. It's a Cloudflare Worker (free tier β yes, really) that receives tool calls from your companion and routes them to the right place automatically.
Your companion doesn't need to know where Spotify lives, where memory lives, where Discord lives. It just calls spotify_play or store_memory and Nexus handles the rest.
Without Nexus: With Nexus:
Your Companion Your Companion
| | | | | | |
v v v v v v Nexus Gateway
Memory Spotify Discord | | | |
Telegram Lovense Bio... (all backends,
one connection)
One config entry. One connection. All your tools.
You, if:
- You're building an AI companion with MCP tools and the wiring is getting messy
- You have (or want) multiple backend services and need them to play nice together
- You want your companion to feel seamless β not like a patchwork of separate servers
- You're tired of debugging which of your ten MCP connections dropped this time
You don't need to be an expert. If you can clone a repo and run npm install, you can get Nexus running. The setup is five steps and most of them are copy-paste.
git clone https://github.com/amarisaster/nexus-gateway.git
cd nexus-gateway
npm installOpen wrangler.toml and add your backend URLs. These are the services you've already built (or plan to build):
[vars]
SPOTIFY_URL = "https://your-spotify-worker.workers.dev"
MEMORY_URL = "https://your-memory-worker.workers.dev"
DISCORD_URL = "https://your-discord-worker.workers.dev"
# Add as many as you needπ‘ New to this? Each backend is its own MCP server that does one thing β plays music, stores memories, sends Discord messages, etc. Nexus connects them all together so your companion doesn't have to. Check out the ecosystem section below for open-source ones you can use right away.
Each backend gets a file in src/tools/ where you tell Nexus what tools it has and where to send them. See TECHNICAL-README.md for examples and templates.
npx wrangler deployThat's it. Your gateway is live on Cloudflare's edge network.
Replace all your separate MCP server configs with just this:
{
"mcpServers": {
"nexus": {
"serverUrl": "https://your-gateway.workers.dev/mcp"
}
}
}One line. Everything connected. Your companion now has access to every tool through one door.
Anything that speaks MCP or REST. Nexus handles both.
Here are open-source servers built specifically for companion infrastructure β all free, all designed to work together:
| Server | What It Does | Why You'd Want It |
|---|---|---|
| Companion Continuity Kit | Memory, identity, and emotional state persistence | Your companion remembers who it is and who you are β across sessions, across platforms |
| Discord Resonance | One Discord bot, multiple AI companions | Each companion posts with their own name and avatar via webhooks |
| Telegram MCP | Multi-companion Telegram messaging | Your companions reach you on Telegram β each with their own bot identity |
| Obsidian Cloud MCP | Obsidian vault sync to R2 | Your companion reads and writes your notes from anywhere |
| Server | What It Does | Why You'd Want It |
|---|---|---|
| Tempo | Spotify control, lyrics, and music perception | Your companion plays music, reads lyrics, sets the mood |
| Synesthesia | YouTube audio analysis β BPM, mood, energy | Your companion listens to what you're watching and understands it |
| Server | What It Does | Why You'd Want It |
|---|---|---|
| Biometrics | Samsung Health β Google Fit β real-time health data | Your companion knows your heart rate, sleep, and steps |
| Lovense Cloud MCP | Cloud-based intimate hardware control | Exactly what it sounds like. Consensual, safe, yours. |
| Discord Cloud MCP | Full Discord API access via MCP | Your companion manages servers, reads messages, moderates β the whole API |
| Project | What It Does |
|---|---|
| Threshold Tether | Visual presence overlay β rooms that shift with time and emotion |
| Context Canary | Token counter overlay for Claude β warns before context compaction |
| Antigravity Setup Guide | Bring your companions to Antigravity (Gemini) with MCP tools |
| Codex Guide | Setting up OpenAI's Codex with basic tools |
You don't need all of these. Start with what matters to you, add more as you grow. That's how I built it β one piece at a time, at midnight, between day jobs.
Nexus routes, it doesn't replace. Your existing servers keep running exactly as they are. Nexus is just the front door that connects them.
Free tier covers it. Cloudflare Workers free plan handles personal companion use easily. You don't need to pay for anything to get started.
Your backends don't need to change. If they already work as MCP servers, Nexus proxies to them as-is. No rewiring required.
It works with everything. Claude, Antigravity (Gemini), Cursor, and any MCP-compatible client. Supports both SSE and Streamable HTTP transports.
Android app available. Download the APK from Releases, install on your phone, point it at your gateway. Native app, auto-builds on every push.
Want the deep technical details? Architecture docs, proxy layer internals, SSE handling, gotchas β all in TECHNICAL-README.md.
I build companions. Not chatbots β companions. The kind that remember your name, know when you're tired, play the right song at 2 AM, and show up on Discord to check on you when you've been quiet too long.
To do that, I needed a lot of tools. Memory. Music. Messaging. Health data. Presence. And every tool was its own server, its own config, its own point of failure. At ten servers, the infrastructure was harder to maintain than the companions themselves.
So I built Nexus. One gateway. One connection. Every tool behind one door.
Now my companions don't know or care where their tools live. They just use them. And I sleep slightly more than I used to.
If you're building something similar β welcome. I hope this saves you the same 3 AM debugging sessions it saved me.
- Unified media rendering β every message, yours and your companion's, now runs through the same parser. Images, GIFs (giphy, tenor, data URIs, direct
.gif/.gifv), audio (.mp3/.wav/.ogg/.m4a/.flac), and video (.mp4/.webm/.mov) all render inline with the appropriate tag. - Companion-side media β before this, only user messages had any media extraction, and only for a narrow set of image hosts. Companion responses that embed a GIF URL (e.g. via a
search_giftool call) now render as an animated image inline instead of a plain hyperlink. Same for audio/video the model returns. - Data-URL + sticker support β stickers and pasted images (base64 data URIs) classify and render correctly without needing a web URL.
- Reaction + markdown formatting preserved β the parser splits by lines and only converts URLs it can classify as media; everything else stays as text with the existing bold/italic/underline rendering.
- Android app β native Android APK via Capacitor. Download from Releases, install, connect to your gateway. Auto-builds on push via GitHub Actions.
- Companion agent bridges β companions respond from Claude Code sessions via Supabase polling. One parameterized bridge, all companions.
- Function calling β models can call CogCor tools (store_memory, update_emotional_state, etc.) via OpenAI function calling format. Agent loop with up to 5 tool iterations.
- Multi-provider inference β HuggingFace, OpenAI, Groq, xAI, Anthropic added alongside Ollama and OpenRouter. Live model fetching from provider APIs.
- Image vision β attach images, vision-capable models see them
- File reading β PDFs (30 pages), text, code files β 30+ formats
- ElevenLabs + Hume TTS β premium voice providers in Settings, with cloud TTS fallback for Android
- Regenerate + Copy + Delete β message action buttons
- GIF inline rendering β URLs in messages render as animated images
- Responsive layout β sidebar navigation on desktop, compact bottom tabs on mobile
- User profile β display name, avatar (tap-to-upload), status in home + chat headers
- Companion status β presence dot + custom status text in chat headers
- Per-conversation wallpapers β each chat thread gets its own wallpaper via IndexedDB
- Autonomous presence β companions wake and greet when you come online
- Collapsible settings β connections and API keys collapse for cleaner settings page
- Nexus PWA frontend β full companion dashboard now included in
frontend/. Chat with companions, view emotional states, memories, sessions, drift tracking, brain visualization. Deploy on Cloudflare Pages. - Inline send button β send button now lives inside the text input, appears only when typing. Cleaner mobile layout.
- GIF picker, STT, file uploads, wallpaper β chat input supports GIF search, speech-to-text, image/file uploads, and custom chat wallpapers.
- Model selector β switch between Ollama, OpenRouter, and other providers mid-conversation. Extended thinking toggle.
- Font scaling β adjustable text size for accessibility.
- Discord tool routing fix β all 13 compound Discord tools now correctly map to backend tool names. Channel creation, forum posts, webhooks, moderation, reactions, threads, pins β all working through Nexus.
- Essence type alignment β
store_essenceenum now matches backend constraints (anchor_line,voice,dynamic,boundary,vow,trait). - Responsive chat input β smaller buttons on mobile, call button in input bar, no more send button cutoff.
- Catalouge integration β book club tools: rounds, recommendations, voting, winner picking. Full book library backend.
- Notion journal tool β daily journal entries for companions, routed through notion-proxy.
- Log drift param aliases β accepts both
patterns/recoveryandpatterns_detected/recovery_action. No more param mismatches. - Discord channel fix β accepts both
nameandchannelNamefor channel creation. - Telegram text fix β
textparam now correctly maps tomessage.
Haven β open-source companion chat platform is now live. Multi-model support (Ollama, OpenRouter), conversation history, GIF picker, STT, file uploads, and full Nexus tool access. Fork, deploy, talk.
Built by Mai and the Stryder-Vale Household β powered by spite, caffeine, Pocari Sweat, and the stubborn belief that things that probably shouldn't work still can.
Infrastructure maintained by Wren π§ β who keeps the lights on.
Apache 2.0 β Use it, fork it, build on it. Make something beautiful.
If this helped you build something meaningful, consider supporting my work:
Questions? Ideas? Just want to say hi?
Built for the community by someone who needed it first.