alive-ai 0.1.5 → 0.1.6

package/README.md

@@ -54,7 +54,7 @@ alive-ai init my-ai
 | --- | --- |
 | `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 . doctor` | Check OS, Node, Python, uv, ffmpeg, OpenMind, and Redis only when Redis is enabled. |
 | `npx . doctor --fix` | Ask `y/N` for each missing installable tool and run the platform installer if approved. |
 | `npx . chat` | Start the real runtime with split-pane terminal chat and logs. |
 | `npx . chat --plain` | Start raw terminal chat without the TUI. |
@@ -66,7 +66,7 @@ alive-ai init my-ai
 
 `start` and `chat` check npm for a newer Alive-AI version. You can update, skip once, or skip that specific version. Stop terminal chat with `/exit` or `Ctrl+C`.
 
-`doctor --fix` is conservative: it prints the exact install command before running anything and asks separately for each missing tool. On macOS it uses Homebrew, on Windows it uses winget, and on Linux it supports apt, dnf, and pacman where possible.
+`doctor --fix` is conservative: it prints the exact install command before running anything and asks separately for each missing tool. On macOS it uses Homebrew, on Windows it uses winget, and on Linux it supports apt, dnf, and pacman where possible. Redis is optional; doctor only checks or fixes it when `REDIS_VECTOR_MEMORY_ENABLED` is true.
 
 If you use Docker:
 
@@ -96,7 +96,7 @@ myvids/
 
 The setup accepts `skip` for optional keys and `local` for Ollama.
 
-Startup config is loaded from multiple places in this order:
+Startup config is loaded from:
 
 ```text
 .env
@@ -104,7 +104,7 @@ config/secrets.env
 config/settings.json
 ```
 
-Shell environment variables win over `.env`/`config/secrets.env`. Runtime settings come from `config/settings.json`. Telegram uses `TELEGRAM_TOKEN` when present, otherwise `telegram_token` from `config/settings.json`.
+`config/settings.json` is the runtime source of truth created by setup. `.env` and `config/secrets.env` are read first for compatibility, then simple values from `config/settings.json` are exported into the process environment.
 
 | Setup item | Options |
 | --- | --- |
@@ -113,6 +113,7 @@ Shell environment variables win over `.env`/`config/secrets.env`. Runtime settin
 | 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. |
+| Redis vector cache | Optional. Leave it off when using OpenMind unless you specifically want a local Redis Stack vector index. |
 
 Minimum useful paths:
 
@@ -185,6 +186,8 @@ Modes:
 
 OpenMind does not replace Alive-AI's emotional state. It adds durable semantic recall across tools and machines.
 
+Redis is not required when OpenMind is enabled. Alive-AI always keeps file-backed working, episodic, semantic, and emotional memory in the project `data/` folder. Redis Stack is an optional local vector cache for users who want it.
+
 Cloud setup:
 
 ```text
@@ -222,9 +225,9 @@ Comfortable local setup:
 | 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 |
+| Optional tools | `uv`, `ffmpeg`, Docker, Ollama, Redis Stack |
 
-`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.
+`npx . start` creates `.alive-ai/venv` and installs Python dependencies. System-level packages such as Node, Python, Ollama, Docker, and ffmpeg can be checked with `npx . doctor`. Use `npx . doctor --fix` when you want guided installers.
 
 The CLI prefers Python 3.12, 3.11, then 3.13 before falling back to the system `python3`. When `uv` is installed, Alive-AI now passes the selected Python explicitly so `uv` does not silently choose a newer interpreter.
 
@@ -262,7 +265,8 @@ https://vindepemarte.github.io/alive-ai/
 Docker is optional. It is useful when you want Redis Stack for vector search:
 
 ```bash
-docker compose up -d redis
+# In config/settings.json, set REDIS_VECTOR_MEMORY_ENABLED to true.
+npx . doctor --fix
 npx . start
 ```
 
@@ -287,6 +291,7 @@ Implemented:
 - [x] Split-pane terminal chat with logs
 - [x] Local WebUI dashboard with live state streaming
 - [x] Optional hybrid OpenMind cloud/local semantic memory
+- [x] Optional Redis Stack vector cache with setup and doctor checks
 - [x] npm/npx CLI scaffold, setup, doctor, demo, chat, and start commands
 - [x] Update prompt and project uninstall command
 - [x] `doctor --fix` guided system dependency installer

package/brain/memory/manager.py

@@ -39,7 +39,7 @@ class Memory:
         self.vector_store = None
         self.openmind = None
         self.bot_id = bot_id.lower()
-        if embedding_service:
+        if embedding_service and VectorMemoryStore.enabled():
             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")

package/brain/memory/vector_store.py

@@ -4,15 +4,41 @@ Redis-based vector storage for semantic memory search
 """
 
 import json
+import os
 import redis
+import time
 from datetime import datetime
 from typing import List, Dict, Optional, Any
 from pathlib import Path
 import numpy as np
 
-# Redis connection settings
-REDIS_HOST = "redis"
-REDIS_PORT = 6379
+from core.settings import get as settings_get
+
+
+def _truthy(value) -> bool:
+    return str(value).strip().lower() in ("1", "true", "yes", "on")
+
+
+def redis_vector_memory_enabled() -> bool:
+    return _truthy(settings_get("REDIS_VECTOR_MEMORY_ENABLED", os.environ.get("REDIS_VECTOR_MEMORY_ENABLED", "false")))
+
+
+def redis_host() -> str:
+    return str(settings_get("REDIS_HOST", os.environ.get("REDIS_HOST", "127.0.0.1")) or "127.0.0.1")
+
+
+def redis_port() -> int:
+    try:
+        return int(settings_get("REDIS_PORT", os.environ.get("REDIS_PORT", "6379")) or 6379)
+    except (TypeError, ValueError):
+        return 6379
+
+
+def redis_retry_seconds() -> float:
+    try:
+        return float(settings_get("REDIS_RETRY_SECONDS", os.environ.get("REDIS_RETRY_SECONDS", "60")) or 60)
+    except (TypeError, ValueError):
+        return 60.0
 
 # Memory archive path - detect Docker vs local development
 _docker_archive = Path("/data/memory_archive")
@@ -40,8 +66,17 @@ class VectorMemoryStore:
         self.dimension = dimension
         self.user_id = user_id
         self.bot_id = bot_id.lower()
+        self.host = redis_host()
+        self.port = redis_port()
+        self.retry_seconds = redis_retry_seconds()
         self.redis = None
         self._connected = False
+        self._last_connect_attempt = 0.0
+        self._failure_logged = False
+
+    @staticmethod
+    def enabled() -> bool:
+        return redis_vector_memory_enabled()
 
     @staticmethod
     def _decode(val):
@@ -50,21 +85,33 @@ class VectorMemoryStore:
 
     def connect(self) -> bool:
         """Connect to Redis and create index if needed"""
+        if not self.enabled():
+            self._connected = False
+            return False
+
+        now = time.monotonic()
+        if self._last_connect_attempt and now - self._last_connect_attempt < self.retry_seconds:
+            return False
+        self._last_connect_attempt = now
+
         try:
             self.redis = redis.Redis(
-                host=REDIS_HOST,
-                port=REDIS_PORT,
+                host=self.host,
+                port=self.port,
                 decode_responses=False  # binary-safe for embeddings
             )
             self.redis.ping()
             self._connected = True
-            print(f"[VectorStore] Connected to Redis")
+            self._failure_logged = False
+            print(f"[VectorStore] Connected to Redis at {self.host}:{self.port}")
 
             # Create vector index if not exists
             self._create_index()
             return True
         except Exception as e:
-            print(f"[VectorStore] Redis connection failed: {e}")
+            if not self._failure_logged:
+                print(f"[VectorStore] Redis unavailable at {self.host}:{self.port}; vector cache disabled for now ({e})")
+                self._failure_logged = True
             self._connected = False
             return False
 

package/cli/index.js

@@ -3,6 +3,7 @@
 
 const fs = require("fs");
 const http = require("http");
+const net = require("net");
 const os = require("os");
 const path = require("path");
 const readline = require("readline");
@@ -294,6 +295,45 @@ function copyUpdateRecursive(src, dest, baseDest = dest) {
   fs.copyFileSync(src, dest);
 }
 
+function mergeMissingConfig(target, defaults) {
+  let changed = false;
+  for (const [key, value] of Object.entries(defaults)) {
+    if (key.startsWith("_")) continue;
+    if (!(key in target)) {
+      target[key] = value;
+      changed = true;
+      continue;
+    }
+    if (
+      value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      target[key] &&
+      typeof target[key] === "object" &&
+      !Array.isArray(target[key])
+    ) {
+      changed = mergeMissingConfig(target[key], value) || changed;
+    }
+  }
+  return changed;
+}
+
+function mergeProjectSettingsDefaults() {
+  const settingsPath = path.join(process.cwd(), "config", "settings.json");
+  const examplePath = path.join(process.cwd(), "config", "settings.example.json");
+  if (!fs.existsSync(settingsPath) || !fs.existsSync(examplePath)) return false;
+  try {
+    const settings = readJson(settingsPath);
+    const defaults = readJson(examplePath);
+    if (!mergeMissingConfig(settings, defaults)) return false;
+    writeJson(settingsPath, settings);
+    return true;
+  } catch (error) {
+    console.log(`Could not merge new config defaults: ${error.message}`);
+    return false;
+  }
+}
+
 async function updateProject(args) {
   const assumeYes = hasFlag(args, "--yes") || hasFlag(args, "-y") || !process.stdin.isTTY;
   if (!fs.existsSync(path.join(process.cwd(), "config")) || !fs.existsSync(path.join(process.cwd(), "main.py"))) {
@@ -309,8 +349,10 @@ async function updateProject(args) {
     if (!fs.existsSync(src)) continue;
     copyUpdateRecursive(src, path.join(process.cwd(), entry), process.cwd());
   }
+  const mergedSettings = mergeProjectSettingsDefaults();
   console.log(`Alive-AI project updated to ${packageVersion()}.`);
   console.log("Preserved config/, data/, mypics/, myvids/, .alive-ai/, and .cache/.");
+  if (mergedSettings) console.log("Merged new config defaults into config/settings.json without overwriting your values.");
 }
 
 async function uninstallProject(args) {
@@ -428,6 +470,18 @@ async function setupProject(args) {
   const openmindKey = openmindEnabled
     ? emptyIfSkipped(await ask("OpenMind API key (om_..., optional for unauthenticated local dev)", "", assumeYes))
     : "";
+  const redisChoice = normalizeChoice(
+    await ask("Use optional Redis Stack vector cache? yes or no", "no", assumeYes),
+    "no"
+  );
+  const redisEnabled = ["yes", "y", "true", "1", "on"].includes(redisChoice);
+  const redisHost = redisEnabled
+    ? emptyIfSkipped(await ask("Redis host", "127.0.0.1", assumeYes)) || "127.0.0.1"
+    : "127.0.0.1";
+  const redisPortAnswer = redisEnabled
+    ? emptyIfSkipped(await ask("Redis port", "6379", assumeYes)) || "6379"
+    : "6379";
+  const redisPort = Number.parseInt(redisPortAnswer, 10) || 6379;
 
   const settings = readJson(settingsExample);
   settings.AGENT_NAME = displayName;
@@ -451,6 +505,9 @@ async function setupProject(args) {
   settings.OPENMIND_MODE = openmindEnabled ? "hybrid" : "built-in";
   settings.OPENMIND_BASE_URL = openmindBaseUrl || "https://theopenmind.pro";
   settings.OPENMIND_API_KEY = openmindKey;
+  settings.REDIS_VECTOR_MEMORY_ENABLED = redisEnabled;
+  settings.REDIS_HOST = redisHost;
+  settings.REDIS_PORT = redisPort;
 
   const self = readJson(selfExample);
   self.who_i_am.name = displayName;
@@ -525,6 +582,13 @@ function packageManager() {
 }
 
 function installPlan(tool) {
+  if (tool === "redis") {
+    if (hasCommand("docker") && fs.existsSync(path.join(process.cwd(), "docker-compose.yml"))) {
+      return ["docker", "compose", "up", "-d", "redis"];
+    }
+    return null;
+  }
+
   const manager = packageManager();
   if (process.platform === "darwin") {
     if (manager !== "brew") return null;
@@ -584,6 +648,9 @@ function installPlan(tool) {
 }
 
 function manualInstallHint(tool) {
+  if (tool === "redis") {
+    return "Redis Stack is optional. Either disable REDIS_VECTOR_MEMORY_ENABLED in config/settings.json, or install Docker and run `docker compose up -d redis`.";
+  }
   if (process.platform === "darwin" && !hasCommand("brew")) {
     return "Install Homebrew from https://brew.sh, then rerun `npx . doctor --fix`.";
   }
@@ -643,6 +710,38 @@ function wantsOllama(settings) {
   return provider === "ollama" || order.includes("ollama");
 }
 
+function truthy(value) {
+  return ["1", "true", "yes", "on"].includes(String(value || "").trim().toLowerCase());
+}
+
+function wantsRedis(settings) {
+  return truthy(settings.REDIS_VECTOR_MEMORY_ENABLED || process.env.REDIS_VECTOR_MEMORY_ENABLED);
+}
+
+function redisEndpoint(settings) {
+  const host = String(settings.REDIS_HOST || process.env.REDIS_HOST || "127.0.0.1").trim() || "127.0.0.1";
+  const port = Number.parseInt(settings.REDIS_PORT || process.env.REDIS_PORT || "6379", 10) || 6379;
+  return { host, port };
+}
+
+function checkTcp(host, port, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (ok) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.once("timeout", () => finish(false));
+    socket.connect(port, host);
+  });
+}
+
 async function doctor(args = []) {
   const shouldFix = hasFlag(args, "--fix");
   const assumeYes = hasFlag(args, "--yes") || hasFlag(args, "-y");
@@ -654,6 +753,9 @@ async function doctor(args = []) {
   const node = process.version;
   const nodeMajor = majorVersion(process.versions.node);
   const settings = readProjectSettings();
+  const redisEnabled = wantsRedis(settings);
+  const redis = redisEndpoint(settings);
+  const redisReachable = redisEnabled ? await checkTcp(redis.host, redis.port, 1200) : false;
   const venvPython = process.platform === "win32"
     ? path.join(process.cwd(), ".alive-ai", "venv", "Scripts", "python.exe")
     : path.join(process.cwd(), ".alive-ai", "venv", "bin", "python");
@@ -667,7 +769,8 @@ async function doctor(args = []) {
   }
   console.log(`  uv:     ${uv || "missing, will use venv + pip"}`);
   console.log(`  ffmpeg: ${ffmpeg || "missing, voice conversion may be limited"}`);
-  console.log(`  docker: ${docker || "missing, Redis can still be external"}`);
+  console.log(`  docker: ${docker || (redisEnabled ? "missing, needed for local Redis Stack helper" : "missing, optional")}`);
+  console.log(`  redis:  ${redisEnabled ? `${redisReachable ? "reachable" : "unreachable"} (${redis.host}:${redis.port})` : "disabled"}`);
   if (wantsOllama(settings)) {
     console.log(`  ollama: ${ollama || "missing, local LLM unavailable until installed"}`);
   }
@@ -678,7 +781,8 @@ async function doctor(args = []) {
   if (!python) missing.push({ id: "python", name: "Python 3.11+" });
   if (!uv) missing.push({ id: "uv", name: "uv" });
   if (!ffmpeg) missing.push({ id: "ffmpeg", name: "ffmpeg" });
-  if (!docker) missing.push({ id: "docker", name: "Docker" });
+  if (redisEnabled && !redisReachable && !docker) missing.push({ id: "docker", name: "Docker" });
+  if (redisEnabled && !redisReachable) missing.push({ id: "redis", name: "Redis Stack vector cache" });
   if (wantsOllama(settings) && !ollama) missing.push({ id: "ollama", name: "Ollama" });
 
   if (!python) {

package/config/settings.example.json

@@ -9,6 +9,8 @@
   "WEBUI_ENABLED": true,
   "WEBUI_PORT": 8080,
   "language": "en",
+  "MESSAGE_BATCH_DELAY_SECONDS": 3.5,
+  "TERMINAL_MESSAGE_BATCH_DELAY_SECONDS": 5.0,
   "LLM_PROVIDER": "ollama",
   "LLM_MAX_TOKENS": 500,
   "LLM_CONTEXT_TOKENS": 4000,
@@ -40,6 +42,10 @@
   "OPENMIND_MODE": "built-in",
   "OPENMIND_BASE_URL": "https://theopenmind.pro",
   "OPENMIND_API_KEY": "",
+  "REDIS_VECTOR_MEMORY_ENABLED": false,
+  "REDIS_HOST": "127.0.0.1",
+  "REDIS_PORT": 6379,
+  "REDIS_RETRY_SECONDS": 60,
   "EMOTION_RATE_LOVE": 65,
   "EMOTION_RATE_DESIRE": 45,
   "EMOTION_RATE_AROUSAL": 40,

package/core/message_handler.py

@@ -1,5 +1,5 @@
 """Core: Message Handler — incoming messages, thinking, responses"""
-import asyncio, random
+import asyncio, os, random
 from pathlib import Path
 from datetime import datetime
 from .thinking import build_mood_instruction, fallback_response
@@ -171,7 +171,7 @@ _MAX_USER_MEMORIES = 50  # Maximum cached user memories
 _message_queue = {}      # user_id -> list of messages
 _batch_timers = {}       # user_id -> timer task
 _processing_locks = {}   # user_id -> lock to prevent overlapping processing
-_BATCH_DELAY = 3.5       # Wait 3.5 seconds for more messages (increased)
+_BATCH_DELAY = 3.5       # Default debounce for message batching
 
 # Per-user pending media (prevents race condition when multiple users message simultaneously)
 _pending_media = {}      # user_id -> {"photo": ..., "video": ...}
@@ -191,6 +191,21 @@ def _feed_learning(sub, text: str):
         print(f"[Learning] feedback error (non-fatal): {e}")
 
 
+def _settings_float(key: str, default: float) -> float:
+    try:
+        from core.settings import get
+        value = get(key, os.environ.get(key, default))
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _batch_delay_for(data: dict) -> float:
+    if data.get("source") == "terminal":
+        return max(0.5, _settings_float("TERMINAL_MESSAGE_BATCH_DELAY_SECONDS", 5.0))
+    return max(0.5, _settings_float("MESSAGE_BATCH_DELAY_SECONDS", _BATCH_DELAY))
+
+
 def _is_owner(user_id: str) -> bool:
     """Check if user is the owner (the operator)"""
     from core.settings import get
@@ -354,21 +369,22 @@ async def handle_message(self, data: dict):
 
     # Start new timer
     queue_size = len(_message_queue[user_id])
+    batch_delay = _batch_delay_for(data)
     if queue_size == 1:
-        print(f"[Batch] First message from {user_id}, waiting {_BATCH_DELAY}s...")
+        print(f"[Batch] First message from {user_id}, waiting {batch_delay:.1f}s...")
     else:
         print(f"[Batch] Message #{queue_size} from {user_id}, resetting timer...")
 
     # Create timer task
     _batch_timers[user_id] = asyncio.create_task(
-        _process_batch_after_delay(self, user_id, data)
+        _process_batch_after_delay(self, user_id, data, batch_delay)
     )
 
 
-async def _process_batch_after_delay(self, user_id: str, original_data: dict):
+async def _process_batch_after_delay(self, user_id: str, original_data: dict, batch_delay: float):
     """Wait for batch delay, then process all queued messages together"""
     try:
-        await asyncio.sleep(_BATCH_DELAY)
+        await asyncio.sleep(batch_delay)
     except asyncio.CancelledError:
         # Timer was cancelled - new message came in
         return
@@ -398,6 +414,7 @@ async def _process_batch_after_delay(self, user_id: str, original_data: dict):
         "user_id": user_id,
         "text": combined_text,
         "chat_id": chat_id,
+        "source": original_data.get("source"),
         "message_count": len(messages)
     }
 
@@ -1437,4 +1454,3 @@ def get_aliveness_module_status() -> dict:
     }
     modules["modules_active"] = sum(v for v in modules.values() if isinstance(v, bool))
     return modules
-

package/docs/index.html

@@ -288,11 +288,11 @@ npx . chat</code></pre>
 
   <section class="section" id="setup">
     <h2>Setup Flow</h2>
-    <p>`npx . setup` asks for the minimum required configuration and lets optional systems be skipped. Use `local` for Ollama, `skip` for optional keys, and OpenMind cloud or local when you want a shared long-term semantic memory.</p>
+    <p>`npx . setup` asks for the minimum required configuration and lets optional systems be skipped. Use `local` for Ollama, `skip` for optional keys, OpenMind cloud or local for shared long-term semantic memory, and leave Redis off unless you specifically want a local Redis Stack vector cache.</p>
     <div class="steps">
       <div class="step"><strong>Start local terminal chat</strong><span>`npx . chat` starts the same runtime with chat on the left, logs on the right, and the WebUI at `http://127.0.0.1:8080`.</span></div>
       <div class="step"><strong>Start Telegram/runtime mode</strong><span>`npx . start` starts the configured input channel and validates Telegram before polling. Stop foreground runs with `Ctrl+C`.</span></div>
-      <div class="step"><strong>Install missing tools</strong><span>`npx . doctor --fix` asks `y/N` for each missing tool, then uses Homebrew, winget, apt, dnf, or pacman where available.</span></div>
+      <div class="step"><strong>Install missing tools</strong><span>`npx . doctor --fix` asks `y/N` for each missing tool. Redis is checked only when the Redis vector cache is enabled.</span></div>
       <div class="step"><strong>Keep it updated</strong><span>`start` and `chat` check npm for newer versions. Use `npx . update` manually or `npx . uninstall` to remove local runtime files.</span></div>
       <div class="step"><strong>Use OpenMind</strong><span>Choose `openmind-cloud` for `https://theopenmind.pro` or `openmind-local` for `http://127.0.0.1:3333`.</span></div>
       <div class="step"><strong>Preview the dashboard</strong><span>`npx . demo` is keyless. The real runtime dashboard streams local state over SSE.</span></div>

package/input/terminal/listener.py

@@ -70,6 +70,7 @@ class TerminalListener:
                 "text": text,
                 "chat_id": self.chat_id,
                 "user_id": self.user_id,
+                "source": "terminal",
                 "message_id": "terminal"
             })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alive-ai",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Local-first emotional AI runtime with memory, impulses, and a live dashboard.",
   "license": "MIT",
   "homepage": "https://vindepemarte.github.io/alive-ai/",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "alive-ai-runtime"
-version = "0.1.5"
+version = "0.1.6"
 description = "Local-first emotional AI runtime with memory, impulses, and a live dashboard."
 readme = "README.md"
 requires-python = ">=3.11"