Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
docs: update permissions, second brain, commands, token budget, fix claims
Salman Qureshie54e6838cfb0
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex df8f8006..da61587e 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -157,7 +157,7 @@ All runtime data lives in `~/.mercury/` (not the project directory):- Short-term context: last 10 messages- Long-term facts: keyword-matched, ~3 facts injected- Second brain: relevant user memories injected via `retrieveRelevant()` (~900 chars)-- Daily default: 50,000 tokens+- Daily default: 1,000,000 tokens## Second Braindiff --git a/README.md b/README.mdindex abf519b2..70794358 100644--- a/README.md+++ b/README.md@@ -110,6 +110,7 @@ In daemon mode, Telegram becomes your primary channel — CLI is log-only since| `mercury setup` | Re-run the setup wizard || `mercury status` | Show config and daemon status || `mercury help` | Show full manual |+| `mercury upgrade` | Upgrade to latest version || `mercury telegram list` | List approved and pending Telegram users || `mercury telegram approve <code\|id>` | Approve a pairing code or pending request || `mercury telegram reject <id>` | Reject a pending Telegram access request |@@ -138,6 +139,10 @@ Type these during a conversation — they don't consume API tokens. Work on both| `/budget override` | Override budget for one request || `/budget reset` | Reset usage to zero || `/budget set <n>` | Change daily token budget |+| `/permissions` | Change permission mode (Ask Me / Allow All) |+| `/tasks` | List scheduled tasks |+| `/memory` | View and manage second brain memory |+| `/unpair` | Telegram: reset all access |## Built-in Tools@@ -156,8 +161,8 @@ Type these during a conversation — they don't consume API tokens. Work on both| Channel | Features ||---------|----------|-| **CLI** | Readline prompt, arrow-key command menus, real-time text streaming, markdown rendering |-| **Telegram** | HTML formatting, file uploads, typing indicators, multi-user access with admin/member roles |+| **CLI** | Readline prompt, arrow-key command menus, real-time text streaming, markdown rendering, permission mode picker |+| **Telegram** | HTML formatting, file uploads, typing indicators, multi-user access with admin/member roles, editable status messages |### Telegram Access@@ -178,6 +183,18 @@ CLI commands: `mercury telegram list|approve|reject|remove|promote|demote|reset`- Tasks persist to `~/.mercury/schedules.yaml` and restore on restart- Responses route back to the channel where the task was created+## Second Brain++Mercury builds a structured memory of facts about you, your preferences, and your project context — stored locally in SQLite with full-text search.++- **10 memory types** — preferences, relationships, project facts, decisions, routines, and more+- **Automatic extraction** — after each conversation, Mercury pulls important facts and stores them+- **Relevant recall** — only memories matching the current context are injected into the system prompt+- **User controls** — `/memory` to view, search, and manage stored facts+- **Auto-pruning** — stale entries are expired after 7 days of inactivity++All memory stays on your machine in `~/.mercury/memory/second-brain.db`.+## ConfigurationAll runtime data lives in `~/.mercury/` — not in your project directory.@@ -192,6 +209,7 @@ All runtime data lives in `~/.mercury/` — not in your project directory.| `~/.mercury/schedules.yaml` | Scheduled tasks || `~/.mercury/token-usage.json` | Daily token usage tracking || `~/.mercury/memory/` | Short-term, long-term, episodic memory |+| `~/.mercury/memory/second-brain.db` | SQLite database for structured long-term memory (FTS5) || `~/.mercury/daemon.pid` | Background process PID || `~/.mercury/daemon.log` | Daemon mode logs |@@ -214,10 +232,10 @@ When a provider fails, Mercury automatically tries the next one. It remembers th## Architecture-- **TypeScript + Node.js 20+** — ESM, tsup build, zero native dependencies+- **TypeScript + Node.js 18+** — ESM, tsup build- **Vercel AI SDK v4** — `generateText` + `streamText`, 10-step agentic loop, provider fallback- **grammY** — Telegram bot with typing indicators and file uploads-- **Flat-file persistence** — No database. YAML + JSON in `~/.mercury/`+- **SQLite + JSONL** — Second brain (SQLite with FTS5), short/long-term/episodic memory (JSONL)- **Daemon manager** — Background spawn + PID file + watchdog crash recovery- **System services** — macOS LaunchAgent, Linux systemd, Windows Task Schedulerdiff --git a/docs/docs.html b/docs/docs.htmlindex 6bddd3da..73e881bc 100644--- a/docs/docs.html+++ b/docs/docs.html@@ -589,6 +589,22 @@<td>/budget set <n></td><td>Change daily token budget</td></tr>+ <tr>+ <td>/permissions</td>+ <td>Change permission mode (Ask Me / Allow All) — Telegram only</td>+ </tr>+ <tr>+ <td>/tasks</td>+ <td>List scheduled tasks</td>+ </tr>+ <tr>+ <td>/memory</td>+ <td>View and manage second brain memory</td>+ </tr>+ <tr>+ <td>/unpair</td>+ <td>Telegram only: reset all access, new users can /start again</td>+ </tr></tbody></table><div class="callout">@@ -1200,11 +1216,6 @@<td>Permanently approve a command type</td><td>command (e.g. "curl")</td></tr>- <tr>- <td>send_message</td>- <td>Send a message to the paired Telegram chat</td>- <td>message</td>- </tr></tbody></table>@@ -1359,6 +1370,16 @@<p>Edit <code>~/.mercury/permissions.yaml</code> to customize. Skill elevation: skills with <code>allowed-tools</code> in their SKILL.md get automatic approval for those tools during execution.</p>+ <h3>Permission Modes</h3>+ <p>At session start, Mercury asks you to choose a permission mode:</p>+ <ul>+ <li><strong>🔒 Ask Me</strong> — Mercury asks for confirmation before file writes, shell commands that need approval, and scope changes. Default on both CLI and Telegram.</li>+ <li><strong>✅ Allow All</strong> — Mercury auto-approves all directory scopes, all shell commands (except blocked), and loop-continuation prompts. No interruptions during the session. Resets on restart.</li>+ </ul>+ <p>On <strong>CLI</strong>: an arrow-key menu appears at startup before the first prompt.</p>+ <p>On <strong>Telegram</strong>: inline keyboard buttons appear with the first message. Use <code>/permissions</code> to change mode at any time.</p>+ <p><strong>Scheduled tasks</strong> always run in Allow All mode — filesystem access and shell commands are auto-approved. You receive a notification before each task executes.</p>+<h2 id="providers">Provider Fallback</h2><p>Configure multiple LLM providers. Mercury tries them in order and falls back automatically. When a providerfails, Mercury tries the next one and remembers the last successful provider.</p>diff --git a/docs/index.html b/docs/index.htmlindex 628d0b85..ec4ce1e0 100644--- a/docs/index.html+++ b/docs/index.html@@ -247,7 +247,6 @@<li><code>run_command</code> — Execute shell commands</li><li><code>cd</code> — Change working directory (persists)</li><li><code>approve_command</code> — Permanently approve a command</li>- <li><code>send_message</code> — Message paired Telegram chat</li></ul></div><div class="cap-group" data-reveal>@@ -521,7 +520,7 @@<div class="arch-card" data-reveal><div class="arch-label">Core</div><div class="arch-value">TypeScript + Node.js 18+</div>- <div class="arch-desc">ESM, tsup build, zero native deps</div>+ <div class="arch-desc">ESM, tsup build, SQLite-backed second brain</div></div><div class="arch-card" data-reveal><div class="arch-label">AI SDK</div>@@ -535,8 +534,8 @@</div><div class="arch-card" data-reveal><div class="arch-label">Memory</div>- <div class="arch-value">Flat-file JSONL/JSON</div>- <div class="arch-desc">Short-term, long-term, episodic — no database</div>+ <div class="arch-value">JSONL + SQLite</div>+ <div class="arch-desc">Short-term, long-term, episodic + second brain</div></div><div class="arch-card" data-reveal><div class="arch-label">Telegram</div>diff --git a/src/utils/manual.ts b/src/utils/manual.tsindex 38b6d858..877de325 100644--- a/src/utils/manual.ts+++ b/src/utils/manual.ts@@ -100,6 +100,9 @@ export function getManual(): string {['/telegram reset', 'CLI chat only: reset all Telegram access'],['/tools', 'List currently loaded tools'],['/skills', 'List installed skills'],+ ['/permissions', 'Change permission mode (Ask Me / Allow All)'],+ ['/tasks', 'List scheduled tasks'],+ ['/memory', 'View and manage second brain memory'],['/stream', 'Toggle text streaming on/off (Telegram)'],['/stream on', 'Enable streaming (live text updates)'],['/stream off', 'Disable streaming (single message)'],@@ -119,6 +122,8 @@ export function getManual(): string {'Say "always" when prompted to permanently approve a command type.','Edit ~/.mercury/permissions.yaml to customize manually.','File access is scoped — new paths need approval (y/n/always).',+ 'At session start, choose "Ask Me" (confirm each action) or "Allow All" (auto-approve everything).',+ 'Scheduled tasks always run in Allow All mode.',];for (const p of perms) {