clementine-agent 1.4.3 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +166 -298
  2. package/dist/cli/dashboard.js +954 -164
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -20,43 +20,15 @@ Connects to Discord, Slack, Telegram, WhatsApp, and webhooks. Remembers everythi
20
20
 
21
21
  ## How it works
22
22
 
23
- Clementine is three layers stacked on a shared memory store:
24
-
25
- ```
26
- ┌─────────────────────────────────────────┐
27
- │ Channel Layer │
28
- │ Discord · Slack · Telegram · WhatsApp │
29
- │ Webhook API · Discord Guild Channels │
30
- └────────────────┬────────────────────────┘
31
- │
32
- ┌────────────────▼────────────────────────┐
33
- │ Gateway Layer │
34
- │ Router · Session Manager · Heartbeat │
35
- │ Cron Scheduler · Unleashed Engine │
36
- │ Notification Dispatch │
37
- └────────────────┬────────────────────────┘
38
- │
39
- ┌────────────────▼────────────────────────┐
40
- │ Agent Layer │
41
- │ Claude Code SDK · Security Hooks │
42
- │ Auto-Memory · Session Rotation │
43
- │ Agent Profiles · Sub-Agent Teams │
44
- │ Self-Improvement Loop │
45
- └────────────────┬────────────────────────┘
46
- │
47
- ┌────────────────▼────────────────────────┐
48
- │ MCP Tool Server │
49
- │ 30+ tools over stdio transport │
50
- │ Memory · Tasks · Vault · Workspace │
51
- └────────────────┬────────────────────────┘
52
- │
53
- ┌──────────────────────▼──────────────────────┐
54
- │ Memory Store │
55
- │ SQLite FTS5 · Salience Scoring · Decay │
56
- │ Episodic Memory · Wikilink Graph │
57
- │ FalkorDB Knowledge Graph · Procedural Skills│
58
- │ Obsidian Vault (source of truth) │
59
- └─────────────────────────────────────────────┘
23
+ Clementine is four layers over a shared memory store:
24
+
25
+ ```
26
+ Channels → Gateway → Agent → MCP tools → Memory
27
+ Discord Router Claude SDK 100+ tools SQLite FTS5
28
+ Slack Sessions Security hooks stdio + vectors
29
+ Telegram Heartbeats Auto-memory Knowledge graph
30
+ WhatsApp Cron + queues Sub-agents Obsidian vault
31
+ Webhook Delivery Self-improve (source of truth)
60
32
  ```
61
33
 
62
34
  ### The memory loop
@@ -86,7 +58,7 @@ clementine dashboard # open the web command center
86
58
 
87
59
  Already installed? Update in place with `clementine update`.
88
60
 
89
- ### Troubleshooting
61
+ ### Install issues
90
62
 
91
63
  **`EACCES: permission denied` on `npm install -g`.** Your Node was installed system-wide (`/usr/local/lib/...`) and npm can't write there without sudo. Fix it once, permanently:
92
64
 
@@ -127,72 +99,34 @@ Handles system dependencies (redis, libomp, build tools), npm packages, TypeScri
127
99
  ~/.clementine/ ← Data home (created on first run)
128
100
  ├── .env ← Configuration (created by setup wizard)
129
101
  ├── .sessions.json ← Session persistence
130
- ├── .memory.db ← (legacy, unused — real DB is vault/.memory.db)
131
102
  ├── .clementine.pid ← Daemon PID lock
132
- ├── logs/
133
- │ ├── clementine.log ← Daemon stdout/stderr
134
- │ └── audit.log ← Security audit trail
103
+ ├── logs/ ← Daemon log + security audit log
135
104
  ├── cron/runs/ ← Per-job JSONL run logs
136
- ├── unleashed/ ← Unleashed task progress & checkpoints
137
- │ └── <task>/
138
- │ ├── status.json ← Current status, phase, timing
139
- │ └── progress.jsonl ← Phase-by-phase event log
140
- ├── self-improve/ ← Self-improvement state
141
- │ ├── experiment-log.jsonl ← Append-only experiment history
142
- │ ├── state.json ← Loop status, baseline metrics
143
- │ └── pending-changes/ ← Proposed diffs awaiting approval
144
- │ └── {experiment-id}.json
145
- └── vault/ ← Obsidian-compatible vault
146
- ├── 00-System/ ← SOUL.md, MEMORY.md, HEARTBEAT.md, CRON.md
147
- │ └── skills/ ← Procedural memory (auto-extracted from successful tasks)
148
- ├── 01-Daily-Notes/ ← Auto-generated daily logs (YYYY-MM-DD.md)
149
- ├── 02-People/ ← Person notes (auto-created from conversations)
150
- ├── 03-Projects/ ← Project notes
151
- ├── 04-Topics/ ← Knowledge topics
152
- ├── 05-Tasks/ ← TASKS.md master list ({T-NNN} IDs)
153
- ├── 06-Templates/ ← Note templates
154
- └── 07-Inbox/ ← Quick captures
155
-
156
- src/ ← Package code (wherever npm installed it)
157
- ├── agent/
158
- │ ├── assistant.ts ← PersonalAssistant — the brain
159
- │ ├── hooks.ts ← Security enforcement (3-tier model)
160
- │ ├── profiles.ts ← Agent profile switching
161
- │ └── self-improve.ts ← Nightly self-improvement loop engine
162
- ├── channels/
163
- │ ├── discord.ts ← Discord.js adapter
164
- │ ├── slack.ts ← Slack Socket Mode adapter
165
- │ ├── telegram.ts ← grammY adapter
166
- │ ├── whatsapp.ts ← Twilio WhatsApp bridge
167
- │ └── webhook.ts ← HTTP webhook API
168
- ├── gateway/
169
- │ ├── router.ts ← Message routing + session management
170
- │ ├── heartbeat.ts ← HeartbeatScheduler + CronScheduler
171
- │ └── notifications.ts ← Channel-agnostic notification fan-out
172
- ├── memory/
173
- │ ├── store.ts ← SQLite FTS5 memory store + embedding backfill
174
- │ ├── embeddings.ts ← TF-IDF embedding provider (local, 512-dim vectors)
175
- │ ├── search.ts ← Temporal decay, dedup, formatting
176
- │ ├── chunker.ts ← Vault file parser (## headers, frontmatter)
177
- │ ├── mmr.ts ← Maximal Marginal Relevance reranker
178
- │ ├── consolidation.ts ← Evening consolidation engine (dedup, summarize, extract)
179
- │ ├── context-assembler.ts ← Token-budgeted context slot filler
180
- │ └── graph-store.ts ← FalkorDB knowledge graph layer (optional)
181
- ├── tools/ ← MCP stdio server (30+ tools, decomposed by domain)
182
- │ ├── mcp-server.ts ← Server entry + registration
183
- │ ├── goal-tools.ts ← Goal lifecycle tools
184
- │ ├── vault-tools.ts ← Vault read/write/search tools
185
- │ ├── team-tools.ts ← Team agent tools
186
- │ ├── session-tools.ts ← Session management tools
187
- │ └── admin-tools.ts ← System admin tools
188
- ├── cli/
189
- │ ├── index.ts ← CLI commands (launch, stop, status, config, doctor)
190
- │ ├── setup.ts ← Interactive configuration wizard
191
- │ ├── dashboard.ts ← Local web dashboard (command center)
192
- │ └── cron.ts ← Cron job runner and scheduler
193
- ├── config.ts ← Paths, secrets, models (never pollutes process.env)
194
- ├── types.ts ← Shared TypeScript interfaces
195
- └── index.ts ← Main entry point (multi-channel startup)
105
+ ├── unleashed/<task>/ ← Long-running task progress + status
106
+ ├── self-improve/ ← Experiment log, state, pending proposals
107
+ ├── heartbeat/agents/<slug>/ ← Per-agent heartbeat state
108
+ └── vault/ ← Obsidian-compatible vault (see Vault section)
109
+ └── .memory.db ← SQLite FTS5 + vector index
110
+
111
+ src/ ← Package code (npm install location)
112
+ ├── agent/ ← The brain: assistant, hooks, agent manager,
113
+ │ proactive engine, self-improvement, advisor,
114
+ │ skill extraction, complexity classifier, …
115
+ ├── channels/ ← Discord, Slack, Telegram, WhatsApp, Webhook
116
+ │ (+ per-agent Discord/Slack bot managers)
117
+ ├── gateway/ ← Router, heartbeat schedulers, cron scheduler,
118
+ │ delivery queue, failure monitor
119
+ ├── memory/ ← SQLite FTS5 store, embeddings, MMR rerank,
120
+ │ chunker, consolidation, graph store
121
+ ├── tools/ ← MCP stdio server (100+ tools, by domain)
122
+ ├── cli/ ← CLI entry, setup wizard, dashboard, cron runner
123
+ ├── brain/ ← Ingestion pipeline + connectors
124
+ ├── analytics/ ← Tool-usage telemetry
125
+ ├── security/, secrets/ ← Secret/credential helpers, hardening
126
+ ├── vault-migrations/ ← Versioned vault upgrades
127
+ ├── config.ts ← Paths, secrets, models (never leaks to env)
128
+ ├── types.ts ← Shared TypeScript types
129
+ └── index.ts ← Multi-channel startup entry
196
130
  ```
197
131
 
198
132
  ### Code vs. data separation
@@ -220,143 +154,99 @@ Secrets never reach the Claude subprocess — `SAFE_ENV` filters credentials fro
220
154
 
221
155
  ### Memory architecture
222
156
 
223
- Three-layer retrieval merges full-text, vector, and recency signals into a single ranked context window:
224
-
225
- ```
226
- User message
227
- │
228
- ├──▶ Layer 1: FTS5 (BM25 relevance)
229
- ├──▶ Layer 2: TF-IDF vector similarity (cosine, threshold 0.15)
230
- ├──▶ Layer 3: Recent chunks (time-windowed)
231
- │
232
- ▼
233
- ┌──────────────────┐ ┌────────────────────┐
234
- │ MMR rerank │────▶│ Context assembly │──▶ System prompt
235
- │ + deduplication │ │ (token-budgeted) │
236
- └──────────────────┘ └────────────────────┘
237
- │
238
- │ salience boost on retrieval
239
- ▼
240
- ┌──────────────┐ ┌────────────────────┐
241
- │ Assistant │────▶│ Auto-memory pass │──▶ Vault writes
242
- │ responds │ │ (background Sonnet) │ (MEMORY.md, people, tasks)
243
- └──────────────┘ └────────────────────┘
244
- │
245
- ▼
246
- ┌──────────────┐
247
- │ Session │──▶ Episodic chunk indexed
248
- │ summarization │ (sector='episodic')
249
- └──────────────┘
250
- │
251
- ▼
252
- ┌──────────────────────┐
253
- │ Evening consolidation │──▶ Dedup (Jaccard) + topic summarization (LLM)
254
- │ + embedding rebuild │ + principle extraction + TF-IDF vocab rebuild
255
- └──────────────────────┘
256
- │
257
- ▼
258
- ┌──────────────┐
259
- │ Startup │──▶ Temporal decay + pruning
260
- │ maintenance │ (stale memories sink, old data trimmed)
261
- └──────────────┘
262
- ```
263
-
264
- - **FTS5** — Full-text search with BM25 ranking, zero-cost, zero-latency
265
- - **TF-IDF embeddings** — Local 512-dim vectors (no API calls), vocabulary rebuilt during sync and evening consolidation, cosine similarity search over recent chunks
266
- - **MMR reranking** — Maximal Marginal Relevance via Jaccard similarity removes near-duplicates and promotes diversity in results
267
- - **Salience scoring** — Chunks gain score on retrieval, decay over time (7-day half-life). Formula: `log(access_count + 1) * 0.15 + recency_decay * 0.3`
157
+ Retrieval merges three signals (FTS5 BM25, TF-IDF cosine, recency), reranks with MMR for diversity, and fills a token-budgeted context window. After each turn, a background Sonnet pass extracts memories to the vault. Sessions get summarized into episodic chunks. A nightly consolidation pass dedups, summarizes, and rebuilds the embedding vocabulary. Startup applies temporal decay and prunes old data.
158
+
159
+ - **FTS5** — Full-text BM25 search, local, zero-cost
160
+ - **TF-IDF embeddings** — Local 512-dim vectors (no API calls), rebuilt nightly
161
+ - **MMR reranking** — Jaccard-based diversity, removes near-duplicates
162
+ - **Salience** — Boost on retrieval, 7-day half-life decay
268
163
  - **Episodic memory** — Session summaries indexed as searchable chunks
269
- - **Wikilink graph** — `[[wikilinks]]` parsed and queryable for connection discovery
270
- - **Knowledge graph** — FalkorDB-powered typed relationships and multi-hop traversal (people → projects → topics). Visualized on a dark canvas in the dashboard with type legend and edge labels.
271
- - **Procedural skills** — Reusable how-to recipes auto-extracted from successful task executions. Stored as Markdown in `vault/00-System/skills/` and injected into cron jobs and unleashed tasks at runtime. Teach new skills manually via the dashboard Skills tab or let Clementine learn them from conversations.
272
- - **Evening consolidation** — Nightly pass: deduplicates chunks by Jaccard similarity (>70%), summarizes topic groups via LLM (Haiku), extracts recurring behavioral corrections into permanent rules, and rebuilds TF-IDF vocabulary + backfills embeddings
273
- - **Agent isolation** — Per-agent memory scoping via `agent_slug` column. Soft mode (default) boosts matching agent chunks 1.4x; strict mode filters to agent + global only
274
- - **Memory transparency** — Every memory write is logged to `memory_extractions` with user correction/dismissal support from the dashboard
275
- - **Temporal decay** — Applied on every startup; stale memories naturally sink
276
- - **Pruning** — Episodic chunks >90 days with salience <0.01 are removed; old transcripts, access logs, and orphaned references trimmed
277
-
278
- ### MCP tools (30+)
279
-
280
- | Tool | Description |
281
- |------|-------------|
282
- | `memory_read` | Read vault notes (shortcuts: today, yesterday, memory, tasks, soul) |
283
- | `memory_write` | Write/append to vault (daily log, MEMORY.md sections, arbitrary notes) |
284
- | `memory_search` | FTS5 full-text search across all vault notes |
285
- | `memory_recall` | Combined FTS5 + recency search with salience boost |
286
- | `memory_connections` | Query the wikilink graph for a note |
287
- | `memory_timeline` | Chronological view of vault changes by date range |
288
- | `transcript_search` | Search past conversation transcripts |
289
- | `note_create` | Create notes (person, project, topic, task, inbox) |
290
- | `note_take` | Quick timestamped capture to daily log |
291
- | `daily_note` | Create or read today's daily note |
292
- | `task_list` | List tasks with status/project filters |
293
- | `task_add` | Add tasks with priority, due dates, projects |
294
- | `task_update` | Update task status (supports recurring tasks) |
295
- | `vault_stats` | Dashboard of vault health and activity |
296
- | `rss_fetch` | Fetch and parse RSS/Atom feeds |
297
- | `github_prs` | Check GitHub PRs (review-requested + authored) |
298
- | `browser_screenshot` | Take screenshots via Kernel cloud browser |
299
- | `set_timer` | Set short-term reminders (notifies via active channels) |
300
- | `outlook_inbox` | Read recent emails from Outlook inbox |
301
- | `outlook_search` | Search Outlook emails by query |
302
- | `outlook_calendar` | View upcoming calendar events |
303
- | `outlook_draft` | Create an email draft in Outlook |
304
- | `outlook_send` | Send an email from Outlook (Tier 3, requires approval) |
305
- | `discord_channel_send` | Post messages to any Discord text channel by ID |
306
- | `workspace_config` | Add, remove, or list workspace directories at runtime |
307
- | `workspace_list` | Scan workspace directories for local project roots |
308
- | `workspace_info` | Read a project's README, CLAUDE.md, manifest, and directory tree |
309
- | `add_cron_job` | Create scheduled tasks (supports standard and unleashed mode, project context) |
310
- | `self_restart` | Restart the daemon (for self-updates and config changes) |
311
- | `analyze_image` | Analyze images with vision capabilities |
312
- | `memory_report` | Generate a transparency report of all memory extractions |
313
- | `memory_correct` | Correct or dismiss a previously extracted memory |
314
- | `feedback_log` | Log user feedback on responses |
315
- | `feedback_report` | View feedback history and patterns |
316
- | `team_list` | List all team agents with status, channel, and capabilities |
317
- | `team_message` | Send a message to another agent (permission-scoped, synchronous) |
318
- | `create_agent` | Create a new agent with name, role, tools, project, and team connections |
319
- | `self_improve_status` | Check self-improvement state, pending approvals, experiment history |
320
- | `self_improve_run` | Trigger a self-improvement analysis cycle |
164
+ - **Wikilink + knowledge graph** — `[[wikilinks]]` graph + optional FalkorDB typed relationships (visualized in dashboard)
165
+ - **Procedural skills** — Auto-extracted from successful tasks, stored at `vault/00-System/skills/`, injected into future runs
166
+ - **Evening consolidation** — Nightly: Jaccard dedup (>70%), topic summarization (Haiku), behavioral-rule extraction, vocabulary rebuild
167
+ - **Agent isolation** — Per-agent scoping via `agent_slug`; soft (1.4× boost) or strict modes
168
+ - **Transparency** — Every write logged to `memory_extractions`; correct/dismiss from dashboard
169
+ - **Pruning** — Episodic >90 days with salience <0.01 removed; old transcripts and access logs trimmed
170
+
171
+ ### MCP tools (100+)
172
+
173
+ Tools are grouped by domain. Run `clementine tools` to see the live list.
174
+
175
+ | Group | Examples |
176
+ |-------|----------|
177
+ | **Memory** | `memory_read`, `memory_write`, `memory_search`, `memory_recall`, `memory_connections`, `memory_timeline`, `memory_consolidate`, `memory_correct`, `memory_report`, `memory_graph_*` |
178
+ | **Vault & notes** | `note_create`, `note_take`, `daily_note`, `task_list`, `task_add`, `task_update`, `vault_stats`, `transcript_search` |
179
+ | **Workspace** | `workspace_config`, `workspace_list`, `workspace_info` |
180
+ | **External** | `web_search`, `rss_fetch`, `github_prs`, `browser_screenshot`, `analyze_image`, `outlook_*`, `sf_*` (Salesforce), `discord_channel_*` |
181
+ | **Agents & teams** | `create_agent`, `update_agent`, `delete_agent`, `team_list`, `team_message`, `team_request`, `team_status`, `delegate_task`, `wake_agent` |
182
+ | **Goals & background** | `goal_create`, `goal_update`, `goal_work`, `start_background_task`, `get_background_task`, `discover_work` |
183
+ | **Cron & workflows** | `add_cron_job`, `cron_list`, `cron_run_history`, `trigger_cron_job`, `workflow_create`, `workflow_run`, `workflow_save`, `workflow_*` |
184
+ | **Self-improvement** | `self_improve_run`, `self_improve_status`, `self_edit_source`, `prompt_override_*`, `decision_reflection`, `feedback_log`, `feedback_report` |
185
+ | **System** | `self_restart`, `self_update`, `set_timer`, `env_set`, `allow_tool`, `setup_integration`, `auth_profile_status` |
321
186
 
322
187
  ---
323
188
 
324
189
  ## CLI reference
325
190
 
191
+ Run `clementine --help` to see everything; the most common commands:
192
+
193
+ **Daemon**
194
+ ```
195
+ clementine launch [-f] [--install] Start daemon (foreground / macOS login service)
196
+ clementine stop | restart | rebuild Lifecycle controls
197
+ clementine status PID, uptime, active channels
198
+ clementine update [--dry-run] Pull latest, rebuild, reinstall (preserves config)
199
+ clementine doctor [--fix] Verify (and optionally repair) config and vault
200
+ clementine dashboard Open the web command center (localhost:3030)
201
+ clementine tools List available MCP tools, plugins, and channels
202
+ ```
203
+
204
+ **Config & secrets**
326
205
  ```
327
- clementine launch Start as background daemon (default)
328
- clementine launch -f Start in foreground (debug mode)
329
- clementine launch --install Install as macOS login service (survives reboots)
330
- clementine stop Stop the daemon
331
- clementine restart Stop + relaunch
332
- clementine rebuild Build + restart daemon + dashboard in one step
333
- clementine status Show PID, uptime, active channels
334
- clementine update Pull latest, rebuild, reinstall (preserves config)
335
- clementine update --dry-run Preview update without making changes
336
- clementine doctor Verify configuration and vault health
337
- clementine doctor --fix Auto-fix common issues (redis, sqlite, FalkorDB)
338
- clementine dashboard Open the local web command center (localhost:3030)
339
- clementine tools List available MCP tools, plugins, and channels
340
- clementine config setup Interactive configuration wizard
341
- clementine config set KEY VAL Set a single config value
342
- clementine config get KEY Read a config value
343
- clementine config edit Open .env in your editor ($EDITOR)
344
- clementine memory search <q> Search memory from the terminal (FTS5)
345
- clementine projects list Show all linked projects
346
- clementine projects add <path> Link a project directory (-d desc, -k keywords)
347
- clementine projects remove <p> Unlink a project directory
348
- clementine cron list List all cron jobs and last run status
349
- clementine cron run <job> Run a specific cron job
350
- clementine cron run-due Run all due jobs (for OS scheduler)
351
- clementine cron runs [job] View run history (with retry/error details)
352
- clementine cron install Install OS-level scheduler (launchd/crontab)
353
- clementine cron uninstall Remove OS-level scheduler
354
- clementine heartbeat Run a one-shot heartbeat check
355
- clementine self-improve status Show self-improvement state and baseline metrics
356
- clementine self-improve run Trigger a self-improvement cycle
357
- clementine self-improve history Show experiment history
358
- clementine self-improve apply <id> Approve and apply a pending change
359
- clementine --help Show all commands
206
+ clementine setup Interactive setup wizard
207
+ clementine config set KEY VAL Write to ~/.clementine/.env
208
+ clementine config get KEY
209
+ clementine config list Show all overrides
210
+ clementine config edit Open .env in $EDITOR
211
+ clementine login | auth Authenticate Claude Code / OAuth providers
212
+ ```
213
+
214
+ **Chat & memory**
215
+ ```
216
+ clementine chat Interactive REPL
217
+ clementine memory status Index size, recent activity
218
+ clementine memory search <q> FTS5 search
219
+ clementine memory dedup | reembed Maintenance
220
+ clementine brain digest Run the brain digest pipeline
221
+ ```
222
+
223
+ **Projects & agents**
224
+ ```
225
+ clementine projects list | add <p> | remove <p>
226
+ clementine agent list | new <slug> | show <slug>
227
+ clementine skills list | pending | approve <name> | reject <name> | search <q>
228
+ ```
229
+
230
+ **Cron, workflows, heartbeat**
231
+ ```
232
+ clementine cron list | run <job> | run-due | runs [job]
233
+ clementine cron add <name> <schedule> <prompt>
234
+ clementine cron install | uninstall OS-level scheduler (launchd / crontab)
235
+ clementine workflow list | run <name>
236
+ clementine heartbeat One-shot heartbeat tick
237
+ ```
238
+
239
+ **Self-improvement**
240
+ ```
241
+ clementine self-improve status | run | history | pending | apply <id>
242
+ ```
243
+
244
+ **Diagnostics**
245
+ ```
246
+ clementine advisor | rules Live advisor rules
247
+ clementine mode <mode> Switch operating mode
248
+ clementine analytics | tool-usage Telemetry on tool usage
249
+ clementine ingest seed <path> | run <slug> | list
360
250
  ```
361
251
 
362
252
  ### Daemon behavior
@@ -369,27 +259,17 @@ clementine --help Show all commands
369
259
 
370
260
  ### Dashboard
371
261
 
372
- Run `clementine dashboard` to open a local web command center at `http://localhost:3030`. The dashboard provides:
373
-
374
- - **Metrics** — Time saved estimates, session counts, cron job stats, memory size
375
- - **Chat** — Talk to your assistant directly from the browser
376
- - **Memory search** — Full-text search across all vault notes (FTS5)
377
- - **Scheduled tasks** — Create, edit, run, toggle, and delete cron jobs with a visual schedule builder
378
- - **Project-aware cron** — Assign cron jobs to specific project directories
379
- - **Unleashed mode** — Create long-running autonomous tasks, monitor phase progress, cancel running tasks
380
- - **Projects** — Browse all discovered workspace projects with type, description, and tool badges
381
- - **Live status** — Daemon health, LaunchAgent status, active channels
382
- - **Sessions** — View and manage active conversation sessions
383
- - **The Office** — Visual agent management with desk-station cards showing status, avatars, channels, and tools
384
- - **Hiring Interview** — Click "Hire a New Employee" and Clementine interviews you to build the agent config conversationally
385
- - **Manual Agent Setup** — Form modal with project dropdown (auto-populated from discovered projects) and categorized tool browser with checkboxes
386
- - **Auto-restart** — Daemon restarts automatically when the agent roster changes (from either the interview or manual path)
387
- - **Training Center** — Click any agent to open a 4-tab detail view: Schedule (per-agent cron jobs), Skills (per-agent procedural memory), Execution Traces (tool call history with timing), and Prompt Lab (test prompts against the agent)
388
- - **Skills** — Teach, view, and delete procedural skills. Skills are auto-extracted from successful tasks or taught manually via the dashboard.
389
- - **Self-Improvement** — View experiment history, approve/deny pending proposals, monitor baseline metrics
390
- - **Settings** — API key management, model config, custom env vars, service status
391
-
392
- No extra dependencies — the dashboard uses Express, which is already installed.
262
+ Run `clementine dashboard` to open the command center at `http://localhost:3030`. Five pages:
263
+
264
+ | Page | What's there |
265
+ |------|--------------|
266
+ | **Home** | Chat with Clementine, today's briefing, recent activity, KPIs |
267
+ | **Build** | Workflows, scheduled tasks (visual cron builder), skills, unleashed tasks |
268
+ | **Team** | Agents (hire / edit / let go), goals, delegations, decision-reflection reports |
269
+ | **Brain** | Memory search (FTS5), knowledge graph, ingestion sources, vault health |
270
+ | **Settings** | Channels, integrations, API keys, model config, env vars, service status |
271
+
272
+ Cron jobs can be project-aware (assign a `work_dir`) and switched between standard and unleashed mode. The agent roster auto-restarts the daemon on changes. No extra deps — runs on Express.
393
273
 
394
274
  ---
395
275
 
@@ -475,13 +355,13 @@ clementine restart
475
355
 
476
356
  ## Models
477
357
 
478
- | Tier | Model Alias | Use case |
479
- |------|-------------|----------|
480
- | `haiku` | `haiku` (latest Haiku) | Lightweight tasks, cron noise filtering |
481
- | `sonnet` | `sonnet` (latest Sonnet) | Default conversation + auto-memory extraction |
482
- | `opus` | `opus` (latest Opus) | Available via config or agent profiles |
358
+ | Tier | Use case |
359
+ |------|----------|
360
+ | `haiku` | Lightweight tasks, cron noise filtering |
361
+ | `sonnet` | Default conversation + auto-memory extraction |
362
+ | `opus` | Per-agent override or global default |
483
363
 
484
- Model aliases always resolve to the latest version via the Claude Code SDK. To pin a specific version, set `DEFAULT_MODEL_TIER` to a full model name (e.g. `claude-sonnet-4-6`).
364
+ Aliases resolve to the latest version via the Claude Code SDK. To pin a specific version, set `DEFAULT_MODEL_TIER` to a full model name (e.g. `claude-sonnet-4-6`). Each agent can override the model in its `agent.md` frontmatter.
485
365
 
486
366
  Change the default with `clementine config set DEFAULT_MODEL_TIER opus`, then `clementine restart`.
487
367
 
@@ -545,14 +425,12 @@ Clementine supports multi-agent teams — each agent gets its own Discord bot, c
545
425
 
546
426
  ### Creating agents
547
427
 
548
- Two paths to create a new agent:
428
+ Open the **Team** page in the dashboard, then either:
549
429
 
550
- | Method | How |
551
- |--------|-----|
552
- | **Hiring interview** | Click "Hire a New Employee" in the dashboard (or an empty desk card). Clementine asks 3–5 questions about the agent's name, role, tools, project, and team connections, then calls `create_agent` automatically. |
553
- | **Manual setup** | Click "Manual Setup" to open a form with project dropdown, categorized tool browser, model selector, and team connection fields. |
430
+ - **Hire a New Employee** — Clementine interviews you (3–5 questions: name, role, tools, project, team connections) and calls `create_agent`.
431
+ - **Manual Setup** — form with project dropdown, categorized tool browser, model selector, and team-connection fields.
554
432
 
555
- Both paths trigger an automatic daemon restart when the new agent is detected.
433
+ Both paths auto-restart the daemon when the new agent appears.
556
434
 
557
435
  ### Agent configuration
558
436
 
@@ -577,14 +455,6 @@ Agents communicate via the `team_message` tool. Messages are permission-scoped
577
455
 
578
456
  Messages are delivered synchronously: the sender waits for the recipient's response. Conversation depth is tracked to prevent infinite loops.
579
457
 
580
- ### The Office (dashboard)
581
-
582
- The dashboard's "The Office" page shows each agent as an animated desk station with:
583
- - Live status indicator (online / connecting / error / offline)
584
- - Discord bot avatar (auto-pulled) or initial
585
- - Channel assignment, model badge, project badge, tool count
586
- - Edit and "Let Go" (delete) actions
587
-
588
458
  ### Decision-loop reflection
589
459
 
590
460
  Each agent's autonomous decisions are recorded to a proactive ledger (action chosen, signal source, eventual outcome). The `decision_reflection` MCP tool reads that ledger, computes per-action success rates, and surfaces calibration patterns:
@@ -657,20 +527,14 @@ The dashboard provides a visual schedule builder with dropdowns for frequency (d
657
527
 
658
528
  ## Unleashed mode
659
529
 
660
- For tasks that take hours — codebase refactors, research projects, content generation pipelines — unleashed mode runs autonomously with phased execution and checkpointing.
661
-
662
- ```
663
- Phase 1 (75 turns) ──▶ Checkpoint ──▶ Phase 2 (75 turns) ──▶ Checkpoint ──▶ ...
664
- │ │ │ │
665
- └─ Session resume ─────┘ └─ Session resume ─────┘
666
- ```
530
+ For tasks that take hours — codebase refactors, research projects, content pipelines — unleashed mode runs autonomously in phases with session resumption between each.
667
531
 
668
532
  ### How it works
669
533
 
670
- 1. The task runs in phases (default 75 turns per phase)
671
- 2. Between phases, the SDK session is **resumed** — the agent keeps its full conversation history
672
- 3. Progress is saved to `~/.clementine/unleashed/<task>/` (JSONL log + status file)
673
- 4. The agent can spawn sub-agents for parallel work streams
534
+ 1. Runs in phases (default 75 turns each)
535
+ 2. Between phases, the SDK session is **resumed** — full conversation history preserved
536
+ 3. Progress saved to `~/.clementine/unleashed/<task>/` (status + JSONL log)
537
+ 4. Can spawn sub-agents for parallel work
674
538
  5. Cancel anytime via the dashboard or by touching a `CANCEL` file
675
539
 
676
540
  ### Safety guardrails
@@ -719,19 +583,7 @@ Progress is also logged to `~/.clementine/unleashed/<task>/progress.jsonl` for d
719
583
 
720
584
  ## Self-improvement
721
585
 
722
- Clementine can autonomously improve herself using an iterative loop inspired by Karpathy's autoresearch pattern: **gather data, diagnose weaknesses, hypothesize a fix, evaluate the fix, and propose the change for approval**.
723
-
724
- ```
725
- ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐
726
- │ Gather │───▶│ Diagnose │───▶│ Hypothesize │───▶│ Evaluate │───▶│ Gate │
727
- │ feedback │ │ weakness │ │ a change │ │ LLM judge│ │ approve? │
728
- │ cron logs│ │ patterns │ │ (minimal) │ │ 0-10 │ │ │
729
- └──────────┘ └──────────┘ └─────────────┘ └──────────┘ └──────────┘
730
- │ │
731
- │ ┌──────────────────────────────────────┐ │
732
- └──────────────│ Repeat until plateau or time limit │◀────────────┘
733
- └──────────────────────────────────────┘
734
- ```
586
+ Clementine runs an iterative self-improvement loop: **gather data → diagnose weakness → hypothesize a fix → LLM-judge it → gate for human approval**. Repeats until plateau or time limit.
735
587
 
736
588
  ### What it targets
737
589
 
@@ -800,6 +652,21 @@ After the loop completes, memory maintenance runs automatically (temporal decay
800
652
 
801
653
  The vault is an Obsidian-compatible folder of Markdown files with YAML frontmatter, `[[wikilinks]]`, and `#tags`. Open `~/.clementine/vault/` in Obsidian to browse your assistant's memory visually.
802
654
 
655
+ Folder structure under `~/.clementine/vault/`:
656
+
657
+ ```
658
+ 00-System/ SOUL.md, MEMORY.md, HEARTBEAT.md, CRON.md, AGENTS.md
659
+ agents/<slug>/agent.md ← per-agent config
660
+ skills/ ← procedural skills
661
+ 01-Daily-Notes/ YYYY-MM-DD.md auto-generated daily logs
662
+ 02-People/ Person notes (auto-created from conversations)
663
+ 03-Projects/ Project notes
664
+ 04-Topics/ Knowledge topics
665
+ 05-Tasks/ TASKS.md master list with {T-NNN} IDs
666
+ 06-Templates/ Note templates
667
+ 07-Inbox/ Quick captures
668
+ ```
669
+
803
670
  Key system files:
804
671
 
805
672
  | File | Purpose |
@@ -807,7 +674,8 @@ Key system files:
807
674
  | `SOUL.md` | Core personality and behavioral instructions |
808
675
  | `MEMORY.md` | Auto-extracted facts, preferences, people context |
809
676
  | `HEARTBEAT.md` | Autonomous check-in configuration |
810
- | `CRON.md` | Scheduled task definitions (cron syntax) |
677
+ | `CRON.md` | Scheduled task definitions |
678
+ | `AGENTS.md` | Master roster of agents |
811
679
  | `TASKS.md` | Master task list with `{T-NNN}` IDs |
812
680
 
813
681
  ---