alvin-bot 4.21.0 → 4.22.1

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.22.1] — 2026-05-09
+
+### Fixed
+
+- **Cron scheduler:** prevent duplicate catch-up runs for already-attempted slots. When a daily/scheduled job fired but crashed before completion, the boot-time catch-up would re-fire it hours later (e.g. an `0 8 * * *` job retried at 11:00 after a 10:51 reboot). The catch-up now skips jobs whose current schedule slot has already been attempted: for cron expressions, `lastAttemptAt >= mostRecentPastTrigger` short-circuits the rewind; for interval schedules, `now - lastAttemptAt < intervalMs` does the same. Crashed runs from *previous* slots within the 6h grace window still catch up as before. New `prevCronRun()` helper in `cron-scheduling.ts`. ([#cron-catchup-bug](src/services/cron-scheduling.ts))
+
+## [4.22.0] — 2026-05-05
+
+### 🧠 Memory architecture overhaul: pluggable providers + smart inject
+
+Public users without `GOOGLE_API_KEY` (the v4.20–v4.21 default for embeddings) now get a working indexed memory store out of the box. The embeddings layer is refactored behind a provider interface with four backends auto-detected at startup:
+
+| Tier | Provider | Setup | Cost | Dim |
+|---|---|---|---|---|
+| 1 | Gemini (`gemini-embedding-001`) | `GOOGLE_API_KEY` | free tier | 3072 |
+| 2 | OpenAI (`text-embedding-3-small`) | `OPENAI_API_KEY` | ~$0.02 / 1M tokens | 1536 |
+| 3 | Ollama (default `nomic-embed-text`) | `ollama pull nomic-embed-text` | free, local, private | 768 |
+| 4 | **FTS5 (BM25 keyword)** | nothing | free | n/a |
+
+The FTS5 fallback is the headline: SQLite's built-in full-text-search virtual table with BM25 ranking. No API key, no network, no setup. Indexes the same chunks as the vector providers (`MEMORY.md`, daily logs, project files, hub memory, asset index) and ranks matches by relevance. Excellent for proper-noun and exact-term lookups (project names, commands, error messages); weaker than vector search for synonyms and conceptual paraphrase queries — but available everywhere.
+
+**Upgrade path.** A user starts on FTS5 (no keys needed). Later they set `GOOGLE_API_KEY` in their `.env` → next bot start detects the schema mismatch via `meta.embedding_model`, drops the FTS5 table, initialises the vector schema, and reindexes. Same in reverse. All seamless, no manual steps.
+
+Override the auto-detection with `EMBEDDINGS_PROVIDER=gemini|openai|ollama|fts5|auto` (default `auto`).
+
+### ✂️ MEMORY.md no longer bulk-injected into every system prompt (when SQLite is populated)
+
+Pre-v4.22, `MEMORY.md` (typically tens of KB of curated long-term knowledge) and the last two daily logs were plain-text-injected into the system prompt on **every turn**. With a populated SQLite store, the same content is available via the smaller, query-targeted `searchMemory()` retrieval — much smaller prompts, much more relevant context.
+
+New `MEMORY_INJECT_MODE` env var:
+
+- `auto` (default) — sqlite when the store has indexed entries, else legacy
+- `legacy` — pre-v4.22 behaviour, full plain-text inject every turn
+- `sqlite` — never plain-text-inject `MEMORY.md` or daily logs (force smart mode regardless of store state)
+
+Always plain-text injected regardless of mode: `identity.md` (L0) and `preferences.md` (L1) — these are tiny by design and contain always-on facts that semantic search may miss for short or generic queries. Recommended pattern: keep critical "never X" / "always Y" rules in `preferences.md`, let the bulk knowledge live in `MEMORY.md` and be retrieved on demand.
+
+For users still on the legacy monolithic `MEMORY.md` setup (no `identity.md`, no `preferences.md`), auto mode kicks in only after the SQLite store is populated — until then, plain-text injection of `MEMORY.md` continues to work as before. Zero-touch upgrade.
+
+### 🔇 Quieter logs for missing keys
+
+The `⚠️ Embeddings init failed: Google API key not configured` warning is gone — that startup line is now `ℹ️ Memory provider: fts5-bm25 (keyword-local). Initial index will run on first use.` Public users without Gemini no longer see a scary warning that suggested the bot was broken when in fact it was working correctly.
+
+### 🩺 `alvin-bot doctor` Memory section expanded
+
+Reports the active provider, dimension, indexed entry/file counts, last-reindex timestamp, and effective inject mode. For not-yet-initialised stores it predicts which provider will run on first start so users can confirm the auto-detection picked what they expected.
+
+```
+  Memory:
+  ✅ Provider: gemini-embedding-001 (vector-cloud, 3072-dim)
+     3827 entries / 316 files indexed, 48.8 MB on disk
+     Last reindex: 25 h ago
+     Inject mode: sqlite (auto)
+```
+
+### Architecture
+
+- New: `src/services/embeddings/` directory — `provider.ts` (interface), `vector-base.ts` (shared vector logic), `gemini.ts`, `openai.ts`, `ollama.ts`, `fts5.ts`, `auto-detect.ts`, `index.ts` (facade)
+- New: `src/services/memory-inject-mode.ts` — env resolver
+- Updated: `src/services/memory-layers.ts`, `src/services/memory.ts` — gate plain-text injection on inject mode
+- `src/services/embeddings.ts` is now a thin re-export shim — all existing imports keep working
+
+### Tests
+
+- 24 new tests across FTS5 provider, auto-detection, and inject-mode resolver
+- All 535 existing tests still pass (one pre-existing port-binding flake in `web-server-integration.test.ts` is unrelated)
+
 ## [4.21.0] — 2026-05-04
 
 ### 🌐 New skill: Agent Browser (Tier-1.5)

package/README.md

@@ -1,104 +1,49 @@
 # 🤖 Alvin Bot — Autonomous AI Agent
 
-> Your personal AI assistant — on Telegram, WhatsApp, Discord, Signal, Terminal, and Web.
+> Your personal AI agent — on Telegram, WhatsApp, Discord, Slack, Signal, Terminal, and Web.
 
-Alvin Bot is an open-source, self-hosted AI agent that lives where you chat. Built on a multi-model engine with full system access, memory, plugins, and a rich web dashboard. Not just a chatbot — an autonomous agent that remembers, acts, and learns.
+Open-source, self-hosted, multi-model. Lives where you chat, has full shell + filesystem access, remembers across sessions, and dispatches detached sub-agents for long-running work. Built on the Claude Agent SDK with a provider-agnostic engine that also drives OpenAI, Groq, Gemini, NVIDIA NIM, OpenRouter, and Ollama.
 
+> **What's new — v4.22 (May 2026):** Pluggable memory backends — Gemini · OpenAI · Ollama · **FTS5 keyword fallback (zero-config)**. Users without an embedding API key now get a working indexed memory store out of the box. Smart inject mode trims ~25 k tokens per turn off long system prompts. [Full changelog →](CHANGELOG.md)
 
 ---
 
-## 📸 Preview
-
-<table>
-<tr>
-<td align="center"><b>💬 Chat (Dark Mode)</b><br><img src="docs/screenshots/01-Chat-Dark-Conversation.png" width="400"></td>
-<td align="center"><b>📊 Dashboard</b><br><img src="docs/screenshots/03-Dashboard-Overview.png" width="400"></td>
-</tr>
-<tr>
-<td align="center"><b>🤖 AI Models & Providers</b><br><img src="docs/screenshots/04-AI-Models-and-Providers.png" width="400"></td>
-<td align="center"><b>🎭 Personality Editor</b><br><img src="docs/screenshots/05-Personality-Editor.png" width="400"></td>
-</tr>
-<tr>
-<td align="center"><b>💬 Telegram</b><br><img src="docs/screenshots/TG.png" width="400"></td>
-<td align="center"><b>📱 Messaging Platforms</b><br><img src="docs/screenshots/12-Messaging-Platforms.png" width="400"></td>
-</tr>
-<tr>
-<td align="center"><b>🔧 Custom Tools</b><br><img src="docs/screenshots/10-Custom-Tools.png" width="400"></td>
-<td align="center"><b>🩺 Health & Maintenance</b><br><img src="docs/screenshots/15-Maintenance-and-Health.png" width="400"></td>
-</tr>
-</table>
-
-<details>
-<summary><b>🖼️ More Screenshots</b> (click to expand)</summary>
-<br>
-
-| Feature | Screenshot |
-|---------|-----------|
-| Login | <img src="docs/screenshots/00-Login.png" width="500"> |
-| Chat (Light) | <img src="docs/screenshots/02-Chat.png" width="500"> |
-| Memory Manager | <img src="docs/screenshots/06-Memory-Manager.png" width="500"> |
-| Active Sessions | <img src="docs/screenshots/07-Active-Sessions.png" width="500"> |
-| File Browser | <img src="docs/screenshots/08-File-Browser.png" width="500"> |
-| Scheduled Jobs | <img src="docs/screenshots/09-Scheduled-Jobs.png" width="500"> |
-| Plugins & MCP | <img src="docs/screenshots/11-Plugins-and-MCP.png" width="500"> |
-| WhatsApp Groups | <img src="docs/screenshots/12.1-Messaging-Platforms-WhatsApp-Groups-List.png" width="500"> |
-| WA Group Details | <img src="docs/screenshots/12.2-Messaging-Platforms-WA-Group-Details.png" width="500"> |
-| User Management | <img src="docs/screenshots/13-User-Management.png" width="500"> |
-| Web Terminal | <img src="docs/screenshots/14-Web-Terminal.png" width="500"> |
-| Settings & Env | <img src="docs/screenshots/16-Settings-and-Env.png" width="500"> |
-| Telegram Commands | <img src="docs/screenshots/TG-commands.png" width="500"> |
-| macOS Installer | <img src="docs/screenshots/_Mac-Installer.png" width="500"> |
-
-</details>
-
----
-
-
 ## ✨ Features
 
 ### 🧠 Intelligence
-- **Multi-Model Engine** — Claude (Agent SDK with full tool use), OpenAI, Groq, NVIDIA NIM, Google Gemini, OpenRouter, or any OpenAI-compatible API
-- **Automatic Fallback** — If one provider fails, seamlessly tries the next
-- **Heartbeat Monitor** — Pings providers every 5 minutes, auto-failover after 2 failures, auto-recovery
-- **User-Configurable Fallback Order** — Rearrange provider priority via Telegram (`/fallback`), Web UI, or API
-- **Adjustable Thinking** — From quick answers (`/effort low`) to deep analysis (`/effort max`)
-- **Persistent Memory** — Remembers across sessions via vector-indexed knowledge base; session state (Claude SDK resume tokens, conversation history, language, effort) survives bot restarts (v4.11.0)
-- **Multi-Session Workspaces** — Run multiple parallel, context-isolated sessions on the same bot — one per Slack channel or per Telegram `/workspace` — each with its own working directory, purpose, and persona. Memory, skills, and sub-agents stay globally shared (v4.12.0). [How-to ↓](#-multi-session-workspaces-v4120)
-- **Truly Detached Sub-Agents** — Claude dispatches long-running research/audit tasks via the `alvin_dispatch_agent` MCP tool, which spawns independent `claude -p` subprocesses with their own PID + process group. Main session stays fully responsive, user can interrupt freely without killing sub-agents. Results deliver as separate messages. Works identically on Telegram, Slack, Discord, and WhatsApp (v4.13.0+ dispatch, v4.14.0 multi-platform)
-- **Smart Tool Discovery** — Scans your system at startup, knows exactly what CLI tools, plugins, and APIs are available
-- **Skill System** — 12 built-in SKILL.md files (code, data analysis, email, docs, research, sysadmin, browse, etc.) auto-activate based on message context
-- **Self-Awareness** — Knows it IS the AI model — won't call external APIs for tasks it can do itself
-- **Automatic Language Detection** — Detects user language (EN/DE/ES/FR) and adapts; learns preference over time
+- **Multi-model engine** — Claude Agent SDK · OpenAI · Groq · NVIDIA NIM · Gemini · OpenRouter · Ollama · Codex CLI · any OpenAI-compatible API
+- **Automatic fallback + heartbeat monitor** — pings providers every 5 min, auto-failover after 2 failures, auto-recovery; reorder priority via Telegram `/fallback`, Web UI, or API
+- **Adjustable thinking depth** — `/effort low` to `/effort max`
+- **Pluggable memory backends (v4.22)** — Gemini · OpenAI · Ollama · FTS5 keyword fallback. Auto-detection picks the best available. Indexed search across `MEMORY.md`, daily logs, project files, hub memory, asset index. Override via `EMBEDDINGS_PROVIDER`.
+- **Smart system-prompt injection (v4.22)** — once SQLite is populated, stops bulk-injecting `MEMORY.md` and surfaces only the chunks relevant to the user's current message. Cuts ~25 k tokens per turn for typical setups. `MEMORY_INJECT_MODE=auto|legacy|sqlite` to override.
+- **Layered memory (L0–L3)** — `identity.md` + `preferences.md` always plain-text · project memories on topic match · daily logs / curated knowledge via semantic or keyword search
+- **Persistent sessions** — Claude SDK resume tokens, conversation history, language, effort survive bot restarts
+- **Multi-session workspaces** — parallel context-isolated sessions per Slack channel or `/workspace` switch, each with its own cwd, purpose, persona. Memory + skills stay globally shared. [How-to ↓](#-multi-session-workspaces-v4120)
+- **Detached sub-agents** — `alvin_dispatch_agent` MCP tool spawns independent `claude -p` subprocesses that survive parent aborts. Results deliver as separate messages. Works identically on Telegram / Slack / Discord / WhatsApp.
+- **Smart tool discovery** — scans your system at startup; typical install surfaces 30–70 tools depending on what's locally available
+- **Skill system** — 14 SKILL.md files (see [Skills ↓](#-skills)) auto-activate based on message context
+- **Self-awareness + auto-language** — knows it IS the AI · detects EN/DE/ES/FR and adapts; learns preference over time
 
 ### 💬 Multi-Platform
-- **Telegram** — Full-featured with streaming, inline keyboards, voice, photos, documents
-- **Slack** — Socket Mode bot via `@slack/bolt`, DMs + @mentions, file attachments, reactions, `assistant.threads.setStatus` typing indicator. **One channel = one isolated workspace.** See [Multi-Session Workspaces](#-multi-session-workspaces-v4120) below.
-- **WhatsApp** — Via WhatsApp Web: self-chat as AI notepad, group whitelist with per-contact access control, full media support (photos, docs, audio, video)
-- **WhatsApp Group Approval** — Owner gets approval requests via Telegram (or WhatsApp DM fallback) before the bot responds to group messages. Silent — group members see nothing.
-- **Discord** — Server bot with mention/reply detection, slash commands
-- **Signal** — Via signal-cli REST API with voice transcription
-- **Terminal** — Rich TUI with ANSI colors and streaming (`alvin-bot tui`)
-- **Web UI** — Full dashboard with chat, settings, file manager, terminal, workspace overview
+- **Telegram** — streaming, inline keyboards, voice, photos, documents
+- **Slack** — Socket Mode via `@slack/bolt`, DMs + @mentions, file attachments, `assistant.threads.setStatus` typing. **One channel = one isolated workspace.**
+- **WhatsApp** — via WhatsApp Web; self-chat as AI notepad, group whitelist with per-contact access, full media. Owner approval gate routes to Telegram (DM / Discord / Signal fallback) before the bot replies.
+- **Discord** — server bot with mention/reply detection and slash commands
+- **Signal** — via signal-cli REST API, voice transcription
+- **Terminal** — rich TUI with ANSI colors + streaming (`alvin-bot tui`)
+- **Web UI** — full dashboard, chat, settings, file manager, terminal, workspace overview
 
 ### 🔧 Capabilities
-- **52+ Built-in Tools** — Shell, files, email, screenshots, PDF, media, git, system control
-- **Plugin System** — 6 built-in plugins (weather, finance, notes, calendar, email, smarthome)
-- **MCP Client** — Connect any Model Context Protocol server
-- **Cron Jobs** — Scheduled tasks with AI-driven creation ("check my email every morning")
-- **Voice** — Speech-to-text (Groq Whisper) + text-to-speech (Edge TTS)
-- **Vision** — Photo analysis, document scanning, screenshot understanding
-- **Image Generation** — Via Google Gemini / DALL·E (with API key)
-- **Web Browsing** — Fetch and summarize web pages
+- **Tool layer** — Shell · files · Python · git · email · PDF · media · vision · screenshots · system control. Universal tool use across any provider that supports function calling; text-only fallback for those that don't.
+- **6 built-in plugins** — weather · finance · notes · calendar · email · smarthome
+- **MCP client** — connect any Model Context Protocol server
+- **Cron** — AI-driven scheduled tasks (`"check my email every morning"`)
+- **Voice** — STT via Groq Whisper, TTS via Edge TTS or ElevenLabs
+- **Vision + image generation** — photo / document analysis · Gemini / DALL·E generation with API key
+- **Browser** — 4-tier strategy: WebFetch · stealth Playwright · CDP with persistent profile · agent-browser CLI (Tier-1.5, opt-in)
 
 ### 🖥️ Web Dashboard
-- **Live Chat** — WebSocket streaming, same experience as Telegram
-- **Model Switcher** — Change AI models on the fly
-- **Platform Setup** — Configure all messengers and providers via UI, WhatsApp group management inline
-- **File Manager** — Browse, edit, create files in the working directory
-- **Memory Editor** — View and edit the agent's knowledge base
-- **Session Browser** — Inspect conversation history
-- **Terminal** — Run commands directly from the browser
-- **Maintenance** — Health checks, backups, bot controls
+- WebSocket streaming chat · model switcher · platform & provider setup · file manager · memory editor · session browser · in-browser terminal · maintenance + health · workspace cards with cost aggregation
 
 ---
 
@@ -121,7 +66,7 @@ Free AI providers available — no credit card needed. **Privacy-first?** Pick t
 
 ### 📘 First-time setup walkthroughs
 
-Step-by-step guides with screenshots and screen-for-screen instructions:
+Step-by-step printable PDF guides:
 
 | Platform | PDF (printable) |
 |---|---|
@@ -262,69 +207,72 @@ If your AI provider isn't working, run `doctor` — it tests the actual API conn
 
 ## 🏗️ Architecture
 
-```
-                            ┌──────────────┐
-                            │   Web UI     │ (Dashboard, Workspaces, Chat, Settings)
-                            └──────┬───────┘
-                                   │ HTTP/WS
-┌──────────┐  ┌───────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
-│ Telegram │  │ Slack │  │ WhatsApp │  │ Discord  │  │  Signal  │
-└────┬─────┘  └───┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
-     │            │           │             │              │
-     └────────────┴───────────┴─────────────┴──────────────┘
-                           │
-                 ┌─────────┴──────────┐
-                 │ Workspace Resolver │ (per-channel context: cwd + persona)
-                 └─────────┬──────────┘
-                           │
-                    ┌──────┴───────┐
-                    │   Engine     │ (Query routing, fallback)
-                    └──────┬───────┘
-                           │
-          ┌────────────────┼────────────────┐
-          │                │                │
-   ┌──────┴──────┐  ┌─────┴──────┐  ┌──────┴──────┐
-   │ Claude SDK  │  │  OpenAI    │  │  Custom     │
-   │ (full agent)│  │ Compatible │  │  Models     │
-   └─────────────┘  └────────────┘  └─────────────┘
+```mermaid
+flowchart TB
+    classDef ent fill:#1e293b,color:#e2e8f0,stroke:#475569
+    classDef core fill:#0f172a,color:#f1f5f9,stroke:#3b82f6,stroke-width:2px
+    classDef prov fill:#1e293b,color:#cbd5e1,stroke:#64748b
+    classDef mem fill:#1e293b,color:#cbd5e1,stroke:#10b981
+
+    TG[Telegram]:::ent
+    SL[Slack]:::ent
+    WA[WhatsApp]:::ent
+    DC[Discord]:::ent
+    SG[Signal]:::ent
+    WEB[Web UI · TUI · CLI]:::ent
+
+    TG & SL & WA & DC & SG & WEB --> WR
+
+    WR[Workspace Resolver<br/>per-channel cwd + persona]:::core
+    WR --> ENG[Engine<br/>routing · fallback · heartbeat]:::core
+
+    ENG --> CL[Claude SDK]:::prov
+    ENG --> OAI[OpenAI · Groq · Gemini ·<br/>NVIDIA · OpenRouter]:::prov
+    ENG --> OL[Ollama · Codex CLI ·<br/>OpenAI-compatible]:::prov
+
+    ENG -.reads.-> MEM
+    MEM[Memory Layer]:::mem
+    MEM --> L0[L0 / L1<br/>identity.md · preferences.md<br/>always plain-text]:::mem
+    MEM --> SQL[SQLite store · provider auto-detect<br/>Gemini · OpenAI · Ollama · FTS5]:::mem
+
+    ENG -.dispatches.-> SUB[Detached sub-agents<br/>independent claude -p]:::prov
 ```
 
-### Provider Types
+### Provider matrix
 
-| Provider | Tool Use | Streaming | Vision | Auth |
-|----------|----------|-----------|--------|------|
-| Claude SDK | ✅ Full (native Bash, Read, Write, Web) | ✅ | ✅ | Claude CLI (OAuth) |
-| OpenAI, Groq, Gemini | ✅ Full (Shell, Files, Python, Web) | ✅ | Varies | API Key |
-| NVIDIA NIM | ✅ Full (Shell, Files, Python, Web) | ✅ | Varies | API Key (free) |
-| OpenRouter | ✅ Full (Shell, Files, Python, Web) | ✅ | ✅ | API Key |
-| Other OpenAI-compatible | ⚡ Auto-detect | ✅ | Varies | API Key |
+| Provider | Tool use | Streaming | Vision | Auth |
+|---|---|---|---|---|
+| Claude SDK (Agent) | ✅ native (Bash, Read, Write, Web, MCP) | ✅ | ✅ | Claude CLI OAuth |
+| OpenAI · Groq · Gemini · NVIDIA NIM · OpenRouter | ✅ universal tool use | ✅ | varies | API key |
+| Ollama (local) | ✅ via tool-bridge | ✅ | varies | none |
+| Codex CLI | ✅ subprocess | ✅ | — | Codex CLI auth |
+| Any OpenAI-compatible | ⚡ auto-detect | ✅ | varies | API key |
 
-> **Universal Tool Use:** Alvin Bot gives full agent capabilities to *any* provider that supports function calling — not just Claude. Shell commands, file operations, Python execution, web search, and more work across all major providers. If a provider doesn't support tool calls, Alvin Bot automatically falls back to text-only chat mode.
+> **Universal tool use** — Alvin gives full agent powers to any provider that supports function calling. Shell · files · Python · web work everywhere; providers without tool calls degrade cleanly to text-only chat.
 
-### Project Structure
+### Project layout
 
 ```
-alvin-bot/
-├── src/
-│   ├── index.ts                 # Entry point
-│   ├── engine.ts                # Multi-model query engine
-│   ├── config.ts                # Configuration
-│   ├── handlers/                # Message & command handlers
-│   ├── middleware/              # Auth & access control
-│   ├── platforms/               # Telegram, Slack, WhatsApp, Discord, Signal adapters
-│   ├── providers/               # AI provider implementations
-│   ├── services/                # Memory, voice, cron, plugins, workspaces, tool discovery
-│   ├── tui/                     # Terminal UI
-│   └── web/                     # Web server, APIs, setup wizard
-├── web/public/                  # Web UI (HTML/CSS/JS, zero build step)
-├── plugins/                     # Plugin directory (6 built-in)
-├── docs/
-│   ├── install/                 # Setup guides (macOS, Windows, Slack)
-│   └── custom-models.json       # Custom model configurations
-├── TOOLS.md                     # Custom tool definitions (Markdown)
-├── SOUL.md                      # Agent personality
-├── bin/cli.js                   # CLI entry point
-└── ecosystem.config.cjs         # PM2 configuration
+src/
+├── index.ts                 entry point
+├── engine.ts                multi-model query engine
+├── handlers/                message + command handlers
+├── platforms/               Telegram · Slack · WhatsApp · Discord · Signal
+├── providers/               Claude SDK · OpenAI-compat · Ollama · Codex CLI
+├── services/
+│   ├── embeddings/          v4.22 pluggable provider facade (Gemini/OpenAI/Ollama/FTS5)
+│   ├── memory*.ts           layered memory (L0-L3) + inject-mode resolver
+│   ├── workspaces.ts        per-channel cwd + persona registry
+│   ├── alvin-dispatch.ts    detached sub-agent orchestration
+│   ├── browser-manager.ts   4-tier browser strategy
+│   └── …                    cron · voice · skills · MCP · hooks · …
+├── tui/                     terminal chat UI
+└── web/                     dashboard server + APIs
+web/public/                  zero-build HTML/CSS/JS UI
+plugins/                     6 built-in plugins (hot-reload)
+skills/                      14 SKILL.md files (hot-reload)
+bin/cli.js                   CLI entry point
+electron/                    Electron wrapper for the .dmg build
 ```
 
 ---
@@ -368,7 +316,7 @@ The `cwd` auto-loads the project-specific `CLAUDE.md` via Claude SDK's `settingS
 ### Slack setup (5 minutes)
 
 1. Download the setup guide + manifest from the [latest release](https://github.com/alvbln/Alvin-Bot/releases/latest):
-   - `slack-setup.md` — step-by-step instructions with screenshots
+   - `slack-setup.md` — step-by-step instructions
    - `slack-manifest.json` — copy-paste ready Slack App manifest
 2. Create a Slack App from the manifest at https://api.slack.com/apps → **Create New App** → **From an app manifest**
 3. Enable Socket Mode, generate an **App-Level Token** (starts with `xapp-`)
@@ -433,6 +381,13 @@ OPENROUTER_API_KEY=<key>        # OpenRouter (100+ models)
 PRIMARY_PROVIDER=claude-sdk     # Primary AI provider
 FALLBACK_PROVIDERS=nvidia-kimi-k2.5,nvidia-llama-3.3-70b
 
+# Memory backend (v4.22+) — auto-detects based on what keys you have.
+# Set to override the default priority: gemini → openai → ollama → fts5.
+# fts5 is the zero-config keyword fallback — no key needed, works for everyone.
+EMBEDDINGS_PROVIDER=auto                  # auto | gemini | openai | ollama | fts5
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text   # only used for ollama provider
+MEMORY_INJECT_MODE=auto                   # auto | legacy | sqlite (see CHANGELOG v4.22)
+
 # Optional Platforms
 WHATSAPP_ENABLED=true           # Enable WhatsApp (needs Chrome)
 DISCORD_TOKEN=<token>           # Enable Discord
@@ -541,18 +496,26 @@ Plugins are auto-loaded at startup. Create your own by adding a directory with a
 
 ## 🎯 Skills
 
-Built-in skills in `skills/`:
+Skills are markdown files in `skills/` that auto-activate when the user's message matches their trigger keywords. The skill body gets injected into the system prompt, giving the agent specialized expertise on demand. 14 ship built-in:
 
-| Skill | Triggers | Description |
-|-------|----------|-------------|
-| code-project | code, build, implement, debug, refactor | Software development workflows, architecture patterns |
-| data-analysis | analyze, chart, csv, excel, statistics | Data processing, visualization, statistical analysis |
-| document-creation | document, report, letter, pdf, write | Professional document creation and formatting |
-| email-summary | email, inbox, unread, newsletter | Email triage, summarization, priority sorting |
-| system-admin | server, deploy, docker, nginx, ssl | DevOps, deployment, system administration |
-| web-research | research, compare, find, review | Deep web research with source verification |
-
-Skills activate automatically when your message matches their trigger keywords. The skill's SKILL.md content is injected into the system prompt, giving the agent specialized expertise for that task.
+| Skill | Description |
+|---|---|
+| **agent-browser** | Token-efficient web automation via the agent-browser CLI (accessibility-tree snapshots) — Tier 1.5 of the browser stack |
+| **apple-notes** | Read, create, search Apple Notes via AppleScript (macOS) |
+| **browse** | 3-tier browser control: WebFetch · stealth Playwright · CDP with persistent profile |
+| **code-project** | Software development workflows: build, debug, refactor, architecture patterns |
+| **data-analysis** | CSV / JSON / Excel processing, charts, statistics via Python |
+| **document-creation** | Professional PDFs, reports, letters with formatting |
+| **email-summary** | Inbox triage, newsletter digests, priority sorting |
+| **github** | Issues, PRs, releases, workflows via the `gh` CLI |
+| **social-fetch** | Analyse Instagram / TikTok / YouTube / X URLs the user shares |
+| **summarize** | Condense URLs, PDFs, long documents |
+| **system-admin** | Server management, deploys, Docker, nginx, SSL |
+| **weather** | Forecasts and conditions |
+| **web-research** | Deep multi-source research with citation aggregation |
+| **webcheck** | Security / SEO audit of a website |
+
+Drop your own `<name>/SKILL.md` into `~/.alvin-bot/skills/` for hot-reload. List active skills via `/skills` or `alvin-bot skills`.
 
 ---
 
@@ -579,96 +542,40 @@ alvin-bot version   # Show version
 
 ## 🗺️ Roadmap
 
-- [x] **Phase 1** — Multi-Model Engine (provider abstraction, fallback chains)
-- [x] **Phase 2** — Memory System (vector search, user profiles, smart context)
-- [x] **Phase 3** — Rich Interactions (video messages, browser automation, email)
-- [x] **Phase 4** — Plugins & Tools (plugin ecosystem, MCP client, custom tools)
-- [x] **Phase 5** — CLI Installer (setup wizard, Docker, health check)
-- [x] **Phase 6** — Web Dashboard (chat, settings, file manager, terminal)
-- [x] **Phase 7** — Multi-Platform (Telegram, Discord, WhatsApp, Signal adapters)
-- [x] **Phase 8** — Universal Tool Use *(NEW)* — All providers get agent powers:
-  - ✅ Shell execution, file read/write/edit, directory listing
-  - ✅ Python execution (Excel, PDF, charts, data processing)
-  - ✅ Web fetch & search
-  - ✅ Auto-detect function calling support per provider
-  - ✅ Graceful fallback to text-only for providers without tool support
-- [x] **Phase 9** — Skill System + Self-Awareness + Language Adaptation:
-  - ✅ SKILL.md files for specialized domain knowledge (email, data analysis, code, docs, research, sysadmin)
-  - ✅ Auto-matching: skill triggers activate contextual expertise on demand
-  - ✅ Self-Awareness Core: agent knows it IS the AI (no external LLM calls for text tasks)
-  - ✅ Automatic language detection and adaptation (EN default, learns user preference)
-  - ✅ Human-readable cron schedules + visual schedule builder in WebUI
-  - ✅ Platform Manager refactor: all adapters via unified registration system
-  - ✅ Cron notifications for all platforms (Telegram, WhatsApp, Discord, Signal)
-  - ✅ PM2 auto-refresh on Maintenance page
-  - ✅ WhatsApp group whitelist with per-contact access control
-  - ✅ Owner approval gate (Telegram → WhatsApp DM → Discord → Signal fallback)
-  - ✅ Full media processing: photos, documents, audio/voice, video across all platforms
-  - ✅ File Browser: create, edit, delete files with safety guards
-  - ✅ Git history sanitized (personal data removed via git-filter-repo)
-- [x] **Phase 10** — Anthropic API Provider + WebUI Provider Management
-  - [x] Anthropic API key test case in WebUI (validation endpoint)
-  - [x] "Add Provider" flow in WebUI — add new providers post-setup without editing `.env`
-  - [x] Claude SDK guided setup from WebUI (install check, login status, step-by-step)
-  - [x] `.env.example` update with `ANTHROPIC_API_KEY`
-- [x] **Phase 11** — WebUI Professional Redesign
-  - [x] Replace emoji icons with Lucide SVG icons (60+ icons, sidebar, pages, buttons)
-  - [x] i18n framework (`i18n.js`) — bilingual DE/EN with browser-locale detection (~400 keys)
-  - [x] Language toggle in sidebar footer (DE | EN)
-  - [x] Typography upgrade (Inter webfont via Google Fonts)
-  - [x] Gradient accents + subtle glassmorphism on cards
-  - [x] Smooth page transitions (fade animation on page switch)
-  - [x] Skeleton loading states + status pulse animations
-  - [x] Command Palette (Cmd+K / Ctrl+K) with fuzzy search
-- [x] **Phase 12** — Native Installers (Non-Techie Friendly)
-  - [x] Electron wrapper (embedded Node.js + WebUI + tray icon)
-  - [x] macOS `.dmg` build via electron-builder (arm64)
-  - [ ] Windows `.exe` (NSIS) via electron-builder
-  - [ ] Linux `.AppImage` + `.deb` via electron-builder
-  - [x] Auto-update mechanism (electron-updater)
-  - [x] GUI Setup Wizard (provider selection, Telegram token, first-run experience)
-  - [ ] Homebrew formula (`brew install alvin-bot`)
-  - [ ] Scoop manifest for Windows
-  - [ ] One-line install script
-  - [x] Docker Compose polish (production-ready `docker-compose.yml`)
-- [x] **Phase 13** — npm publish (security audit)
-- [x] **Phase 14** — Async Sub-Agents (v4.10.0)
-  - [x] `run_in_background: true` system prompt hint for Claude SDK
-  - [x] Async-agent watcher polling `outputFile` JSONL, delivering results as separate messages
-  - [x] Session-bound sub-agents (each session spawns its own background workers)
-- [x] **Phase 15** — Memory Persistence + Smart Loading (v4.11.0)
-  - [x] Session persistence across bot restarts (debounced atomic flush, v2 envelope)
-  - [x] SDK memory injection (MEMORY.md in every system prompt, not just tool-call dependent)
-  - [x] Semantic recall on SDK first-turn via embeddings
-  - [x] Layered memory stack (L0 identity / L1 preferences / L2 projects / L3 vector search)
-  - [x] Auto-fact extraction during compaction (Mem0-style)
-- [x] **Phase 16** — Multi-Session + Slack Interface (v4.12.0)
-  - [x] Session-key fix: platform-message.ts routes through `buildSessionKey()`
-  - [x] Workspace registry with hot-reload (`~/.alvin-bot/workspaces/*.md`)
-  - [x] Workspace resolver in platform handlers (per-channel persona + cwd)
-  - [x] Slack adapter polish: progress ticker (`chat.update`), typing status (`assistant.threads.setStatus`), channel name cache
-  - [x] Telegram `/workspace` + `/workspaces` commands (feature parity)
-  - [x] Per-workspace cost aggregation + Web UI workspace cards
-  - [x] Slack setup guide + copy-paste app manifest (in GitHub Release assets)
-- [x] **Phase 17** — Truly detached sub-agents + multi-platform dispatch (v4.13.0 – v4.14.2, 2026-04-16)
-  - [x] `alvin_dispatch_agent` MCP tool — spawns independent `claude -p` subprocesses that survive parent aborts (v4.13.0)
-  - [x] Slack `/alvin` slash command (namespaced parent with subcommands: status / new / effort / help + LLM fallthrough) (v4.13.2)
-  - [x] Sub-agent dispatch on Slack, Discord, WhatsApp via platform-aware delivery registry (v4.14.0)
-  - [x] `/subagents list` merged view — v4.0.0 bot-level agents + v4.13+ detached dispatches in one list (v4.14.1)
-  - [x] Watcher zombie guard — missing outputFile > 10 min delivers as failed instead of 12h timeout (v4.14.2)
-  - [x] Staleness-based partial output recovery for interrupted sub-agents (v4.12.4)
-  - [ ] SQLite migration of the embeddings index (currently 128 MB JSON)
-  - [ ] Per-workspace memory layer (additive over global) — facts learned in one workspace stay there unless explicitly promoted to global
-  - [ ] Per-workspace provider override (`provider:` in frontmatter) — e.g. one workspace uses Claude Opus, another uses a cheaper model
-  - [ ] Per-workspace skill allowlist — scope Apple Notes to personal workspace, sysadmin only to devops workspace, etc.
-  - [ ] Multi-User Slack (real `per-channel-peer` mode) — different users in the same Slack channel get their own sub-sessions
-  - [ ] Workspace cloning / templates — `/workspace clone my-project as my-fork` spins up a new workspace from an existing one
-  - [ ] Daily log decay / archive — older daily logs move to cold storage after N days
-- [ ] **Phase 18** — Security + Platform hardening (from v4.12.1 audit, prioritized)
-  - [ ] **P1 — Electron major upgrade** (35 → 41+) — fixes 1 HIGH + 5 MODERATE Electron CVEs in the Desktop-Build path. Major version jump, requires full rebuild + test of `.dmg` flow. Separate release (likely bundled with Windows `.exe` work).
-  - [ ] **P1 — Prompt injection defense strategy** — not a single fix but a design debate: heuristic filters vs allow-list vs no-sandbox-accept-the-risk. Currently handled as a documented design-constraint (README security section), not as a code filter. When we decide the policy, implement it across all message entry points.
-  - [ ] **P2 — TypeScript 5 → 6 upgrade** — major release, likely breaking changes in strict mode. Needs a dedicated release + test sweep. Low priority since 5.x is still supported.
-  - [ ] **P0 for v5.0 — MCP plugin sandboxing** — currently MCP servers run with full Node privileges. Plan: run each MCP in a child process with restricted FS + network policy (similar to deno-permission model). Architectural change, v5.0 territory.
+> Per-version details: see [`CHANGELOG.md`](CHANGELOG.md). The roadmap is a forward-looking summary, not a changelog.
+
+### ✅ Recently shipped
+
+| Version | Theme | Highlights |
+|---|---|---|
+| **v4.22** *(May 2026)* | Memory architecture overhaul | Pluggable embedding providers — **Gemini · OpenAI · Ollama · FTS5 (zero-config keyword fallback)**. Auto-detection picks the best available, so users with no API key still get a working indexed memory store. Smart inject mode stops bulk-injecting `MEMORY.md` once SQLite is populated. |
+| **v4.21** | Agent Browser skill | Tier-1.5 token-efficient web automation via the [agent-browser](https://github.com/vercel-labs/agent-browser) CLI — opt-in by install. ~90 % token reduction vs Playwright on cooperative pages. |
+| **v4.20** | SQLite-backed vector memory | Replaces the legacy 128 MB JSON index. Automatic migration on first start, per-chunk INSERT/UPDATE, lazy native binary load with graceful fallback. |
+| **v4.18 – v4.19** | Reliability + per-workspace overrides | SDK auto-recovery on token rotation / quota exhaustion / empty streams. Per-workspace `effort` / `provider` / `voice` / `temperature` / `toolset`. |
+| **v4.17** | Hardening audit | Disk cleanup service, hardening fixes from internal audit. |
+| **v4.13 – v4.14** | Detached sub-agents | `alvin_dispatch_agent` MCP tool spawns independent `claude -p` subprocesses that survive parent aborts. Multi-platform dispatch (Slack / Discord / WhatsApp). Watcher zombie guard. |
+| **v4.10 – v4.12** | Multi-session + Slack | Workspace registry with hot-reload, per-channel personas + cwd, Slack adapter with progress ticker + typing status, owner approval gate, async sub-agents. |
+
+### 🏛️ Foundations (built before v4.10)
+
+Multi-model provider abstraction with fallback chains · plugin & skill ecosystems with hot-reload · multi-platform adapters (Telegram, WhatsApp, Discord, Signal, Slack) · Web UI with i18n + command palette · native macOS `.dmg` via Electron · Docker Compose · npm distribution · MCP client + custom tools · universal tool use across providers · full media pipeline (audio · video · photo · voice).
+
+### 🎯 On the radar
+
+| Priority | Item | Why |
+|---|---|---|
+| **P0 → v5.0** | MCP plugin sandboxing | MCP servers currently run with full Node privileges. Plan: child process with restricted FS + network policy (deno-permission style). Architectural change. |
+| **P1** | Electron major upgrade (35 → 41+) + Windows `.exe` | Closes desktop-build CVEs, unblocks the only platform still missing a native installer. |
+| **P1** | Prompt injection defense policy | Needs a design decision (heuristic filter / allow-list / accept-the-risk with clearer warnings) and consistent enforcement at every message entry point. |
+| **P2** | Per-workspace memory layer | Facts learned in one workspace stay scoped unless explicitly promoted. Builds on the v4.22 SQLite store. |
+| **P2** | Per-workspace skill allowlist | Scope Apple Notes to personal workspace, sysadmin tools to devops only, etc. |
+| **P2** | Multi-user Slack (`per-channel-peer`) | Different users in the same Slack channel get their own sub-sessions. |
+| **P3** | Linux `.AppImage` / `.deb`, Homebrew formula, Scoop manifest, one-line install script | Platform reach for non-npm users. |
+| **P3** | Daily-log decay / archive | Older daily logs move to cold storage after N days. |
+| **P3** | Workspace cloning / templates | `/workspace clone my-project as my-fork` spins up a new workspace from an existing one. |
+| **P3** | TypeScript 5 → 6 | 5.x still supported; strict-mode break-fix work, not urgent. |
+
+Pull requests welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ---