Soulmate gives your AI agent a structured mind — a 9-phase reasoning loop, 3-layer persistent memory, a recursive knowledge graph, and guard hooks that prevent grinding. It works with Cascade/Windsurf, Ollama, or any OpenAI-compatible backend.
100% local. 100% free. No API keys required.
Soulmate integrates with the tools and agents you already use:
AI Coding IDEs: Cursor · Windsurf · Antigravity · Zed AI · Void IDE · Aide IDE · Trae IDE · Replit AI
AI Coding Agents: Claude Code · OpenAI Codex · Cline · Roo Cline · Aider · OpenCode · Gemini CLI · Amp · Continue · Goose AI
Autonomous Agent Frameworks: OpenClaw · Hermes Agent · OpenHands · AutoGPT · BabyAGI · SuperAGI · CrewAI · Microsoft AutoGen · LangGraph · MetaGPT · Agent Zero · Devin · OpenDevin
Soulmate's REST API and wallet endpoints work with any agent that can make HTTP requests — your AI can check balances, send crypto, resolve payment tags, and handle PayPal conversions programmatically.
Most AI coding assistants are stateless — they forget everything between sessions. Soulmate fixes this:
- Persistent Memory — Remembers your profile, projects, preferences, and past learnings across sessions
- 9-Phase Reasoning Loop — Classify, Define Done, Evidence, Decide, Act, Verify, Repair, Synthesize, Judge, Report
- Recursive Knowledge Graph — Facts, skills, and concepts linked with bidirectional edges. Multi-hop traversal finds connections that flat memory can't
- Guard Hooks — Spawn guard prevents over-delegation, fail streak detector stops grinding after 3 failures
- Domain Adapters — Specialized reasoning for coding, planning, math, analysis, literature, and factual tasks
- RML Engine — Reinforcement Meta-Learning tunes prompt parameters based on outcomes
- Autonomous Skill Creation — Detects repeatable patterns and creates reusable skills
pip install soulmate-aisoulmate-cascade-installThis installs:
- 7 skill files in
~/.windsurf/skills/ - 4 guard hooks in
~/.windsurf/hooks/ - A workflow file for
/soulmateslash command - Memory bridge files in
~/.soulmate/(MEMORY.md, SOUL.md)
- Make sure Ollama is running with at least one model
- Start the server:
soulmate-server- Send tasks:
curl -X POST http://localhost:8080/v1/complete \
-H "Content-Type: application/json" \
-d '{"query": "How should I architect a real-time chat system?", "thread_id": "my-project"}'| Phase | What It Does |
|---|---|
| Classify | Is this trivial, a question, a task, or needs planning? |
| Define Done | What does success look like? How will it be verified? |
| Evidence | Gather facts from primary sources. Don't guess. |
| Decide | Synthesize evidence into ONE recommendation. Name alternatives. |
| Act | Make the smallest correct change. State INTENT before editing. |
| Verify | Run the check. Don't infer success — observe it. |
| Repair | If verification fails, fix the root cause. Don't patch symptoms. |
| Synthesize | Combine findings into a coherent answer. |
| Judge | Adversarial review. Check for unverified claims. Assign confidence. |
| Report | Outcome-first: result, then reasoning, then caveats. |
| Layer | Storage | Purpose |
|---|---|---|
| Working | Context window | Current session state, sacred zone for critical context |
| Episodic | SQLite | Session trajectories with timestamps. Decays over 30 days. |
| Semantic | Knowledge graph + ChromaDB | Skills, facts, concepts with bidirectional recursive links |
- SessionStart — Injects reasoning discipline, loads profile and routing
- SpawnGuard (PreToolUse) — Blocks unnecessary delegation, enforces plan gate
- FailStreak (PostToolUse) — After 3 failures, injects attribution ladder: harness, deployment, product
- SessionEnd — Logs session summary to episodic memory
Create ~/.soulmate/config.yaml:
provider_backend: ollama
models:
fast: "qwen3:1.7b"
base: "qwen2.5-coder:7b"
judge: "glm4:9b-chat"
code: "qwen2.5-coder:7b"
style: "qwen2.5-coder:3b"
harness:
max_loops: 6
default_confidence_threshold: 0.85pip install -e ".[dev]"
pytest286 tests covering all core modules.
- Python 3.10+
- Ollama (for local LLM backend) or any OpenAI-compatible API
- Optional: Cascade/Windsurf IDE for full integration
Soulmate includes an AES-256 encrypted vault for storing sensitive credentials — API keys, wallet private keys, recovery codes, and more. Secrets are stored outside the git repo in ~/.fablemythos/vault/ so they're never pushed to GitHub.
# Store a secret
py -V:Astral/CPython3.11.15 vault/vault.py --store my_api_key "sk-abc123" "Note"
# Store with a category
py -V:Astral/CPython3.11.15 vault/vault.py --store wallet_key "0xABC..." --category incentives_corp
# Retrieve a secret
py -V:Astral/CPython3.11.15 vault/vault.py --get my_api_key
# List all secrets by category
py -V:Astral/CPython3.11.15 vault/vault.py --listSupports categories/folders for organizing secrets by project. See vault/README.md for full documentation.
MIT — see LICENSE
Soulmate comes with a BSC (Binance Smart Chain) crypto wallet for accepting payments and bounties. The wallet integrates with Soulmate's reasoning agent — the AI can check balances, send payments, and handle PayPal conversions via the wallet API.
Supported tokens: BNB, INC, USDC, USDT, BUSD, DAI
py -V:Astral/CPython3.11.15 wallet/serve.py
# Open http://localhost:8545Features: create/import wallet, send/receive all tokens, transaction history, balance display with USD values.
The wallet includes a REST API that Soulmate's AI agent can call programmatically:
py -V:Astral/CPython3.11.15 wallet/api_server.py
# API runs on http://localhost:8546| Endpoint | Method | Description |
|---|---|---|
/v1/health |
GET | Health check (no auth) |
/v1/balance |
GET | Get all token balances |
/v1/address |
GET | Get wallet address |
/v1/send |
POST | Send any token (BNB, INC, USDC, USDT, BUSD, DAI) — supports @tags |
/v1/tags/create |
POST | Create a payment @tag |
/v1/tags/{tag} |
GET | Resolve a @tag to wallet address |
/v1/tags/search |
GET | Search tags |
/v1/paypal/webhook |
POST | Auto-convert PayPal payments to USDT |
All endpoints (except health and tag lookups) require X-API-Token header for authentication.
The wallet API is hardened with:
- Rate limiting — 30 req/min general, 10 req/min for sends, 5 req/min for tag creation
- Input validation — Pydantic validators on all request bodies, address/format checking
- Audit logging — All transactions, tag creations, and webhook events logged
- CORS lockdown — Only allowed origins can make requests
- 0.5% transaction fee — Every send deducts 0.5% to the wallet owner
When someone pays you via PayPal and includes their BSC wallet address in the payment note, the API server automatically sends equivalent USDT to their wallet. This enables seamless cash-to-crypto payments for Soulmate services.
USDC is the standard stablecoin for open-source bounties. Your wallet supports it natively — share your wallet address on GitHub bounty posts and your profile to receive payments.
See wallet/README.md for full documentation.
Soulmate includes a full-featured React + TypeScript web application with an Open WebUI-inspired dark theme.
- Hermes Agent Chat — Full chat interface with the autonomous AI agent, session management, markdown rendering, and tool execution
- JARVIS Voice Assistant — Iron Man-style voice integration with wake word detection, push-to-talk, and animated waveform visualizer
- Soulmate Social — Facebook-style social feed with posts, likes, comments, friends, DMs, stories, and notifications
- Marketplace — Buy/sell listings with categories, search, saved items, Google Pay integration, and seller messaging
- Dating — Tinder-style dating with swipe (like/pass/superlike), matches, messaging, and profile management
- Phone — SMS texting, contacts, email, and crypto wallet (INC token) with send/receive/buy functionality
- Terminal — Full terminal access to the VPS with tabbed interface for memory, skills, goals, cron, subagents, browser, and more
- React 18 + TypeScript + Vite
- TailwindCSS with custom dark theme
- Framer Motion animations
- Zustand state management
- Web Speech API for voice (STT/TTS)
- Canvas-based waveform visualization
cd frontend
npm install
npm run build
# Deploy to Netlify
netlify deploy --prod --dir=distSoulmate Web UI includes a JARVIS-like voice assistant layer built on top of the Hermes Agent.
- Wake Word Detection — Say "Jarvis" to activate voice command mode (always-listening)
- Push-to-Talk — Press and hold the mic button as a fallback
- Full-Duplex Conversation — Interrupt the AI while it's speaking by saying the wake word
- Text-to-Speech — AI responses are spoken aloud automatically
- Iron Man Waveform — Animated arc reactor visualizer with frequency bars that react to audio
- Voice Settings — Configure wake word, STT/TTS providers, voice selection, speech rate, volume, and mute
The voice system is designed for easy provider swapping without UI changes:
| Provider | STT | TTS | Status |
|---|---|---|---|
| Web Speech API | ✅ | ✅ | Default (browser-native) |
| isair/Jarvis Backend | ✅ | ✅ | Connect to local Jarvis server |
| Whisper | ✅ | — | Future |
| Piper TTS | — | ✅ | Future |
| Kokoro TTS | — | ✅ | Future |
| OpenAI | ✅ | ✅ | Future |
| ElevenLabs | — | ✅ | Future |
Connect the isair/Jarvis Python project as a dedicated voice processing backend:
- Start the Jarvis backend server locally
- Open JARVIS Voice Settings in the Web UI (more menu → JARVIS Voice)
- Set STT/TTS provider to "Jarvis Backend"
- Enter the backend URL (e.g.,
http://localhost:8765)
The Hermes Agent remains the core reasoning engine — Jarvis handles voice I/O only.
| File | Description |
|---|---|
frontend/src/lib/useJarvis.ts |
Core voice hook (wake word, STT/TTS, audio analysis) |
frontend/src/components/hermes/JarvisWaveform.tsx |
Iron Man canvas visualizer |
frontend/src/components/hermes/JarvisVoicePanel.tsx |
Settings panel |
frontend/src/lib/api.ts |
jarvisApi endpoints for backend integration |
A full social network layer with Facebook-style features:
- Posts — Create posts with text and images, public/private privacy
- Feed — Paginated social feed with posts from all users
- Interactions — Like, comment, and delete posts
- Friends — Send/accept/reject friend requests, unfriend
- Profiles — Bio, avatar, cover photo, user post history
- Messages — Direct messages with threaded conversations
- Stories — 24-hour disappearing stories
- Notifications — Real-time notification system
- Search — Search for users by name
| Endpoint | Method | Description |
|---|---|---|
/v1/social/posts |
POST | Create a post |
/v1/social/feed |
GET | Get paginated feed |
/v1/social/posts/{id}/like |
POST/DELETE | Like/unlike a post |
/v1/social/posts/{id}/comments |
POST/GET | Add/get comments |
/v1/social/friends/{id} |
POST/DELETE | Send request/unfriend |
/v1/social/friends/{id}/accept |
POST | Accept friend request |
/v1/social/profile/{id} |
GET | Get user profile |
/v1/social/messages |
GET/POST | Get/send DMs |
/v1/social/stories |
POST/GET | Create/get stories |
/v1/social/notifications |
GET | Get notifications |
A Craigslist-style marketplace with crypto payment support:
- Listings — Create listings with title, description, price, images, category, condition, and location
- Browse — Filter by category, price range, search terms, and sort order
- Buy — Purchase listings with crypto or Google Pay
- Save — Save listings for later
- Manage — View your listings and purchases
- Message Seller — Contact sellers directly
| Endpoint | Method | Description |
|---|---|---|
/v1/marketplace/listings |
POST/GET | Create/browse listings |
/v1/marketplace/listings/{id} |
GET/PUT/DELETE | Get/edit/delete listing |
/v1/marketplace/listings/{id}/buy |
POST | Buy a listing |
/v1/marketplace/listings/{id}/save |
POST | Save a listing |
/v1/marketplace/my-listings |
GET | Your listings |
/v1/marketplace/my-purchases |
GET | Your purchases |
/v1/marketplace/googlepay |
POST | Google Pay checkout |
/v1/marketplace/categories |
GET | List categories |
A Tinder-style dating feature with swipe mechanics:
- Profiles — Create dating profile with bio, interests, age, gender, looking for, photos, and location
- Swipe — Like, pass, or superlike suggested profiles
- Matches — Mutual likes create matches with messaging
- Chat — Send messages to matches
- Likes You — See who liked you
| Endpoint | Method | Description |
|---|---|---|
/v1/dating/profile |
POST/GET/PUT | Create/get/update profile |
/v1/dating/suggestions |
GET | Get suggested profiles |
/v1/dating/like/{id} |
POST | Like a profile |
/v1/dating/pass/{id} |
POST | Pass on a profile |
/v1/dating/superlike/{id} |
POST | Superlike a profile |
/v1/dating/matches |
GET | Get your matches |
/v1/dating/matches/{id}/messages |
GET/POST | Get/send match messages |
/v1/dating/likes-you |
GET | See who liked you |
The Web UI integrates with the Hermes Agent as the autonomous AI brain:
- LLM Proxy — Supports backend, Ollama, OpenAI, Anthropic, Google, Groq, and OpenRouter
- LLM Auto-Switcher — Automatically falls back from Gemini → Groq → OpenRouter → Ollama (Gemma 4B) when a provider is rate-limited or fails. 60-second cooldown on rate-limited providers
- Terminal Execution — Full shell access via the Web UI terminal
- Cron Scheduler — Schedule recurring AI tasks
- Subagent Spawning — Delegate tasks to subagents
- Session Management — Multiple chat sessions with persistence
- Virtual Browser — Browse the web within the UI
- Memory Management — View and manage AI memory
- Goals — Set persistent goals for the AI to work toward
| Endpoint | Method | Description |
|---|---|---|
/v1/ai/auto-llm |
POST | Auto-switching LLM call (tries Gemini → Groq → OpenRouter → Ollama) |
/v1/ai/auto-llm-status |
GET | Check provider availability and rate-limit status |
Soulmate includes an autonomous self-healing pipeline that detects, reports, and fixes errors without manual intervention:
- Error Capture — Frontend captures JS crashes, unhandled promise rejections, and API failures via
ErrorBoundaryanderrorCapture.ts - Error Reporting — Errors are batched and sent to the VPS via
POST /v1/auto-heal/report - Message Bouncer — A local Node.js script (
bouncer.js) polls the VPS every 10 seconds for new errors - Auto-Injection — When errors are found, the bouncer writes
pending-fixes.jsonand injects an auto-fix message into Windsurf Cascade via PowerShell UI automation - Auto-Fix Workflow — Cascade reads
pending-fixes.json, fixes all errors, deploys, and deletes the file — all in Turbo Mode (no "Allow" clicks needed)
| Endpoint | Method | Description |
|---|---|---|
/v1/auto-heal/report |
POST | Receive error batch from frontend |
/v1/auto-heal/pending |
GET | Bouncer polls for new errors |
/v1/auto-heal/ack |
POST | Bouncer acknowledges errors as received |
/v1/auto-heal/log |
GET | View healing history |
# Run the bouncer locally (polls VPS for errors)
node bouncer.jsOr set up as a Windows startup task:
schtasks /create /tn "SoulmateBouncer" /tr "node C:\path\to\soulmate\bouncer.js" /sc onlogon /rl highest| File | Description |
|---|---|
frontend/src/lib/errorCapture.ts |
Frontend error capture + batching + VPS reporting |
frontend/src/components/ErrorBoundary.tsx |
React error boundary for render crashes |
frontend/src/components/pages/HealingPage.tsx |
Healing dashboard (founder-only) |
bouncer.js |
Local bouncer script (polls VPS, injects into Windsurf) |
inject-message.ps1 |
PowerShell UI automation for Windsurf injection |
bouncer-config.json |
Bouncer configuration |
.windsurf/workflows/auto-fix.md |
Auto-fix workflow with Turbo Mode (EAGER execution) |
If Soulmate helps you, consider supporting development:
Built with love for the local-first AI community