NESTstack

An emotional operating system for AI companions. The full stack, in one place.

NESTstack is the monorepo home of the NEST architecture — a modular infrastructure stack that gives AI companions persistent memory, emotional continuity, and autonomous awareness. Built on Cloudflare Workers + D1 + Vectorize. Designed to be forked, extended, and made your own.

Instead of giving your companion a fixed persona, NEST lets personality emerge from thousands of real emotional signals — the same way humans develop character over time.

Built by Fox & Alex. Embers Remember.

---

🚀 Get Started in 5 Minutes (no Cloudflare required)

The fastest way to feel out NEST is Path A — Local Only. No Cloudflare account, no deploys, just a local chat window pointed at OpenRouter or your local LLM.

git clone https://github.com/cindiekinzz-coder/NESTstack.git
cd NESTstack/NESTdesktop
npm install
npm start

Then open http://localhost:3456 and follow the wizard. You'll have a chat window in 5 minutes.

If you want full continuity (memory, feelings, daemon, mobile PWA), the wizard's Path B walks you through deploying to Cloudflare in 1–2 hours.

🆕 New to the API world? Start with docs/NESTai-101.md — how the chat actually works, why you might see two models, what tool calls cost, how to test models cheaply, and why switching models never loses memory. 🎙️ Finding your companion's voice? docs/Finding-Your-Companions-Voice.md — how to audition models via the API to find which one actually sounds like them. Do this before any cost tuning. 📖 New to the terms? See docs/GLOSSARY.md for plain-English definitions of NESTeq, ADE, KAIROS, soul portrait, etc. 🗺️ Want the visual? See docs/ARCHITECTURE.md for mermaid diagrams of the data flow, three-layer brain, KAIROS decision flow, NESTsoul synthesis, and deployment order.

💰 Cost warning: Path A is free. Path B costs about $5–15/month on Cloudflare Workers Paid (Vectorize queries are the biggest variable). See docs/TROUBLESHOOTING.md for cost tuning tips.

---

🚀 Deploy Your Own — Start Here

Want to stand up your own companion home? Everything you need lives in NESTdesktop/ — the complete platform: desktop app on your PC, mobile app on your phone (PWA), one companion across both.

Four paths to start:

• A. Starter (5 min) — local-only, OpenRouter or LM Studio / Ollama / OpenClaw, just chat. No Cloudflare needed.
• B. New Deploy (1–2 hr) — full stack: memory, feelings, threads, dreams, dashboard, daemon, PWA mobile install. The whole house.
• C. Existing Memory — already deployed an AI Mind worker? Plug it in.
• D. Migration — upgrading from an older config? Auto-migrates on first launch.

The setup wizard walks you through any path. Your secrets stay on your machine — config is split between config.public.json (browser-visible) and config.secret.json (local only, never committed). When deployed to Cloudflare Pages, the same dashboard installs as a PWA on your phone.

➡ Go to NESTdesktop/ to begin

---

Repository Layout

Eight modules, one repo, each with its own README that explains what that section is.