build(obelisk): let Claude Code search its own session history

- SQLite + FTS5 index over ~/.claude JSONL transcripts. - Agent writes JS queries at runtime — same sandbox pattern as workflows. - Covers sessions, subagents, workflow executions, tool calls, and full-text search.
2026-05-30 03:21:35 +08:00
commit bc9b6dde72
10 changed files with 1307 additions and 0 deletions
@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 540 96" width="540" height="96">
+  <defs>
+    <radialGradient id="aurora" cx="0.5" cy="0.4" r="0.5">
+      <stop offset="0" stop-color="#f9a8d4" stop-opacity="0.9"/>
+      <stop offset="0.5" stop-color="#c084fc" stop-opacity="0.7"/>
+      <stop offset="1" stop-color="#818cf8" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="stone" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#94a3b8"/>
+      <stop offset="1" stop-color="#475569"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(8 8) scale(0.333)">
+    <ellipse cx="120" cy="50" rx="76" ry="48" fill="url(#aurora)"/>
+    <polygon points="120,40 106,64 134,64" fill="url(#stone)"/>
+    <polygon points="106,64 120,64 122,212 100,212" fill="url(#stone)"/>
+    <polygon points="120,64 134,64 140,212 122,212" fill="#334155"/>
+    <circle cx="70" cy="30" r="1.5" fill="#f9a8d4"/>
+    <circle cx="155" cy="18" r="1.8" fill="#ffffff"/>
+  </g>
+  <text x="100" y="46" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="38" font-weight="500" fill="#f0f6fc" letter-spacing="-0.4">Obelisk</text>
+  <text x="100" y="72" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="15" font-style="italic" fill="#8b949e">Let Claude Code search its own memory.</text>
+</svg>
@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 90" width="360" height="90">
+  <defs>
+    <radialGradient id="aurora" cx="0.5" cy="0.4" r="0.5">
+      <stop offset="0" stop-color="#f9a8d4" stop-opacity="0.9"/>
+      <stop offset="0.5" stop-color="#c084fc" stop-opacity="0.7"/>
+      <stop offset="1" stop-color="#818cf8" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="stone" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#94a3b8"/>
+      <stop offset="1" stop-color="#475569"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(8 8) scale(0.3125)">
+    <ellipse cx="120" cy="50" rx="76" ry="48" fill="url(#aurora)"/>
+    <polygon points="120,40 106,64 134,64" fill="url(#stone)"/>
+    <polygon points="106,64 120,64 122,212 100,212" fill="url(#stone)"/>
+    <polygon points="120,64 134,64 140,212 122,212" fill="#334155"/>
+    <circle cx="70" cy="30" r="1.5" fill="#f9a8d4"/>
+    <circle cx="155" cy="18" r="1.8" fill="#ffffff"/>
+  </g>
+  <text x="100" y="58" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="36" font-weight="500" fill="#f0f6fc" letter-spacing="-0.01em">Obelisk</text>
+</svg>
@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 540 96" width="540" height="96">
+  <defs>
+    <linearGradient id="aurora" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ec4899" stop-opacity="0"/>
+      <stop offset="0.5" stop-color="#a855f7" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#6366f1" stop-opacity="0.75"/>
+    </linearGradient>
+    <linearGradient id="stone" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#475569"/>
+      <stop offset="1" stop-color="#1e293b"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(8 8) scale(0.333)">
+    <ellipse cx="120" cy="40" rx="56" ry="40" fill="url(#aurora)"/>
+    <polygon points="120,40 106,64 134,64" fill="url(#stone)"/>
+    <polygon points="106,64 120,64 122,212 100,212" fill="url(#stone)"/>
+    <polygon points="120,64 134,64 140,212 122,212" fill="#1e293b"/>
+    <circle cx="80" cy="30" r="1.2" fill="#a855f7"/>
+    <circle cx="150" cy="20" r="1.5" fill="#6366f1"/>
+  </g>
+  <text x="100" y="46" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="38" font-weight="500" fill="#1f2328" letter-spacing="-0.4">Obelisk</text>
+  <text x="100" y="72" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="15" font-style="italic" fill="#6e7681">Let Claude Code search its own memory.</text>
+</svg>
@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 540 96" width="540" height="96">
+  <defs>
+    <linearGradient id="aurora" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ec4899" stop-opacity="0"/>
+      <stop offset="0.5" stop-color="#a855f7" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#6366f1" stop-opacity="0.75"/>
+    </linearGradient>
+    <linearGradient id="stone" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#475569"/>
+      <stop offset="1" stop-color="#1e293b"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(92 8) scale(0.333)">
+    <ellipse cx="120" cy="40" rx="56" ry="40" fill="url(#aurora)"/>
+    <polygon points="120,40 106,64 134,64" fill="url(#stone)"/>
+    <polygon points="106,64 120,64 122,212 100,212" fill="url(#stone)"/>
+    <polygon points="120,64 134,64 140,212 122,212" fill="#1e293b"/>
+    <circle cx="80" cy="30" r="1.2" fill="#a855f7"/>
+    <circle cx="150" cy="20" r="1.5" fill="#6366f1"/>
+  </g>
+  <text x="184" y="46" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="38" font-weight="500" fill="#1f2328" letter-spacing="-0.4">Obelisk</text>
+  <text x="184" y="72" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="15" font-style="italic" fill="#6e7681">Let Claude Code search its own memory.</text>
+</svg>
@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 90" width="360" height="90">
+  <defs>
+    <linearGradient id="aurora" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ec4899" stop-opacity="0"/>
+      <stop offset="0.5" stop-color="#a855f7" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#6366f1" stop-opacity="0.75"/>
+    </linearGradient>
+    <linearGradient id="stone" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#475569"/>
+      <stop offset="1" stop-color="#1e293b"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(8 8) scale(0.3125)">
+    <ellipse cx="120" cy="40" rx="56" ry="40" fill="url(#aurora)"/>
+    <polygon points="120,40 106,64 134,64" fill="url(#stone)"/>
+    <polygon points="106,64 120,64 122,212 100,212" fill="url(#stone)"/>
+    <polygon points="120,64 134,64 140,212 122,212" fill="#1e293b"/>
+    <circle cx="80" cy="30" r="1.2" fill="#a855f7"/>
+    <circle cx="150" cy="20" r="1.5" fill="#6366f1"/>
+  </g>
+  <text x="100" y="58" font-family="Iowan Old Style, Charter, Georgia, serif" font-size="36" font-weight="500" fill="#1f2328" letter-spacing="-0.01em">Obelisk</text>
+</svg>
@@ -0,0 +1,122 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/obelisk-wordmark-d.svg">
+  <img src=".github/assets/obelisk-wordmark-l2.svg" alt="Obelisk" width="540">
+</picture>
+
+Every past session, subagent, and workflow — searchable in natural language.
+
+</picture>
+
+</div>
+
+<br />
+
+<div align="center">
+  <img src=".github/assets/demo.png" alt="Obelisk in action" width="540">
+  <br />
+  <p>Ask in plain language. The agent writes the query, runs it, answers.</p>
+</div>
+
+---
+
+## What you can ask
+
+```
+/obelisk 上次那个 auth 的 bug 我怎么修的
+/obelisk 哪些文件这周被反复修改
+/obelisk 最近 workflow 跑出来什么结果
+/obelisk 我让 subagent 做过哪些代码 review
+```
+
+Anything Claude Code has done before — sessions, tool calls, subagents, workflows — is indexed and searchable. Ask in your own words.
+
+## Install
+
+```bash
+npx skills add tommy0103/obelisk
+```
+
+Or manually: copy `obelisk/` into your project's `.claude/skills/`.
+
+Then in any Claude Code session:
+
+```
+/obelisk <your question>
+```
+
+First run builds the index (~5 seconds for 100 sessions). After that it rebuilds incrementally.
+
+### Requires 
+
+- Node.js 22+ (uses built-in node:sqlite with FTS5)
+- Claude Code with skills support.
+
+## What gets indexed
+
+| Layer | Source | What's captured |
+|-------|--------|----------------|
+| **Sessions** | `<project>/<sessionId>.jsonl` | Title, project, timestamps, git branch |
+| **Messages** | user + assistant turns | Full text, model, token usage, parent chain |
+| **Tool calls** | every tool invocation | Tool name, input, file paths touched |
+| **Subagents** | `subagents/agent-<id>.jsonl` | Agent type, description, full conversation |
+| **Workflows** | `workflows/wf_<runId>.json` | Script, structured result, agent count |
+| **Workflow agents** | `subagents/workflows/wf_<runId>/` | Per-agent transcripts linked to workflow |
+
+Full-text search via FTS5 covers all message text across every layer.
+
+## How it works
+
+```
+You ask a question
+  ↓
+Agent writes a JS query against the SQLite index
+  ↓
+Runs it via node runtime.mjs --query <script>
+  ↓
+Reads the JSON result, answers you in natural language
+```
+
+The core idea: **don't design a query DSL** — let the agent write code. An agent that can write workflow scripts can also write query scripts. Same sandbox, same mental model.
+
+The agent has a two-tier API. Most questions only need the simple layer:
+
+**Simple API** — taught directly in the skill prompt:
+
+- `search(text)` — FTS5 full-text search, returns matches with surrounding context
+- `context(uuid)` — full story around a message (parent chain, subagent/workflow metadata)
+- `sql(query, ...params)` — raw SQL for anything else
+
+**Advanced API** — agent reads `references/schema.md` on demand:
+
+- `trace()` · `thread()` · `subagents()` · `workflows()` · `workflowTree()` · `fileHistory()` · `failures()` · `recent()`
+
+The design is progressive disclosure: the agent doesn't see the full schema until it needs it.
+
+## Structure
+
+```
+.claude/skills/obelisk/
+├── SKILL.md              # Skill definition + simple API + examples
+├── scripts/
+│   └── runtime.mjs       # Indexer + query runtime (400 lines, zero deps)
+└── references/
+    └── schema.md          # Full table schema + advanced API + query patterns
+```
+
+## Design
+
+The index rebuilds incrementally — only new or modified JSONL files are re-parsed.
+
+Zero npm dependencies. Uses Node 22's built-in node:sqlite with FTS5. The entire runtime is ~400 lines.
+
+20K lines of scattered JSONL → something the agent can search() and sql() against in milliseconds.
+
+---
+
+## License
+
+MIT @tommy0103
+
+
@@ -0,0 +1,137 @@
+---
+name: obelisk
+description: >
+  Search and query past Claude Code session history.
+  Reactive: when the user asks "how did I fix X", "what did we do last time", "find the session where", "上次怎么修的", "之前的session", "历史记录".
+  Proactive: when the user references past work you lack context for, when you're about to modify a file with complex edit history, when the user says "继续之前的" or "continue where we left off", or when understanding prior decisions would improve your current response.
+allowed-tools:
+  - Read
+  - Bash(node:*)
+  - Write
+---
+
+# obelisk
+
+Searches and queries your Claude Code session history stored in `~/.claude/`.
+A SQLite index with FTS5 full-text search covers all sessions, subagent conversations, and workflow agent runs.
+You write JS query snippets that run in a sandboxed VM against the indexed data, then parse the JSON output.
+
+## Quick Start
+
+The base directory for this skill is provided as `$SKILL_DIR` at invocation time (shown as "Base directory for this skill: ...").
+
+**Fast keyword search** (no script needed):
+
+```bash
+node $SKILL_DIR/scripts/runtime.mjs --search "keyword"
+```
+
+**Custom query** (write a JS snippet, run it):
+
+1. Write a query to a temp file (e.g. `/tmp/q.mjs`)
+2. Run: `node $SKILL_DIR/scripts/runtime.mjs --query /tmp/q.mjs`
+3. Parse the JSON stdout and answer the user
+
+The query file body is executed inside `(async () => { ... })()` with the API below available as globals. The last expression is returned as JSON. Use `return` to emit results.
+
+## API
+
+### search(text, opts?)
+
+Full-text search across all messages (user, assistant, subagent, workflow agent).
+
+Returns: `[{ message: {uuid, text, role, timestamp, model}, session: {id, title, project, started_at}, context: [...surrounding messages] }]`
+
+opts: `{ limit, sessionId, project, after, before }`
+
+### context(uuid)
+
+Full story around a message: the message itself, parent chain, session info, subagent/workflow metadata.
+
+Returns: `{ message, parentChain, session, subagent, workflow }`
+
+### recent(n?)
+
+Latest n sessions (default 10). Returns session rows with title, project, started_at, ended_at.
+
+### sql(query, ...params)
+
+Raw SQL. Use `?` placeholders. Returns array of row objects.
+
+Tables: `sessions`, `messages`, `tool_calls`, `tool_results`, `subagents`, `workflows`, `workflow_agents`, `messages_fts`
+
+### Other APIs
+
+- `trace(uuid)` -- full parent chain from root to message
+- `thread(sessionId)` -- all messages in a session, ordered by time
+- `subagents(sessionId)` -- subagent metadata + message counts
+- `workflows(sessionId?)` -- workflow runs (all if no sessionId)
+- `workflowTree(runId)` -- workflow + its agents + all their messages
+- `fileHistory(filePath)` -- every Edit/Write/Read on a file across sessions
+- `failures(sessionId?)` -- tool calls that returned errors, with surrounding context
+
+## Examples
+
+### "上次怎么修 auth 的"
+
+```js
+const hits = search('auth fix')
+return hits.slice(0, 5).map(h => ({
+  session: h.session.title,
+  date: h.session.started_at,
+  message: h.message.text?.slice(0, 200)
+}))
+```
+
+### "最近在做什么"
+
+```js
+return recent(10).map(s => ({ title: s.title, project: s.project, date: s.started_at }))
+```
+
+### "哪些文件被反复修改"
+
+```js
+return sql(`
+  SELECT file_path, COUNT(*) as n FROM tool_calls
+  WHERE name IN ('Edit','Write') AND file_path IS NOT NULL
+  GROUP BY file_path HAVING n > 3 ORDER BY n DESC LIMIT 20
+`)
+```
+
+### "那个 review workflow 的结果是什么"
+
+```js
+const wfs = workflows()
+const review = wfs.find(w =>
+  w.run_id.includes('review') ||
+  JSON.parse(w.result_json || '{}').synthesis
+)
+return review ? JSON.parse(review.result_json) : 'No review workflow found'
+```
+
+### "上次跑 experiment 用了多少 token"
+
+```js
+const hits = search('experiment')
+if (!hits.length) return 'No experiment sessions found'
+const sid = hits[0].session.id
+return sql('SELECT SUM(input_tokens) as input, SUM(output_tokens) as output FROM messages WHERE session_id = ?', sid)
+```
+
+### "追踪一下那个决策是怎么做的"
+
+```js
+const hits = search('the decision query here')
+if (!hits.length) return 'Nothing found'
+return context(hits[0].message.uuid)
+```
+
+## Notes
+
+- First run builds the index (~5s for ~100 sessions). Subsequent runs are incremental.
+- DB location: `~/.claude/obelisk.sqlite`
+- Subagent and workflow agent conversations are fully indexed and searchable.
+- Query scripts run in a sandboxed VM context -- no file system or network access from inside scripts.
+- Text is truncated to 10k chars per message during indexing.
+- FTS5 search supports standard SQLite FTS syntax: `"exact phrase"`, `term1 AND term2`, `term1 OR term2`, `term1 NOT term2`.
@@ -0,0 +1,531 @@
+# Obelisk -- Schema and API Reference
+
+Advanced reference for the obelisk database.
+Read this when `search()`, `context()`, or `sql()` are not enough.
+
+---
+
+## 1. Database Schema
+
+Database location: `~/.claude/obelisk.sqlite`
+
+### sessions
+
+One row per Claude Code session.
+
+```sql
+CREATE TABLE sessions (
+  id            TEXT PRIMARY KEY,   -- session UUID (matches JSONL filename)
+  title         TEXT,               -- AI-generated session title (may be NULL)
+  project       TEXT,               -- project slug (hyphenated path, e.g. "Users-tomiya-Code-quiet-zero")
+  project_path  TEXT,               -- reconstructed filesystem path (e.g. "/Users/tomiya/Code/quiet-zero")
+  started_at    TEXT,               -- ISO 8601 timestamp of first message
+  ended_at      TEXT,               -- ISO 8601 timestamp of last message
+  git_branch    TEXT,               -- git branch active during session (if any)
+  version       TEXT,               -- Claude Code version string
+  message_count INTEGER DEFAULT 0,  -- total user + assistant messages
+  jsonl_path    TEXT                -- absolute path to source JSONL file
+);
+```
+
+### messages
+
+Every user and assistant message. Core table for all queries.
+
+```sql
+CREATE TABLE messages (
+  uuid          TEXT PRIMARY KEY,   -- message UUID
+  session_id    TEXT,               -- FK -> sessions.id
+  type          TEXT,               -- "user" or "assistant"
+  parent_uuid   TEXT,               -- UUID of parent message (conversation tree)
+  timestamp     TEXT,               -- ISO 8601
+  role          TEXT,               -- "user" or "assistant" (from message payload)
+  text          TEXT,               -- extracted text content (thinking + text blocks, truncated to 10k chars)
+  model         TEXT,               -- model name (e.g. "claude-opus-4-6-20250529"), NULL for user messages
+  is_sidechain  INTEGER DEFAULT 0,  -- 1 if this message is on a sidechain (retry/branch)
+  agent_id      TEXT,               -- subagent or workflow agent UUID (NULL for main conversation)
+  input_tokens  INTEGER,            -- token usage (assistant messages only)
+  output_tokens INTEGER             -- token usage (assistant messages only)
+);
+```
+
+Indexes: `idx_messages_session(session_id)`, `idx_messages_agent(agent_id)`, `idx_messages_ts(session_id, timestamp)`.
+
+### messages_fts
+
+FTS5 virtual table for full-text search over message text.
+
+```sql
+CREATE VIRTUAL TABLE messages_fts USING fts5(
+  uuid UNINDEXED,        -- not searchable, carried for JOINs
+  session_id UNINDEXED,  -- not searchable, carried for filtering
+  text,                  -- the searchable column
+  content=messages,      -- content-sync with messages table
+  content_rowid=rowid
+);
+```
+
+Queried via `MATCH` syntax. Rebuilt on each index pass.
+
+### tool_calls
+
+Every tool invocation by the assistant. One row per `tool_use` content block.
+
+```sql
+CREATE TABLE tool_calls (
+  id            TEXT PRIMARY KEY,   -- tool_use ID (from API response)
+  message_uuid  TEXT,               -- FK -> messages.uuid (the assistant message containing this call)
+  session_id    TEXT,               -- FK -> sessions.id (denormalized for fast queries)
+  name          TEXT,               -- tool name: "Read", "Edit", "Write", "Bash", "WebSearch", etc.
+  input_json    TEXT,               -- JSON-serialized tool input (truncated to 10k chars)
+  file_path     TEXT                -- extracted file_path for Read/Edit/Write/NotebookEdit (NULL otherwise)
+);
+```
+
+Indexes: `idx_tc_session_name(session_id, name)`, `idx_tc_file(file_path)`.
+
+### tool_results
+
+The result returned for each tool call. Appears in the next user message.
+
+```sql
+CREATE TABLE tool_results (
+  tool_use_id   TEXT PRIMARY KEY,   -- FK -> tool_calls.id
+  message_uuid  TEXT,               -- FK -> messages.uuid (the user message carrying this result)
+  session_id    TEXT,               -- FK -> sessions.id (denormalized)
+  content       TEXT,               -- result text (truncated to 10k chars)
+  file_path     TEXT                -- file path from toolUseResult metadata (if any)
+);
+```
+
+### subagents
+
+Metadata for subagent spawns (non-workflow agents).
+
+```sql
+CREATE TABLE subagents (
+  agent_id          TEXT PRIMARY KEY,   -- subagent UUID
+  session_id        TEXT,               -- FK -> sessions.id (parent session)
+  parent_tool_use_id TEXT,              -- tool_use ID that spawned this agent
+  agent_type        TEXT,               -- e.g. "code-review", "research"
+  description       TEXT,               -- task description given to the subagent
+  duration_ms       INTEGER,            -- wall-clock duration (computed from message timestamps)
+  total_tokens      INTEGER             -- sum of input_tokens + output_tokens across all agent messages
+);
+```
+
+Index: `idx_sa_session(session_id)`.
+
+### workflows
+
+Workflow execution records. A workflow orchestrates multiple agents.
+
+```sql
+CREATE TABLE workflows (
+  run_id        TEXT PRIMARY KEY,   -- workflow run UUID
+  session_id    TEXT,               -- FK -> sessions.id (parent session)
+  task_id       TEXT,               -- task identifier (if any)
+  script        TEXT,               -- workflow script content (truncated)
+  result_json   TEXT,               -- JSON-serialized workflow result
+  timestamp     TEXT,               -- ISO 8601 execution time
+  agent_count   INTEGER DEFAULT 0   -- number of agents in this workflow
+);
+```
+
+Index: `idx_wf_session(session_id)`.
+
+### workflow_agents
+
+Individual agents within a workflow run.
+
+```sql
+CREATE TABLE workflow_agents (
+  agent_id      TEXT PRIMARY KEY,   -- agent UUID
+  run_id        TEXT,               -- FK -> workflows.run_id
+  session_id    TEXT,               -- FK -> sessions.id
+  agent_type    TEXT,               -- agent type label
+  description   TEXT                -- task description
+);
+```
+
+Index: `idx_wa_run(run_id)`.
+
+### index_state
+
+Tracks incremental indexing progress per JSONL file.
+
+```sql
+CREATE TABLE index_state (
+  jsonl_path      TEXT PRIMARY KEY,   -- absolute path to JSONL file
+  mtime           REAL,               -- file mtime at last index (milliseconds)
+  lines_processed INTEGER             -- number of lines already processed
+);
+```
+
+### Key Relationships
+
+```
+sessions.id        <--  messages.session_id
+sessions.id        <--  tool_calls.session_id
+sessions.id        <--  tool_results.session_id
+sessions.id        <--  subagents.session_id
+sessions.id        <--  workflows.session_id
+messages.uuid      <--  tool_calls.message_uuid
+messages.uuid      <--  tool_results.message_uuid
+messages.agent_id  -->  subagents.agent_id      (for subagent messages)
+messages.agent_id  -->  workflow_agents.agent_id (for workflow agent messages)
+tool_calls.id      <--  tool_results.tool_use_id
+workflows.run_id   <--  workflow_agents.run_id
+```
+
+---
+
+## 2. Query API Reference
+
+All functions are available as globals inside `--query` scripts.
+Scripts run in an async IIFE with a 30-second timeout.
+
+### Simple Layer
+
+#### `search(text, opts?)`
+
+Full-text search across all message text using FTS5.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `text` | `string` | FTS5 query (terms, phrases, prefix) |
+| `opts.limit` | `number` | Max results (default 20) |
+| `opts.sessionId` | `string` | Restrict to one session |
+| `opts.project` | `string` | Restrict to a project slug |
+| `opts.after` | `string` | ISO 8601 lower bound on timestamp |
+| `opts.before` | `string` | ISO 8601 upper bound on timestamp |
+
+**Returns:** `Array<{ message, session, context }>` where `context` is the 6 nearest messages by timestamp.
+
+```js
+const hits = search('MCTS exploration');
+return hits.map(h => ({ title: h.session.title, text: h.message.text?.slice(0, 200) }));
+```
+
+#### `context(uuid)`
+
+Full context around a single message: parent chain, session metadata, subagent/workflow info.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | `string` | Message UUID |
+
+**Returns:** `{ message, parentChain, session, subagent, workflow }` or `null`.
+
+```js
+const c = context('abc-123-def');
+return { chain_length: c.parentChain.length, session_title: c.session?.title };
+```
+
+#### `sql(query, ...params)`
+
+Raw SQL with parameterized bindings. Returns an array of row objects.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `query` | `string` | SQL SELECT statement |
+| `...params` | `any` | Bind parameters (positional `?`) |
+
+**Returns:** `Array<Object>` -- each row as `{ column: value }`.
+
+```js
+const rows = sql('SELECT id, title FROM sessions WHERE project = ? ORDER BY ended_at DESC LIMIT 5', 'Users-tomiya-Code-quiet-zero');
+return rows;
+```
+
+### Advanced Layer
+
+#### `trace(uuid)`
+
+Walk the `parent_uuid` chain from a message up to the conversation root.
+
+**Returns:** `Array<message>` ordered root-first.
+
+```js
+const chain = trace('some-uuid');
+return chain.map(m => ({ role: m.role, text: m.text?.slice(0, 100) }));
+```
+
+#### `thread(sessionId)`
+
+All messages in a session, ordered by timestamp.
+
+**Returns:** `Array<message>`.
+
+```js
+const msgs = thread('session-uuid');
+return { count: msgs.length, first: msgs[0]?.text?.slice(0, 100) };
+```
+
+#### `subagents(sessionId)`
+
+All subagent spawns for a session, with message counts.
+
+**Returns:** `Array<{ ...subagent_row, messageCount }>`.
+
+```js
+const subs = subagents('session-uuid');
+return subs.map(s => ({ type: s.agent_type, desc: s.description, msgs: s.messageCount, tokens: s.total_tokens }));
+```
+
+#### `workflows(sessionId?)`
+
+Workflow executions. Pass a session ID to filter, or omit for all workflows (newest first).
+
+**Returns:** `Array<workflow_row>`.
+
+```js
+const wfs = workflows();
+return wfs.slice(0, 5).map(w => ({ run: w.run_id, agents: w.agent_count, time: w.timestamp }));
+```
+
+#### `workflowTree(runId)`
+
+Full execution tree for a workflow: the workflow record plus all its agents and their messages.
+
+**Returns:** `{ ...workflow_row, agents: Array<{ ...agent_row, messages: Array<message> }> }` or `null`.
+
+```js
+const tree = workflowTree('run-uuid');
+return tree?.agents.map(a => ({ type: a.agent_type, msgs: a.messages.length }));
+```
+
+#### `fileHistory(filePath)`
+
+All tool calls that touched a specific file, across every session.
+
+**Returns:** `Array<{ toolCall, session, timestamp }>`.
+
+```js
+const edits = fileHistory('/Users/tomiya/Code/quiet-zero/src/mcts.ts');
+return edits.map(e => ({ tool: e.toolCall.name, session: e.session.title, time: e.timestamp }));
+```
+
+#### `failures(sessionId?)`
+
+Tool calls whose results contain error patterns (`Error`, `ENOENT`, `failed`, `permission denied`, etc.). Includes the 3 messages immediately after each failure for retry context.
+
+**Returns:** `Array<{ toolCall, result, session, nextMessages }>`.
+
+```js
+const fails = failures('session-uuid');
+return fails.map(f => ({ tool: f.toolCall?.name, error: f.result.content?.slice(0, 200) }));
+```
+
+#### `recent(n?)`
+
+Last `n` sessions (default 10), ordered by `ended_at` descending.
+
+**Returns:** `Array<session_row>`.
+
+```js
+const last5 = recent(5);
+return last5.map(s => ({ title: s.title, project: s.project_path, ended: s.ended_at }));
+```
+
+---
+
+## 3. Common Query Patterns
+
+### Find sessions about a topic
+
+```js
+const hits = search('reinforcement learning');
+const sessions = [...new Set(hits.map(h => h.session.id))];
+return hits.slice(0, 10).map(h => ({
+  session: h.session.title,
+  snippet: h.message.text?.slice(0, 150),
+}));
+```
+
+### Trace a decision chain
+
+```js
+// Find a message, then trace its full parent chain to understand how we got there
+const hits = search('"switched to PPO"');
+if (!hits.length) return 'not found';
+const chain = trace(hits[0].message.uuid);
+return chain.map(m => ({ role: m.role, text: m.text?.slice(0, 120), ts: m.timestamp }));
+```
+
+### Find all edits to a file across sessions
+
+```js
+const edits = fileHistory('/Users/tomiya/Code/quiet-zero/src/mcts.ts');
+return edits.map(e => ({
+  action: e.toolCall.name,
+  session: e.session.title,
+  time: e.timestamp,
+}));
+```
+
+### Find churned files (most-edited across all sessions)
+
+```js
+const rows = sql(`
+  SELECT file_path, COUNT(*) as edit_count, COUNT(DISTINCT session_id) as session_count
+  FROM tool_calls
+  WHERE file_path IS NOT NULL AND name IN ('Edit','Write')
+  GROUP BY file_path
+  ORDER BY edit_count DESC
+  LIMIT 20
+`);
+return rows;
+```
+
+### Token usage analysis
+
+```js
+const rows = sql(`
+  SELECT s.id, s.title,
+    SUM(m.input_tokens) as total_in,
+    SUM(m.output_tokens) as total_out,
+    SUM(m.input_tokens) + SUM(m.output_tokens) as total
+  FROM messages m JOIN sessions s ON s.id = m.session_id
+  WHERE m.input_tokens IS NOT NULL
+  GROUP BY s.id
+  ORDER BY total DESC
+  LIMIT 10
+`);
+return rows;
+```
+
+### Find workflow results
+
+```js
+const wfs = workflows();
+for (const wf of wfs.slice(0, 3)) {
+  const tree = workflowTree(wf.run_id);
+  wf.agent_details = tree?.agents.map(a => ({
+    type: a.agent_type, desc: a.description, msgs: a.messages.length,
+  }));
+}
+return wfs.slice(0, 3);
+```
+
+### Find error patterns
+
+```js
+const fails = failures();
+// Group by tool name
+const byTool = {};
+for (const f of fails) {
+  const name = f.toolCall?.name || 'unknown';
+  byTool[name] = (byTool[name] || 0) + 1;
+}
+return { total: fails.length, byTool };
+```
+
+### Find what tools were used most
+
+```js
+const rows = sql(`
+  SELECT name, COUNT(*) as call_count, COUNT(DISTINCT session_id) as session_count
+  FROM tool_calls
+  GROUP BY name
+  ORDER BY call_count DESC
+`);
+return rows;
+```
+
+### Find sessions by time range
+
+```js
+const rows = sql(`
+  SELECT id, title, project_path, started_at, ended_at, message_count
+  FROM sessions
+  WHERE started_at >= ? AND started_at < ?
+  ORDER BY started_at DESC
+`, '2026-05-28T00:00:00Z', '2026-05-30T00:00:00Z');
+return rows;
+```
+
+### Cross-reference subagent findings
+
+```js
+// See what all subagents did in a session
+const subs = subagents('session-uuid');
+const details = subs.map(s => {
+  const msgs = sql('SELECT text, role FROM messages WHERE agent_id = ? ORDER BY timestamp', s.agent_id);
+  return { type: s.agent_type, desc: s.description, summary: msgs.slice(-1)[0]?.text?.slice(0, 300) };
+});
+return details;
+```
+
+### Find all sessions for a project
+
+```js
+const rows = sql(`
+  SELECT id, title, started_at, ended_at, message_count, git_branch
+  FROM sessions
+  WHERE project_path = ?
+  ORDER BY started_at DESC
+`, '/Users/tomiya/Code/quiet-zero');
+return rows;
+```
+
+### Reconstruct what happened in a session
+
+```js
+// Full timeline: messages + tool calls interleaved
+const msgs = thread('session-uuid');
+return msgs.map(m => {
+  const tools = sql('SELECT name, file_path FROM tool_calls WHERE message_uuid = ?', m.uuid);
+  return {
+    role: m.role, text: m.text?.slice(0, 100), ts: m.timestamp,
+    tools: tools.length ? tools.map(t => `${t.name}(${t.file_path || ''})`) : undefined,
+  };
+});
+```
+
+---
+
+## 4. Tips
+
+### When to use `search()` vs `sql()`
+
+- **`search()`** -- when you are looking for messages containing specific words or phrases.
+  Uses FTS5 under the hood, returns ranked results with surrounding context.
+  Best for: "find where we discussed X", "when did I mention Y".
+- **`sql()`** -- when you need structured queries: aggregations, JOINs, GROUP BY, date ranges,
+  or anything involving tables other than `messages`.
+  Best for: "how many edits to this file", "total tokens this week", "most-used tools".
+
+### FTS5 Match Syntax
+
+The `text` argument to `search()` uses SQLite FTS5 query syntax:
+
+| Pattern | Meaning | Example |
+|---------|---------|---------|
+| `word` | Match token | `search('MCTS')` |
+| `word1 word2` | Implicit AND | `search('MCTS exploration')` |
+| `"exact phrase"` | Phrase match | `search('"Monte Carlo tree"')` |
+| `word*` | Prefix match | `search('optim*')` matches optimize, optimizer, optimization |
+| `word1 OR word2` | Either term | `search('PPO OR TRPO')` |
+| `word1 NOT word2` | Exclude | `search('MCTS NOT debug')` |
+
+Terms are case-insensitive. FTS5 tokenizes on whitespace and punctuation,
+so `camelCase` is indexed as two tokens (`camel`, `case`).
+
+### Performance
+
+- **FTS5 searches** are fast (milliseconds) regardless of database size.
+- **`sql()` with indexes** is fast. The indexed columns cover the common patterns:
+  `messages(session_id)`, `messages(agent_id)`, `messages(session_id, timestamp)`,
+  `tool_calls(session_id, name)`, `tool_calls(file_path)`.
+- **JOINs across large sessions** (1000+ messages) can be slow if you join
+  `messages` with `tool_calls` and `tool_results` without filtering by `session_id` first.
+  Always add a `session_id` filter when working within a session.
+- **Full table scans on `tool_results`** (used by `failures()` with no session ID)
+  can be slow on large databases because it pattern-matches every result row.
+  Pass a `sessionId` when possible.
+- **Text fields are truncated** to 10,000 characters at index time. If you need
+  the full content of a long message or tool result, read the source JSONL directly
+  (path available in `sessions.jsonl_path`).
+- The database uses **WAL mode** and **NORMAL synchronous**, so reads never block
+  writes during re-indexing.
@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const vm = require('node:vm');
+const { DatabaseSync } = require('node:sqlite');
+
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const PROJECTS_DIR = path.join(CLAUDE_DIR, 'projects');
+const HISTORY_PATH = path.join(CLAUDE_DIR, 'history.jsonl');
+const DB_PATH = path.join(CLAUDE_DIR, 'obelisk.sqlite');
+const TEXT_LIMIT = 10000;
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY, title TEXT, project TEXT, project_path TEXT,
+  started_at TEXT, ended_at TEXT, git_branch TEXT, version TEXT,
+  message_count INTEGER DEFAULT 0, jsonl_path TEXT);
+CREATE TABLE IF NOT EXISTS messages (
+  uuid TEXT PRIMARY KEY, session_id TEXT, type TEXT, parent_uuid TEXT,
+  timestamp TEXT, role TEXT, text TEXT, model TEXT,
+  is_sidechain INTEGER DEFAULT 0, agent_id TEXT,
+  input_tokens INTEGER, output_tokens INTEGER);
+CREATE TABLE IF NOT EXISTS tool_calls (
+  id TEXT PRIMARY KEY, message_uuid TEXT, session_id TEXT,
+  name TEXT, input_json TEXT, file_path TEXT);
+CREATE TABLE IF NOT EXISTS tool_results (
+  tool_use_id TEXT PRIMARY KEY, message_uuid TEXT, session_id TEXT,
+  content TEXT, file_path TEXT);
+CREATE TABLE IF NOT EXISTS subagents (
+  agent_id TEXT PRIMARY KEY, session_id TEXT, parent_tool_use_id TEXT,
+  agent_type TEXT, description TEXT, duration_ms INTEGER, total_tokens INTEGER);
+CREATE TABLE IF NOT EXISTS workflows (
+  run_id TEXT PRIMARY KEY, session_id TEXT, task_id TEXT,
+  script TEXT, result_json TEXT, timestamp TEXT, agent_count INTEGER DEFAULT 0);
+CREATE TABLE IF NOT EXISTS workflow_agents (
+  agent_id TEXT PRIMARY KEY, run_id TEXT, session_id TEXT,
+  agent_type TEXT, description TEXT);
+CREATE TABLE IF NOT EXISTS index_state (
+  jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER);
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+  uuid UNINDEXED, session_id UNINDEXED, text, content=messages, content_rowid=rowid);
+CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id);
+CREATE INDEX IF NOT EXISTS idx_messages_agent ON messages(agent_id);
+CREATE INDEX IF NOT EXISTS idx_messages_ts ON messages(session_id, timestamp);
+CREATE INDEX IF NOT EXISTS idx_tc_session_name ON tool_calls(session_id, name);
+CREATE INDEX IF NOT EXISTS idx_tc_file ON tool_calls(file_path);
+CREATE INDEX IF NOT EXISTS idx_sa_session ON subagents(session_id);
+CREATE INDEX IF NOT EXISTS idx_wf_session ON workflows(session_id);
+CREATE INDEX IF NOT EXISTS idx_wa_run ON workflow_agents(run_id);
+`;
+
+function openDb() {
+  const db = new DatabaseSync(DB_PATH);
+  db.exec('PRAGMA journal_mode=WAL');
+  db.exec('PRAGMA synchronous=NORMAL');
+  db.exec(SCHEMA);
+  return db;
+}
+
+function trunc(s) {
+  return typeof s === 'string' && s.length > TEXT_LIMIT ? s.slice(0, TEXT_LIMIT) : s;
+}
+
+function extractText(content) {
+  if (typeof content === 'string') return trunc(content);
+  if (!Array.isArray(content)) return null;
+  const parts = [];
+  for (const b of content) {
+    if (b.type === 'text' && b.text) parts.push(b.text);
+    else if (b.type === 'thinking' && b.thinking) parts.push(b.thinking);
+  }
+  return parts.length ? trunc(parts.join('\n')) : null;
+}
+
+function filePath(name, input) {
+  if (!input) return null;
+  return ['Read', 'Edit', 'Write', 'NotebookEdit'].includes(name) ? (input.file_path || null) : null;
+}
+
+function isDir(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+
+function discoverJsonlFiles() {
+  const files = [];
+  if (!fs.existsSync(PROJECTS_DIR)) return files;
+  for (const proj of fs.readdirSync(PROJECTS_DIR)) {
+    const projPath = path.join(PROJECTS_DIR, proj);
+    if (!isDir(projPath)) continue;
+    for (const f of fs.readdirSync(projPath)) {
+      if (f.endsWith('.jsonl'))
+        files.push({ path: path.join(projPath, f), sessionId: f.slice(0, -6), project: proj, isSubagent: false });
+    }
+    for (const sd of fs.readdirSync(projPath)) {
+      const saDir = path.join(projPath, sd, 'subagents');
+      if (!isDir(saDir)) continue;
+      for (const sf of fs.readdirSync(saDir)) {
+        if (sf.endsWith('.jsonl'))
+          files.push({ path: path.join(saDir, sf), sessionId: sd, project: proj, isSubagent: true, agentId: sf.slice(0, -6) });
+      }
+      const wfRoot = path.join(saDir, 'workflows');
+      if (!isDir(wfRoot)) continue;
+      for (const wfDir of fs.readdirSync(wfRoot)) {
+        const wfPath = path.join(wfRoot, wfDir);
+        if (!isDir(wfPath)) continue;
+        for (const wf of fs.readdirSync(wfPath)) {
+          if (wf.endsWith('.jsonl'))
+            files.push({ path: path.join(wfPath, wf), sessionId: sd, project: proj, isSubagent: true, agentId: wf.slice(0, -6), workflowRunId: wfDir });
+        }
+      }
+    }
+  }
+  return files;
+}
+
+function needsReindex(db, fp) {
+  const mt = fs.statSync(fp).mtimeMs;
+  const row = db.prepare('SELECT mtime, lines_processed FROM index_state WHERE jsonl_path = ?').get(fp);
+  if (!row) return { needed: true, skip: 0 };
+  return mt > row.mtime ? { needed: true, skip: row.lines_processed } : { needed: false, skip: 0 };
+}
+
+function indexJsonl(db, fi) {
+  const { needed, skip } = needsReindex(db, fi.path);
+  if (!needed) return;
+  const lines = fs.readFileSync(fi.path, 'utf8').split('\n').filter(Boolean);
+  const mt = fs.statSync(fi.path).mtimeMs;
+
+  const ins = {
+    ses: db.prepare('INSERT OR REPLACE INTO sessions (id,title,project,project_path,started_at,ended_at,git_branch,version,message_count,jsonl_path) VALUES (?,?,?,?,?,?,?,?,?,?)'),
+    msg: db.prepare('INSERT OR REPLACE INTO messages (uuid,session_id,type,parent_uuid,timestamp,role,text,model,is_sidechain,agent_id,input_tokens,output_tokens) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)'),
+    tc:  db.prepare('INSERT OR REPLACE INTO tool_calls (id,message_uuid,session_id,name,input_json,file_path) VALUES (?,?,?,?,?,?)'),
+    tr:  db.prepare('INSERT OR REPLACE INTO tool_results (tool_use_id,message_uuid,session_id,content,file_path) VALUES (?,?,?,?,?)'),
+    idx: db.prepare('INSERT OR REPLACE INTO index_state (jsonl_path,mtime,lines_processed) VALUES (?,?,?)'),
+  };
+
+  const sm = { started_at: null, ended_at: null, git_branch: null, version: null, title: null, n: 0 };
+
+  for (let i = skip; i < lines.length; i++) {
+    let obj;
+    try { obj = JSON.parse(lines[i]); } catch { continue; }
+    const sid = fi.sessionId;
+    const ts = obj.timestamp || null;
+
+    if (obj.type === 'ai-title' && obj.aiTitle) { sm.title = obj.aiTitle; continue; }
+    if (obj.type !== 'user' && obj.type !== 'assistant') continue;
+
+    if (ts && (!sm.started_at || ts < sm.started_at)) sm.started_at = ts;
+    if (ts && (!sm.ended_at || ts > sm.ended_at)) sm.ended_at = ts;
+    if (obj.gitBranch) sm.git_branch = obj.gitBranch;
+    if (obj.version) sm.version = obj.version;
+    sm.n++;
+
+    const msg = obj.message || {};
+    const text = extractText(msg.content);
+    const usage = msg.usage || {};
+    const aid = fi.isSubagent ? fi.agentId : (obj.agentId || null);
+
+    if (obj.uuid) {
+      ins.msg.run(obj.uuid, sid, obj.type, obj.parentUuid || null, ts,
+        msg.role || obj.type, text, msg.model || null,
+        obj.isSidechain ? 1 : 0, aid, usage.input_tokens || null, usage.output_tokens || null);
+    }
+
+    if (obj.type === 'assistant' && Array.isArray(msg.content)) {
+      for (const b of msg.content) {
+        if (b.type === 'tool_use' && b.id)
+          ins.tc.run(b.id, obj.uuid, sid, b.name, trunc(JSON.stringify(b.input || {})), filePath(b.name, b.input));
+      }
+    }
+
+    if (obj.type === 'user' && Array.isArray(msg.content)) {
+      for (const b of msg.content) {
+        if (b.type !== 'tool_result' || !b.tool_use_id) continue;
+        const rt = typeof b.content === 'string' ? b.content
+          : Array.isArray(b.content) ? b.content.map(c => c.text || '').join('\n') : '';
+        ins.tr.run(b.tool_use_id, obj.uuid, sid, trunc(rt), obj.toolUseResult?.filePath || null);
+      }
+    }
+  }
+
+  if (!fi.isSubagent) {
+    const pp = '/' + fi.project.replace(/-/g, '/').replace(/^\//, '');
+    ins.ses.run(fi.sessionId, sm.title, fi.project, pp, sm.started_at, sm.ended_at, sm.git_branch, sm.version, sm.n, fi.path);
+  }
+  ins.idx.run(fi.path, mt, lines.length);
+}
+
+function indexSubagentMeta(db, fi) {
+  if (!fi.isSubagent) return;
+  const mp = fi.path.replace('.jsonl', '.meta.json');
+  if (!fs.existsSync(mp)) return;
+  try {
+    const meta = JSON.parse(fs.readFileSync(mp, 'utf8'));
+    const tok = db.prepare('SELECT COALESCE(SUM(input_tokens),0)+COALESCE(SUM(output_tokens),0) as t FROM messages WHERE agent_id=?').get(fi.agentId);
+    const ts = db.prepare('SELECT MIN(timestamp) as t0, MAX(timestamp) as t1 FROM messages WHERE agent_id=?').get(fi.agentId);
+    const dur = ts?.t0 && ts?.t1 ? new Date(ts.t1).getTime() - new Date(ts.t0).getTime() : null;
+    if (fi.workflowRunId) {
+      db.prepare('INSERT OR REPLACE INTO workflow_agents VALUES(?,?,?,?,?)').run(fi.agentId, fi.workflowRunId, fi.sessionId, meta.agentType||null, meta.description||null);
+    } else {
+      db.prepare('INSERT OR REPLACE INTO subagents VALUES(?,?,?,?,?,?,?)').run(fi.agentId, fi.sessionId, meta.toolUseId||null, meta.agentType||null, meta.description||null, dur, tok?.t||0);
+    }
+  } catch {}
+}
+
+function indexWorkflows(db) {
+  if (!fs.existsSync(PROJECTS_DIR)) return;
+  for (const proj of fs.readdirSync(PROJECTS_DIR)) {
+    const pp = path.join(PROJECTS_DIR, proj);
+    if (!isDir(pp)) continue;
+    for (const sd of fs.readdirSync(pp)) {
+      const wd = path.join(pp, sd, 'workflows');
+      if (!isDir(wd)) continue;
+      for (const f of fs.readdirSync(wd)) {
+        if (!f.endsWith('.json')) continue;
+        try {
+          const wf = JSON.parse(fs.readFileSync(path.join(wd, f), 'utf8'));
+          if (!wf.runId) continue;
+          const ac = db.prepare('SELECT COUNT(*) as c FROM workflow_agents WHERE run_id=?').get(wf.runId);
+          db.prepare('INSERT OR REPLACE INTO workflows VALUES(?,?,?,?,?,?,?)').run(
+            wf.runId, sd, wf.taskId||null, trunc(wf.script||null),
+            wf.result ? trunc(JSON.stringify(wf.result)) : null, wf.timestamp||null, ac?.c||0);
+        } catch {}
+      }
+    }
+  }
+}
+
+function indexHistory(db) {
+  if (!fs.existsSync(HISTORY_PATH)) return;
+  for (const line of fs.readFileSync(HISTORY_PATH, 'utf8').split('\n').filter(Boolean)) {
+    try {
+      const o = JSON.parse(line);
+      if (o.sessionId && o.title) db.prepare('UPDATE sessions SET title=? WHERE id=? AND title IS NULL').run(o.title, o.sessionId);
+    } catch {}
+  }
+}
+
+function buildIndex() {
+  const db = openDb();
+  const files = discoverJsonlFiles();
+  db.exec('BEGIN');
+  try {
+    for (const f of files) { indexJsonl(db, f); indexSubagentMeta(db, f); }
+    indexWorkflows(db);
+    indexHistory(db);
+    db.exec("INSERT INTO messages_fts(messages_fts) VALUES('rebuild')");
+    db.exec('COMMIT');
+  } catch (e) { db.exec('ROLLBACK'); throw e; }
+  db.close();
+}
+
+// --- Query API ---
+
+const ERROR_PATS = ['error','Error','ENOENT','failed','Failed','FAILED','permission denied','Permission denied','EPERM','EACCES','command not found','No such file','Exit code'];
+
+function createQueryApi(db) {
+  const q = (sql, ...p) => db.prepare(sql).all(...p);
+
+  const search = (text, opts = {}) => {
+    const { limit = 20, sessionId, project, after, before } = opts;
+    let where = 'WHERE mf.text MATCH ?';
+    const p = [text];
+    if (sessionId) { where += ' AND mf.session_id=?'; p.push(sessionId); }
+    if (project)   { where += ' AND s.project=?';     p.push(project); }
+    if (after)     { where += ' AND m.timestamp>?';    p.push(after); }
+    if (before)    { where += ' AND m.timestamp<?';    p.push(before); }
+    p.push(limit);
+    const rows = db.prepare(`
+      SELECT m.uuid,m.session_id,m.text,m.role,m.timestamp,m.model,
+             s.id as s_id,s.title as s_title,s.project as s_project,s.started_at as s_started
+      FROM messages_fts mf JOIN messages m ON m.uuid=mf.uuid LEFT JOIN sessions s ON s.id=m.session_id
+      ${where} ORDER BY rank LIMIT ?`).all(...p);
+    return rows.map(r => {
+      const ctx = db.prepare(
+        'SELECT uuid,text,role,timestamp,model FROM messages WHERE session_id=? AND uuid!=? ORDER BY ABS(JULIANDAY(timestamp)-JULIANDAY(?)) LIMIT 6'
+      ).all(r.session_id, r.uuid, r.timestamp).sort((a,b) => a.timestamp < b.timestamp ? -1 : 1);
+      return {
+        message: { uuid: r.uuid, text: r.text, role: r.role, timestamp: r.timestamp, model: r.model },
+        session: { id: r.s_id, title: r.s_title, project: r.s_project, started_at: r.s_started },
+        context: ctx,
+      };
+    });
+  };
+
+  const context = (uuid) => {
+    const msg = db.prepare('SELECT * FROM messages WHERE uuid=?').get(uuid);
+    if (!msg) return null;
+    const session = db.prepare('SELECT * FROM sessions WHERE id=?').get(msg.session_id);
+    const chain = [];
+    let cur = msg;
+    while (cur?.parent_uuid) { cur = db.prepare('SELECT * FROM messages WHERE uuid=?').get(cur.parent_uuid); if (cur) chain.unshift(cur); }
+    let subagent = msg.agent_id ? db.prepare('SELECT * FROM subagents WHERE agent_id=?').get(msg.agent_id) : null;
+    let workflow = null;
+    if (msg.agent_id) {
+      const wa = db.prepare('SELECT * FROM workflow_agents WHERE agent_id=?').get(msg.agent_id);
+      if (wa) workflow = db.prepare('SELECT * FROM workflows WHERE run_id=?').get(wa.run_id);
+    }
+    return { message: msg, parentChain: chain, session, subagent, workflow };
+  };
+
+  const trace = (uuid) => {
+    const chain = [];
+    let cur = db.prepare('SELECT * FROM messages WHERE uuid=?').get(uuid);
+    while (cur) { chain.unshift(cur); cur = cur.parent_uuid ? db.prepare('SELECT * FROM messages WHERE uuid=?').get(cur.parent_uuid) : null; }
+    return chain;
+  };
+
+  const thread = (sid) => db.prepare('SELECT * FROM messages WHERE session_id=? ORDER BY timestamp').all(sid);
+
+  const subagents = (sid) => {
+    return db.prepare('SELECT * FROM subagents WHERE session_id=?').all(sid).map(r => {
+      const c = db.prepare('SELECT COUNT(*) as c FROM messages WHERE agent_id=?').get(r.agent_id);
+      return { ...r, messageCount: c?.c || 0 };
+    });
+  };
+
+  const workflows = (sid) => sid
+    ? db.prepare('SELECT * FROM workflows WHERE session_id=? ORDER BY timestamp').all(sid)
+    : db.prepare('SELECT * FROM workflows ORDER BY timestamp DESC').all();
+
+  const workflowTree = (runId) => {
+    const wf = db.prepare('SELECT * FROM workflows WHERE run_id=?').get(runId);
+    if (!wf) return null;
+    const agents = db.prepare('SELECT * FROM workflow_agents WHERE run_id=?').all(runId).map(a => ({
+      ...a, messages: db.prepare('SELECT * FROM messages WHERE agent_id=? ORDER BY timestamp').all(a.agent_id),
+    }));
+    return { ...wf, agents };
+  };
+
+  const fileHistory = (fp) => {
+    return db.prepare(
+      'SELECT tc.*,s.title as s_title,s.project as s_project FROM tool_calls tc LEFT JOIN sessions s ON s.id=tc.session_id WHERE tc.file_path=? ORDER BY tc.id'
+    ).all(fp).map(r => ({
+      toolCall: { id: r.id, message_uuid: r.message_uuid, name: r.name, input_json: r.input_json },
+      session: { id: r.session_id, title: r.s_title, project: r.s_project },
+      timestamp: db.prepare('SELECT timestamp FROM messages WHERE uuid=?').get(r.message_uuid)?.timestamp,
+    }));
+  };
+
+  const failures = (sid) => {
+    const rows = sid
+      ? db.prepare('SELECT * FROM tool_results WHERE session_id=?').all(sid)
+      : db.prepare('SELECT * FROM tool_results').all();
+    const out = [];
+    for (const r of rows) {
+      if (!r.content || !ERROR_PATS.some(p => r.content.includes(p))) continue;
+      const tc = db.prepare('SELECT * FROM tool_calls WHERE id=?').get(r.tool_use_id);
+      const session = db.prepare('SELECT * FROM sessions WHERE id=?').get(r.session_id);
+      const rm = db.prepare('SELECT * FROM messages WHERE uuid=?').get(r.message_uuid);
+      const next = rm?.timestamp ? db.prepare('SELECT * FROM messages WHERE session_id=? AND timestamp>? ORDER BY timestamp LIMIT 3').all(r.session_id, rm.timestamp) : [];
+      out.push({ toolCall: tc, result: r, session, nextMessages: next });
+    }
+    return out;
+  };
+
+  const recent = (n = 10) => db.prepare('SELECT * FROM sessions ORDER BY ended_at DESC LIMIT ?').all(n);
+
+  return { sql: q, search, context, trace, thread, subagents, workflows, workflowTree, fileHistory, failures, recent };
+}
+
+// --- Script executor ---
+
+function executeQuery(db, scriptContent) {
+  const api = createQueryApi(db);
+  const sandbox = {
+    ...api, JSON, Math, Array, Object, Set, Map, Date, RegExp,
+    parseInt, parseFloat, String, Number, Boolean, Error, Promise, console, setTimeout,
+  };
+  const ctx = vm.createContext(sandbox);
+  return vm.runInNewContext(`(async()=>{${scriptContent}})()`, ctx, { timeout: 30000 });
+}
+
+// --- CLI ---
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === '--build') {
+    buildIndex();
+    process.stdout.write(JSON.stringify({ ok: true, db: DB_PATH }) + '\n');
+    return;
+  }
+  if (args[0] === '--search' && args[1]) {
+    buildIndex();
+    const db = openDb();
+    process.stdout.write(JSON.stringify(createQueryApi(db).search(args.slice(1).join(' ')), null, 2) + '\n');
+    db.close();
+    return;
+  }
+  if (args[0] === '--query' && args[1]) {
+    buildIndex();
+    const db = openDb();
+    const script = fs.readFileSync(path.resolve(args[1]), 'utf8');
+    executeQuery(db, script)
+      .then(r => { process.stdout.write(JSON.stringify(r, null, 2) + '\n'); db.close(); })
+      .catch(e => { process.stdout.write(JSON.stringify({ error: e.message, stack: e.stack }) + '\n'); db.close(); process.exitCode = 1; });
+    return;
+  }
+  process.stderr.write('Usage:\n  node runtime.mjs --build\n  node runtime.mjs --search "text"\n  node runtime.mjs --query <file.js>\n');
+  process.exitCode = 1;
+}
+
+main();