2ndbrain 2026.2.1 → 2026.2.2

package/.claude/settings.local.json

@@ -19,7 +19,8 @@
       "mcp__dude__get_project_context",
       "mcp__dude__create_project",
       "mcp__dude__create_issue",
-      "mcp__dude__update_issue"
+      "mcp__dude__update_issue",
+      "Bash(npx --version)"
     ]
   }
 }

package/PERFORMANCE-AUDIT.md

@@ -0,0 +1,417 @@
+# Performance Audit Report
+
+**Project:** 2ndbrain v0.5.0
+**Date:** 2026-02-01
+**Scope:** Full source code review (~5,600 LOC across 18 JS files + 1 bash script)
+
+---
+
+## Executive Summary
+
+2ndbrain is a single-user personal assistant running on low-power hardware (e.g., Raspberry Pi 5). Performance requirements are modest -- the system processes one message at a time and serves a single web admin user. Most performance issues identified are relevant for long-running uptime (days/weeks), not peak throughput. The most impactful findings are synchronous file I/O blocking the event loop, sequential embedding processing, and missing caching for repeated database queries.
+
+**Overall Assessment:** The performance profile is acceptable for the intended use case. The issues below are ordered by impact and should be addressed as the system scales or as uptime requirements increase.
+
+| Priority | Count |
+|----------|-------|
+| High     | 3     |
+| Medium   | 7     |
+| Low      | 6     |
+
+---
+
+## High Priority
+
+### PERF-01: Synchronous File I/O Blocks Event Loop
+
+**File:** `src/attachments/store.js:102, 105`
+
+```javascript
+fs.mkdirSync(absoluteDir, { recursive: true });  // line 102
+fs.writeFileSync(absolutePath, fileBuffer);       // line 105
+```
+
+Attachment saving uses synchronous `mkdirSync` and `writeFileSync`. These block the entire Node.js event loop for the duration of the disk operation. On an SD card (common for Raspberry Pi), a large file write could block for hundreds of milliseconds, during which:
+
+- Telegram long-polling cannot process new updates
+- The web admin panel becomes unresponsive
+- Typing indicator refreshes are delayed
+- Rate limiter drain timers are delayed
+
+Additional synchronous file operations that block during startup (acceptable but worth noting):
+- `src/index.js:61-93` -- `setupRuntimeFiles()` uses `mkdirSync`, `copyFileSync`, `chmodSync`
+- `src/config.js:15-23` -- `.env` migration and directory creation
+- `src/mcp/config.js:26-27, 49, 69` -- MCP config file writes
+
+**Impact:** Event loop stalls proportional to file size and disk speed.
+
+**Recommendation:** Replace `mkdirSync`/`writeFileSync` with `fs.promises.mkdir`/`fs.promises.writeFile` in the attachment store. Startup file operations can remain synchronous since they run before the event loop serves requests.
+
+### PERF-02: Sequential Embedding Processing
+
+**File:** `src/embeddings/worker.js:168-178`
+
+```javascript
+for (const row of result.rows) {
+  try {
+    await this._processRow(row);  // sequential
+  } catch (err) { ... }
+}
+```
+
+Each embedding is processed sequentially: fetch source text from DB, call OpenAI API, write vector back to DB. With OpenAI API latency of ~200-500ms per call and a batch size of 10, processing takes 2-5 seconds per batch with a 5-second poll interval.
+
+For a backlog of 1,000 messages, embedding takes ~8-17 minutes. For 10,000 messages (e.g., after a model switch that nullifies all vectors), it takes ~1.5-3 hours.
+
+**Impact:** Slow embedding generation after initial setup or model changes.
+
+**Recommendation:** Process embeddings concurrently within each batch using `Promise.allSettled()` with a concurrency limit of 3-5. This would reduce per-batch time to ~400-1000ms:
+
+```javascript
+const CONCURRENCY = 5;
+for (let i = 0; i < result.rows.length; i += CONCURRENCY) {
+  const batch = result.rows.slice(i, i + CONCURRENCY);
+  await Promise.allSettled(batch.map(row => this._processRow(row)));
+}
+```
+
+### PERF-03: Per-Log Database INSERT
+
+**File:** `src/logging.js:42-52`
+
+```javascript
+if (this._pool) {
+  try {
+    await this._pool.query(
+      'INSERT INTO system_logs (level, source, content) VALUES ($1, $2, $3)',
+      [level, source, content],
+    );
+  } catch (err) { ... }
+}
+```
+
+Every log statement issues a separate `INSERT` query to PostgreSQL. The logger methods (`debug`, `info`, `warn`, `error`) return the promise from `_log`, but callers do not await them -- meaning log writes are fire-and-forget but still consume database connections from the pool.
+
+During heavy logging (e.g., debug level with embedding worker processing), this could saturate the connection pool (default 10 connections in pg) and delay actual application queries.
+
+**Impact:** Database connection pool contention under heavy logging. Each log adds ~1-5ms of database overhead.
+
+**Recommendation:** Implement batched log writing -- queue log entries in memory and flush to the database in a single multi-row INSERT every N seconds or every M entries:
+
+```javascript
+// Example: batch insert every 5 seconds or 50 entries
+INSERT INTO system_logs (level, source, content) VALUES
+  ($1, $2, $3), ($4, $5, $6), ...
+```
+
+---
+
+## Medium Priority
+
+### PERF-04: Array.reverse() on Every History Fetch
+
+**Files:** `src/claude/conversation.js:67`, `src/hooks/lifecycle.js:256`
+
+```javascript
+// conversation.js:58-67
+const result = await this.db.query(
+  `SELECT ... FROM conversation_messages ORDER BY created_at DESC LIMIT $1`,
+  [effectiveLimit],
+);
+return result.rows.reverse();
+```
+
+The query sorts `DESC` to get the N most recent rows, then reverses the array in JavaScript to get chronological order. With the default threshold of 100 messages, this creates and copies a 100-element array on every call.
+
+The same pattern appears in `lifecycle.js:250-256` where 20 rows are fetched DESC and reversed.
+
+**Impact:** Minor -- O(n) array copy per call. Negligible for current sizes but wasteful.
+
+**Recommendation:** Use a subquery to get the correct order from SQL:
+
+```sql
+SELECT * FROM (
+  SELECT ... FROM conversation_messages ORDER BY created_at DESC LIMIT $1
+) sub ORDER BY created_at ASC
+```
+
+### PERF-05: No Caching for Dashboard and Health Queries
+
+**File:** `src/web/server.js:172-228, 289-319`
+
+The dashboard handler issues 4 database queries per page load:
+1. `COUNT(*) FROM conversation_messages` (line 185)
+2. `SELECT ... FROM conversation_messages ORDER BY ... LIMIT 10` (line 197)
+3. `SELECT session_id ... LIMIT 1` (line 208)
+4. `SELECT ... FROM system_logs WHERE level = 'error' LIMIT 5` (line 217)
+
+The health endpoint issues `SELECT 1` on every request (line 302).
+
+The database page handler issues 4 queries including `pg_total_relation_size` (line 358-369) which scans system catalogs.
+
+**Impact:** Unnecessary database load if the dashboard is auto-refreshed or monitored.
+
+**Recommendation:** Add simple in-memory TTL caching (30-60 seconds) for dashboard stats and health checks. Example:
+
+```javascript
+class Cache {
+  constructor(ttlMs = 30000) { ... }
+  get(key) { ... }
+  set(key, value) { ... }
+}
+```
+
+### PERF-06: Array.shift() in Rate Limiter Hot Path
+
+**File:** `src/rate-limiter.js:30-32`
+
+```javascript
+while (this._timestamps.length > 0 && this._timestamps[0] <= cutoff) {
+  this._timestamps.shift();  // O(n) per call
+}
+```
+
+`Array.shift()` is O(n) because it copies all remaining elements forward. With `maxPerMinute` of 10-30, the array is small and the cost is negligible. However, if rate limits are increased significantly, this becomes a hot path.
+
+**Impact:** Negligible at current scale. O(n^2) total cost over a sliding window cycle.
+
+**Recommendation:** Track the window start index instead of shifting, and reset the array when the index passes halfway:
+
+```javascript
+_prune() {
+  const cutoff = Date.now() - WINDOW_MS;
+  while (this._startIdx < this._timestamps.length && this._timestamps[this._startIdx] <= cutoff) {
+    this._startIdx++;
+  }
+  if (this._startIdx > this._timestamps.length / 2) {
+    this._timestamps = this._timestamps.slice(this._startIdx);
+    this._startIdx = 0;
+  }
+}
+```
+
+### PERF-07: No Connection Pool Configuration
+
+**File:** `src/db/pool.js:6-8`
+
+```javascript
+const pool = new Pool({
+  connectionString: config.DATABASE_URL,
+});
+```
+
+The pg pool uses default settings: `max: 10` connections, `idleTimeoutMillis: 10000`, `connectionTimeoutMillis: 0` (infinite). For a single-user bot on a Raspberry Pi:
+
+- 10 connections is likely excessive for PostgreSQL's memory overhead (~10MB each)
+- Infinite connection timeout means a query will wait forever if the pool is exhausted
+- No `statement_timeout` to catch runaway queries
+
+**Impact:** Excessive memory usage on constrained hardware; potential hangs on pool exhaustion.
+
+**Recommendation:** Configure the pool explicitly:
+
+```javascript
+const pool = new Pool({
+  connectionString: config.DATABASE_URL,
+  max: 5,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 5000,
+  statement_timeout: 30000,
+});
+```
+
+### PERF-08: `execSync` Blocks Event Loop During Startup
+
+**File:** `src/index.js:103`
+
+```javascript
+const version = execSync('claude --version', {
+  timeout: 10_000,
+  encoding: 'utf-8',
+}).trim();
+```
+
+`execSync` blocks the entire event loop for up to 10 seconds. During startup this is less critical since no requests are being served, but if `claude` is slow to respond (e.g., network lookup, first-time `npx` download), the web admin panel won't start until this completes.
+
+**Impact:** Startup delay of up to 10 seconds if `claude --version` is slow.
+
+**Recommendation:** Use async `execFile` or `spawn` with a promise wrapper. This allows the web server to start serving the settings page in parallel.
+
+### PERF-09: String Concatenation in HTTP Response Handlers
+
+**File:** `src/mcp/embed-server.js:48-49`
+
+```javascript
+let data = '';
+res.on('data', (chunk) => { data += chunk; });
+```
+
+String concatenation in a loop creates intermediate strings that must be garbage collected. For typical embedding API responses (~5-20KB), this is negligible. For larger responses, using an array and join would be more efficient.
+
+The same pattern appears in `src/telegram/bot.js` for the API call response, but there it correctly uses `Buffer.concat` (line 420).
+
+**Impact:** Minor -- only affects embedding API responses.
+
+**Recommendation:** Use the array-and-join pattern for consistency:
+
+```javascript
+const chunks = [];
+res.on('data', (chunk) => chunks.push(chunk));
+res.on('end', () => {
+  const data = Buffer.concat(chunks).toString('utf-8');
+  ...
+});
+```
+
+### PERF-10: Unbounded Rate Limiter Queue
+
+**File:** `src/rate-limiter.js:87-89`
+
+```javascript
+return new Promise((resolve) => {
+  this._queue.push({ resolve });
+  this._scheduleDrain();
+});
+```
+
+The rate limiter queue grows without bound. If messages arrive faster than the rate limit allows, the queue accumulates promises. Each queued promise holds a reference to its closure, preventing garbage collection.
+
+At 10 calls/minute for Claude, a burst of 100 messages would queue 90 promises, each waiting up to 9 minutes. For Telegram at 30/minute, the queue drains faster but is still unbounded.
+
+**Impact:** Memory growth during sustained bursts. Each queued item is small (~100 bytes), so 100 items is ~10KB -- negligible. But in degenerate cases (e.g., bot added to a group chat receiving hundreds of messages), the queue could grow significantly.
+
+**Recommendation:** Add a maximum queue depth with a rejection behavior:
+
+```javascript
+if (this._queue.length >= MAX_QUEUE_DEPTH) {
+  return Promise.reject(new Error('Rate limit queue full'));
+}
+```
+
+---
+
+## Low Priority
+
+### PERF-11: nextCronDate Scans Up to 527,040 Minutes
+
+**File:** `src/scheduler/worker.js:26-48`
+
+```javascript
+for (let i = 0; i < MAX_SCAN_MINUTES; i++) {  // MAX_SCAN_MINUTES = 527,040
+  if (matcher.match(candidate)) {
+    return new Date(candidate.getTime());
+  }
+  candidate.setMinutes(candidate.getMinutes() + 1);
+}
+```
+
+For each scheduled task, the worst case scans ~366 days of minutes (527,040 iterations) to find the next match. For well-formed cron expressions this completes quickly (usually < 60 iterations), but a pathological expression like `0 0 31 2 *` (Feb 31) would scan all 527K minutes before returning null.
+
+Additionally, a new `cron.schedule()` task object is created just to access the matcher (line 28-31), which is wasteful.
+
+**Impact:** Occasional CPU spike during scheduler initialization if tasks have unusual expressions.
+
+**Recommendation:** Consider using a dedicated cron-parsing library that computes next-run analytically rather than by minute-scanning.
+
+### PERF-12: Dashboard Queries Not Parallelized
+
+**File:** `src/web/server.js:184-226`
+
+The dashboard handler runs 4 sequential database queries with `await` between each. These queries are independent and could run concurrently:
+
+```javascript
+const [countRes, recent, session, errors] = await Promise.all([
+  this._db.query('SELECT COUNT(*)::int ...'),
+  this._db.query('SELECT ... FROM conversation_messages ... LIMIT 10'),
+  this._db.query('SELECT session_id ... LIMIT 1'),
+  this._db.query('SELECT ... FROM system_logs ... LIMIT 5'),
+]);
+```
+
+**Impact:** Dashboard page load takes ~4x the single-query latency instead of ~1x.
+
+**Recommendation:** Use `Promise.all` or `Promise.allSettled` for independent queries.
+
+### PERF-13: Lifecycle Hook Conversation History Fetch is Redundant
+
+**File:** `src/hooks/lifecycle.js:248-264`
+
+The `on_pre_claude` hook fetches the 20 most recent conversation messages and attaches them to the context as `conversationContext`. However, this context doesn't appear to be used by the Claude bridge invocation at `src/index.js:198-202` -- the bridge only receives `text`, `sessionId`, and `systemPrompt`. The conversation context is fetched and then discarded.
+
+**Impact:** Unnecessary database query and memory allocation on every message.
+
+**Recommendation:** Remove the conversation history fetch from the hook if it's not consumed downstream. If it's intended for future use, add a feature flag to skip it.
+
+### PERF-14: Compaction Loads All Old Messages Into Memory
+
+**File:** `src/claude/conversation.js:146-161`
+
+```javascript
+const oldMessages = await this.db.query(
+  `SELECT id, created_at, role, content FROM conversation_messages
+   ORDER BY created_at ASC LIMIT $1`,
+  [removeCount],
+);
+```
+
+With a threshold of 100 and `keepRecent` of 20, compaction loads up to 80 messages into memory. With an average message size of ~500 bytes, this is ~40KB -- negligible. However, if the threshold is increased to 1000 or messages are very long, this could consume significant memory.
+
+The messages are then formatted into a single string and sent to Claude for summarization (line 159-161), which could produce a very large prompt.
+
+**Impact:** Memory spike proportional to `HISTORY_COMPACT_THRESHOLD * avg_message_size`.
+
+**Recommendation:** For large thresholds, consider streaming or chunked summarization.
+
+### PERF-15: Typing Indicator Interval Overhead
+
+**File:** `src/telegram/bot.js:331-344`
+
+Each active typing indicator creates a `setInterval` that fires every 4 seconds, making an HTTPS request to Telegram. While only one conversation is active at a time (single user), the interval continues even if the Claude response is assembling quickly.
+
+**Impact:** Unnecessary network traffic (~1 request/4 seconds during processing). Negligible bandwidth but adds noise to logs and consumes a connection slot.
+
+**Recommendation:** Consider using a single pending-typing flag checked by the poll loop instead of per-chat intervals.
+
+### PERF-16: Web Admin HTML Templates Regenerated Per Request
+
+**File:** `src/web/server.js:595-1255`
+
+All HTML templates (`layoutHTML`, `dashboardHTML`, `settingsHTML`, `logsHTML`, `databaseHTML`) are generated from scratch on every request via string concatenation. The CSS (~280 lines) is inlined in every page response.
+
+For a single-user admin panel, this is acceptable. The CSS is ~5KB and the templates are simple string concatenation.
+
+**Impact:** Negligible for single-user access. ~5KB overhead per page from repeated CSS.
+
+**Recommendation:** Optional: Extract CSS to a static file served with cache headers. This would also enable browser caching.
+
+---
+
+## Architecture Notes
+
+### What Works Well
+
+1. **Single-threaded simplicity** -- The application avoids concurrency complexity by processing one message at a time through the Claude bridge. This eliminates most race condition classes.
+
+2. **Event-driven lifecycle hooks** -- The hook pipeline cleanly separates concerns without adding overhead. Sequential handler execution prevents ordering bugs.
+
+3. **Rate limiter design** -- The sliding-window rate limiter with queuing is an effective pattern that backpressures callers without dropping requests.
+
+4. **Minimal dependencies** -- Only 5 runtime dependencies (express, pg, node-cron, dotenv, open), which minimizes supply chain risk and keeps the bundle small.
+
+5. **Background workers with overlap guards** -- Both the embedding worker and scheduler worker use `_processing` flags to prevent overlapping iterations, which is appropriate for the polling pattern.
+
+### Scaling Considerations
+
+If the application were to scale beyond single-user:
+
+1. **Database queries should be indexed** -- The `conversation_messages` table is queried by `created_at DESC` frequently. Ensure a B-tree index exists on `created_at`.
+
+2. **Connection pooling** would need to be properly sized per concurrent user.
+
+3. **The Claude bridge is single-process** -- Only one Claude subprocess runs at a time. Multiple users would need a queue or multiple bridge instances.
+
+4. **The scheduler checks `claudeBridge.isActive()`** before running tasks (line 183). This means scheduled tasks are delayed while any user message is being processed. For multi-user, the scheduler would need its own bridge instance.
+
+---
+
+*End of Performance Audit Report*

package/README.md

@@ -1,70 +1,123 @@
 # 2ndbrain
 
-An always-on Node.js npx service that bridges Telegram messges to Claude with
-* persistent conversation history (logs)
-* receive text messages w/ attachments
-* slash commands
-* send text message responses w/ "Typing" indicator
-* whitelist users that it will interact with (multi-layered)
-* can run local commands, access local postgres (mcp) (whitelisted)
+A personal, always-on AI assistant that lives on your local network. **2ndbrain** bridges Telegram to Claude via a Node.js service, giving you a private conversational AI with persistent memory, a knowledge platform, and full access to local tools — all from your phone.
+
+You set it up on a device on your LAN (e.g. a Raspberry Pi 5), and you — and only you — interact with it by chatting over Telegram.
+
+
+## How It Works
+
+```
+Telegram  ──long-polling──▸  2ndbrain  ──subprocess──▸  Claude CLI
+                                │                          │
+                                │                     MCP tools
+                                │                     (postgres, embeddings,
+                                │                      shell commands)
+                                │
+                           PostgreSQL
+                         (history, knowledge,
+                          projects, journal,
+                          embeddings)
+```
+
+1. Messages arrive from Telegram via long-polling (no public URL required)
+2. Slash commands are routed to built-in handlers; everything else goes to Claude
+3. Claude is spawned as a subprocess with access to MCP tools (database, semantic search, whitelisted shell commands)
+4. Responses stream back through Telegram with a typing indicator
+5. All conversations are persisted in PostgreSQL for recall and search
+
+
+## Integrations
+
+| Integration | Role |
+|---|---|
+| **Telegram Bot API** | Messaging interface — long-polling, attachments (photos, docs, audio, video, voice), typing indicators |
+| **Claude CLI** | Conversational AI — spawned as subprocess with streaming JSON, thinking mode, session continuity |
+| **PostgreSQL + pgvector** | Persistent storage — conversation history, knowledge graph, projects, journal, vector embeddings with HNSW indexing |
+| **Model Context Protocol (MCP)** | Tool framework — gives Claude direct access to the database (`pg` server) and a custom `embed_query` tool for semantic search |
+| **OpenAI Embeddings API** | Vector embeddings — optional provider for semantic search (configurable model and dimensions) |
+| **Express** | Web admin dashboard — settings, environment config, activity logs (LAN-only) |
+
+
+## Features
+
+### Conversation
+- Persistent conversation history with session tracking
+- Auto-compaction when history exceeds a configurable threshold
+- Rate limiting for both Claude calls and Telegram sends
+- Attachment storage (photos, documents, audio, video, voice) in `~/data`
+
+### Skills (Claude-managed via MCP)
+
+| Skill | Description |
+|---|---|
+| **Knowledge Graph** | Entities and relationships with full-text search and embedding queue |
+| **Journal** | Timestamped personal notes with semantic search |
+| **Project Management** | Projects with specifications and issues, completion tracking |
+| **Scheduler** | Recurring tasks via cron expressions with timezone support |
+| **Recall** | Unified semantic search across journal, knowledge, projects, and history |
+| **System Ops** | Read-only diagnostics — memory, disk, uptime, database status, logs |
+
+### Slash Commands
+
+| Command | Action |
+|---|---|
+| `/status` | Current system status |
+| `/health` | Health check across all subsystems |
+| `/restart` | Restart the service |
+| `/reboot` | Reboot the host |
+| `/stop` | Graceful shutdown |
+| `/new` | Start a new conversation session |
+| `/help` | List available commands |
+
+### Security
+- Whitelisted Telegram users (multi-layered)
+- Whitelisted MCP tools and shell commands
+- Configurable file-edit path restrictions
+- LAN-only web admin interface
+
+### Lifecycle Hooks
+Custom scripts that run at startup, shutdown, pre/post Claude invocation, and on errors.
 
 
 ## Setup
 
-* Start the `npx ...` runner on boot
-* Ensure that local postgres & MCP are ready
-* Ensure that claude-cli is ready
+1. Ensure **PostgreSQL** is running with the `pgvector` extension
+2. Ensure **claude-cli** is installed and configured
+3. Create a `.env` file at `~/.2ndbrain/.env` (see Configuration below)
+4. Start the service: `npx 2ndbrain`
+5. (Optional) Configure to start on boot via systemd or similar
 
 
-## Vision
+## Configuration
 
-* You setup `2ndbrain` on a computer on your LAN (e.g. rapsberry pi 5)
-* You, and only you, can access with it by chatting over Telegram
-* **2ndbrain** uses Claude + local MCP tools to do stuff and respond to you
-* Web server interface
-  * Setup wizard
-  * Adjust settings & environment variables
-  * View activity logs
-* GPIO interaction
-* Auto-compact history
-* Errors get pushed to the user
-* Graceful shutdown/restart
-* Rate-limiting of Claude and Telegram
-* Store attachments in `~/data`
-* Vector embeddings of db records
+All configuration lives in `~/.2ndbrain/.env`:
 
+| Category | Key Variables |
+|---|---|
+| **Required** | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ALLOWED_USERS`, `DATABASE_URL` |
+| **Claude** | `CLAUDE_MODEL`, `CLAUDE_THINKING`, `CLAUDE_TIMEOUT`, `CLAUDE_MAX_BUDGET` |
+| **MCP** | `MCP_CONFIG_PATH`, `MCP_TOOLS_WHITELIST`, `COMMANDS_WHITELIST` |
+| **Embeddings** | `EMBEDDING_PROVIDER`, `EMBEDDING_API_KEY`, `EMBEDDING_MODEL`, `EMBEDDING_DIMENSIONS` |
+| **Rate Limits** | `RATE_LIMIT_CLAUDE` (default 10/min), `RATE_LIMIT_TELEGRAM` (default 30/min) |
+| **Web Admin** | `WEB_PORT`, `WEB_BIND`, `AUTO_OPEN_BROWSER` |
+| **Storage** | `DATA_DIR` (default `~/data`) |
+| **Conversation** | `HISTORY_COMPACT_THRESHOLD` (default 100) |
+| **Security** | `FILE_EDIT_PATHS` |
+| **Logging** | `LOG_LEVEL` |
 
-## Slashes
-
-Enter slash commands in Telegram messages to perform tasks
-
-`/status`
-`/health`
-`/restart`
-`/reboot`
-`/stop`
- 
 
 ## Data Schema
 
-* Projects(id, created, updated, name)
-  * Specifications(id, created, updated, project_id, note)
-  * Issues(id, created, updated, note, completed)
-* _knowledge_graph
-  * Nodes(id, created, updated, name, note)
-  * Edges(id, created, updated, node1_id, node2_id, name)
-* Journal(id, created, updated, note)
-* History(id, created, updated, user_id, message_id, content)
-* Logs(id, timestamp, content, level)
-* Embeddings(id, created, updated, entity_type, vector)
-
-
-## Claude Stuff
-
-Skills <TBD>
-Hooks <TBD>
-
-
-## Caveats
-
-* Run Claude w/ top model, thinking, ?accept edits?
+- **Projects** (id, created, updated, name)
+  - Specifications (id, created, updated, project_id, note)
+  - Issues (id, created, updated, note, completed)
+- **Knowledge Graph**
+  - Nodes (id, created, updated, name, note)
+  - Edges (id, created, updated, node1_id, node2_id, name)
+- **Journal** (id, created, updated, note)
+- **Conversation Messages** (id, created, updated, user_id, message_id, content, session_id)
+- **System Logs** (id, timestamp, content, level)
+- **Attachments** (id, created, updated, file_path, metadata)
+- **Scheduled Tasks** (id, cron_expression, timezone, next_run, error tracking)
+- **Embeddings** (id, created, updated, entity_type, vector)

package/SECURITY-AUDIT.md

@@ -0,0 +1,413 @@
+# Security & Reliability Audit Report
+
+**Project:** 2ndbrain v0.5.0
+**Date:** 2026-02-01
+**Scope:** Full source code review (~5,600 LOC across 18 JS files + 1 bash script)
+
+---
+
+## Executive Summary
+
+2ndbrain is a Node.js service bridging Telegram to Claude CLI, with a PostgreSQL backend and an Express-based admin panel. The architecture follows a defense-in-depth approach with Telegram user whitelisting, command whitelisting, and rate limiting. However, several gaps remain -- the most critical being the unauthenticated web admin panel that can modify all credentials and system configuration.
+
+| Severity | Count |
+|----------|-------|
+| Critical | 2     |
+| High     | 6     |
+| Medium   | 8     |
+| Low      | 6     |
+
+---
+
+## Critical
+
+### SEC-01: Unauthenticated Web Admin Panel
+
+**Files:** `src/web/server.js:124-131`
+
+All web admin routes are served without any authentication:
+
+```
+app.get('/',          ... _handleDashboard)
+app.get('/settings',  ... _handleSettings)
+app.post('/settings', ... _handleSaveSettings)
+app.post('/database/migrate', ... _handleRunMigrations)
+```
+
+The settings page allows reading masked versions of, and writing new values for: `TELEGRAM_BOT_TOKEN`, `DATABASE_URL`, `EMBEDDING_API_KEY`, and all other configuration. The database page allows running arbitrary schema migrations.
+
+While the default bind address is `127.0.0.1`, nothing prevents a user from setting `WEB_BIND=0.0.0.0` (there is even a UI field for it at `src/web/server.js:76`), which exposes the entire admin panel to the network.
+
+**Impact:** Full account takeover. An attacker on the local network (or remotely if `WEB_BIND` is `0.0.0.0`) can replace the Telegram bot token, database URL, or embedding API key with attacker-controlled values.
+
+**Recommendation:** Add authentication to the web admin panel (token-based, password, or at minimum an admin secret in the `.env`). If the panel must remain open, hard-enforce `127.0.0.1` binding and do not expose it as a configurable option.
+
+### SEC-02: No CSRF Protection on State-Changing Endpoints
+
+**Files:** `src/web/server.js:127, 131`
+
+`POST /settings` and `POST /database/migrate` have no CSRF token validation. Since the admin panel has no authentication, any page a local user visits can submit a form to `http://localhost:3000/settings` and overwrite credentials.
+
+**Impact:** A malicious website visited in the same browser can silently reconfigure the entire application.
+
+**Recommendation:** Add CSRF tokens to all POST forms. Even with authentication, CSRF protection is necessary.
+
+---
+
+## High
+
+### SEC-03: Database Credentials Visible in Process Arguments
+
+**File:** `src/mcp/config.js:35`
+
+```javascript
+args: ['-y', '@modelcontextprotocol/server-postgres', config.DATABASE_URL],
+```
+
+The full `DATABASE_URL` (including username and password) is passed as a command-line argument to the MCP postgres server spawned by `npx`. Command-line arguments are visible to all users on the system via `ps aux`.
+
+**Impact:** Any local user can read database credentials from the process listing.
+
+**Recommendation:** Pass the connection string via an environment variable in the child process `env` option, not via `args`.
+
+### SEC-04: Error Messages Leak Internal Details to Telegram Users
+
+**File:** `src/index.js:261-263`
+
+```javascript
+const userMessage = isTimeout
+  ? 'Response timed out, please try again.'
+  : `Sorry, an error occurred: ${err.message}`;
+```
+
+Non-timeout error messages are forwarded verbatim to the Telegram user. `err.message` can contain database connection strings, file paths, stack traces from child process stderr, or other internal details.
+
+**Impact:** Information disclosure. Even though the Telegram user is whitelisted, the messages traverse Telegram's servers.
+
+**Recommendation:** Send a generic error message to users and log the full error internally. If the detail is useful, provide a reference ID that can be looked up in the logs.
+
+### SEC-05: `sudo reboot` Execution After Single-Factor Confirmation
+
+**File:** `src/telegram/commands.js:233`
+
+```javascript
+execSync('sudo reboot', { timeout: 10_000 });
+```
+
+The `/reboot` command executes `sudo reboot` after a single "YES" reply within 60 seconds. The confirmation flow relies solely on the Telegram user whitelist -- if the bot token is compromised (e.g., via SEC-01), an attacker can reboot the host.
+
+**Impact:** Denial of service / physical disruption of the host system.
+
+**Recommendation:** Consider removing the reboot command entirely, or require a secondary authentication factor (e.g., a passphrase, TOTP code, or physical button press).
+
+### SEC-06: Validate Command Hook Can Be Bypassed via Whitelist Patterns
+
+**File:** `hooks/validate-command.sh:278-280`
+
+Whitelisted commands bypass all subsequent security checks, including dangerous-command blocking and write-target inspection. If `COMMANDS_WHITELIST` contains an overly broad pattern (e.g., `*`), all commands including `sudo`, `rm -rf /`, and arbitrary writes become allowed.
+
+Additionally, the glob matching at line 134-140 checks the command prefix, but compound commands like `echo hello; rm -rf /` would be checked against the whitelist as the full string, not the individual subcommands. The dangerous-command check at lines 287-333 does inspect for embedded dangerous commands using grep patterns, but the whitelist check (Rule 1) runs first and exits 0 before those checks.
+
+**Impact:** A permissive whitelist pattern bypasses all safety checks.
+
+**Recommendation:** Always run the dangerous-command checks (Rule 2) regardless of whitelist match. The whitelist should only skip Rule 4/5 (read-only and default allow), not the unconditional block rules.
+
+### SEC-07: Missing Security Headers on Web Admin
+
+**File:** `src/web/server.js:116-148`
+
+The Express server sets no security headers:
+
+- No `Content-Security-Policy` (allows inline scripts, external resource loading)
+- No `X-Frame-Options` (clickjacking possible)
+- No `X-Content-Type-Options: nosniff`
+- No `Strict-Transport-Security`
+- No `Referrer-Policy`
+
+The admin panel contains inline `onclick` handlers (line 1032) which would need CSP allowances, but the absence of CSP entirely is worse.
+
+**Impact:** The admin panel is vulnerable to clickjacking and content injection attacks.
+
+**Recommendation:** Add a security headers middleware. At minimum: `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, and a restrictive `Content-Security-Policy`.
+
+### SEC-08: Full Process Environment Passed to Claude Subprocess
+
+**File:** `src/claude/bridge.js:47`
+
+```javascript
+env: { ...process.env },
+```
+
+The entire process environment -- including `DATABASE_URL`, `TELEGRAM_BOT_TOKEN`, `EMBEDDING_API_KEY`, and any other secrets -- is passed to the Claude CLI subprocess. Claude CLI can access these via its MCP tools or tool-use capabilities.
+
+**Impact:** If Claude's sandboxing is incomplete or a tool allows environment variable access, all application secrets are exposed.
+
+**Recommendation:** Construct a minimal environment for the Claude subprocess containing only required variables (PATH, HOME, etc.).
+
+---
+
+## Medium
+
+### SEC-09: Unvalidated Query Parameter Rendered in HTML
+
+**File:** `src/web/server.js:339-340`
+
+```javascript
+} else if (req.query.error) {
+  data.message = { type: 'error', text: req.query.error };
+}
+```
+
+The `error` query parameter from `/database?error=...` is set as the message text. It is later rendered through `esc()` at line 1114, so XSS is prevented. However, this pattern of reflecting user-controlled input is fragile -- if any template path omits the `esc()` call, it becomes an XSS vector.
+
+**Recommendation:** Validate and sanitize the error parameter, or use a flash message stored server-side.
+
+### SEC-10: No Rate Limiting on Web Admin Endpoints
+
+**File:** `src/web/server.js:116-148`
+
+While Telegram and Claude rate limiters exist, the web admin endpoints have none. An attacker could:
+- Rapidly POST to `/settings` to cause disk I/O (`.env` writes)
+- Repeatedly POST to `/database/migrate` to trigger migration attempts
+- Flood `/health` which issues a `SELECT 1` on every request
+
+**Recommendation:** Add basic rate limiting to web admin routes.
+
+### SEC-11: Database CREATE Statement Uses String Interpolation
+
+**File:** `src/embeddings/engine.js:224, 271`
+
+```javascript
+await this.db.query(`CREATE TABLE IF NOT EXISTS embeddings (
+  ...
+  vector VECTOR(${dimensions}),
+  ...
+)`);
+```
+
+The `dimensions` value is interpolated directly into SQL DDL. While the code validates it is a positive integer at `src/embeddings/engine.js:169-174`, this validation happens in the same class. If `_resolveDimensions` is called with `EMBEDDING_DIMENSIONS` containing a non-numeric value that passes `parseInt` (e.g., `"100; DROP TABLE users--"`), `parseInt` would return `100` and the injection would fail. However, this pattern is inherently risky.
+
+**Impact:** Low given current validation, but defense-in-depth is missing.
+
+**Recommendation:** Add an explicit integer range check (e.g., `dim > 0 && dim <= 10000`) before interpolation into DDL.
+
+### SEC-12: `ensureDatabase` Uses Unsanitized Database Name in DDL
+
+**File:** `src/db/pool.js:39`
+
+```javascript
+await client.query(`CREATE DATABASE "${dbName}"`);
+```
+
+The database name is extracted from the URL pathname and used in a `CREATE DATABASE` statement with double-quote escaping. If the URL contains a database name with double quotes (e.g., `postgresql://.../"test"--drop`), the escaping could be bypassed. In practice this is unlikely since the user controls the `.env` file.
+
+**Impact:** Low -- self-inflicted SQL injection via config file.
+
+**Recommendation:** Use `pg_catalog.quote_ident()` or validate the database name against `[a-zA-Z0-9_-]+`.
+
+### SEC-13: Telegram Bot Token in URLs and Logs
+
+**Files:** `src/telegram/bot.js:401, 372`
+
+```javascript
+const url = new URL(`/bot${this._token}/${method}`, TELEGRAM_API_BASE);
+```
+
+The bot token is embedded in every API URL. If an error occurs during an HTTP request and the URL is logged, the token is exposed. The `_getFileUrl` method at line 372 also constructs download URLs containing the token. While the logger appears to not log full URLs directly, any unexpected error that includes the request URL would leak the token.
+
+**Recommendation:** Never log full Telegram API URLs. Mask the token portion in error messages.
+
+### SEC-14: Sensitive Data Stored in Logs Table
+
+**File:** `src/logging.js:44-47`
+
+All log entries, including those containing user messages and error details, are persisted to the `system_logs` database table. The web admin logs page (`/logs`) displays these without any redaction. User messages may contain personal information, and error logs may contain credentials or tokens.
+
+**Recommendation:** Implement log-level content filtering, redact known secret patterns, and consider adding access controls to the logs page.
+
+### SEC-15: Command Validation Script Has Sed-Based JSON Parsing Fallback
+
+**File:** `hooks/validate-command.sh:38-42`
+
+When `jq` is not installed, command extraction falls back to `sed`:
+
+```bash
+COMMAND=$(printf '%s' "$INPUT" \
+  | tr '\n' ' ' \
+  | sed 's/.*"command"[[:space:]]*:[[:space:]]*"//' \
+  | sed 's/"[[:space:]]*[,}].*//' \
+  | sed 's/\\"/"/g; s/\\\\/\\/g')
+```
+
+This fallback cannot correctly handle all JSON edge cases (e.g., nested quotes, unicode escapes, multi-line commands). A specially crafted command string could cause incorrect extraction, potentially allowing the wrong string to be validated.
+
+**Recommendation:** Require `jq` as a dependency, or use Node.js for JSON parsing instead of bash.
+
+### SEC-16: Relative Path Assumption in Command Validator
+
+**File:** `hooks/validate-command.sh:176`
+
+```bash
+"."*|[^/]*) return 0 ;;  # Relative paths resolve under cwd (within home)
+```
+
+The validator assumes relative paths resolve within the home directory. However, Claude CLI's working directory is configurable via the `--cwd` flag or by the runtime directory. If the working directory is set to `/`, relative paths like `../etc/passwd` would resolve outside home.
+
+**Impact:** Depends on Claude CLI's working directory configuration.
+
+**Recommendation:** Resolve relative paths to absolute before validation, using the actual working directory.
+
+---
+
+## Low
+
+### SEC-17: No Input Length Validation
+
+**File:** `src/index.js:152`
+
+User messages from Telegram are saved to the database and forwarded to Claude without any length validation. Telegram allows messages up to 4096 characters, but captions and forwarded messages could be longer. Extremely large messages could cause:
+- Database storage bloat
+- Claude CLI buffer overflow or timeout
+- Memory pressure during compaction (all messages loaded into memory)
+
+**Recommendation:** Enforce a maximum message length (e.g., 10,000 chars) before processing.
+
+### SEC-18: `_executeConfirmed` Not Awaited
+
+**File:** `src/telegram/commands.js:200`
+
+```javascript
+this._executeConfirmed(chatId, command);
+return true;
+```
+
+The async `_executeConfirmed` method is called without `await`, making it fire-and-forget. If it throws after the `return true`, the error is an unhandled promise rejection. The method has its own try/catch (line 212-248), but any error in `this._sendPlain` within the catch block would be unhandled.
+
+**Recommendation:** Await the call, or add `.catch()` to handle edge cases.
+
+### SEC-19: Attachment MIME Type Derived from Untrusted Source
+
+**File:** `src/attachments/store.js:43-45`
+
+```javascript
+function extFromMime(mimeType) {
+  if (!mimeType) return 'bin';
+  return MIME_TO_EXT[mimeType] || mimeType.split('/').pop() || 'bin';
+}
+```
+
+The MIME type comes from Telegram's message data (client-provided). The fallback `mimeType.split('/').pop()` could produce unexpected extensions from crafted MIME types. While files are stored with UUID names (mitigating path-based attacks), the extension could confuse downstream consumers.
+
+**Recommendation:** Use a strict whitelist of allowed MIME types. Reject or default unknown types.
+
+### SEC-20: Unhandled Rejection Handler Only Logs
+
+**File:** `src/index.js:552-554`
+
+```javascript
+process.on('unhandledRejection', (reason) => {
+  logger.error('process', `Unhandled rejection: ${reason}`);
+});
+```
+
+Unhandled promise rejections are logged but do not trigger the `on_error` hook, shutdown, or user notification. In Node.js 15+, unhandled rejections terminate the process by default, but this handler prevents that. Silent failures accumulate.
+
+**Recommendation:** Either call `shutdown()` on unhandled rejections (as done for uncaught exceptions) or at minimum emit the `on_error` hook.
+
+### SEC-21: Conversation Compaction Is Not Transactional
+
+**File:** `src/claude/conversation.js:145-203`
+
+Compaction performs three sequential database operations (INSERT summary, then DELETE old messages) without wrapping them in a transaction. If the process crashes between the INSERT and DELETE, duplicate data accumulates. If it crashes after DELETE but before INSERT completes, messages are lost.
+
+**Recommendation:** Wrap the INSERT and DELETE in a database transaction.
+
+### SEC-22: Web Admin `.env` File Write Has No Locking
+
+**File:** `src/web/server.js:416-442`
+
+The `_writeEnvFile` method reads and rewrites the `.env` file without file locking. Concurrent POST requests to `/settings` could produce corrupted output. While unlikely with a single-user admin panel, it's a correctness issue.
+
+**Recommendation:** Use a file lock or serialize writes through an in-memory queue.
+
+---
+
+## Positive Findings
+
+The following security practices are well-implemented:
+
+- **Parameterized SQL queries** throughout -- SQL injection risk is minimal (`$1, $2, $3` pattern used consistently)
+- **HTML escaping** via `esc()` function applied consistently in all template outputs
+- **UUID-based attachment filenames** prevent path traversal and name collision
+- **Telegram user whitelist** provides a strong first layer of access control
+- **Secrets masked in UI** with `maskValue()` / `maskDatabaseUrl()`
+- **Bot token validated** before starting Telegram polling
+- **Dangerous command blocking** is comprehensive (sudo, rm -rf, shutdown, kill, network config, package managers)
+- **File write path validation** blocks writes to system directories unconditionally
+- **Rate limiting** on both Claude and Telegram prevents resource exhaustion
+- **Embed MCP server** binds to `127.0.0.1` only
+- **Signal handling** with graceful shutdown on SIGTERM/SIGINT
+
+---
+
+## Failure Points & Reliability
+
+### FP-01: No Retry Logic for Telegram API Calls
+
+**File:** `src/telegram/bot.js:398-453`
+
+`_apiCall` makes a single HTTPS request with no retry on transient failures (network timeouts, 429 rate limits, 500 server errors). The polling loop at line 131-133 has a fixed 5-second backoff with no exponential backoff.
+
+**Impact:** Temporary Telegram API outages cause message loss.
+
+### FP-02: No Timeout on File Downloads
+
+**File:** `src/telegram/bot.js:463-484`
+
+`_httpsGet` has no timeout. A stalled download from Telegram's file servers blocks the message handler indefinitely, preventing all other message processing.
+
+### FP-03: Session ID Race Condition on Concurrent Messages
+
+**File:** `src/claude/conversation.js:20-21, 109-111`
+
+`currentSessionId` is a mutable instance variable with no synchronization. If two Telegram messages arrive in rapid succession, the first may start a Claude invocation (which takes seconds to minutes), and the second may overwrite `currentSessionId` before the first completes.
+
+**Impact:** Messages saved with incorrect session IDs, corrupted conversation threading.
+
+### FP-04: Embedding Worker Duplicate Processing
+
+**File:** `src/embeddings/worker.js:150-157`
+
+The worker SELECTs rows with `vector IS NULL` and then updates them after processing. Between the SELECT and UPDATE, no row lock is held. If two workers were running (e.g., after a hot restart), both could process the same row.
+
+**Impact:** Wasted API calls and potential database constraint violations.
+
+### FP-05: Claude Subprocess Zombie After SIGTERM
+
+**File:** `src/claude/bridge.js:281-287`
+
+The `kill()` method sends `SIGTERM` and immediately sets `activeProcess = null`. If the child process ignores SIGTERM, no SIGKILL follow-up occurs. The process becomes a zombie.
+
+**Impact:** Resource leak, potential blocking of future invocations.
+
+### FP-06: Scheduler Task Has No Execution Timeout
+
+**File:** `src/scheduler/worker.js:243-316`
+
+`_executeTask` calls `claudeBridge.invoke()` which has a configurable timeout (default 120s). However, the scheduler worker itself has no per-task timeout. If the Claude timeout fails to trigger (e.g., due to a hung process that partially responds), the task blocks the scheduler indefinitely.
+
+### FP-07: Database Connection Loss Not Detected
+
+**File:** `src/db/pool.js:11-13`
+
+The pool's error handler only logs to console. There is no mechanism to notify the application that the database has become unavailable. The health endpoint checks with `SELECT 1` on each request, but background workers (embedding worker, scheduler) will fail silently and retry every poll interval without alerting the user.
+
+### FP-08: Compaction During Active Processing Can Lose Context
+
+**File:** `src/claude/conversation.js:124-129`
+
+Compaction checks `claudeBridge.isActive()` before starting, but the compaction itself takes significant time (it invokes Claude for summarization). A new user message could arrive and start processing while compaction is running, causing both to use Claude simultaneously.
+
+---
+
+*End of Security & Reliability Audit Report*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "2ndbrain",
-  "version": "2026.2.1",
+  "version": "2026.2.2",
   "description": "Always-on Node.js service bridging Telegram messaging to Claude AI with knowledge graph, journal, project management, and semantic search.",
   "main": "src/index.js",
   "bin": {

package/src/claude/bridge.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
+import path from 'node:path';
 
 /**
  * Claude CLI subprocess bridge (spec section 5).
@@ -41,9 +42,14 @@ class ClaudeBridge extends EventEmitter {
     const startTime = Date.now();
     const args = this._buildArgs(sessionId, systemPrompt);
 
+    this.logger.info('claude', `Spawning: claude ${args.join(' ')}`);
+
+    const runtimeDir = path.join(this.config.DATA_DIR, 'claude-runtime');
+
     return new Promise((resolve, reject) => {
       const proc = spawn('claude', args, {
         stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: runtimeDir,
         env: { ...process.env },
       });
 
@@ -55,6 +61,19 @@ class ClaudeBridge extends EventEmitter {
       const toolCalls = [];
       let resultData = null;
       let timedOut = false;
+      let receivedFirstOutput = false;
+
+      // Startup watchdog: warn if no stdout arrives within 30s
+      const startupTimeout = setTimeout(() => {
+        if (!receivedFirstOutput) {
+          this.logger.warn(
+            'claude',
+            'No output received from Claude CLI within 30s of spawn -- ' +
+            'subprocess may be stuck during MCP server initialization or permission prompt. ' +
+            `stderr so far: ${stderrBuffer.trim() || '(empty)'}`,
+          );
+        }
+      }, 30_000);
 
       // Set up the timeout guard
       const timeout = setTimeout(() => {
@@ -69,6 +88,12 @@ class ClaudeBridge extends EventEmitter {
 
       // Collect and parse stdout stream-json chunks
       proc.stdout.on('data', (chunk) => {
+        if (!receivedFirstOutput) {
+          receivedFirstOutput = true;
+          clearTimeout(startupTimeout);
+          this.logger.debug('claude', `First output received after ${Date.now() - startTime}ms`);
+        }
+
         stdoutBuffer += chunk.toString();
 
         // Process complete lines (NDJSON: one JSON object per line)
@@ -94,13 +119,21 @@ class ClaudeBridge extends EventEmitter {
         }
       });
 
-      // Monitor stderr for errors
+      // Monitor stderr for errors (log in real time for diagnostics)
       proc.stderr.on('data', (chunk) => {
-        stderrBuffer += chunk.toString();
+        const text = chunk.toString();
+        stderrBuffer += text;
+        for (const line of text.split('\n')) {
+          const trimmed = line.trim();
+          if (trimmed) {
+            this.logger.debug('claude-stderr', trimmed);
+          }
+        }
       });
 
       proc.on('close', (code) => {
         clearTimeout(timeout);
+        clearTimeout(startupTimeout);
         this.activeProcess = null;
 
         // Process any remaining data in the stdout buffer
@@ -172,7 +205,7 @@ class ClaudeBridge extends EventEmitter {
    * @private
    */
   _buildArgs(sessionId, systemPrompt) {
-    const args = ['-p', '--output-format', 'stream-json', '--verbose'];
+    const args = ['-p', '--output-format', 'stream-json', '--verbose', '--permission-mode', 'bypassPermissions'];
 
     if (sessionId) {
       // Continuation: resume an existing session
@@ -188,6 +221,11 @@ class ClaudeBridge extends EventEmitter {
       args.push('--mcp-config', this.config.MCP_CONFIG_PATH);
       args.push('--allowed-tools', this.config.MCP_TOOLS_WHITELIST);
 
+      const settingsPath = path.join(
+        this.config.DATA_DIR, 'claude-runtime', '.claude', 'settings.json',
+      );
+      args.push('--settings', settingsPath);
+
       if (this.config.CLAUDE_MAX_BUDGET) {
         args.push('--max-budget-usd', this.config.CLAUDE_MAX_BUDGET);
       }