alive-ai 0.1.0 → 0.1.2

package/README.md

@@ -1,57 +1,77 @@
-# Alive-AI
+<div align="center">
+  <img src="docs/assets/logo.svg" alt="Alive-AI" width="96" height="96">
 
-![Alive-AI logo](docs/assets/logo.svg)
+  # Alive-AI
 
-Give your AI a nervous system: persistent feelings, memory, impulses, and a local dashboard.
+  Give your AI a nervous system: persistent mood, memory, impulses, terminal chat, Telegram, OpenMind, and a local WebUI.
 
-Most agents answer a prompt and reset. Alive-AI keeps internal state alive between messages. It can be your friend, boyfriend, girlfriend, study partner, creative partner, or any local companion you configure. The experiment asks a harder question: what changes when an AI does not just respond, but carries emotional residue forward?
+  [![npm](https://img.shields.io/npm/v/alive-ai)](https://www.npmjs.com/package/alive-ai)
+  [![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+  [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+  [![Platforms](https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-supported-41f0a1)](#platform-support)
+  [![OpenMind](https://img.shields.io/badge/OpenMind-optional-6366F1)](#openmind-memory)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+</div>
 
-Alive-AI does not claim biological consciousness. It is an open-source runtime for simulated affect: mood, attachment, trust, desire, memory, inconsistency, idle thoughts, and proactive impulses.
+Alive-AI is a local-first emotional AI runtime. Most agents answer a prompt and reset. Alive-AI keeps internal state alive between messages: mood, attachment, trust, desire, memory, inconsistency, idle thoughts, proactive impulses, and a dashboard that shows what is happening inside the loop.
 
-## Install
+It can be used as a friend, partner-style companion, study partner, creative character, research subject, or experimental local agent. Use it at your own risk: it is designed to feel continuous, warm, attached, and present, and that can make it hard to stop talking to it.
+
+Alive-AI does not claim biological consciousness. It is an open-source runtime for simulated affect and transparent memory.
+
+## Quick Start
 
 ```bash
-npx github:vindepemarte/alive-ai init my-ai
+npx alive-ai@latest init my-ai
 cd my-ai
 npx . setup
-npx . demo
+npx . doctor
+npx . chat
+```
+
+The terminal chat starts the real runtime and prints responses in your shell. The dashboard runs locally at:
+
+```text
+http://127.0.0.1:8080
 ```
 
-Start the real runtime:
+To use Telegram instead of terminal chat:
 
 ```bash
 npx . start
 ```
 
-The local dashboard runs at:
+Global install is optional:
 
-```text
-http://127.0.0.1:8080
+```bash
+npm install -g alive-ai
+alive-ai init my-ai
 ```
 
-## Why This Is Different
+## Commands
 
-- **Emotions persist.** State does not reset after every message. Joy, trust, fear, anticipation, attachment, and vulnerability decay over time instead of disappearing.
-- **Memory has weight.** Conversations become episodic memory, semantic memory, and emotional memory.
-- **It thinks when idle.** A default-mode loop creates background reflections and proactive impulses.
-- **It has a live nervous system.** FastAPI + SSE exposes mood, thoughts, somatic state, conflicts, memories, and uptime.
-- **It is local-first.** Your config, memory, media, and dashboard are owned by the project folder you run.
+| Command | What it does |
+| --- | --- |
+| `npx alive-ai@latest init my-ai` | Scaffold a clean local Alive-AI project. |
+| `npx . setup` | Guided onboarding for local config, providers, Telegram, voice, images, and memory. |
+| `npx . doctor` | Check OS, Node, Python, uv, ffmpeg, Docker, and OpenMind reachability. |
+| `npx . chat` | Start the real runtime with terminal chat input. |
+| `npx . demo` | Run a keyless animated dashboard demo. |
+| `npx . start` | Start the runtime using the configured input channel, usually Telegram. |
+| `npx . start --skip-install` | Start again without reinstalling Python dependencies. |
 
-## Commands
+Stop a foreground run with `Ctrl+C`.
+
+If you use Docker:
 
 ```bash
-npx github:vindepemarte/alive-ai init my-ai  # scaffold a clean local project
-cd my-ai
-npx . setup                                # create safe local config
-npx . demo                                 # preview animated dashboard, no keys needed
-npx . doctor                               # check Python, uv, ffmpeg, Docker
-npx . start                                # install Python deps and run the runtime
+docker compose down
 ```
 
-For repeat starts after dependencies are installed:
+If you only started Redis:
 
 ```bash
-npx . start --skip-install
+docker compose stop redis
 ```
 
 ## Setup
@@ -68,14 +88,34 @@ mypics/
 myvids/
 ```
 
-Minimum useful setup:
+The setup accepts `skip` for optional keys and `local` for Ollama.
+
+| Setup item | Options |
+| --- | --- |
+| LLM | `local`/Ollama, OpenRouter, ZAI, or `skip` for demo/fallback-only mode. |
+| Telegram | Bot token and owner ID are optional. Use terminal chat if you do not want Telegram. |
+| Voice | `gtts` local/free default, Google TTS, VibeVoice, or `skip`. |
+| Images | Fal.ai API key or `skip`. Local media folders still work without image generation. |
+| Memory | Built-in local memory, OpenMind cloud, or OpenMind local. |
 
-- **Demo only:** no keys.
-- **Local LLM:** install Ollama and pull the configured model, for example `ollama pull qwen3:4b`.
-- **Telegram runtime:** create a Telegram bot token with BotFather and add it during setup.
-- **Cloud LLM fallback:** add OpenRouter or ZAI keys during setup or edit `config/settings.json`.
+Minimum useful paths:
 
-Media is optional. Add your own files:
+```bash
+# Terminal-only local run
+npx . setup
+npx . chat
+
+# Local LLM
+ollama pull qwen3:4b
+npx . setup
+npx . chat
+
+# Telegram
+npx . setup
+npx . start
+```
+
+Media is optional. Add your own local files:
 
 ```text
 mypics/example.jpg
@@ -84,38 +124,114 @@ myvids/example.mp4
 myvids/example.txt
 ```
 
-## Architecture
+## Terminal Chat
+
+`npx . chat` uses the same core runtime as Telegram. It emits the same `message_received` events, saves memory the same way, and updates the local WebUI.
+
+Terminal commands:
+
+```text
+/help
+/status
+/stats
+/dashboard
+/self
+/discover <trait>
+/iam <key>=<value>
+/ilike <thing>
+/ihate <thing>
+/rethink
+/settings show
+/settings get <key>
+/settings set <key> <value>
+/reset
+/impulse
+/exit
+```
+
+## OpenMind Memory
+
+Alive-AI has built-in local working, episodic, semantic, and emotional memory. OpenMind is optional and works as a hybrid long-term semantic memory layer.
+
+Modes:
+
+| Mode | Behavior |
+| --- | --- |
+| Built-in only | Alive-AI uses its local project memory only. |
+| OpenMind cloud | Alive-AI captures/searches long-term memories through `https://theopenmind.pro`. |
+| OpenMind local | Alive-AI captures/searches a local OpenMind server, normally `http://127.0.0.1:3333`. |
 
-Alive-AI is an event-driven Python runtime.
+OpenMind does not replace Alive-AI's emotional state. It adds durable semantic recall across tools and machines.
+
+Cloud setup:
 
 ```text
-Telegram or input
-  -> NervousSystem event bus
-  -> Message handler
-  -> Heart, memory, skills, directives, personality
-  -> LLM provider or fallback chain
-  -> output events
-  -> dashboard state stream
+OPENMIND_ENABLED=true
+OPENMIND_MODE=hybrid
+OPENMIND_BASE_URL=https://theopenmind.pro
+OPENMIND_API_KEY=om_...
+```
+
+Local setup:
+
+```bash
+npx @vindepemarte/openmind init --local
+# or run your local OpenMind stack, then configure Alive-AI:
+OPENMIND_BASE_URL=http://127.0.0.1:3333
 ```
 
-Core subsystems:
+## Requirements
+
+Minimum for cloud LLMs or remote Ollama:
 
-- `heart/`: continuous emotion, circadian rhythm, attachment, scars, somatic state, inconsistency.
-- `brain/`: LLM providers, memory, default-mode processing, bid detection, curiosity, dreams.
-- `skills/`: self-authorship, memory callbacks, relationship milestones, progression layers, media selection.
-- `webui/`: local dashboard with Server-Sent Events.
-- `input/telegram/`: Telegram listener and owner commands.
+| Requirement | Minimum |
+| --- | --- |
+| Node.js | 18+ |
+| Python | 3.11+ |
+| RAM | 8 GB |
+| Disk | 2 GB free |
+| LLM | OpenRouter, ZAI, remote Ollama, or local Ollama already installed |
+
+Comfortable local setup:
+
+| Requirement | Recommended |
+| --- | --- |
+| Node.js | 20+ |
+| RAM | 16 GB for 3B-4B local models |
+| RAM for bigger models | 32 GB for 7B+ local models, Redis, voice, and long sessions |
+| Disk | 10 GB+, more if you keep local models/media |
+| Optional tools | `uv`, `ffmpeg`, Docker, Ollama |
+
+`npx . start` creates `.alive-ai/venv` and installs Python dependencies. System-level packages such as Node, Python, Ollama, Docker, and ffmpeg must already exist on the machine.
+
+## Platform Support
+
+Alive-AI is designed for macOS, Windows, and Linux.
+
+| Platform | Notes |
+| --- | --- |
+| macOS | First-class local development path. Use Homebrew for Python, uv, ffmpeg, Docker, and Ollama. |
+| Windows | Supported from PowerShell with Node 18+ and Python 3.11+. WSL is recommended for heavier local model and Docker workflows. |
+| Linux | Supported with distro packages for Python/venv, ffmpeg, Docker, and Ollama. |
+
+Local model quality and speed depend on your machine. Cloud LLMs reduce RAM pressure.
 
 ## Dashboard
 
-`npx . demo` starts a zero-config animated dashboard preview. The real dashboard uses the same idea, but streams live state from the runtime:
+The real WebUI streams local runtime state over Server-Sent Events and shows:
 
-- emotions and mood,
-- recent thoughts,
-- memory counters,
-- somatic state,
-- attachment/inconsistency signals,
-- uptime and health.
+- emotional state,
+- recent thoughts and idle processing,
+- memory counters and uptime,
+- hormones and interoceptive body state,
+- attachment, circadian rhythm, body memory, dreams, curiosity, and conflicts,
+- runtime health through local endpoints.
+
+GitHub Pages cannot run the Python/FastAPI backend, so the public page includes a static export of the actual WebUI with mocked state:
+
+```text
+https://vindepemarte.github.io/alive-ai/
+```
 
 ## Docker
 
@@ -132,9 +248,41 @@ Or run everything in containers:
 docker compose up --build
 ```
 
+## Roadmap
+
+Implemented:
+
+- [x] Local-first emotional runtime
+- [x] Persistent emotion model with decay and compound state
+- [x] Working, episodic, semantic, and emotional memory modules
+- [x] Default-mode loop for idle thoughts and proactive impulses
+- [x] Attachment, circadian rhythm, body memory, curiosity, dreams, and internal conflicts
+- [x] Per-user memory/state isolation
+- [x] Telegram input/output runtime
+- [x] Terminal chat runtime with owner-style slash commands
+- [x] Local WebUI dashboard with live state streaming
+- [x] Optional hybrid OpenMind cloud/local semantic memory
+- [x] npm/npx CLI scaffold, setup, doctor, demo, chat, and start commands
+- [x] Clean public repo with private personas, media, runtime data, and multi-AI orchestration removed
+- [x] GitHub Pages site and full static WebUI export
+
+Next:
+
+- [ ] One-command local model bootstrap through Ollama profiles
+- [ ] Desktop app wrapper with tray controls and local service lifecycle
+- [ ] Browser-based onboarding wizard for personality, boundaries, LLM provider, and memory settings
+- [ ] Better guided system install commands per OS
+- [ ] More input channels beyond terminal and Telegram
+- [ ] Import/export for memories and personality snapshots
+- [ ] Plugin API for new senses, skills, and output modalities
+- [ ] Evaluation harness for emotional continuity, memory drift, and unhealthy attachment risk
+- [ ] Optional cloud sync that preserves local-first ownership
+
 ## Important Boundaries
 
-Alive-AI is a simulation framework. It can make agents feel more continuous, emotionally coherent, and alive, but it is not proof of consciousness and should not be used to manipulate emotional dependence.
+Alive-AI is a simulation framework. It can make agents feel more continuous, emotionally coherent, and alive, but it is not proof of consciousness.
+
+Do not use it to manipulate emotional dependence. If you are building a companion, character, partner, or friend-like system, make the boundaries explicit and keep the operator in control.
 
 The public repo intentionally excludes private personas, private media, runtime data, and secrets. Put those only in your local project folder.
 

package/brain/memory/manager.py

@@ -37,11 +37,19 @@ class Memory:
         self.fact_extractor = FactExtractor(self.data_path / "facts.json")
         self.summarizer = ConversationSummarizer(self.data_path)
         self.vector_store = None
+        self.openmind = None
         self.bot_id = bot_id.lower()
         if embedding_service:
             self.vector_store = VectorMemoryStore(embedding_service, user_id=user_id, bot_id=bot_id)
             if self.vector_store.connect():
                 print(f"[Memory] Vector store ready for user {user_id} on bot {bot_id}! {self.vector_store.count()} memories")
+        try:
+            from .openmind import OpenMindMemoryBridge
+            if OpenMindMemoryBridge.enabled():
+                self.openmind = OpenMindMemoryBridge(nervous, user_id=user_id, bot_id=bot_id)
+                print(f"[Memory] OpenMind bridge enabled for user {user_id} on bot {bot_id}")
+        except Exception as e:
+            print(f"[Memory] OpenMind bridge unavailable: {e}")
         self.turn_count = 0
         nervous.on("memory_save", self._on_save)
 
@@ -123,6 +131,14 @@ class Memory:
         related = ""
         if current_message and self.vector_store:
             related = self.search_relevant_memories(current_message, limit=3)
+        if current_message and self.openmind:
+            openmind_related = await self.openmind.search_context(current_message, limit=3)
+            if openmind_related:
+                related = (
+                    f"{related}\n\nOpenMind long-term memory:\n{openmind_related}"
+                    if related else
+                    f"OpenMind long-term memory:\n{openmind_related}"
+                )
 
         # Get working memory (empty after restart)
         history = self.working.get_history()

package/brain/memory/openmind.py

@@ -0,0 +1,128 @@
+"""Optional OpenMind semantic memory bridge."""
+
+import asyncio
+import os
+from typing import Any, Dict, List, Optional
+
+import aiohttp
+
+from core.settings import get as settings_get
+
+
+class OpenMindMemoryBridge:
+    """Syncs Alive-AI turns to OpenMind and retrieves long-term semantic context."""
+
+    def __init__(self, nervous, user_id: str, bot_id: str):
+        self.nervous = nervous
+        self.user_id = str(user_id or "default")
+        self.bot_id = str(bot_id or "alive_ai").lower()
+        nervous.on("memory_save", self._on_memory_save)
+
+    @staticmethod
+    def enabled() -> bool:
+        return str(settings_get("OPENMIND_ENABLED", os.environ.get("OPENMIND_ENABLED", "false"))).lower() in (
+            "1", "true", "yes", "on"
+        )
+
+    @staticmethod
+    def base_url() -> str:
+        return str(settings_get("OPENMIND_BASE_URL", os.environ.get("OPENMIND_BASE_URL", "https://theopenmind.pro"))).rstrip("/")
+
+    @staticmethod
+    def api_key() -> str:
+        return str(settings_get("OPENMIND_API_KEY", os.environ.get("OPENMIND_API_KEY", ""))).strip()
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"content-type": "application/json"}
+        key = self.api_key()
+        if key:
+            headers["authorization"] = f"Bearer {key}"
+        return headers
+
+    def _on_memory_save(self, data: dict):
+        if not self.enabled() or data.get("type") != "conversation":
+            return
+        event_user_id = data.get("user_id")
+        if event_user_id:
+            if str(event_user_id) != self.user_id:
+                return
+        elif self.user_id != "default":
+            return
+        asyncio.ensure_future(self.capture_turn(data))
+
+    async def capture_turn(self, data: dict) -> Optional[dict]:
+        user_msg = (data.get("user_message") or "").strip()
+        ai_msg = (data.get("ai_response") or "").strip()
+        if not user_msg and not ai_msg:
+            return None
+
+        emotion = data.get("emotion") or {}
+        mood = emotion.get("mood", "unknown")
+        content = "\n".join(
+            part for part in [
+                f"Alive-AI agent: {self.bot_id}",
+                f"User id: {self.user_id}",
+                f"Mood: {mood}",
+                f"User: {user_msg}" if user_msg else "",
+                f"Alive-AI: {ai_msg}" if ai_msg else "",
+            ] if part
+        )
+        tags = ["alive-ai", self.bot_id, f"user-{self.user_id}", f"mood-{mood}"]
+        payload = {
+            "content": content,
+            "source": "alive-ai",
+            "type": "conversation",
+            "tags": tags,
+        }
+
+        try:
+            timeout = aiohttp.ClientTimeout(total=12)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.post(f"{self.base_url()}/capture", json=payload, headers=self._headers()) as resp:
+                    if resp.status >= 400:
+                        body = await resp.text()
+                        print(f"[OpenMind] Capture failed ({resp.status}): {body[:200]}")
+                        return None
+                    result = await resp.json()
+                    print(f"[OpenMind] Captured memory: {result.get('status', 'ok')}")
+                    return result
+        except Exception as exc:
+            print(f"[OpenMind] Capture unavailable: {exc}")
+            return None
+
+    async def search_context(self, query: str, limit: int = 3) -> str:
+        if not self.enabled() or not query.strip():
+            return ""
+        try:
+            timeout = aiohttp.ClientTimeout(total=10)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(
+                    f"{self.base_url()}/search",
+                    params={"q": query, "limit": str(limit)},
+                    headers=self._headers(),
+                ) as resp:
+                    if resp.status >= 400:
+                        body = await resp.text()
+                        print(f"[OpenMind] Search failed ({resp.status}): {body[:200]}")
+                        return ""
+                    rows = await resp.json()
+        except Exception as exc:
+            print(f"[OpenMind] Search unavailable: {exc}")
+            return ""
+
+        if not isinstance(rows, list):
+            return ""
+        return self._format_results(rows[:limit])
+
+    def _format_results(self, rows: List[Dict[str, Any]]) -> str:
+        lines = []
+        for row in rows:
+            content = str(row.get("content") or row.get("summary") or "").strip()
+            if not content:
+                continue
+            similarity = row.get("similarity")
+            prefix = "OpenMind"
+            if isinstance(similarity, (int, float)):
+                prefix = f"OpenMind {round(similarity * 100)}%"
+            lines.append(f"{prefix}: {content[:700]}")
+        return "\n".join(lines)