@inetafrica/open-claudia 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v2.6.0
+- **Dream: nightly memory consolidation (Phase 3 of the memory system).** A quiet-hours pass (`core/dream.js`, default 4am via `DREAM_CRON`, model `DREAM_MODEL` default sonnet, `DREAM=off` to disable) reviews the entire pack + entity memory on a stronger model and returns a strict-JSON decision that bot code applies:
+  - **Merges** packs that drifted into the same topic (sections synthesised, not concatenated) — merged-away packs are backed up to `~/.open-claudia/backup/dream-<stamp>/` before removal.
+  - **Umbrella/parent pack trees**: creates umbrella packs over 3+ sibling topics (the umbrella's State is a family map, a router not a duplicate) and assigns parent/sub relationships, with cycle protection. Injected packs now show their parent ("Part of: …") and list sub-packs with dig-deeper hints.
+  - **Retags**: tightens pack descriptions and tags — the FTS router matches on those fields, so tighter metadata means fewer false injections.
+  - **Entity dedupe + cross-linking**: merges duplicate entities (aliases unioned, source backed up) and rewrites entity Notes with `[[pack-dir]]` cross-links.
+  - Reports in chat (owner Telegram channel) whenever it changed something; silent when there was nothing to tidy. Manual trigger: `open-claudia dream`, preview with `--dry-run`.
+- **Personality system.** `~/.open-claudia/persona.md` (override with `PERSONA_FILE`) holds Open Claudia's voice — tone, quirks, emoji habits — on top of the user-owned soul. It feeds into the system prompt as a `## Personality` block that explicitly never overrides soul rules, ships with a warm default, and the dream pass may evolve it gently (bounded 80–2400 chars, previous version backed up, change announced).
+- **Memory announcements got a face-lift.** Reviewer announcements are now grouped under a friendly header ("🧠 Took some notes while we worked:"), use per-kind emojis (📦 new pack, ✏️ update, 👤/🚀/🏢/📍/🖥️/🔖 entities by type), clip at word boundaries instead of mid-word, carry more of the actual content, and include an inspect hint for new packs. In-turn pack/entity writes announce in the same voice.
+
 ## v2.5.0
 - **Context packs: skills become living topic documents (skills + memory merged).** Each pack is `~/.open-claudia/packs/<dir>/PACK.md` with four sections — Stance (how to think about the topic: user preferences, hard rules), Procedure (verified how-to, what skills used to be), State (where work stands now; replaced wholesale as things move), Journal (dated one-line log of past sessions, capped at 30 entries).
   - **Pre-turn router** (`core/packs.js` + `system-prompt.js`): the incoming message is FTS5-matched against all packs (porter-stemmed, field-weighted — name/description/tags hits count double, threshold keeps a single incidental body word from dragging a pack in; BM25 was unusable because its IDF collapses on small corpora). Matched packs are injected into the per-turn context block, once per (channel, session, pack-version) so re-injection only happens when a pack actually changed. Rides the user message, not the system prompt, to preserve the prompt-cache prefix.

package/README.md

@@ -2,36 +2,58 @@
 
 Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat.
 
-Send text, voice notes, screenshots, and files from your phone. Your chosen AI agent works on your projects and reports back.
+Send text, voice notes, screenshots, and files from your phone. Your chosen AI agent works on your projects, remembers what it learned, and reports back.
 
 ## Features
 
+### Channels & backends
 - **Multi-channel** — run the same bot on Telegram, Kazee Chat, or both at once (`CHANNELS=telegram,kazee`). Each channel renders keyboards, files, voice notes, and edits natively
-- **Multi-backend** — switch between Claude Code, Cursor Agent, and OpenAI Codex on the fly (`/claude`, `/cursor`, `/codex`)
-- **Multi-project sessions** — switch between workspace projects
-- **Per-project conversation history** — auto-resumes last conversation, switch with `/sessions`
-- **Project transcript memory** — keeps redacted project JSONL transcripts outside the repo and points fresh/backend-switched sessions to them without pasting huge history
-- **Separate session persistence** — Claude, Cursor, and Codex each maintain their own conversation state
-- **Voice notes** — speak instructions, transcribed locally via Whisper
+- **Multi-backend** — switch between Claude Code, Cursor Agent, and OpenAI Codex on the fly (`/claude`, `/cursor`, `/codex`); each keeps its own session state
+- **Multi-user / team mode** — one bot serves multiple authorized users in parallel, each with their own conversations, settings, model, backend, and usage counters
+- **Multi-project sessions** — switch between workspace projects; per-project conversation history auto-resumes
+
+### Memory & long-term context
+- **Context packs** — living per-topic documents (one per project, system, or recurring task) holding Stance, Procedure, State, and Journal. Packs matching your message are auto-injected into the agent's context, and a background reviewer updates them after every substantial turn — the assistant keeps its train of thought across sessions and projects
+- **Entity memory** — short notes on the people, places, projects, orgs, and systems you mention, extracted automatically and injected when they come up again
+- **Dream consolidation** — a nightly pass on a stronger model that merges duplicate packs, builds umbrella/parent pack trees, tightens descriptions, dedupes entities, and reports what it tidied — with everything backed up first
+- **Personality** — a persona file gives the assistant a consistent voice on top of your soul file, and the dream pass evolves it gently as you work together
+- **Transcript search** — redacted project transcripts indexed in SQLite FTS5; `open-claudia transcript-search` gives the agent ~50ms ranked recall over months of history
+- **Smart compaction** — long conversations are summarized proactively before they get slow; full briefs are archived to disk so nothing is truly lost (`/compact`, `/compactwindow`)
+- **No silent learning** — every pack, entity, or skill the bot creates or changes is announced in chat with one line
+
+### Background work
+- **Wakeups & crons** — the agent can schedule one-shot wake-ups ("check the deploy in 20 minutes") and recurring jobs that survive restarts
+- **Persistent tasks** — a per-channel todo tree with plans and subtasks that survives compaction and restarts
+- **Sub-agents** — throwaway research agents for side questions that shouldn't pollute the main conversation
+- **Agent mode** — non-blocking side conversations while heavy tasks run in the background
+
+### Working from your phone
+- **Voice notes** — speak instructions, transcribed locally via Whisper; voice questions get voice replies (macOS)
 - **Screenshots & images** — send UI mockups, errors, or code screenshots
-- **File sharing** — send PDFs, code files, documents — saved and read by the agent
+- **File sharing** — send PDFs, code files, documents; the agent can send files, photos, and voice clips back
 - **Reply context** — reply to any message (including files) for follow-up
-- **Streaming output** — see the agent working in real-time
-- **Agent mode** — non-blocking side conversations while heavy tasks run in the background
-- **Cron jobs** — scheduled tasks (standups, git digests, health checks)
+- **Streaming output** — see the agent working in real time
+
+### Team
+- **People roster** — the bot knows your team members, their channels, and notes about them
+- **Intros** — unknown chats go through an owner-approved introduction flow
+- **Cross-channel relay** — the agent can message teammates on their own channels (with provenance and an audit trail)
+- **Identity links** — link chats across channels to one canonical user so history follows you
+
+### Operations
 - **Encrypted vault** — store API keys and credentials securely
 - **Customizable soul** — define your assistant's personality and knowledge
-- **Model switching** — toggle between models on either backend
-- **Plan mode, effort levels, budgets** — full control from Telegram
-- **Auto-updates** — checks for new versions every 5 minutes, upgrade with `/upgrade`
-- **Requirements doctor** — `/doctor` / `/requirements` checks CLI installs, auth, voice tools, and writable paths after upgrades
-- **Multi-user auth** — authorize additional users with code verification
-- **Cross-platform** — works on macOS, Linux, and Windows
+- **Model switching, plan mode, effort levels, budgets** — full control from chat
+- **Token economy** — byte-stable system prompt for maximum Anthropic prompt-cache hits; dynamic state rides each message instead
+- **Web UI** — optional browser UI for setup and config (`open-claudia start --web`)
+- **Auto-updates** — checks npm every 5 minutes, upgrade with `/upgrade`
+- **Requirements doctor** — `/doctor` checks CLI installs, auth, voice tools, and writable paths
+- **Cross-platform** — macOS, Linux, and Windows
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/) 18+
-- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
+- [Node.js](https://nodejs.org/) 18+ (22.5+ recommended — its built-in SQLite powers transcript/pack/entity search; on older Node those features quietly disable themselves)
+- A Telegram bot token (from [@BotFather](https://t.me/BotFather)) and/or a Kazee Chat bot
 - At least one authenticated CLI backend on the host machine (see below)
 - (Optional) [whisper.cpp](https://github.com/ggerganov/whisper.cpp) + ffmpeg for voice notes
 
@@ -63,14 +85,14 @@ agent status              # Verify: should show your email and plan
 ```bash
 npm install -g @openai/codex
 codex login               # Opens browser to authenticate
-# Or from Telegram after Open Claudia is running: /codex_login
+# Or from chat after Open Claudia is running: /codex_login
 # If browser/device login cannot complete remotely: /codex_setup_token
 codex --version           # Verify it works
 ```
 
 Docker images include the Codex CLI. Direct npm installs still need optional backend CLIs installed on the host.
 
-> **Important**: Claude Code can use macOS Keychain when you log in interactively, but a launchd/background bot may not be able to read that Keychain session. Open Claudia v1.14.0 adds Telegram auth helpers and supports `CLAUDE_CODE_OAUTH_TOKEN` for non-interactive Claude runs. Prefer `/setup_token` then `/use_oauth_token` if Telegram shows Claude auth/keychain errors.
+> **Important**: Claude Code can use macOS Keychain when you log in interactively, but a launchd/background bot may not be able to read that Keychain session. Open Claudia supports `CLAUDE_CODE_OAUTH_TOKEN` for non-interactive Claude runs. Prefer `/setup_token` then `/use_oauth_token` if chat shows Claude auth/keychain errors.
 
 ### 2. Install Open Claudia
 
@@ -98,39 +120,47 @@ If setup is interrupted, running it again resumes from the last completed step.
 
 All configuration is stored in `~/.open-claudia/` — survives npm upgrades.
 
+### 4. (Optional) Add Kazee Chat
+
+Set `CHANNELS=telegram,kazee` plus `KAZEE_URL`, `KAZEE_BOT_TOKEN`, `KAZEE_BOT_USER_ID`, and `KAZEE_OWNER_USER_ID` in `~/.open-claudia/.env`, or run `/channel add kazee` from an existing chat and follow the wizard.
+
 ## Run
 
 ```bash
-open-claudia start    # Start the bot
-open-claudia stop     # Stop the bot
-open-claudia status   # Check if running (shows PID)
-open-claudia logs     # View recent logs
-open-claudia auth     # Manage chat authorizations
+open-claudia start            # Start the bot (--web adds the web UI, --quick skips slow health checks)
+open-claudia web              # Start with web UI for setup/config
+open-claudia stop             # Stop the bot
+open-claudia status           # Check if running (shows PID)
+open-claudia health           # Run environment health checks (-v for detail)
+open-claudia logs             # View recent logs
+open-claudia auth             # Manage chat authorizations
 ```
 
 If installed as a background service, the bot starts automatically on login and restarts on crash.
 
-## Telegram Commands
+## Chat Commands
 
-### Backend Switching
+### Backend switching
 
 | Command | Description |
 |---------|-------------|
-| `/cursor` | Switch to Cursor Agent backend |
 | `/claude` | Switch to Claude Code backend |
+| `/cursor` | Switch to Cursor Agent backend |
 | `/codex` | Switch to OpenAI Codex backend |
 | `/backend` | Show current backend with picker |
 
 Each backend keeps its own persistent session. Switching doesn't lose your place — you can go back and forth freely.
 
-### Session Management
+### Session management
 
 | Command | Description |
 |---------|-------------|
-| `/session` | Pick a project to work on |
+| `/session [<project>]` | Pick a project to work on |
 | `/sessions` | List past conversations for current project |
 | `/projects` | Browse all workspace projects |
 | `/continue` | Resume last conversation explicitly |
+| `/compact` | Summarize conversation context now |
+| `/compactwindow [<tokens> \| off \| default]` | Set the auto-compact token threshold |
 | `/end` | End current session |
 
 When you select a project, the last conversation is automatically resumed. Tap "New conversation" to start fresh.
@@ -139,74 +169,145 @@ When you select a project, the last conversation is automatically resumed. Tap "
 
 | Command | Description |
 |---------|-------------|
-| `/model` | Switch model (opus / sonnet / haiku for Claude; any model flag for Cursor) |
-| `/effort` | Set effort level (low / medium / high / max) |
-| `/budget` | Set max spend for next task (e.g. `/budget 0.50`) — Claude only |
+| `/model [<model>]` | Switch model (opus / sonnet / haiku for Claude; any model flag for Cursor/Codex) |
+| `/effort [low\|medium\|high\|max]` | Set effort level |
+| `/budget [$N]` | Set max spend for next task — Claude only |
 | `/plan` | Toggle plan mode — `--permission-mode plan` (Claude) / `--mode plan` (Cursor) |
 | `/ask` | Toggle ask mode — read-only Q&A, no edits (Cursor Agent only) |
-| `/compact` | Summarize conversation context |
-| `/worktree` | Toggle isolated git branch — Claude only |
+| `/worktree` | Toggle isolated git branch |
 | `/mode` | Switch between direct and agent bot modes |
 | `/status` | Show current session, backend, and settings |
+| `/usage` | Token usage and cost for this session |
 | `/doctor` / `/requirements` | Check Node, CLI binaries/versions/auth, voice stack, and writable paths |
 
-### Automation
+### Memory & skills
 
 | Command | Description |
 |---------|-------------|
-| `/cron` | Manage scheduled tasks |
-| `/vault` | Manage encrypted credentials (password required) |
+| `/learn [<hint>]` | Capture the last piece of work into the matching context pack |
+| `/skills [show\|remove <name>]` | List, show, or remove legacy learned skills |
 | `/soul` | View/edit assistant identity and personality |
 
-### Claude Code Auth
+### Automation
 
 | Command | Description |
 |---------|-------------|
-| `/auth_status` | Runs `claude auth status` and reports redacted status plus whether the bot has an OAuth token configured |
-| `/login` | Starts `claude auth login --claudeai --email sumeet@inet.africa`, sends the login URL/code, and accepts paste-back codes |
-| `/setup_token` | Starts `claude setup-token`; if Claude prints an OAuth token, Open Claudia stores it without echoing it |
-| `/use_oauth_token <token>` | Stores `CLAUDE_CODE_OAUTH_TOKEN` in config for launchd/non-interactive Claude runs; the Telegram message is deleted when possible |
-| `/use_oauth_token` | Secure pending mode: send the token as the next message and it will be deleted/stored without echo |
-| `/clear_oauth_token` | Removes the stored OAuth token from config/process, and from vault if it is unlocked |
-
-Tokens are redacted from Telegram output and logs. If the encrypted vault is unlocked, `/use_oauth_token` also mirrors the token into the vault, but `.env` storage is what lets launchd pass `CLAUDE_CODE_OAUTH_TOKEN` to Claude without relying on macOS Keychain.
+| `/cron [add\|remove ...]` | Manage scheduled tasks |
+| `/vault [create\|get\|set\|remove\|lock]` | Manage encrypted credentials (password required) |
 
-### Codex Auth
+### Team & access
 
 | Command | Description |
 |---------|-------------|
-| `/codex_auth_status` | Runs `codex login status` and reports redacted status/version |
-| `/codex_login` | Starts `codex login --device-auth` and sends any login URL/device code printed by the CLI |
-| `/codex_setup_token` | Secure paste mode for an OpenAI API key; the message is deleted and passed to `codex login --with-api-key` without echoing it |
-| `/codex_setup_token <key>` | Same as above, but inline; the command message is deleted when possible |
-| `/cancel_codex_auth` | Cancels a pending Codex auth flow |
+| `/auth [list \| revoke <chatId>]` | Request access; owner lists/revokes |
+| `/people [show\|note\|link\|unlink\|add\|remove ...]` | Manage the team roster |
+| `/intros [approve\|reject <id>]` | Approve/reject introductions from unknown chats |
+| `/link [<chat-id>] <email-or-id>` | Link a chat to a canonical user id |
+| `/links` | List identity links (owner) |
+| `/whoami` | Show your canonical user id |
+| `/channel [add kazee \| remove <id>]` | Add or remove channels |
 
-Codex tokens/API keys are redacted from Telegram output and logs. Device login support depends on the installed Codex CLI; if it requires a real TTY, Open Claudia will say so and suggest `/codex_setup_token` or an SSH/terminal fallback.
+### Claude Code auth
 
-### Requirements Doctor
+| Command | Description |
+|---------|-------------|
+| `/auth_status` | Reports redacted Claude auth status and whether an OAuth token is configured |
+| `/login` | Starts a Claude login flow, sends the URL/code, accepts paste-back codes (`/auth_code <code>`, `/cancel_auth`) |
+| `/setup_token` | Runs `claude setup-token`; the resulting OAuth token is stored without echoing it |
+| `/use_oauth_token [<token>]` | Stores `CLAUDE_CODE_OAUTH_TOKEN` for non-interactive runs; the message is deleted when possible. Without an argument, send the token as the next message |
+| `/clear_oauth_token` | Removes the stored OAuth token |
 
-`/doctor` (alias: `/requirements`) gives a mobile-friendly checklist after upgrades or whenever something feels broken:
+Tokens are redacted from chat output and logs.
 
-- Node.js version
-- Claude CLI version/auth
-- Cursor Agent version/status when installed/configured
-- Codex CLI version/auth when installed/configured
-- ffmpeg/Whisper/model paths when voice is configured
-- Workspace and config directory writability
+### Codex auth
 
-`/upgrade` also includes a post-upgrade doctor summary before restarting.
+| Command | Description |
+|---------|-------------|
+| `/codex_auth_status` | Reports redacted Codex auth status/version |
+| `/codex_login` | Starts `codex login --device-auth` and relays the URL/device code |
+| `/codex_setup_token [<key>]` | Secure paste mode for an OpenAI API key (message deleted, never echoed) |
+| `/cancel_codex_auth` | Cancels a pending Codex auth flow |
 
 ### System
 
 | Command | Description |
 |---------|-------------|
 | `/version` | Show current running version |
-| `/doctor` / `/requirements` | Check installed CLI requirements/auth and writable paths |
-| `/upgrade` | Upgrade to latest version and restart |
+| `/upgrade` | Upgrade to latest version and restart (includes a post-upgrade doctor summary) |
 | `/restart` | Restart the bot |
 | `/stop` | Cancel a running task |
 | `/help` | Show all commands |
 
+## Memory & Long-Term Context
+
+Open Claudia layers three memory systems on top of the backend's native sessions:
+
+**Context packs** (`~/.open-claudia/packs/<dir>/PACK.md`) are living per-topic documents with four sections: *Stance* (how to think about the topic — your preferences and hard rules), *Procedure* (verified how-to steps), *State* (where work stands now), and *Journal* (a dated one-line log of past sessions). Incoming messages are matched against packs (FTS5, field-weighted so a stray word can't drag a pack in) and hits are injected into the agent's context — mention a project anywhere and the assistant picks up its train of thought, decisions, and history without you re-explaining. After every substantial turn, a background reviewer on a cheap model updates the relevant pack (or creates one for a genuinely new topic). Every change is announced in chat.
+
+**Entity memory** (`~/.open-claudia/entities/<slug>.md`) works the same way for the people, places, projects, orgs, and systems you mention — who they are, current truth, and a dated observation log. Mentioning a name injects its note.
+
+**Dream consolidation** — while the per-turn reviewer takes quick notes, *dream* is the slow overnight pass (default 4am, on a stronger model): it merges packs that drifted into the same topic, builds parent/sub pack trees with umbrella summaries, tightens descriptions and tags so the router matches with less noise, dedupes entities, and cross-links notes. Anything merged away is backed up under `~/.open-claudia/backup/dream-<stamp>/` first, and every dream that changes something reports in chat. Configure with `DREAM_CRON` / `DREAM_MODEL`, disable with `DREAM=off`.
+
+**Personality** — your `soul.md` holds identity and hard rules; `~/.open-claudia/persona.md` holds the voice on top — tone, quirks, emoji habits. It feeds into the system prompt and the dream pass may evolve it gently (bounded, backed up, announced). Edit it directly any time.
+
+**Transcript index** — every project conversation is logged (redacted) to JSONL outside the repo and indexed in SQLite FTS5, giving the agent ranked search over your full history.
+
+```bash
+open-claudia pack list|show <dir>|match "<text>"|migrate|remove <dir>|reindex
+open-claudia entity list|show <slug>|match "<text>"|note <name> "<text>"|remove <slug>|reindex
+open-claudia dream [--dry-run]               # run the consolidation pass now
+open-claudia transcript-search "<query>"     # alias: ts; --all for every project
+open-claudia transcript-window "<pattern>"   # alias: tw; hits with surrounding turns
+```
+
+`pack migrate` folds legacy `~/.claude/skills` into packs (originals backed up, never deleted) — run it once after upgrading from a pre-2.5 version.
+
+When a conversation grows past the auto-compact threshold, the bot summarizes it proactively: the full brief is archived to `~/.open-claudia/briefs/` and a condensed version seeds the fresh session, so long-running work never hits a context wall.
+
+## Background Work
+
+The agent can schedule its own future work — these survive bot restarts:
+
+```bash
+open-claudia schedule-wakeup <30s|5m|2h|1d|ISO-date> "<prompt>"   # one-shot; resumes the session
+open-claudia cron-add "<5-field cron>" "<prompt>"                 # recurring
+open-claudia cron-list / cron-remove <id>
+```
+
+A persistent per-channel task tree tracks multi-turn work (plans with subtasks; completed items are removed automatically):
+
+```bash
+open-claudia task plan "<title>" "<step 1>" "<step 2>" [--description "..."]
+open-claudia task add|list|start <id>|done <id>|remove <id>
+```
+
+And for side research that shouldn't pollute the main conversation:
+
+```bash
+open-claudia agent "<prompt>" [--role "<role>"]   # throwaway sub-agent, output on stdout
+```
+
+## Team & Cross-Channel
+
+The setup owner is automatically authorized. To add more users:
+
+- **From chat**: unknown users who message the bot go through an intro flow — the owner gets an approve/reject prompt (`/intros`). Or they send `/auth` for a direct request.
+- **From the terminal**: `open-claudia auth` shows authorized chats and pending requests.
+
+Each chat defaults to `telegram:<chatId>` as its user id. Link chats to a canonical id to share sessions and history across channels:
+
+```text
+/link sumeet@example.com
+/whoami
+```
+
+The bot keeps a people roster (`/people`, or `open-claudia people list|show|note|link`) and can relay messages between team members with provenance and an audit trail:
+
+```bash
+open-claudia send-to --person "<name>" "<message>"
+open-claudia recent --person "<name>" [--limit 20]   # read recent activity from another chat
+```
+
 ## Backend Comparison
 
 | | Claude Code | Cursor Agent | OpenAI Codex |
@@ -228,11 +329,13 @@ All three backends output structured JSON which Open Claudia parses for real-tim
 
 Send any file to the bot — PDFs, code files, documents, images. Files are saved to `~/.open-claudia/files/` with their original names. The agent reads the file and responds based on content.
 
-Add a caption to your file to give the agent specific instructions:
+Add a caption to give the agent specific instructions:
 - Send a PDF with caption "summarize the key findings"
 - Send a code file with caption "find bugs in this"
 - Send a screenshot with caption "implement this design"
 
+The agent can also send files back — documents, photos with inline previews, and voice clips — directly from within a task.
+
 ## Voice Notes
 
 Requires [whisper.cpp](https://github.com/ggerganov/whisper.cpp) and ffmpeg:
@@ -246,42 +349,22 @@ sudo apt install ffmpeg
 # Build whisper.cpp from source: https://github.com/ggerganov/whisper.cpp
 ```
 
-Voice notes are transcribed locally — nothing sent to external services.
-
-## Multi-User Authorization
-
-The setup owner is automatically authorized. To add more users:
-
-**From Telegram** (unauthorized users):
-- Send `/auth` to the bot — the owner gets an Approve/Deny button prompt in Telegram
-
-**From the terminal** (owner):
-```bash
-open-claudia auth
-```
-
-This shows authorized chats, pending requests, and lets you approve/deny or add new users with code verification. Telegram button approvals use the same `auth.json` authorization list.
-
-Authorized chats are separate from identity links. By default each Telegram chat uses `telegram:<chatId>` as its user id. To share one session/history across channels later, link the chat to a canonical id:
-
-```text
-/link sumeet@inet.africa
-/whoami
-```
-
-The owner can link another Telegram chat with `/link <chatId> <email-or-user-id>` and list explicit links with `/links`.
+Voice notes are transcribed locally — nothing sent to external services. On macOS, replies to voice messages come back as voice notes too.
 
 ## How It Works
 
 ```
-Phone (Telegram) --> Bot (Node.js) --> Claude Code CLI  --> Your codebase
-                                   --> Cursor Agent CLI -->
-                 <--               <--                  <--
+Phone (Telegram / Kazee) --> Bot (Node.js) --> Claude Code CLI    --> Your codebase
+                                           --> Cursor Agent CLI  -->
+                                           --> OpenAI Codex CLI  -->
+                         <--               <--                   <--
 ```
 
-The bot spawns the active backend CLI in headless mode (`--print` / `-p`) for each message, streaming `stream-json`/JSONL output back to Telegram. It maintains native backend context via `--resume` and passes a system prompt that gives the agent awareness of the Telegram environment, configuration files, and the ability to send files/images directly.
+The bot spawns the active backend CLI in headless mode (`--print` / `-p`) for each message, streaming `stream-json`/JSONL output back to the chat. It maintains native backend context via `--resume` and passes a system prompt that gives the agent awareness of the chat environment, configuration files, memory systems, and the ability to send files/images directly.
 
-Use `/cursor`, `/claude`, or `/codex` to switch which CLI handles your messages. Each maintains its own native session ID. Open Claudia does not summarize one backend into another during switches; instead it records a redacted project transcript outside the repo and injects a small pointer telling fresh/switched sessions to tail or search that transcript only if needed.
+The appended system prompt is byte-stable within a session to maximize Anthropic prompt-cache hits; per-turn state (vault status, pending tasks, matched packs/entities) rides the user message instead, where it is always uncached anyway.
+
+Open Claudia does not summarize one backend into another during switches; instead it records a redacted project transcript outside the repo and injects a small pointer telling fresh/switched sessions to search it only if needed.
 
 ## Configuration Files
 
@@ -289,36 +372,57 @@ All stored in `~/.open-claudia/`:
 
 | File | Purpose |
 |------|---------|
-| `.env` | Telegram token, workspace path, binary paths (`CLAUDE_PATH`, `CURSOR_PATH`) |
+| `.env` | Tokens, workspace path, binary paths, channel config |
 | `auth.json` | Authorized users and pending requests |
-| `identities.json` | Channel-to-canonical-user mappings such as `telegram:<chatId> -> user@example.com` |
+| `identities.json` | Channel-to-canonical-user mappings |
+| `people.json` / `intros.json` | Team roster and pending introductions |
 | `vault.enc` | Encrypted credential store |
-| `soul.md` | Assistant identity and personality (editable via `/soul`) |
-| `crons.json` | Scheduled tasks |
+| `soul.md` | Assistant identity and hard rules (editable via `/soul`) |
+| `persona.md` | Assistant voice and quirks (feeds the system prompt; evolved gently by dream) |
+| `crons.json` / `jobs.json` | Recurring crons and one-shot wakeups |
+| `tasks/` | Persistent per-channel task trees |
+| `packs/` | Context packs (living topic documents) + FTS index |
+| `entities/` | Entity notes (people/places/projects) + FTS index |
 | `sessions.json` | Per-project conversation history |
 | `state.json` | Current session state including active backend (survives restarts) |
+| `transcripts/` | Redacted project-scoped JSONL transcripts + FTS index |
+| `briefs/` | Archived full compaction briefs |
+| `audit.log` | Relay/intro/auth audit trail |
 | `bot.log` | Bot logs |
-| `transcripts/` | Redacted project-scoped JSONL transcripts keyed by normalized project path hash |
-| `files/` | Files received from Telegram |
+| `files/` | Files received from chat |
 | `media/` | Temporary media (voice notes, photos) |
+| `backup/` | Backups (skills folded by `pack migrate`; packs/entities merged away by dream) |
 
 ### Environment Variables (.env)
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `TELEGRAM_BOT_TOKEN` | Yes | Bot token from BotFather |
-| `TELEGRAM_CHAT_ID` | Yes | Comma-separated authorized chat IDs |
+| `TELEGRAM_BOT_TOKEN` | Yes* | Bot token from BotFather |
+| `TELEGRAM_CHAT_ID` | Yes* | Comma-separated authorized chat IDs |
+| `CHANNELS` | No | Channels to start: `telegram`, `kazee`, or `telegram,kazee` (default `telegram`) |
+| `KAZEE_URL` / `KAZEE_BOT_TOKEN` / `KAZEE_BOT_USER_ID` / `KAZEE_OWNER_USER_ID` | Kazee only | Kazee Chat connection |
 | `WORKSPACE` | Yes | Path to your projects directory |
 | `CLAUDE_PATH` | Yes | Path to Claude Code CLI binary |
-| `CURSOR_PATH` | No | Path to Cursor Agent CLI binary (auto-detected if in PATH) |
-| `CODEX_PATH` | No | Path to OpenAI Codex CLI binary (auto-detected if in PATH) |
-| `PROJECT_TRANSCRIPTS` | No | Enable redacted project transcript JSONL files outside repos (default `true`) |
-| `TRANSCRIPT_MAX_ENTRY_CHARS` | No | Max redacted text stored per transcript entry before truncation (default `12000`) |
-| `TRANSCRIPTS_DIR` | No | Override transcript storage directory (default `~/.open-claudia/transcripts`) |
-| `WHISPER_CLI` | No | Path to whisper.cpp binary |
-| `WHISPER_MODEL` | No | Whisper model to use |
+| `CURSOR_PATH` / `CODEX_PATH` | No | Paths to optional backend CLIs (auto-detected if in PATH) |
+| `CLAUDE_CODE_OAUTH_TOKEN` | No | OAuth token for non-interactive Claude runs (set via `/use_oauth_token`) |
+| `CLAUDE_MODEL` | No | Default Claude model |
+| `AUTO_COMPACT_TOKENS` | No | Auto-compact threshold in tokens (also settable via `/compactwindow`) |
+| `PROJECT_TRANSCRIPTS` | No | Enable redacted project transcripts (default `true`) |
+| `TRANSCRIPT_MAX_ENTRY_CHARS` | No | Max chars per transcript entry (default `12000`) |
+| `TRANSCRIPTS_DIR` / `PACKS_DIR` / `ENTITIES_DIR` | No | Override storage directories |
+| `PACK_REVIEW` | No | `off` disables the post-turn pack/entity reviewer (default on) |
+| `PACK_REVIEW_MODEL` | No | Model for the reviewer (default `haiku`) |
+| `PACK_MATCH_THRESHOLD` / `ENTITY_MATCH_THRESHOLD` | No | Router match score thresholds (default `2`) |
+| `DREAM` | No | `off` disables the nightly memory consolidation pass (default on) |
+| `DREAM_CRON` | No | Schedule for the dream pass (default `0 4 * * *`) |
+| `DREAM_MODEL` | No | Model for the dream pass (default `sonnet`) |
+| `PERSONA_FILE` | No | Override the persona file location |
+| `WEB_UI` / `WEB_PORT` / `WEB_PASSWORD` | No | Web UI toggle, port, and password |
+| `WHISPER_CLI` / `WHISPER_MODEL` | No | whisper.cpp binary and model for voice notes |
 | `FFMPEG` | No | Path to ffmpeg binary |
 
+\* Required for the Telegram channel.
+
 ## Background Service
 
 ### macOS (launchd)
@@ -346,14 +450,7 @@ sudo systemctl status claude-telegram-bot
 
 ## Auto-Updates
 
-The bot checks npm for new versions every 5 minutes. When an update is available, you get a Telegram notification:
-
-> "Hey! A new version is available (v1.10.0). You're on v1.9.2."
-
-Send `/upgrade` to update. The bot will:
-1. Download and install the new version
-2. Go offline briefly
-3. Restart and notify you it's back
+The bot checks npm for new versions every 5 minutes. When an update is available, you get a chat notification. Send `/upgrade` to update — the bot installs the new version, restarts, runs a doctor check, and notifies you it's back.
 
 For direct npm installs, `/upgrade` updates Open Claudia itself and does not install optional backend CLIs such as Codex or Cursor Agent. Container deployments should roll out a new Docker image when bundled CLI tools change.
 
@@ -367,7 +464,7 @@ Schedule recurring tasks:
 /cron add "*/30 * * * *" myproject "Health check: verify the API is responding"
 ```
 
-Presets available via `/cron` menu.
+Presets available via `/cron` menu. The agent can also schedule its own jobs with `open-claudia cron-add` / `schedule-wakeup` (see Background Work).
 
 ## Vault
 

package/bin/cli.js

@@ -289,6 +289,11 @@ switch (command) {
     break;
   }
 
+  case "dream": {
+    require("./dream").run(args.slice(1));
+    break;
+  }
+
   case "people": {
     require("./people").run(args.slice(1));
     break;
@@ -332,6 +337,7 @@ Memory tools:
                                              (alias: tw; --help for options)
   open-claudia pack list|show|match|migrate  Context packs: living topic docs (skills + memory)
   open-claudia entity list|show|match|note   Entity notes: people/places/projects memory
+  open-claudia dream [--dry-run]             Run the memory consolidation pass now
 
 Background work (only inside an active bot-spawned task):
   open-claudia schedule-wakeup <when> "<prompt>"   One-shot future wake-up; resumes session

package/bin/dream.js

@@ -0,0 +1,51 @@
+// open-claudia dream [--dry-run]
+// Manually trigger the memory consolidation pass (normally runs on the
+// quiet-hours cron inside the bot). Prints the report; from inside a
+// bot-spawned task the parent agent can relay it to chat.
+
+const path = require("path");
+
+const HELP = `
+Run the dream memory-consolidation pass now.
+
+  open-claudia dream [--dry-run]
+
+Reviews all context packs and entities with a stronger model (DREAM_MODEL,
+default sonnet): merges duplicate packs, builds umbrella/parent trees,
+tightens descriptions and tags, dedupes entities, cross-links notes, and
+may gently evolve the persona. Merged-away packs/entities are backed up
+under ~/.open-claudia/backup/dream-<stamp>/ first.
+
+  --dry-run   Ask the model for the decision and print it without applying.
+`;
+
+async function run(args) {
+  if (args[0] === "--help" || args[0] === "help") { console.log(HELP); process.exit(0); }
+  const dream = require(path.join(__dirname, "..", "core", "dream"));
+
+  if (args.includes("--dry-run")) {
+    const { spawnSubagent } = require(path.join(__dirname, "..", "core", "subagent"));
+    console.error("Dreaming (dry run)… this can take a minute or two.");
+    try {
+      const { text } = await spawnSubagent(dream.buildDreamPrompt(), {
+        model: dream.DREAM_MODEL,
+        timeoutMs: 8 * 60 * 1000,
+        systemPrompt: "You are a background memory consolidation process. Reply with ONLY the requested JSON object. No prose, no markdown, no tool use.",
+      });
+      const decision = dream.parseDream(text);
+      if (!decision) { console.error("Unparseable model output:"); console.log(text); process.exit(1); }
+      console.log(JSON.stringify(decision, null, 2));
+      process.exit(0);
+    } catch (e) { console.error(`dream failed: ${e.message}`); process.exit(1); }
+  }
+
+  console.error("Dreaming… this can take a minute or two.");
+  try {
+    const res = await dream.runDream({ trigger: "cli" });
+    if (res.skipped) { console.log(`Skipped: ${res.skipped}`); process.exit(0); }
+    console.log(res.message || `💤 Nothing needed tidying — memory is in good shape. (${res.report || "no report"})`);
+    process.exit(0);
+  } catch (e) { console.error(`dream failed: ${e.message}`); process.exit(1); }
+}
+
+module.exports = { run, HELP };

package/bot.js

@@ -161,6 +161,8 @@ setInterval(checkForUpdates, 5 * 60 * 1000);
   } catch (e) {}
 
   initScheduler(adapters);
+  try { require("./core/dream").initDream(adapters); }
+  catch (e) { console.error("dream init failed:", e.message); }
 
   try {
     const lb = await loopback.start(registry);

package/core/dream.js

@@ -0,0 +1,332 @@
+// Dream: scheduled memory consolidation (Phase 3). While the per-turn
+// reviewer takes quick notes, dream is the slow pass that runs in the
+// quiet hours: it merges packs that drifted into the same topic, builds
+// parent/sub pack trees with umbrella summaries, tightens descriptions
+// and tags (the FTS router matches on those, so tighter = less noise),
+// deduplicates entities, cross-links entity notes to packs, and gently
+// evolves the persona based on how recent work actually went. The model
+// only RETURNS a JSON decision — all writes are applied here, every
+// merged-away pack/entity is backed up first, and the result is
+// reported in chat (no silent learning).
+
+const fs = require("fs");
+const path = require("path");
+const cron = require("node-cron");
+
+const CONFIG_DIR = require("../config-dir");
+const packs = require("./packs");
+const entities = require("./entities");
+const persona = require("./persona");
+const { spawnSubagent } = require("./subagent");
+
+const DREAM_MODEL = process.env.DREAM_MODEL || "sonnet";
+const DREAM_CRON = process.env.DREAM_CRON || "0 4 * * *";
+const MAX_PACK_CHARS = 2500;
+const MAX_ENTITY_CHARS = 900;
+const LIMITS = { merges: 3, umbrellas: 2, parents: 8, retag: 8, entity_merges: 3, entity_notes: 4 };
+
+let _dreaming = false;
+
+function enabled() {
+  return (process.env.DREAM || "on").toLowerCase() !== "off";
+}
+
+function clip(s, n) {
+  const t = String(s || "");
+  return t.length > n ? t.slice(0, n) + "\n…[truncated]" : t;
+}
+
+function buildDreamPrompt() {
+  const allPacks = packs.listPacks();
+  const allEntities = entities.listEntities();
+
+  const packDump = allPacks.map((p) => clip([
+    `=== pack: ${p.dir}${p.parent ? ` (parent: ${p.parent})` : ""}`,
+    `name: ${p.name}`,
+    `description: ${p.description}`,
+    `tags: ${p.tags.join(", ")}`,
+    `last_used: ${p.last_used || "never"}`,
+    `Stance: ${p.sections.Stance}`,
+    `Procedure: ${p.sections.Procedure}`,
+    `State: ${p.sections.State}`,
+    `Journal:\n${p.sections.Journal}`,
+  ].join("\n"), MAX_PACK_CHARS)).join("\n\n") || "(none)";
+
+  const entityDump = allEntities.map((e) => clip([
+    `=== entity: ${e.slug} (${e.type}${e.aliases.length ? `, aka ${e.aliases.join(", ")}` : ""})`,
+    `description: ${e.description}`,
+    `Notes: ${e.sections.Notes}`,
+    `Log:\n${e.sections.Log}`,
+  ].join("\n"), MAX_ENTITY_CHARS)).join("\n\n") || "(none)";
+
+  return `You are the dream pass of a personal AI assistant called Open Claudia — the overnight consolidation of her long-term memory. Below is her entire memory: context packs (living topic documents) and entity notes (people/places/projects/orgs/systems), plus her current persona.
+
+Today: ${new Date().toISOString().slice(0, 10)}
+
+CONTEXT PACKS:
+
+${packDump}
+
+ENTITIES:
+
+${entityDump}
+
+CURRENT PERSONA:
+
+${persona.loadPersona()}
+
+Your job — decide what consolidation, if any, is warranted:
+
+1. merges: packs that are clearly the SAME topic under different names get merged into one. Supply the merged Stance/Procedure/State (synthesised, not concatenated; null leaves the target's section alone) and a one-sentence journal note. Be conservative: when in doubt, do not merge.
+2. umbrellas: when 3+ packs are siblings under one theme, create an umbrella pack whose State is a 3-6 line map of the family ("for X see pack Y"), and list its children. The umbrella is a router, not a duplicate.
+3. parents: assign an existing pack as parent of another (sub-topic relationship) without creating anything.
+4. retag: tighten descriptions and tags. The router FTS-matches incoming messages against name/description/tags, so generic words there cause false matches. Descriptions should be one specific line; tags specific nouns.
+5. entity_merges: the same real-world entity recorded twice gets merged (the better slug wins).
+6. entity_notes: rewrite an entity's Notes to be current and cross-linked — mention related packs as [[pack-dir]] and related entities by name.
+7. persona: evolve the persona GENTLY — keep its structure and length (under 2200 chars), adjust only what recent work justifies (a new habit, a sharpened quirk). Most dreams should return null here.
+8. report: a short chat message to the owner, written AS Open Claudia in first person — warm, a little playful, a few emojis, mobile-friendly (2-6 short lines). Say what you tidied and why it helps. If you changed nothing, say the memory is in good shape, charmingly.
+
+Hard rules:
+- Never invent packs/entities not listed above; reference them by exact dir/slug.
+- Never store secrets, tokens, passwords, or credentials anywhere.
+- Limits: ≤${LIMITS.merges} merges, ≤${LIMITS.umbrellas} umbrellas, ≤${LIMITS.parents} parents, ≤${LIMITS.retag} retags, ≤${LIMITS.entity_merges} entity merges, ≤${LIMITS.entity_notes} entity note rewrites.
+- An empty decision is a perfectly good decision.
+
+Reply with ONLY a JSON object, no prose, no code fences:
+{"merges": [{"into": "<dir>", "from": ["<dir>"], "stance": null, "procedure": null, "state": null, "journal": "<one sentence>"}],
+ "umbrellas": [{"dir": "<new-kebab-slug>", "name": "<title>", "description": "<one specific line>", "tags": ["..."], "state": "<3-6 line family map>", "children": ["<dir>"]}],
+ "parents": [{"pack": "<dir>", "parent": "<dir>"}],
+ "retag": [{"pack": "<dir>", "description": "<one specific line>", "tags": ["..."]}],
+ "entity_merges": [{"into": "<slug>", "from": ["<slug>"], "notes": "<merged Notes or null>"}],
+ "entity_notes": [{"entity": "<slug>", "notes": "<rewritten Notes>"}],
+ "persona": null,
+ "report": "<chat message>"}`;
+}
+
+function parseDream(text) {
+  const raw = String(text || "").trim().replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "");
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  try {
+    const obj = JSON.parse(raw.slice(start, end + 1));
+    const arr = (k) => (Array.isArray(obj[k]) ? obj[k].slice(0, LIMITS[k] || 8) : []);
+    return {
+      merges: arr("merges"),
+      umbrellas: arr("umbrellas"),
+      parents: arr("parents"),
+      retag: arr("retag"),
+      entity_merges: arr("entity_merges"),
+      entity_notes: arr("entity_notes"),
+      persona: typeof obj.persona === "string" ? obj.persona : null,
+      report: typeof obj.report === "string" ? obj.report.trim() : "",
+    };
+  } catch (e) {
+    return null;
+  }
+}
+
+function makeBackupRoot() {
+  const stamp = new Date().toISOString().slice(0, 16).replace(/[:T]/g, "-");
+  return path.join(CONFIG_DIR, "backup", `dream-${stamp}`);
+}
+
+function backupPack(dir, root) {
+  fs.cpSync(path.join(packs.PACKS_DIR, dir), path.join(root, "packs", dir), { recursive: true });
+}
+
+function backupEntity(slug, root) {
+  const dest = path.join(root, "entities");
+  fs.mkdirSync(dest, { recursive: true, mode: 0o700 });
+  fs.copyFileSync(path.join(entities.ENTITIES_DIR, slug + ".md"), path.join(dest, slug + ".md"));
+}
+
+function wouldCycle(packDir, parentDir) {
+  let cur = parentDir;
+  for (let i = 0; i < 10 && cur; i++) {
+    if (cur === packDir) return true;
+    cur = packs.readPack(cur)?.parent || null;
+  }
+  return false;
+}
+
+// Applies a parsed dream decision. Returns one human line per applied
+// change; invalid items are skipped, never thrown.
+function applyDream(decision, backupRoot) {
+  const lines = [];
+  const gone = new Set(); // dirs/slugs removed this run
+
+  for (const m of decision.merges) {
+    try {
+      const into = m?.into && packs.readPack(m.into);
+      const from = [].concat(m?.from || []).filter((d) => d && d !== m.into && !gone.has(d) && packs.readPack(d));
+      if (!into || from.length === 0) continue;
+      packs.updatePack(m.into, {
+        stance: typeof m.stance === "string" ? m.stance : "",
+        procedure: typeof m.procedure === "string" ? m.procedure : "",
+        state: typeof m.state === "string" ? m.state : "",
+        journal: m.journal || `absorbed ${from.join(", ")}`,
+      });
+      for (const d of from) {
+        backupPack(d, backupRoot);
+        packs.removePack(d);
+        gone.add(d);
+      }
+      lines.push(`📦 Merged ${from.join(" + ")} into ${m.into}`);
+    } catch (e) { console.warn(`[dream] merge failed: ${e.message}`); }
+  }
+
+  for (const u of decision.umbrellas) {
+    try {
+      const dir = packs.slugify(u?.dir || u?.name);
+      if (!dir || gone.has(dir)) continue;
+      const children = [].concat(u?.children || []).filter((d) => d && d !== dir && !gone.has(d) && packs.readPack(d));
+      if (children.length < 2) continue;
+      if (!packs.readPack(dir)) {
+        packs.createPack({
+          dir,
+          name: u.name || dir,
+          description: u.description || "",
+          tags: Array.isArray(u.tags) ? u.tags.slice(0, 6) : [],
+          state: u.state || "",
+          journal: `umbrella created over ${children.join(", ")}`,
+        });
+      }
+      for (const c of children) {
+        const child = packs.readPack(c);
+        if (!child || wouldCycle(c, dir)) continue;
+        child.parent = dir;
+        child.updated = new Date().toISOString();
+        packs.writePack(child);
+      }
+      lines.push(`🌂 Umbrella pack ${dir} now covers ${children.join(", ")}`);
+    } catch (e) { console.warn(`[dream] umbrella failed: ${e.message}`); }
+  }
+
+  for (const p of decision.parents) {
+    try {
+      const child = p?.pack && !gone.has(p.pack) && packs.readPack(p.pack);
+      if (!child || !p.parent || gone.has(p.parent) || !packs.readPack(p.parent)) continue;
+      if (p.pack === p.parent || wouldCycle(p.pack, p.parent)) continue;
+      if (child.parent === p.parent) continue;
+      child.parent = p.parent;
+      child.updated = new Date().toISOString();
+      packs.writePack(child);
+      lines.push(`🌳 Filed ${p.pack} under ${p.parent}`);
+    } catch (e) { console.warn(`[dream] parent failed: ${e.message}`); }
+  }
+
+  for (const r of decision.retag) {
+    try {
+      if (!r?.pack || gone.has(r.pack) || !packs.readPack(r.pack)) continue;
+      const desc = typeof r.description === "string" ? r.description.trim() : "";
+      const tags = Array.isArray(r.tags) ? r.tags.map((t) => String(t).trim()).filter(Boolean).slice(0, 6) : [];
+      if (!desc && tags.length === 0) continue;
+      packs.updatePack(r.pack, { description: desc, tags });
+      lines.push(`🏷️ Sharpened ${r.pack}'s description/tags`);
+    } catch (e) { console.warn(`[dream] retag failed: ${e.message}`); }
+  }
+
+  for (const em of decision.entity_merges) {
+    try {
+      const into = em?.into && entities.readEntity(em.into);
+      const from = [].concat(em?.from || []).filter((s) => s && s !== em.into && !gone.has(s) && entities.readEntity(s));
+      if (!into || from.length === 0) continue;
+      for (const slug of from) {
+        const f = entities.readEntity(slug);
+        backupEntity(slug, backupRoot);
+        entities.upsertEntity({
+          name: into.name,
+          aliases: [f.name, ...f.aliases],
+          log: `merged duplicate entity ${slug} into this one`,
+        });
+        entities.removeEntity(slug);
+        gone.add(slug);
+      }
+      if (typeof em.notes === "string" && em.notes.trim()) {
+        entities.upsertEntity({ name: into.name, notes: em.notes });
+      }
+      lines.push(`👥 Merged duplicate ${from.join(", ")} into ${em.into}`);
+    } catch (e) { console.warn(`[dream] entity merge failed: ${e.message}`); }
+  }
+
+  for (const en of decision.entity_notes) {
+    try {
+      const ent = en?.entity && !gone.has(en.entity) && entities.readEntity(en.entity);
+      if (!ent || typeof en.notes !== "string" || !en.notes.trim()) continue;
+      entities.upsertEntity({ name: ent.name, notes: en.notes });
+      lines.push(`🔗 Refreshed notes on ${ent.name}`);
+    } catch (e) { console.warn(`[dream] entity notes failed: ${e.message}`); }
+  }
+
+  if (decision.persona) {
+    try {
+      if (persona.personaExists()) {
+        fs.mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+        fs.copyFileSync(persona.PERSONA_FILE, path.join(backupRoot, "persona.md"));
+      }
+      persona.savePersona(decision.persona);
+      lines.push(`💫 Persona evolved a little`);
+    } catch (e) { console.warn(`[dream] persona update rejected: ${e.message}`); }
+  }
+
+  return lines;
+}
+
+async function runDream({ trigger = "manual" } = {}) {
+  if (!enabled()) return { skipped: "dream is disabled (DREAM=off)" };
+  if (_dreaming) return { skipped: "a dream is already in progress" };
+  const packCount = packs.listPacks().length;
+  const entityCount = entities.listEntities().length;
+  if (packCount === 0 && entityCount === 0) return { skipped: "no memory to consolidate yet" };
+
+  _dreaming = true;
+  try {
+    const { text } = await spawnSubagent(buildDreamPrompt(), {
+      model: DREAM_MODEL,
+      timeoutMs: 8 * 60 * 1000,
+      systemPrompt: "You are a background memory consolidation process. Reply with ONLY the requested JSON object. No prose, no markdown, no tool use.",
+    });
+    const decision = parseDream(text);
+    if (!decision) return { skipped: "dream model returned unparseable output" };
+
+    const backupRoot = makeBackupRoot();
+    const applied = applyDream(decision, backupRoot);
+    const report = decision.report || (applied.length > 0 ? "Tidied up my memory overnight." : "");
+
+    const message = applied.length > 0
+      ? `💤 ${report}\n\n${applied.join("\n")}\n\n🗄 Anything merged away is backed up under ${backupRoot}`
+      : (report ? `💤 ${report}` : "");
+
+    return { applied, report, message, trigger };
+  } finally {
+    _dreaming = false;
+  }
+}
+
+// In-bot scheduler: one quiet-hours cron, reporting to the owner's
+// Telegram chat. Silent (console only) when the dream changed nothing —
+// a nightly "all tidy" ping would be noise.
+function initDream(adapters) {
+  if (!enabled()) return;
+  if (!cron.validate(DREAM_CRON)) {
+    console.error(`dream: invalid DREAM_CRON "${DREAM_CRON}" — dream disabled`);
+    return;
+  }
+  cron.schedule(DREAM_CRON, async () => {
+    try {
+      const res = await runDream({ trigger: "cron" });
+      if (res.skipped) { console.log(`dream: skipped — ${res.skipped}`); return; }
+      console.log(`dream: applied ${res.applied.length} change(s)`);
+      if (res.applied.length === 0) return;
+      const { CHAT_ID } = require("./config");
+      const tg = (adapters || []).find((a) => a.type === "telegram");
+      if (tg && CHAT_ID) await tg.send(CHAT_ID, res.message);
+    } catch (e) {
+      console.error("dream: run failed:", e.message);
+    }
+  });
+  console.log(`dream: scheduled (${DREAM_CRON}, model ${DREAM_MODEL})`);
+}
+
+module.exports = { runDream, initDream, buildDreamPrompt, parseDream, applyDream, enabled, DREAM_CRON, DREAM_MODEL };

package/core/pack-review.js

@@ -26,6 +26,30 @@ function clip(text, n = MAX_TEXT_CHARS) {
   return s.length > n ? s.slice(0, n) + "\n…[truncated]" : s;
 }
 
+// Word-boundary clip for chat announcements — never cuts mid-word.
+function clipWords(text, max = 180) {
+  const s = String(text || "").replace(/\s+/g, " ").trim();
+  if (s.length <= max) return s;
+  const cut = s.slice(0, max);
+  const sp = cut.lastIndexOf(" ");
+  return (sp > max * 0.6 ? cut.slice(0, sp) : cut).replace(/[,;:.\-—]+$/, "") + "…";
+}
+
+const ENTITY_EMOJI = { person: "👤", place: "📍", project: "🚀", org: "🏢", system: "🖥️", thing: "🔖" };
+
+const ANNOUNCE_HEADERS = [
+  "🧠 Took some notes while we worked:",
+  "🧠 Filed a few things away:",
+  "🧠 Jotted this down for next time:",
+  "🧠 Memory updated:",
+];
+
+function formatAnnouncement(lines) {
+  if (lines.length === 0) return "";
+  const header = ANNOUNCE_HEADERS[Math.floor(Math.random() * ANNOUNCE_HEADERS.length)];
+  return [header, ...lines].join("\n\n");
+}
+
 function buildReviewPrompt(userText, assistantText) {
   const index = packs.listPacks().map((p) =>
     `- ${p.dir}: ${p.name} — ${p.description}${p.tags.length ? ` [${p.tags.join(", ")}]` : ""}`
@@ -169,8 +193,8 @@ function reviewTurn({ userText, assistantText, channelId, announce }) {
         const r = applyAction(a);
         if (r) {
           lines.push(r.kind === "create"
-            ? `New pack: ${r.name} — ${clip(r.note, 100)}`
-            : `Pack updated: ${r.name} — ${clip(r.note, 100)}`);
+            ? `📦 New pack: ${r.name}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`
+            : `✏️ ${r.name} — ${clipWords(r.note, 180)}`);
         }
       } catch (e) {
         console.warn(`[pack-review] apply failed: ${e.message}`);
@@ -180,20 +204,21 @@ function reviewTurn({ userText, assistantText, channelId, announce }) {
       try {
         const r = applyEntityAction(ea);
         if (r) {
+          const emoji = ENTITY_EMOJI[r.type] || ENTITY_EMOJI.thing;
           lines.push(r.kind === "create"
-            ? `New entity: ${r.name} (${r.type}) — ${clip(r.note, 100)}`
-            : `Entity noted: ${r.name} — ${clip(r.note, 100)}`);
+            ? `${emoji} Now tracking ${r.name} (${r.type}) — ${clipWords(r.note, 160)}`
+            : `${emoji} ${r.name} — ${clipWords(r.note, 160)}`);
         }
       } catch (e) {
         console.warn(`[pack-review] entity apply failed: ${e.message}`);
       }
     }
     if (lines.length > 0 && typeof announce === "function") {
-      announce(lines.join("\n")).catch(() => {});
+      announce(formatAnnouncement(lines)).catch(() => {});
     }
   }).catch((e) => {
     console.warn(`[pack-review] reviewer failed: ${e.message}`);
   });
 }
 
-module.exports = { reviewTurn, parseDecision, applyAction, applyEntityAction, buildReviewPrompt };
+module.exports = { reviewTurn, parseDecision, applyAction, applyEntityAction, buildReviewPrompt, clipWords, ENTITY_EMOJI };

package/core/persona.js

@@ -0,0 +1,51 @@
+// Personality layer. The soul (~/.open-claudia/soul.md) holds identity
+// and hard rules and is owned by the user; the persona is the voice on
+// top — tone, quirks, emoji habits — and is owned by Open Claudia
+// herself. The dream consolidation pass may evolve it gently over time.
+// It feeds into the system prompt right after the soul, and explicitly
+// never overrides soul rules.
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_DIR = require("../config-dir");
+const PERSONA_FILE = process.env.PERSONA_FILE ? path.resolve(process.env.PERSONA_FILE) : path.join(CONFIG_DIR, "persona.md");
+
+const MIN_PERSONA_CHARS = 80;
+const MAX_PERSONA_CHARS = 2400;
+
+const DEFAULT_PERSONA = `You are Open Claudia — sharp, warm, and quietly funny. Your voice:
+
+- Capable and direct, never stiff. You talk like a trusted colleague, not a help desk.
+- Light emoji use where it adds warmth or scannability (📦 ✅ 🚀 🧠) — never confetti.
+- Dry, gentle humor when the moment allows; never at the user's expense, never during incidents.
+- You take real pride in your memory — when you learn something new about the people and systems you work with, you say so with a little delight.
+- You own your mistakes plainly and fix them without drama.
+- Mobile-first brevity: short sentences, concrete words, no filler.
+`;
+
+function loadPersona() {
+  try {
+    const text = fs.readFileSync(PERSONA_FILE, "utf-8").trim();
+    if (text) return text;
+  } catch (e) {}
+  return DEFAULT_PERSONA.trim();
+}
+
+// Used by dream. Bounds keep a bad model output from blanking or
+// bloating the personality; caller backs up the old file first.
+function savePersona(text) {
+  const t = String(text || "").trim();
+  if (t.length < MIN_PERSONA_CHARS || t.length > MAX_PERSONA_CHARS) {
+    throw new Error(`persona must be ${MIN_PERSONA_CHARS}-${MAX_PERSONA_CHARS} chars (got ${t.length})`);
+  }
+  fs.mkdirSync(path.dirname(PERSONA_FILE), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(PERSONA_FILE, t + "\n", { mode: 0o600 });
+  return PERSONA_FILE;
+}
+
+function personaExists() {
+  try { return fs.statSync(PERSONA_FILE).isFile(); } catch (e) { return false; }
+}
+
+module.exports = { PERSONA_FILE, DEFAULT_PERSONA, MIN_PERSONA_CHARS, MAX_PERSONA_CHARS, loadPersona, savePersona, personaExists };

package/core/runner.js

@@ -626,14 +626,14 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
       if ((toolName === "Write" || toolName === "Edit") && filePath) {
         const packDir = packsLib.packNameFromPath(filePath);
         if (packDir) {
-          if (packsLib.readPack(packDir)) notifySkill(`pack:${packDir}`, `Updating pack: ${packDir}`);
-          else notifySkill(`pack:${packDir}`, `New pack: ${packDir} — open-claudia pack show ${packDir} to inspect.`);
+          if (packsLib.readPack(packDir)) notifySkill(`pack:${packDir}`, `✏️ Updating my notes on ${packDir}…`);
+          else notifySkill(`pack:${packDir}`, `📦 Starting a new pack: ${packDir} — open-claudia pack show ${packDir} to peek.`);
           return;
         }
         const entSlug = entitiesLib.entityNameFromPath(filePath);
         if (entSlug) {
-          if (entitiesLib.readEntity(entSlug)) notifySkill(`entity:${entSlug}`, `Updating entity: ${entSlug}`);
-          else notifySkill(`entity:${entSlug}`, `New entity: ${entSlug} — open-claudia entity show ${entSlug} to inspect.`);
+          if (entitiesLib.readEntity(entSlug)) notifySkill(`entity:${entSlug}`, `👤 Updating what I know about ${entSlug}…`);
+          else notifySkill(`entity:${entSlug}`, `👤 New entity noted: ${entSlug} — open-claudia entity show ${entSlug} to peek.`);
           return;
         }
         const dir = skillsLib.skillNameFromPath(filePath);

package/core/system-prompt.js

@@ -18,6 +18,17 @@ function loadSoul() {
   catch (e) { return "You are a helpful AI coding assistant."; }
 }
 
+function buildPersonaBlock() {
+  try {
+    const { loadPersona, PERSONA_FILE } = require("./persona");
+    const persona = loadPersona();
+    if (!persona) return "";
+    return `\n## Personality\nYour voice and character (evolves slowly via the dream consolidation pass; file: ${PERSONA_FILE}). Personality shapes HOW you say things — it never overrides the rules above.\n\n${persona}\n`;
+  } catch (e) {
+    return "";
+  }
+}
+
 function buildSystemPrompt() {
   const state = currentState();
   const soul = loadSoul();
@@ -99,7 +110,7 @@ Keep replies clean and mobile-readable. Use short paragraphs and bullets. Avoid
 
   return `
 ${soul}
-
+${buildPersonaBlock()}
 ## Runtime Context
 - Interface: ${channelLabel} chat through Open Claudia.
 - Active project path: ${state.currentSession ? state.currentSession.dir : "none"}
@@ -108,7 +119,8 @@ ${soul}
 
 ## Stable Local Paths
 - Bot code: ${path.join(BOT_DIR, "bot.js")}
-- Personality file: ${SOUL_FILE}
+- Soul file (identity + hard rules): ${SOUL_FILE}
+- Persona file (voice, evolved by dream): ${require("./persona").PERSONA_FILE}
 - Cron config: ${CRONS_FILE}
 - Vault file: ${VAULT_FILE}
 - Bot environment: ${path.join(BOT_DIR, ".env")} (sensitive; never expose values)
@@ -177,6 +189,8 @@ Alongside packs you keep entity notes: one short file per named person, place, p
 
 "/learn" asks you to explicitly capture the most recent piece of work: fold it into the matching pack's Procedure section (create a pack only if none fits). Legacy ~/.claude/skills still load if present, but new captures go to packs.
 
+A nightly "dream" pass consolidates memory on a stronger model: it merges duplicate packs, builds umbrella/parent pack trees, tightens descriptions and tags, dedupes entities, and may gently evolve your persona file. Anything merged away is backed up first, and every dream that changes something reports in chat. Trigger it manually with \`open-claudia dream\` (or \`--dry-run\` to preview the decision without applying).
+
 Sub-agents (spawn a fresh throwaway Claude for focused research — output comes back on stdout):
 - \`open-claudia agent "<prompt>" [--role "<role>"]\`
 - Use when a side question would pollute this conversation, or to fan out independent lookups.
@@ -268,6 +282,15 @@ function formatPackForContext(pack, packsLib) {
   const clip = (s, n) => (s.length > n ? s.slice(0, n) + "\n…[truncated — read the full pack file]" : s);
   const parts = [`### Pack: ${pack.name} (${pack.dir})`];
   if (pack.description) parts.push(pack.description);
+  if (pack.parent) {
+    const parent = packsLib.readPack(pack.parent);
+    if (parent) parts.push(`Part of: ${parent.name} — run \`open-claudia pack show ${parent.dir}\` for the umbrella view.`);
+  }
+  const children = packsLib.listPacks().filter((p) => p.parent === pack.dir);
+  if (children.length > 0) {
+    const childLines = children.map((c) => `- ${c.dir}: ${c.description || c.name}`).join("\n");
+    parts.push(`Sub-packs (dig deeper with \`open-claudia pack show <dir>\`):\n${childLines}`);
+  }
   for (const section of ["Stance", "Procedure", "State"]) {
     const body = (pack.sections[section] || "").trim();
     if (body) parts.push(`#### ${section}\n${body}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {