@inetafrica/open-claudia 2.4.2 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 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.
+  - **Post-turn reviewer** (`core/pack-review.js`): after every substantial turn (>400 chars) a haiku subagent reviews the exchange and returns a strict-JSON decision — update a pack (journal line + State rewrite), create one for a new durable topic, or nothing. The model returns JSON only; all file writes are applied by bot code, so the reviewer needs no tools or permissions. Active by default (most working turns produce at least a journal line), `PACK_REVIEW=off` to disable, `PACK_REVIEW_MODEL` to change model. Every applied mutation is announced in chat (one line) — no silent learning.
+  - **In-turn writes announced**: `Write`/`Edit` aimed at a `PACK.md` triggers `Updating pack: X` / `New pack: X` chat lines, same as skills did.
+  - **`open-claudia pack list|show|match|migrate|remove|reindex`**: inspect packs, debug the router (`match` shows scores), and `pack migrate` folds existing `~/.claude/skills` into packs (body → Procedure section) with originals backed up to `~/.open-claudia/backup/skills-pre-packs/` — run it once after upgrading.
+  - `spawnSubagent` learned `model` and `systemPrompt` overrides (used by the reviewer; also available to `open-claudia agent`).
+- **Entity memory (phase 2): contextual notes on people, places, projects, orgs and systems.** Each entity is a short file at `~/.open-claudia/entities/<slug>.md` — frontmatter (name, type, aliases, description) plus Notes (current truth, replaced wholesale) and Log (dated one-line observations, capped at 40).
+  - **Same router, second store** (`core/entities.js`): incoming messages are FTS5-matched against entities with the pack scoring scheme, except the strong fields are name/aliases — a single mention of "Emmanuel" injects the Emmanuel note, but one stray body word can't. Injected as a `## Known entities` block beside packs, deduped per (channel, session, entity-version).
+  - **Same reviewer, one call**: the post-turn haiku reviewer now also returns an `entities` array — it creates or updates entity notes (merge semantics: aliases union, Notes replace, Log appends) in the same pass that maintains packs, at no extra subagent cost. Entity changes are announced in chat like pack changes.
+  - **`open-claudia entity list|show|match|note|remove|reindex`**: inspect the store, debug the router, or jot a note manually (`entity note Emmanuel "owns inet-central org cleanup" --type person`).
+  - Direct `Write`/`Edit` to an entity file announces `Updating entity: X` / `New entity: X`, same as packs.
+  - This completes phase 2 of the packs system; "dream" consolidation (pack merging + skill trees + entity linking) is next.
+
 ## v2.4.2
 - Fix replies losing everything written before tool calls. The backend's final `result` event carries only the LAST text segment of a turn, but the stream parser assigned it over the accumulated `assistantText` — so a turn shaped "long explanation → tool calls → short closing line" delivered only the closing line, which read as nonsense without its context. `evt.result` is now a fallback used only when nothing was accumulated (some Cursor turns). Fixed in both `runClaude` and the auxiliary runner.
 

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

@@ -274,11 +274,26 @@ switch (command) {
     break;
   }
 
+  case "pack": {
+    require("./pack").run(args.slice(1));
+    break;
+  }
+
+  case "entity": {
+    require("./entity").run(args.slice(1));
+    break;
+  }
+
   case "agent": {
     require("./agent").run(args.slice(1));
     break;
   }
 
+  case "dream": {
+    require("./dream").run(args.slice(1));
+    break;
+  }
+
   case "people": {
     require("./people").run(args.slice(1));
     break;
@@ -320,6 +335,9 @@ Memory tools:
                                              (alias: ts; --all for every project; --help for options)
   open-claudia transcript-window <pattern>   Search project transcript, show hits with context
                                              (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 };