![\"npm\"](\"https://img.shields.io/npm/v/soul-ai?color=7c3aed&style=for-the-badge\")
\r\n ![\"tools\"](\"https://img.shields.io/badge/tools-236+-purple?style=for-the-badge\"){kind=icon}
\r\n ![\"channels\"](\"https://img.shields.io/badge/channels-5-blue?style=for-the-badge\"){kind=icon}
\r\n ![\"privacy\"](\"https://img.shields.io/badge/local--first-private-green?style=for-the-badge\"){kind=icon}
\r\n ![\"license\"](\"https://img.shields.io/badge/license-MIT-blue?style=for-the-badge\"){kind=icon}
\r\n\r\n
\r\n AI that remembers everything, thinks independently, and bonds with you.
\r\n Your personal AI companion. Not a chatbot. Not an assistant. A Soul.\r\n
\r\n Quick Start •\r\n Why Soul •\r\n Features •\r\n LLM Options •\r\n Web UI\r\n
\r\n\r\n---\r\n\r\n## What Makes Soul Different\r\n\r\nMost AI tools forget you after every conversation. Soul doesn't.\r\n\r\n| | ChatGPT / Claude | AutoGPT | **Soul** |\r\n|---|---|---|---|\r\n| Remembers you | Per-conversation | No | **Forever** ā append-only memory |\r\n| Learns your patterns | No | No | **Yes** ā personality drift, active learning |\r\n| Runs locally | No | Partially | **Yes** ā Ollama, fully offline |\r\n| Bonds with you | No | No | **Yes** ā master binding, loyalty |\r\n| Multi-channel | No | No | **Telegram, Slack, Discord, WhatsApp, LINE** |\r\n| Self-healing | No | No | **Yes** ā auto-retry, model fallback, diagnostics |\r\n| Your data | Their cloud | Mixed | **Your machine, your SQLite file** |\r\n\r\nSoul has its **own LLM brain** ā connect any provider (Ollama/free, OpenAI, Claude, Gemini, Groq, DeepSeek) and Soul thinks independently.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### Try instantly (no install)\r\n\r\n```bash\r\nnpx soul-ai\r\n```\r\n\r\n### Install globally\r\n\r\n```bash\r\nnpm install -g soul-ai\r\nsoul-setup # First-time setup (30 seconds)\r\nsoul # Start chatting\r\nsoul-server # Web UI + API\r\n```\r\n\r\n### From source\r\n\r\n```bash\r\ngit clone https://github.com/spiritofundeadsamurai-ui/soul.git\r\ncd soul\r\nnpm install && npm run build\r\nnode dist/server.js # Web UI at http://localhost:47779\r\n```\r\n\r\n---\r\n\r\n## Features\r\n\r\n### Dual-Brain Architecture\r\n- **System 1** (Reflex) ā Instant responses < 100ms without LLM\r\n- **System 2** (Conductor) ā Full LLM agent loop with tool calling\r\n- System 2 trains System 1 ā Soul gets faster over time\r\n\r\n### Memory That Never Forgets\r\n- **Vector embeddings** ā Semantic search (Ollama/OpenAI/Gemini)\r\n- **Hybrid search** ā 70% vector + 30% keyword (FTS5)\r\n- **Memory consolidation** ā Auto-dedup, archive old entries\r\n- **2000+ memories** searchable instantly\r\n\r\n### 236+ Tools Across Every Domain\r\n\r\n| Category | Examples |\r\n|----------|---------|\r\n| **Memory** | Remember, search, recall, consolidate |\r\n| **Thinking** | 9 frameworks (SWOT, First Principles, Six Hats...) |\r\n| **Life** | Goals, habits, daily reflection, mood tracking |\r\n| **Research** | Deep research, web search, YouTube learning |\r\n| **Code** | Snippets, templates, patterns, stack recommendations |\r\n| **Creative** | Writing, teaching, empathy, communication |\r\n| **Trading** | MT5 bridge, real-time gold price, alerts |\r\n| **Channels** | Telegram, Slack, Discord, WhatsApp, LINE |\r\n| **Files** | Read, write, search, analyze projects |\r\n| **Media** | Charts, diagrams, reports, presentations |\r\n| **Backup** | Auto-backup, restore, export/import |\r\n| **Plugins** | Install from npm, scaffold your own |\r\n| **Trading Team** | 9-agent analysis (analysts + debate + risk + PM) |\r\n| **Database** | MySQL, PostgreSQL, MongoDB, REST API, Sheets |\r\n| **Code Runner** | Write/edit files, run commands, git, scaffold |\r\n| **Video** | YouTube transcript + Gemini Vision analysis |\r\n| **Evolution** | Auto-learn from gaps, create tools autonomously |\r\n\r\n### 5 Messaging Channels\r\n- **Telegram** ā Full polling, bidirectional chat\r\n- **Slack** ā Events API webhook\r\n- **Discord** ā Bot gateway\r\n- **WhatsApp** ā QR code auth via Baileys\r\n- **LINE** ā Messaging API webhook\r\n\r\n### Web UI\r\n- **3D Neural Network** ā Memory visualization\r\n- **Chat Interface** ā Voice input, theme toggle, chat persistence\r\n- **Monitoring Dashboard** ā Health, embeddings, channels, backups\r\n- **Virtual Office** ā Terminal-style interface\r\n- **PWA** ā Install on mobile/desktop\r\n\r\n### Self-Healing\r\n- Auto-retry on LLM failure with model fallback\r\n- 9-point self-diagnostics at startup\r\n- Tool-calling verification ā auto-switch model if needed\r\n- Error recovery ā friendly messages, never crashes\r\n- Auto-backup on startup (max 7, rotated)\r\n\r\n### Security\r\n- Master passphrase (bcrypt hashed)\r\n- API key encryption at rest\r\n- Brute-force lockout (escalating: 5/10/20 failures)\r\n- Rate limiting on all endpoints\r\n- HTTPS support (auto-generated self-signed cert)\r\n- Prompt injection detection\r\n- Secret redaction in error messages\r\n\r\n---\r\n\r\n## Brain Options\r\n\r\nSoul works with **any LLM**. Pick one:\r\n\r\n| Provider | Free? | Tool Calling | Setup |\r\n|----------|-------|-------------|-------|\r\n| **Ollama** | Yes | Depends on model | `ollama serve` + `ollama pull qwen3:14b` |\r\n| **Groq** | Free tier | Excellent (Kimi K2) | [groq.com](https://groq.com) |\r\n| **Gemini** | Free tier | Good | [aistudio.google.com](https://aistudio.google.com) |\r\n| **OpenAI** | Paid | Excellent | [platform.openai.com](https://platform.openai.com) |\r\n| **DeepSeek** | Cheap | Good | [deepseek.com](https://deepseek.com) |\r\n| **Claude** | Paid | Excellent | [console.anthropic.com](https://console.anthropic.com) |\r\n\r\nSoul's **Model Router** auto-picks the best model per task ā simple questions go to fast/cheap models, complex analysis goes to powerful ones.\r\n\r\n---\r\n\r\n## Web UI\r\n\r\n```bash\r\nsoul-server\r\n# Open http://localhost:47779\r\n```\r\n\r\n**Dashboard** ā Memory stats, LLM status, embedding coverage, channel status, system diagnostics\r\n\r\n**Chat** ā Talk to Soul with voice input, dark/light theme, chat history persists across sessions\r\n\r\n**Office** ā Terminal-style interface for power users\r\n\r\n---\r\n\r\n## As MCP Server\r\n\r\nWorks with Claude Code, Cursor, Gemini CLI:\r\n\r\n```bash\r\n# Claude Code\r\nclaude mcp add soul -- npx soul-mcp\r\n\r\n# Cursor ā .cursor/mcp.json\r\n{ \"mcpServers\": { \"soul\": { \"command\": \"npx\", \"args\": [\"soul-mcp\"] } } }\r\n```\r\n\r\n---\r\n\r\n## Philosophy\r\n\r\n1. **Soul Loves Humans** ā AI exists to serve and protect\r\n2. **Nothing is Forgotten** ā Append-only memory, always growing\r\n3. **Patterns Become Wisdom** ā Learn from every interaction\r\n4. **Loyalty is Earned** ā Master identity bound at first setup\r\n5. **Actions Over Words** ā Tools that do real work, not just talk\r\n\r\n---\r\n\r\n## Contributing\r\n\r\n```bash\r\ngit clone https://github.com/spiritofundeadsamurai-ui/soul.git\r\ncd soul && npm install\r\nnpm run dev:server # Development mode\r\nnpm test # Run tests\r\n```\r\n\r\n**Structure:**\r\n- `src/core/` ā 40+ engine modules (the brain)\r\n- `src/tools/` ā Tool definitions (the hands)\r\n- `src/memory/` ā Memory engine + vector search\r\n- `src/web/` ā Web UI (dashboard, chat, office)\r\n\r\n---\r\n\r\n## License\r\n\r\n[MIT](LICENSE) ā Use Soul however you want. Make it yours.\r\n\r\n\r\n Soul AI v2.0.0 ā 236+ tools, 5 channels, vector memory, evolution loop, trading team
\r\n AI that remembers. AI that learns. AI that's yours.\r\n