From 3822bda89e8341a2c7c288ae61ce5ee03de2a1f2 Mon Sep 17 00:00:00 2001
From: tommy0103 <vast_starry_sky@qq.com>
Date: Mon, 15 Jun 2026 02:25:21 +0800
Subject: [PATCH] feat: evolve retrieval layer with content_type, memory FTS,
 forget(), and recap references

  Extract schema DDL into scripts/schema.sql. Add content_type and is_meta
  columns to messages for transcript control-plane filtering. Introduce
  FTS5-backed memory recall with safe tokenization, memory soft-delete via
  forget() through the renamed --attune runtime, and anchors on memory
  records. Expand query helpers (includeMeta, thread opts, overview
  project-path awareness). Add per-card recap retrieval and writing
  references under references/recap/.
---
 .gitignore                            |   3 +
 README.md                             |  52 +++++-
 SKILL.md                              | 119 ++++++++++++--
 references/query-patterns.md          |  64 +++++++-
 references/recap-patterns.md          |   9 +
 references/recap-writing.md           |   8 +
 references/recap/overview.md          |  74 +++++++++
 references/recap/pattern1-cover.md    |  36 ++++
 references/recap/pattern2-thinking.md |  33 ++++
 references/recap/pattern3-vibe.md     |  30 ++++
 references/recap/pattern4-workflow.md |  41 +++++
 references/recap/pattern5-closing.md  |  35 ++++
 references/recap/writing1-cover.md    |  83 ++++++++++
 references/recap/writing2-thinking.md |  49 ++++++
 references/recap/writing3-vibe.md     |  73 +++++++++
 references/recap/writing4-workflow.md |  68 ++++++++
 references/recap/writing5-closing.md  |  54 ++++++
 references/retrieval-semantics.md     |  38 ++++-
 references/schema.md                  | 226 +++++++++++++++++++++++---
 scripts/db.mjs                        |  99 +++++------
 scripts/indexer.mjs                   |  36 +++-
 scripts/query.mjs                     | 120 ++++++++++----
 scripts/runtime.mjs                   |  12 +-
 scripts/schema.sql                    |  85 ++++++++++
 24 files changed, 1290 insertions(+), 157 deletions(-)
 create mode 100644 references/recap-patterns.md
 create mode 100644 references/recap-writing.md
 create mode 100644 references/recap/overview.md
 create mode 100644 references/recap/pattern1-cover.md
 create mode 100644 references/recap/pattern2-thinking.md
 create mode 100644 references/recap/pattern3-vibe.md
 create mode 100644 references/recap/pattern4-workflow.md
 create mode 100644 references/recap/pattern5-closing.md
 create mode 100644 references/recap/writing1-cover.md
 create mode 100644 references/recap/writing2-thinking.md
 create mode 100644 references/recap/writing3-vibe.md
 create mode 100644 references/recap/writing4-workflow.md
 create mode 100644 references/recap/writing5-closing.md
 create mode 100644 scripts/schema.sql

diff --git a/.gitignore b/.gitignore
index 338e374..d7bb805 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,6 @@
 plans/
 .skillopt-backups
 tests/
+node_modules/
+dist-renderer/
+release/
diff --git a/README.md b/README.md
index 837ee47..55403dd 100644
--- a/README.md
+++ b/README.md
@@ -91,7 +91,14 @@ Reads the JSON result, answers you in natural language
 
 When a retrieval produces a memory worth keeping, the agent proposes a markdown
 memory file. After user approval, it registers that file with the narrow
-`runtime.mjs --remember <script>` runtime, which exposes only `remember()`.
+`runtime.mjs --attune <script>` runtime, which exposes only memory mutation
+helpers such as `remember()` and `forget()`.
+
+Memory is a synthesis cache, not a replacement for raw sessions. The agent can
+decide whether to use, ignore, or verify a memory during an answer. Persistent
+changes still require human approval, but explicit corrections count: if you say
+a memory is wrong, outdated, or should be replaced, the agent can archive or
+update the exact matching record without a second confirmation.
 
 **The core idea: don't make humans browse, tag, or organize sessions.**
 Don't invent a rigid query DSL either.
@@ -104,7 +111,7 @@ references only when the question needs them:
 
 **Core primitives** — the main CodeAct surface:
 
-- `search(text)` — FTS5 full-text search, returns matches with surrounding context
+- `search(text)` — FTS5 full-text search, returns matches with surrounding context plus message `content_type` and `is_meta`
 - `context(uuid)` — full story around a message (parent chain, subagent/workflow metadata)
 - `sql(query, ...params)` — read-only SQL for structured queries
 
@@ -116,11 +123,26 @@ same SQLite data.
 
 - `references/schema.md` — full SQLite schema and API reference
 - `references/query-patterns.md` — copyable CodeAct recipes for common retrieval tasks
+- `references/retrieval-semantics.md` — query design frame for scoped and synthesis retrieval
+- `references/recap/overview.md` — optional `/obelisk recap` card-by-card entrypoint
+- `references/recap/pattern1-cover.md` and `references/recap/writing1-cover.md`
+- `references/recap/pattern2-thinking.md` and `references/recap/writing2-thinking.md`
+- `references/recap/pattern3-vibe.md` and `references/recap/writing3-vibe.md`
+- `references/recap/pattern4-workflow.md` and `references/recap/writing4-workflow.md`
+- `references/recap/pattern5-closing.md` and `references/recap/writing5-closing.md`
 - `references/pitfalls.md` — scope, FTS, ordering, compact/raw, and field-name traps
 
+The executable SQLite schema lives in `scripts/schema.sql`; `references/schema.md`
+is the human/agent explanation of that contract.
+
 The design is progressive disclosure with guardrails: the main skill keeps the
 core contract and high-risk pitfalls visible, while longer recipes and the full
 schema stay out of the first prompt until the agent needs them.
+The optional recap references are only for the explicit `/obelisk recap` intent;
+they are not part of the ordinary retrieval path. `references/recap/overview.md`
+drives a card-by-card loop: read one card's retrieval pattern, gather that
+card's evidence, read its writing reference, update the JSON, then continue.
+This keeps schema, taste, and query planning from competing in one large prompt.
 
 ## What gets indexed
 
@@ -132,9 +154,9 @@ schema stay out of the first prompt until the agent needs them.
 | **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 |
-| **Memories** | markdown files registered by the agent after user approval | Prior conclusions linked to source sessions/messages |
+| **Memories** | markdown files registered by the agent after user approval | Prior conclusions linked to source sessions/messages and optional anchors |
 
-Full-text search via FTS5 covers message text across every layer, while the SQLite tables preserve the structure agents need for investigation.
+Full-text search via FTS5 covers message text across every session layer and ranked memory recall over registered memory summaries, while the SQLite tables preserve the structure agents need for investigation.
 
 ## Structure
 
@@ -142,16 +164,36 @@ Full-text search via FTS5 covers message text across every layer, while the SQLi
 .claude/skills/obelisk/
 ├── SKILL.md              # Skill definition + simple API + examples
 ├── scripts/
-│   └── runtime.mjs       # Indexer + query runtime (400 lines, zero deps)
+│   ├── schema.sql        # Executable SQLite schema
+│   └── runtime.mjs       # Indexer + query runtime (zero deps)
 └── references/
     ├── schema.md          # Full table schema + advanced API reference
     ├── query-patterns.md  # Copyable retrieval recipes
+    ├── retrieval-semantics.md # Query design frame for retrieval semantics
+    ├── recap-patterns.md  # Compatibility pointer to references/recap/overview.md
+    ├── recap-writing.md   # Compatibility pointer to per-card recap writing docs
+    ├── recap/
+    │   ├── overview.md
+    │   ├── pattern1-cover.md
+    │   ├── writing1-cover.md
+    │   ├── pattern2-thinking.md
+    │   ├── writing2-thinking.md
+    │   ├── pattern3-vibe.md
+    │   ├── writing3-vibe.md
+    │   ├── pattern4-workflow.md
+    │   ├── writing4-workflow.md
+    │   ├── pattern5-closing.md
+    │   └── writing5-closing.md
     └── pitfalls.md        # Scope, FTS, ordering, and compactness traps
 ```
 
 ## Implementation Notes
 
 The index rebuilds incrementally — only new or modified JSONL files are re-parsed.
+When the optional app is running, it is the active indexer: it watches Claude
+project files, builds in a worker thread, writes `__app_heartbeat__` plus
+`__app_last_successful_build__` into `index_state`, and the skill-side lazy
+build skips work only while both markers are fresh.
 
 Zero npm dependencies. Uses Node 22's built-in node:sqlite with FTS5. The entire runtime is ~400 lines.
 
diff --git a/SKILL.md b/SKILL.md
index b15a6e9..e2e4a7c 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -44,8 +44,8 @@ Custom query:
 3. Parse JSON stdout and answer with concise evidence.
 
 The query file runs inside `(async () => { ... })()`. Use `return` to emit JSON.
-Query scripts are read-only: `remember()` is not available, and `sql()` only
-accepts read-only SELECT/WITH queries.
+Query scripts are read-only: `remember()` and `forget()` are not available, and
+`sql()` only accepts read-only SELECT/WITH queries.
 
 ## Default First Pass
 
@@ -72,12 +72,40 @@ Use `sql()` only as an escalation path for exact joins, aggregations, or schema
 questions that helpers cannot express cleanly. Do not use raw SQL as a generic
 fallback for broad retrieval.
 
+## Intent Routing
+
+Obelisk supports a small intent prefix layer after `/obelisk`. This is for
+output intent, not retrieval architecture.
+
+| Intent | Description | Reference |
+|---|---|---|
+| `recap [target]` | Generate weekly/monthly recap card content for app handoff or share-style output. | `references/recap/overview.md` |
+
+Routing rules:
+
+1. If the first word is `recap`, read `references/recap/overview.md` before the
+   first query. Everything after `recap` is the recap target.
+   Common app-generated prompts include `/obelisk recap this week`,
+   `/obelisk recap last week`, `/obelisk recap this month`, and
+   `/obelisk recap last month`; interpret these as natural period targets
+   relative to the current date and timezone.
+2. `recap` does not create a separate retrieval layer. It still uses
+   `overview()`, `memories()`, helpers, and `sql()` only when needed.
+3. Follow the overview's card-by-card sequence. Each card has its own retrieval
+   pattern and writing file; retrieve that card's evidence, read that card's
+   writing file, update the JSON, then move to the next card. Do not preload all
+   recap references before the current card is written.
+4. If the first word is not `recap`, do not load
+   `references/recap/overview.md`. Continue with Query Routing below. Do not
+   infer recap from broad requests for weekly/monthly summaries, charts,
+   rankings, shareable cards, or playlist-style metaphors.
+
 ## Query Routing
 
 Before writing a query, classify the task. Progressive disclosure is useful, but
 skipping the relevant reference usually costs extra query rounds.
 
-- Read `references/query-patterns.md` before the first query for broad synthesis, progress summaries, design history, weekly/monthly reviews, or questions that ask what the user did, learned, decided, tried, or abandoned. Start from the first-pass or one-shot synthesis pattern, then run a faceted detail pass if needed.
+- Read `references/query-patterns.md` before the first query for broad synthesis, progress summaries, design history, ordinary weekly/monthly reviews, or questions that ask what the user did, learned, decided, tried, or abandoned. Start from the first-pass or one-shot synthesis pattern, then run a faceted detail pass if needed.
 - Read `references/retrieval-semantics.md` before multi-step retrieval, scoped project/file/session searches, or synthesis/conclusion/history questions. It defines the query design frame.
 - Read `references/schema.md` before raw `sql()` unless the needed table/column relationship is already explicit here. Do this before running the SQL, not after a missing-column error. Do not start with raw SQL for broad synthesis unless helpers cannot express the needed aggregation or join.
 - Read `references/pitfalls.md` after an error or when helper fields, FTS syntax, aliases, or row shapes are unclear.
@@ -95,7 +123,7 @@ messages.
 Returns:
 
 ```js
-[{ message: { uuid, text, role, timestamp, model, cwd },
+[{ message: { uuid, text, content_type, is_meta, role, timestamp, model, cwd },
    session: { id, title, project, started_at },
    rank,
    context }]
@@ -105,7 +133,22 @@ Returns:
 timestamp. It is not the parent chain. Use `context(uuid)` or `trace(uuid)` for
 causal/parent-chain context.
 
-Opts: `{ limit, sessionId, project, after, before, cwd }`.
+Use `message.content_type` to keep evidence boundaries intact:
+`text` is user/assistant visible language, `thinking` is trace/debug material,
+`tool_use` marks a tool-call message whose details live in `tool_calls`, and
+`tool_result` marks a tool-result message whose details live in `tool_results`.
+`unknown` is a conservative fallback. Do not treat `thinking` as a user-visible
+assistant conclusion. Real user input is `type='user'` plus `content_type='text'`;
+do not invent a separate `user_message` content type.
+
+Use `message.is_meta` to separate transcript control-plane material from
+conversation evidence. `is_meta=1` marks injected caveats, command envelopes, or
+other messages that entered the transcript as user-role content but should not
+be treated as the user's request by default. `search()` and `thread()` omit meta
+messages unless `includeMeta: true` is passed; `context()` and `trace()` preserve
+the original chain and expose `is_meta` on rows.
+
+Opts: `{ limit, sessionId, project, after, before, cwd, includeMeta }`.
 
 `project` is a SQL `LIKE` filter over `sessions.project`, not an exact project
 identity. Results are already ordered by FTS5 rank; lower rank sorts earlier.
@@ -129,7 +172,9 @@ Read-only SQL SELECT/WITH with `?` placeholders. Returns array rows. SQL is an
 escape hatch for exact structured joins and aggregations after the helper-first
 surface is insufficient; it is not the default retrieval entry point.
 
-Before writing non-trivial SQL, read `references/schema.md`. Common safe joins:
+Before writing non-trivial SQL, read `references/schema.md`. The executable DDL
+lives in `scripts/schema.sql`; use the reference for query semantics and the SQL
+file for schema-source alignment. Common safe joins:
 
 - `tool_calls` does not have timestamps. Join `messages m ON m.uuid = tc.message_uuid`.
 - `tool_results` does not have timestamps. Join `messages m ON m.uuid = tr.message_uuid`.
@@ -159,9 +204,9 @@ tiny sample before relying on less common filters.
 - `fileHistory(filePath, opts?)` -- Read/Edit/Write tool calls for a file, oldest first; includes many `Read` rows.
 - `failures(opts?)` -- failed tool results with tool/session context, newest first.
 - `trace(uuid)` -- parent chain from root to message.
-- `thread(sessionId)` -- full session messages; last resort only.
+- `thread(sessionId, opts?)` -- session messages ordered by timestamp, omitting meta messages by default. Pass `{ includeMeta: true }` when investigating injected context or command envelopes.
 - `raw(uuid, opts?)` -- windowed access to the original JSONL line.
-- `memories(opts?)` -- recall memory layer, newest first. opts: `{ query, project, sessionId, sessions, after, before, branch, limit }`. `query` filters summary/path by English terms. Returns registered memory records (id, path, summary, project, session_id, created_at). Read the file at `path` for full content.
+- `memories(opts?)` -- recall memory layer. opts: `{ query, project, sessionId, sessions, after, before, branch, limit }`. Without `query`, returns active memory records newest first. With `query`, searches `summary`/`path` through safe FTS5 tokenization and returns `rank`; lower rank sorts earlier. Records may include nullable JSON `anchors` for explicit recall surfaces such as files. Read the file at `path` for full content.
 
 ## Retrieval Contract
 
@@ -173,7 +218,8 @@ Keep queries scoped, bounded, and structural.
 - Plan Before Probe: for conclusion, broad history, failure investigation, or file evolution, write a bounded retrieval script instead of spending turns on intermediate results.
 - Structure Before Text: compute counts, joins, grouping, dedupe, and projection in SQL or JS; keep runtime JSON compact, ideally under 10k-12k chars for synthesis tasks.
 - Evidence Before Conclusion: return compact evidence with stable IDs (`session_id`, `uuid`, `tool_call_id`, `run_id`, `agent_id`) and short snippets, then synthesize in the final answer.
-- Persist Durable Conclusions: after answering, if retrieval produced a durable conclusion that future sessions are likely to reuse and `memories()` does not already cover it, explicitly offer to write a memory. Keep the offer brief. Do not write the markdown file or run `--remember` until the user approves.
+- Exclude Meta By Default: `is_meta=1` rows are injected/control-plane transcript material. Helpers hide them by default; raw SQL for ordinary conversation evidence should include `COALESCE(m.is_meta,0)=0` unless meta rows are the investigation target.
+- Persist Durable Conclusions: after answering, if retrieval produced a durable conclusion that future sessions are likely to reuse and `memories()` does not already cover it, explicitly offer to write a memory. Keep the offer brief. Do not write the markdown file or run `--attune` until the user approves.
 
 If field, context, ordering, FTS, or helper semantics affect the query, read
 `references/retrieval-semantics.md` before coding. If a query errors, read
@@ -196,9 +242,13 @@ obvious CJK text in memory queries and summaries as a guardrail.
 
 **Recall:** query `memories({ query: 'English topic terms', project: '...' })`
 to find prior conclusions relevant to the current task. Translate non-English
-user requests into concise English query terms before calling `memories()`. Like
-other list helpers, passing a string is treated as `sessionId`, and passing a
-number is treated as `limit`. Read the file at `path` for full content.
+user requests into concise English query terms before calling `memories()`.
+Memory recall uses safe FTS5 tokenization over `summary` and `path`, so
+hyphens/punctuation are tokenized instead of causing raw `MATCH` syntax errors.
+Like other list helpers, passing a string is treated as `sessionId`, and passing
+a number is treated as `limit`. Read the file at `path` for full content.
+`memories()` returns active memories only. An archived memory is
+management/audit data, not recall data.
 
 Good memory candidates include design decisions, project conventions, abandoned
 alternatives, repeated failure causes, workflow patterns, and conclusions
@@ -206,6 +256,14 @@ synthesized across multiple raw evidence points. Do not propose memory for
 one-off lookups, uncertain findings, or conclusions already covered by existing
 memories.
 
+**Mutation approvals:** judging whether to use a memory in the current answer is
+an agent decision and does not require approval. Persistent memory changes do.
+If the user explicitly says a memory is wrong, outdated, should be forgotten, or
+should now say something else, that request is the approval to archive or update
+the exact matching memory. Do not ask for a second confirmation unless multiple
+memories could match. If you notice a possible conflict yourself, explain it
+briefly and ask before changing memory state.
+
 **Writing memories:** after a retrieval produces a conclusion worth persisting,
 propose writing a memory file. The user must approve. Flow:
 
@@ -218,6 +276,7 @@ return remember({
   session_id: 'current-session-id',
   message_start: 'uuid-of-first-relevant-msg',
   message_end: 'uuid-of-last-relevant-msg',
+  anchors: [{ kind: 'file', path: 'src/path/to/file.ts' }],
   summary: 'Detailed summary: what was decided, why, what alternatives were considered, and what constraints drove the choice.'
 })
 ```
@@ -225,17 +284,21 @@ return remember({
 Run the registration script with:
 
 ```bash
-node $SKILL_DIR/scripts/runtime.mjs --remember /tmp/register-memory.mjs
+node $SKILL_DIR/scripts/runtime.mjs --attune /tmp/register-memory.mjs
 ```
 
-`--remember` exposes only `remember()`. It does not expose `search()`, `sql()`,
-`memories()`, or other retrieval helpers. If you need source IDs, find them
-first with a normal `--query` script.
+`--attune` exposes only memory mutation helpers: `remember()` and `forget()`.
+It does not expose `search()`, `sql()`, `memories()`, or other retrieval
+helpers. If you need source IDs or memory IDs, find them first with a normal
+`--query` script.
 
 `remember()` validates that `path` already exists and points to a file. Relative
 paths are resolved against the source session's `project_path` when
 `session_id` is provided, then stored as normalized absolute paths. Prefer
 project-relative paths such as `.obelisk/memories/...` plus `session_id`.
+Optional `anchors` must be an array of objects and is stored as nullable JSON
+text. Use it only for explicit recall surfaces, such as files associated with
+the memory.
 
 `summary` must be English and detailed enough that `memories()` results alone
 can judge relevance without reading the file. Include the decision, the
@@ -244,7 +307,29 @@ reasoning, and the key constraints — not just a title.
 The `message_start`/`message_end` range marks where in the conversation this
 conclusion was drawn. Use it later to trace back to the original evidence.
 
-Memory records survive index rebuilds. They are never auto-deleted.
+**Forgetting memories:** if the user says a memory is outdated, wrong, or should
+be forgotten, use normal recall first to identify the exact memory ID. If there
+is exactly one clear candidate, the user's request is approval to archive it. If
+multiple memories could match, ask which one to forget. Then run an `--attune`
+script:
+
+```js
+return forget({
+  id: 'mem-id-to-delete',
+  reason: 'Outdated by newer project guidance.',
+});
+```
+
+`forget()` archives the memory record by setting `deleted_at` and
+`deleted_reason`. It removes the record from active recall but does not delete
+the markdown file. Memory records survive index rebuilds and are never changed
+automatically.
+
+**Updating memories:** updating memory is one user-approved operation:
+archive the old memory with `forget()`, then write and register a replacement
+markdown memory with `remember()`. If the user explicitly corrected the memory,
+that correction is approval for the combined archive-plus-write flow. If you
+discovered the mismatch yourself, ask first.
 
 ## Minimal Patterns
 
diff --git a/references/query-patterns.md b/references/query-patterns.md
index 3a25cd4..a4b462b 100644
--- a/references/query-patterns.md
+++ b/references/query-patterns.md
@@ -1,7 +1,7 @@
 # Obelisk Query Patterns
 
-These are copyable CodeAct patterns for `runtime.mjs --query` scripts, plus one
-`--remember` registration pattern. They are not new APIs. Adapt them to the
+These are copyable CodeAct patterns for `runtime.mjs --query` scripts plus
+`--attune` memory mutation patterns. They are not new APIs. Adapt them to the
 user's scope and return compact evidence.
 
 Read this before the first query for broad synthesis, progress summaries,
@@ -43,14 +43,17 @@ return {
     memories: map.current_project.memories.map(m => ({
       id: m.id,
       path: m.path,
+      anchors: m.anchors,
       summary: m.summary?.slice(0, 240),
     })),
   },
   prior_memories: memories({ ...scoped, query: topic, limit: 5 }).map(m => ({
     id: m.id,
     path: m.path,
+    anchors: m.anchors,
     session_id: m.session_id,
     created_at: m.created_at,
+    rank: m.rank,
     summary: m.summary?.slice(0, 260),
   })),
   session_evidence: search(topic.replace(/[-_]/g, ' '), { ...scoped, limit: 8 })
@@ -88,6 +91,7 @@ return {
     memories: map.current_project.memories.map(m => ({
       id: m.id,
       path: m.path,
+      anchors: m.anchors,
       summary: m.summary?.slice(0, 240),
     })),
   },
@@ -138,11 +142,13 @@ const prior_memories = memories({
 }).map(m => ({
   id: m.id,
   path: m.path,
+  anchors: m.anchors,
   session_id: m.session_id,
   message_start: m.message_start,
   message_end: m.message_end,
   created_at: m.created_at,
   summary: m.summary?.slice(0, 260),
+  rank: m.rank,
 }));
 
 const session_evidence = search(ftsTopic, { project, limit: 8 })
@@ -167,14 +173,14 @@ return {
 };
 ```
 
-## Register Approved Memory
+## Attune Approved Memory
 
 Use this only after the user approves writing memory and the markdown file
 already exists. `remember()` validates the file and stores a normalized absolute
 path, so keep the script small and return the registered record.
 
-Run this script with `runtime.mjs --remember <script>`. The `--remember` runtime
-exposes only `remember()`, not retrieval helpers.
+Run this script with `runtime.mjs --attune <script>`. The `--attune` runtime
+exposes only `remember()` and `forget()`, not retrieval helpers.
 
 ```js
 return remember({
@@ -182,6 +188,7 @@ return remember({
   session_id: 'source-session-id',
   message_start: 'first-message-uuid',
   message_end: 'last-message-uuid',
+  anchors: [{ kind: 'file', path: 'SKILL.md' }],
   summary: [
     'Decision: Obelisk uses one user-facing entry that queries both memory and raw sessions.',
     'Memory records are prior notes and must be identified naturally when they influence an answer.',
@@ -190,6 +197,53 @@ return remember({
 });
 ```
 
+## Forget Approved Memory
+
+Use this only after the user asks to archive an outdated or wrong memory. Identify
+the exact memory ID in a normal `--query` script first. If one candidate clearly
+matches the user's request, that request is approval to archive it; if several
+candidates match, ask which one to forget.
+
+Run the mutation with `runtime.mjs --attune <script>`:
+
+```js
+return forget({
+  id: 'mem-id-to-delete',
+  reason: 'Outdated by newer project guidance.',
+});
+```
+
+`forget()` archives the record. Active recall through `memories()` will omit it,
+and the markdown file at `path` is left in place.
+
+## Update Approved Memory
+
+Use this when the user explicitly corrects an existing memory, or after the
+agent proposes a replacement and the user approves. An update is one combined
+operation: archive the old record and register the replacement markdown file.
+The new markdown file must already exist before running `--attune`.
+
+```js
+const archived = forget({
+  id: 'old-memory-id',
+  reason: 'Replaced by updated memory from the current session.',
+});
+
+const created = remember({
+  path: '.obelisk/memories/updated-memory.md',
+  session_id: 'current-session-id',
+  message_start: 'first-message-uuid',
+  message_end: 'last-message-uuid',
+  anchors: [{ kind: 'file', path: 'src/path/to/file.ts' }],
+  summary: 'Updated summary: concise English retrieval surface for the replacement memory.',
+});
+
+return { archived, created };
+```
+
+If the agent only suspects a memory is stale, do not run this pattern yet.
+Answer from current evidence and ask whether to archive or replace the memory.
+
 ## One-Shot Retrieval For Synthesis
 
 Use this for conclusion, broad history, failure investigation, or file evolution
diff --git a/references/recap-patterns.md b/references/recap-patterns.md
new file mode 100644
index 0000000..9781d87
--- /dev/null
+++ b/references/recap-patterns.md
@@ -0,0 +1,9 @@
+# Obelisk Recap Retrieval Patterns
+
+Compatibility pointer.
+
+The `/obelisk recap` flow now starts at `references/recap/overview.md`.
+Do not use this as an all-in-one retrieval document. The current flow is
+card-by-card: read the overview, then for each card read its `patternN-*.md`,
+retrieve that card's evidence, read its `writingN-*.md`, and update the JSON
+before moving on.
diff --git a/references/recap-writing.md b/references/recap-writing.md
new file mode 100644
index 0000000..f7b8af1
--- /dev/null
+++ b/references/recap-writing.md
@@ -0,0 +1,8 @@
+# Obelisk Recap Writing
+
+Compatibility pointer.
+
+The `/obelisk recap` writing contract now lives in the per-card writing files
+under `references/recap/`, coordinated by `references/recap/overview.md`.
+Read the overview first. Then use each per-card writing file immediately after
+that card's retrieval pattern, rather than loading one large writing prompt.
diff --git a/references/recap/overview.md b/references/recap/overview.md
new file mode 100644
index 0000000..4542c19
--- /dev/null
+++ b/references/recap/overview.md
@@ -0,0 +1,74 @@
+# Obelisk Recap Overview
+
+Use this only when the first word after `/obelisk` is `recap`. Everything after
+`recap` is the target period or style hint.
+
+## Highest Priority: Phase Loop
+
+This workflow is sequential. Do not preload all recap files. Do not gather all
+evidence first and write all cards at the end.
+
+Follow this loop exactly:
+
+1. Resolve the target period from the user's phrase.
+2. Run only a tiny orientation pass such as `overview({ limit: 6 })`.
+3. For Card 1, read `pattern1-cover.md`.
+4. Retrieve only Card 1 evidence.
+5. Read `writing1-cover.md`.
+6. Update/write the JSON for Card 1 now.
+7. Only after the JSON is updated, move to Card 2 and repeat.
+
+Card order:
+
+| card | retrieve | write |
+|---|---|---|
+| 1 cover | `pattern1-cover.md` | `writing1-cover.md` |
+| 2 thinking | `pattern2-thinking.md` | `writing2-thinking.md` |
+| 3 vibe | `pattern3-vibe.md` | `writing3-vibe.md` |
+| 4 workflow | `pattern4-workflow.md` | `writing4-workflow.md` |
+| 5 closing | `pattern5-closing.md` | `writing5-closing.md` |
+
+The per-card files own retrieval details, JSON field duties, and card-specific
+taste. Do not move those concerns back into this file.
+
+## Period Targets
+
+- `this week`, `last week`: calendar week in the user's runtime timezone.
+- `this month`, `last month`: calendar month in the user's runtime timezone.
+
+Do not infer timezone from examples, UTC suffixes, or file timestamps when
+runtime/session timezone is available.
+
+## Overall Deck Taste
+
+This is a Spotify Wrapped-like set of personal share cards: concise, designed,
+slightly playful, and built to make the user's work feel seen.
+
+Do not criticize the user. Do not scold, diagnose, rank their personality, or
+turn friction into a performance review.
+
+Use designed English chrome where it feels like card UI: week/month labels,
+archetype labels, compact stats, verdict seals, and signoffs. Preserve the
+user's own language for prompts, quotes, catchphrases, and reactions. This is
+not a translation task.
+
+The deck should feel like a small artifact from someone who noticed the week,
+not a report generated from a database.
+
+## Archetypes
+
+Choose one dominant archetype from the period's dominant attention, not from the
+current recap-generation session.
+
+| archetype | when it fits | tone baseline |
+|---|---|---|
+| `architect` | structure, boundaries, schema, systems | matter-of-fact structural pride |
+| `debugger` | symptoms, false positives, root-cause loops | wry and bug-comfortable |
+| `shipper` | dense implementation cadence | energetic but not breathless |
+| `curator` | organization, memory, docs, refinement | reflective and precise |
+| `director` | workflows, subagents, orchestration | observant from a slight remove |
+| `cartographer` | moving boundaries and redrawing maps | patient and surveyor-like |
+| `wanderer` | many projects without one center | gentle, exploratory |
+
+If two fit, pick the one that describes what the user spent more thinking time
+on, not what shipped.
diff --git a/references/recap/pattern1-cover.md b/references/recap/pattern1-cover.md
new file mode 100644
index 0000000..14b6a66
--- /dev/null
+++ b/references/recap/pattern1-cover.md
@@ -0,0 +1,36 @@
+# Card 1 Cover Retrieval
+
+Goal: choose the recap's dominant claim, persona, activity shape, and compact
+footer. The cover is not a topic inventory; it is one glanceable claim about
+what the period felt like.
+
+Use the period from `overview.md`. Start from `overview({ limit: 6 })`, then
+look at in-period sessions, summaries, memories, and any obvious project scope.
+If the user asked for a project, keep that scope; otherwise prefer the current
+project only when the evidence makes it the clear center.
+
+Prefer helpers first. If you need custom SQL for activity, token/message counts,
+or source-session scope, read `references/schema.md` before writing the SQL.
+
+Retrieve:
+
+- dominant claim: one thing that defined the period, supported by raw evidence;
+- persona: which archetype best matches the user's attention;
+- source sessions and memories used by this cover claim;
+- activity: weekly day intensities or monthly day intensities when supported;
+- footer: compact public metric such as sessions, messages, or tokens.
+
+Avoid:
+
+- a claim that lists three topics;
+- an archetype chosen from the recap-generation session itself;
+- footer caveats like excluded projects, exact SQL filters, or long session names;
+- making the cover a workflow metric when the week was really about a decision.
+
+Read this card's writing file immediately after the cover evidence is stable:
+`references/recap/writing1-cover.md`. Then update the JSON fields
+`period`, `source`, `metrics`, `persona`, and the first `cards[]` entry.
+Do not read `pattern2-thinking.md` until this JSON update is done.
+
+Stop when the cover has one evidence-backed dominant claim, one chosen persona,
+one metric scope, and at least one `evidence` anchor.
diff --git a/references/recap/pattern2-thinking.md b/references/recap/pattern2-thinking.md
new file mode 100644
index 0000000..b0d46f6
--- /dev/null
+++ b/references/recap/pattern2-thinking.md
@@ -0,0 +1,33 @@
+# Card 2 Thinking Retrieval
+
+Goal: find turning points. This card is not a project timeline and not an implementation log. It is the record of what changed in the user's mind.
+
+Retrieve 3-6 turns. A turn needs both sides:
+
+- the user question, friction, doubt, or request that started the turn;
+- the later decision, reframing, finding, or constraint that replaced the earlier
+  state.
+
+Useful searches:
+
+- user questions in the period: "为什么", "是不是", "怎么", "我觉得", "不应该";
+- places where the user corrected the direction and then approved a new frame;
+- summaries that name decisions, followed by `context()` or `thread()` for the
+  user's actual words;
+- memory records only as hints; raw session evidence must provide the prompt and
+  turn.
+
+Prefer helpers first. If you need custom SQL for message windows or user-turn
+counts, read `references/schema.md` before writing the SQL.
+
+Do not use workflow names, feature names, or agent task labels as prompts when
+the user had their own wording. Do not use counts, "5 rounds", "13 agents", or
+implementation effort as turns unless that count is the turn itself.
+
+Read this card's writing file immediately after the turns are chosen:
+`references/recap/writing2-thinking.md`. Then update the JSON `thinking_path`
+card and add evidence for each item.
+Do not read `pattern3-vibe.md` until this JSON update is done.
+
+Stop when each item has a source-language prompt label, a short changed-state
+prompt, turn, and an `evidence` anchor.
diff --git a/references/recap/pattern3-vibe.md b/references/recap/pattern3-vibe.md
new file mode 100644
index 0000000..be3c8ad
--- /dev/null
+++ b/references/recap/pattern3-vibe.md
@@ -0,0 +1,30 @@
+# Card 3 Vibe Retrieval
+
+Goal: find small human signals in visible user messages. Vibe is not a correction log, not bracketed runtime text, and not a psychological profile.
+
+Look for:
+
+- catchphrases and repeated tiny reactions;
+- unusually blunt praise or rejection;
+- late-night disbelief, jokes, or rituals;
+- one quotable sentence that captures the period's character.
+
+Only count visible user messages. Helper APIs omit meta by default, but custom
+SQL for phrase counts must filter user text with `COALESCE(m.is_meta,0)=0` and
+`m.content_type='text'`. Do not count tool results, injected command envelopes,
+UI labels, or bracketed runtime strings.
+
+Useful retrieval:
+
+- targeted phrase counts after you notice a likely catchphrase;
+- `thread(sessionId)` around high-energy moments;
+- `search()` for exact phrases, then `context()` for timing;
+- a bounded SQL count only after reading `references/schema.md`.
+
+Read this card's writing file immediately after you have the small user signals:
+`references/recap/writing3-vibe.md`. Then update the JSON `vibe` card and add
+evidence for every quote, count, and timestamp.
+Do not read `pattern4-workflow.md` until this JSON update is done.
+
+Stop when every observation is either exact user words or a tiny label backed by
+exact user words.
diff --git a/references/recap/pattern4-workflow.md b/references/recap/pattern4-workflow.md
new file mode 100644
index 0000000..d1dbb94
--- /dev/null
+++ b/references/recap/pattern4-workflow.md
@@ -0,0 +1,41 @@
+# Card 4 Workflow Retrieval
+
+Goal: find actual workflow runs and how the user received them. Card 4 is about
+orchestration as experienced by the user, not an agent performance table.
+
+Workflow rows have their own `workflows.timestamp`. During this card's retrieval,
+call `workflows({ project: projectLike, after, before })` before concluding the
+period had zero workflows.
+
+Prefer helpers first. If you need custom SQL for workflow joins, timestamps, or
+message reactions, read `references/schema.md` before writing the SQL.
+
+Do not derive workflow counts only from `sessions({ after, before })`: long
+sessions can start before the period and still contain workflow runs inside the
+period. Do not scope workflow lookup by exact `project_path`; nested cwd values
+can belong to the same Claude project slug.
+
+For each candidate workflow:
+
+- get the actual workflow_name from `workflows()` or `workflowTree()`;
+- collect run id, timestamp, project, agent count, and compact result for stats
+  and evidence only;
+- search the parent session for the user message immediately following the workflow completion;
+- use that user reaction as `items[].reaction`.
+
+Rank rows by the strength of the user reaction, not by agent count, workflow
+size, duration, or implementation importance. A small workflow with "完美" is a
+better row than a large workflow with no visible response.
+
+Do not use architecture topics, memory-system milestones, app modules, or recap
+feature work as workflow rows unless they are actual workflow_name values.
+Do not make a row for a workflow with no visible user reaction; keep it only in
+`stats`, `metrics`, or `evidence`.
+
+Read this card's writing file immediately after workflow evidence is stable:
+`references/recap/writing4-workflow.md`. Then update the JSON `workflow` card,
+top-level workflow metrics, and source session ids for workflow evidence.
+Do not read `pattern5-closing.md` until this JSON update is done.
+
+Stop when every displayed row has an actual workflow name and a visible user
+reaction.
diff --git a/references/recap/pattern5-closing.md b/references/recap/pattern5-closing.md
new file mode 100644
index 0000000..be5c4c3
--- /dev/null
+++ b/references/recap/pattern5-closing.md
@@ -0,0 +1,35 @@
+# Card 5 Closing Retrieval
+
+Goal: close with a small personal receipt. Use the same period and source scope
+as the recap, or explicitly record a wider metric in `evidence`.
+
+Retrieve:
+
+- one consistent metric that can stand alone, such as streak, active days,
+  sessions, messages, or workflows;
+- one or two compact receipts;
+- most said phrase, only if a real repeated user phrase is supported;
+- signoff material from the period's mood, not a second summary.
+
+For phrase counts, count only non-meta visible user text. For streaks and active
+days, define whether the scope is all Obelisk data, the current project, or the
+selected evidence sessions. Keep the scope consistent with the cover footer
+unless the evidence explicitly says otherwise.
+
+Prefer helpers first. If you need custom SQL for phrase counts, active days, or
+streaks, read `references/schema.md` before writing the SQL.
+
+Avoid:
+
+- naked numbers without units;
+- project report bullets;
+- internal session names;
+- token audits;
+- slogans, advice, or next-action commands.
+
+Read this card's writing file immediately after the closing receipt is chosen:
+`references/recap/writing5-closing.md`. Then update the JSON `closing` card and
+add evidence for counts and phrases.
+This is the final card; save the completed JSON before replying.
+
+Stop when the closing can end the deck without explaining the whole week again.
diff --git a/references/recap/writing1-cover.md b/references/recap/writing1-cover.md
new file mode 100644
index 0000000..96df3fa
--- /dev/null
+++ b/references/recap/writing1-cover.md
@@ -0,0 +1,83 @@
+# Card 1 Cover Writing
+
+The cover should be readable in one glance: badge, persona, one plain claim,
+activity, footer. Before writing, say the claim to the user in a chat bubble.
+If it sounds like a topic list or report heading, shrink it.
+
+## Mock taste anchor
+
+```json
+{
+  "type": "cover",
+  "badge": "Week 24",
+  "title": "The Architect",
+  "claim": "从零设计了一个完整的 memory 系统。",
+  "activity": [0.85, 0.92, 0.72, 0.45, 0.88, 0.30, 0],
+  "footer": "12 sessions · 2.4M tokens"
+}
+```
+
+This works because `从零设计了一个完整的 memory 系统。` is one plain claim, in
+the user's language, and can be read in one breath. `The Architect` is English
+chrome; it gives the card a designed surface without translating the user's
+actual work.
+
+## JSON Shape
+
+```ts
+type CoverCard = {
+  type: "cover";
+  badge: string;
+  title: string;
+  claim: string;
+  activity: number[];
+  footer: string;
+  evidence_refs?: string[];
+};
+```
+
+Field duties:
+
+- `badge`: compact period chrome, such as `Week 24`.
+- `title`: persona label, usually `The Architect`, `The Debugger`, etc.
+- `claim`: one plain claim; not a topic list, project inventory, colon-led
+  tagline, or clever English that hides the user's language.
+- `activity`: period intensity values from retrieval.
+- `footer`: public metric line with no internal filter notes.
+
+After writing, check that `persona.claim` and `cover.claim` tell the same
+story, and attach `evidence_refs` to the claim or metric if it is surprisingly
+specific.
+
+## First JSON Write
+
+After Card 1, create or update the recap JSON file. Do this before reading
+`pattern2-thinking.md`.
+
+Use this top-level shape:
+
+```ts
+type Recap = {
+  schema_version: "obelisk.recap.v1";
+  kind: "weekly" | "monthly";
+  generated_at: string;
+  period: { label: string; start: string; end: string; timezone: string };
+  source: { project?: string; session_ids: string[]; memory_ids?: string[] };
+  metrics: {
+    sessions?: number;
+    messages?: number;
+    tokens?: number;
+    active_days?: number[];
+    streak_days?: number;
+    workflows?: number;
+    workflow_agents?: number;
+    corrections?: number;
+  };
+  persona: { archetype: string; title: string; claim: string; tone: string };
+  cards: [CoverCard, { type: "thinking_path" }, { type: "vibe" }, { type: "workflow" }, { type: "closing" }];
+  evidence?: Array<{ id: string; session_id?: string; message_uuid?: string; memory_id?: string; summary?: string }>;
+};
+```
+
+For app handoff, write JSON under `~/.obelisk/recap/`. Weekly filenames are
+`recap-{YYYY}-W{WW}.json`; monthly filenames are `recap-{YYYY}-{MM}.json`.
diff --git a/references/recap/writing2-thinking.md b/references/recap/writing2-thinking.md
new file mode 100644
index 0000000..39affa3
--- /dev/null
+++ b/references/recap/writing2-thinking.md
@@ -0,0 +1,49 @@
+# Card 2 Thinking Writing
+
+Thinking Path should feel like a few bends in the user's reasoning, not a
+weekly changelog. Before writing, test each row by asking: "what changed here?"
+
+## Mock taste anchor
+
+```json
+{
+  "type": "thinking_path",
+  "title": "Five questions, five turns.",
+  "items": [
+    { "day": "Mon", "prompt": "为什么要把 session 编译成 wiki？", "turn": "raw SQLite, no wiki" },
+    { "day": "Tue", "prompt": "buildWhere 是什么", "turn": "unified filter opts, not DSL" },
+    { "day": "Wed", "prompt": "failures() 90% 误报", "turn": "is_error in JSONL" },
+    { "day": "Thu", "prompt": "memory 层需要清理机制吗", "turn": "soft-delete, human-only" },
+    { "day": "Fri", "prompt": "热力图不选中默认显示本月", "turn": "GitHub-style activity timeline" }
+  ]
+}
+```
+
+The prompts stay close to the user's words. Each turn is a short decision
+fragment, not a full explanation.
+
+## JSON Shape
+
+```ts
+type ThinkingPathCard = {
+  type: "thinking_path";
+  title: string;
+  items: Array<{
+    day: string;
+    prompt: string;
+    turn: string;
+    evidence_refs?: string[];
+  }>;
+};
+```
+
+Field duties:
+
+- `title`: designed deck line, not `本周路径`, not a research-paper heading.
+- `prompt`: user's compact question, friction, or task. Use source language.
+- `turn`: short decision fragment, finding, or shift; usually under 10 words.
+  Compact English fragments are allowed when they work as designed chrome.
+
+After writing, remove any row whose prompt is a workflow name or whose turn
+describes implementation rather than changed thinking.
+Update the JSON now before reading `pattern3-vibe.md`.
diff --git a/references/recap/writing3-vibe.md b/references/recap/writing3-vibe.md
new file mode 100644
index 0000000..348e600
--- /dev/null
+++ b/references/recap/writing3-vibe.md
@@ -0,0 +1,73 @@
+# Card 3 Vibe Writing
+
+Vibe is affectionate observation. It should make the user recognize themselves
+without feeling evaluated. Before writing, remove anything that reads like a
+correction audit, behavior label, diagnosis, or complaint ledger.
+
+## Mock taste anchor
+
+```json
+{
+  "type": "vibe",
+  "title": "A short character study.",
+  "voice_lines": [
+    { "label": "catchphrase", "text": "这太丑了", "count": 4 },
+    { "label": "highest praise", "text": "可以" },
+    { "label": "late night", "text": "你在干什么", "time": "02:47 AM" }
+  ],
+  "meter": {
+    "label": "patience",
+    "value": 0.78,
+    "caption": "saint"
+  },
+  "quote": {
+    "text": "若无必要，勿增实体。",
+    "caption": "your most philosophical moment"
+  }
+}
+```
+
+The humor comes from exact small lines. `可以` is funnier and truer than
+"approval signal".
+
+## JSON Shape
+
+```ts
+type VibeCard = {
+  type: "vibe";
+  title: string;
+  voice_lines: Array<{
+    label: string;
+    text: string;
+    count?: number;
+    time?: string;
+    evidence_refs?: string[];
+  }>;
+  meter?: {
+    label: string;
+    value: number;
+    caption: string;
+  };
+  quote?: {
+    text: string;
+    caption?: string;
+    evidence_refs?: string[];
+  };
+};
+```
+
+Field duties:
+
+- `title`: light character-study line, not a scorecard.
+- `voice_lines[].text`: exact user words; no paraphrase, translation,
+  ellipsized half-quote, meta text, or correction log.
+- `voice_lines[].label`: designed chrome can be English; the quoted user text
+  stays in source language.
+- `meter`: meter is not a diagnosis. Keep the caption one or two words and
+  affectionate, never punitive.
+- `quote.text`: one exact user phrase or sentence.
+
+Do not use `[Request interrupted by user]`, tool output, injected context, or
+UI status text as vibe. After writing, verify every `voice_lines[].text` and
+`quote.text` can be traced to a non-meta user message.
+Update the JSON now before reading `pattern4-workflow.md`.
diff --git a/references/recap/writing4-workflow.md b/references/recap/writing4-workflow.md
new file mode 100644
index 0000000..2f894b6
--- /dev/null
+++ b/references/recap/writing4-workflow.md
@@ -0,0 +1,68 @@
+# Card 4 Workflow Writing
+
+Workflow is the orchestration card. It should show the strongest few workflow
+runs and the user's reaction to them. Before writing, remove any row whose
+reaction is not traceable to a visible user reaction.
+
+## Mock taste anchor
+
+```json
+{
+  "type": "workflow",
+  "title": "Three workflows. Forty-two agents.",
+  "deck": "你召唤了机器军团。结果各有不同。",
+  "stats": "3 workflows · 42 agents",
+  "items": [
+    { "name": "hono-plugin-review", "reaction": "完美" },
+    { "name": "vue-migration", "reaction": "你这页面完全和之前的不一样…" },
+    { "name": "split-render-js", "reaction": "可以" }
+  ],
+  "verdict": "Mostly tolerated."
+}
+```
+
+The row reactions are user reactions. The title carries the metric; the verdict
+is a small English seal.
+
+## JSON Shape
+
+```ts
+type WorkflowCard = {
+  type: "workflow";
+  title: string;
+  deck?: string;
+  stats?: string;
+  items: Array<{
+    name: string;
+    reaction: string;
+    evidence_refs?: string[];
+  }>;
+  verdict: string;
+};
+```
+
+Field duties:
+
+- `title`: human story line or compact metric line.
+- `deck`: optional second line; do not repeat stats mechanically.
+- `stats`: compact count line.
+- `items[].name`: actual workflow name, command name, or run-id prefix.
+- `items[].reaction`: exact or lightly trimmed user reaction. Preserve source
+  language. No feature description, implementation summary, agent count,
+  duration, "framework switch", "modularization", "theming landed", or other
+  internal progress label.
+- `verdict`: compact seal based on the row reactions, often 3-6 words.
+
+Agent counts belong only in `title` or `stats`, never in `items[].reaction`.
+These row values are invalid because they are implementation labels, not user
+reactions:
+
+- `13 agents, the big build` is invalid.
+- `9 agents, framework switch` is invalid.
+- `6 agents, modularization` is invalid.
+- `theming landed` is invalid.
+
+If no user reaction exists, omit the row rather than write an implementation result.
+After writing, check that every row name maps to retrieval evidence and every
+reaction can be read as quoted user verdict text.
+Update the JSON now before reading `pattern5-closing.md`.
diff --git a/references/recap/writing5-closing.md b/references/recap/writing5-closing.md
new file mode 100644
index 0000000..0c80db5
--- /dev/null
+++ b/references/recap/writing5-closing.md
@@ -0,0 +1,54 @@
+# Card 5 Closing Writing
+
+Closing is a receipt, not a second summary. Before writing, read the headline
+alone. If it does not mean anything without the rest of the card, add the unit
+or choose a better line.
+
+## Mock taste anchor
+
+```json
+{
+  "type": "closing",
+  "headline": "19 days",
+  "receipts": ["847 messages exchanged", "12 corrections · 47 approvals"],
+  "most_said_phrase": "好的开始做吧",
+  "signoff": "See you next week."
+}
+```
+
+This works because `19 days` has a unit, the receipts feel like a small receipt,
+and `See you next week.` is a quiet goodbye instead of a slogan.
+
+## JSON Shape
+
+```ts
+type ClosingCard = {
+  type: "closing";
+  headline: string;
+  receipts: string[];
+  most_said_phrase?: string;
+  signoff: string;
+  evidence_refs?: string[];
+};
+```
+
+Field duties:
+
+- `headline`: compact stat or phrase with its unit; not a naked number.
+- `receipts`: at most two `receipts`, compact and personal.
+- `most_said_phrase`: complete phrase the user actually said, or omit it.
+- `signoff`: short and earned; quiet goodbye, not advice or a brand slogan.
+  English signoff chrome such as `See you next week.` is allowed.
+
+After writing, remove internal scope notes from visible fields and put them in
+`evidence`. The final card should feel like the deck ending, not the report
+continuing.
+
+Final save rules:
+
+- The file contains only the JSON object: no Markdown fence, no prose.
+- Keep exactly five cards in this order: cover, thinking_path, vibe, workflow,
+  closing.
+- Keep private SQL, raw tool output, secrets, long paths, and source caveats out
+  of visible card text; put traceability in `evidence`.
+- After saving, reply briefly with the saved path and important evidence caveats.
diff --git a/references/retrieval-semantics.md b/references/retrieval-semantics.md
index 74d5c6c..f5e3cda 100644
--- a/references/retrieval-semantics.md
+++ b/references/retrieval-semantics.md
@@ -78,7 +78,8 @@ the needed join, grouping, or exact schema-level check better than helpers.
 
 Ordering and context are semantic:
 
-- `sessions()`, `memories()`, `summaries()`, `workflows()`, and `failures()` are newest first.
+- `sessions()`, `summaries()`, `workflows()`, and `failures()` are newest first.
+- `memories()` without `query` is newest first; `memories({ query })` is FTS-ranked over memory `summary`/`path`, with lower rank sorting earlier.
 - `fileHistory()` is oldest first.
 - `search().context` is temporal neighbors in one session, not causal context.
 - `context(uuid)` and `trace(uuid)` are for parent-chain/causal expansion.
@@ -97,19 +98,44 @@ For semantic questions, build a task-local evidence view:
 {
   query_plan: { mode, scope, facets, limits },
   prior_memories: [
-    { id, path, session_id, created_at, summary }
+    { id, path, anchors, session_id, created_at, summary }
   ],
   evidence: [
-    { type, id, session_id, timestamp, facet, snippet }
+    { type, id, session_id, timestamp, content_type, is_meta, facet, snippet }
   ],
   omitted: 0
 }
 ```
 
+For message evidence, preserve `content_type` when projecting snippets.
+`text` can support user-visible claims; `thinking` is only trace/debug context;
+`tool_use` means follow `tool_calls` for structured details; `tool_result`
+means follow `tool_results` for structured output. Mixed or unfamiliar message
+surfaces remain `unknown`.
+
+Preserve `is_meta` separately from `content_type`. Default message evidence
+should exclude `is_meta=1` rows because they are transcript control-plane
+content, not ordinary user intent or assistant conclusions. Include them only
+when investigating injected caveats, command envelopes, or transcript structure.
+When writing raw SQL for ordinary conversation evidence, add
+`COALESCE(m.is_meta,0)=0` to message filters unless meta rows are the subject of
+the investigation.
+
 Memory recall is English-indexed: translate non-English user requests into
 concise English query terms before calling `memories({ query })`. Memory
 summaries registered with `remember()` are also English, regardless of the
 conversation language.
+`memories({ query })` uses safe FTS5 tokenization over memory `summary` and
+`path`, so hyphens and punctuation do not need raw `MATCH` escaping.
+`memories()` returns active memories only. For raw SQL memory recall, include
+`deleted_at IS NULL`; archived memory records are management/audit data.
+
+The agent may decide whether to use, ignore, or verify a recalled memory for the
+current answer without user approval because no persistent state changes. If a
+user explicitly says a memory is wrong, outdated, should be forgotten, or should
+be replaced, that request is approval to mutate the exact matching memory. If
+the agent discovers the conflict without an explicit user request, it should
+answer from current evidence and ask before archiving or replacing the memory.
 
 Then synthesize the conclusion in the final answer. Do not pretend the raw
 evidence view is itself a stored Obelisk entity.
@@ -121,7 +147,11 @@ project conventions, abandoned alternatives, repeated failure causes, workflow
 patterns, and conclusions synthesized across multiple raw evidence points. Do
 not propose memory for one-off lookups, uncertain findings, or duplicate
 coverage. The offer is only a proposal: write the markdown file and run
-`--remember` only after user approval.
+`--attune` only after user approval.
+
+Memory updates are archive-plus-write, not in-place edits: run `forget()` on the
+old record and `remember()` the replacement markdown file under the same user
+approval.
 
 ## Text Search Semantics
 
diff --git a/references/schema.md b/references/schema.md
index 835005b..0ace4c2 100644
--- a/references/schema.md
+++ b/references/schema.md
@@ -3,6 +3,9 @@
 Advanced reference for the obelisk database.
 Read this when `search()`, `context()`, or `sql()` are not enough.
 
+Executable schema source: `scripts/schema.sql`. This document explains that
+contract for agents and humans; it is not the runtime source of truth.
+
 ---
 
 ## 1. Database Schema
@@ -41,6 +44,8 @@ CREATE TABLE messages (
   timestamp     TEXT,               -- ISO 8601
   role          TEXT,               -- "user" or "assistant" (from message payload)
   text          TEXT,               -- extracted text content (thinking + text blocks, truncated to 10k chars)
+  content_type  TEXT,               -- "text", "thinking", "tool_use", "tool_result", or "unknown"
+  is_meta       INTEGER DEFAULT 0,  -- 1 for injected/control-plane transcript messages
   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)
@@ -54,6 +59,22 @@ CREATE TABLE messages (
 
 Indexes: `idx_messages_session(session_id)`, `idx_messages_agent(agent_id)`, `idx_messages_ts(session_id, timestamp)`.
 
+`content_type` preserves the top-level Claude Code content block shape for the
+message row. Treat `text` as user/assistant visible language, `thinking` as
+trace/debug material, and `tool_use` as a marker that the assistant message
+contains tool calls. `tool_result` marks a tool-result message, but the
+structured payload remains in `tool_results`. Tool-call details remain in
+`tool_calls`. Messages whose top-level content is not one of these four raw
+message surfaces are `unknown`. Real user input is represented by `type='user'`
+and `content_type='text'`, not by a separate `user_message` content type.
+
+`is_meta` marks transcript control-plane content: injected caveats, command
+envelopes such as `<command-name>/exit</command-name>`, and similar messages
+that may appear as user-role text but are not ordinary user intent. It is
+separate from `type`, `role`, and `content_type`. Default helpers hide meta
+messages from ordinary recall; use `includeMeta: true` or explicit SQL when
+investigating injected context, command messages, or transcript structure.
+
 ### messages_fts
 
 FTS5 virtual table for full-text search over message text.
@@ -68,7 +89,28 @@ CREATE VIRTUAL TABLE messages_fts USING fts5(
 );
 ```
 
-Queried via `MATCH` syntax. Rebuilt on each index pass.
+Queried via `MATCH` syntax. The table is kept in sync by the `messages_fts_*`
+triggers above; rebuild it manually only when repairing FTS state.
+
+### memories_fts
+
+FTS5 virtual table for ranked memory recall over registered memory summaries
+and paths.
+
+```sql
+CREATE VIRTUAL TABLE memories_fts USING fts5(
+  id UNINDEXED,         -- memory record ID, carried for inspection
+  path,                 -- searchable memory file path
+  summary,              -- searchable compact memory summary
+  content=memories,
+  content_rowid=rowid,
+  tokenize='unicode61 remove_diacritics 1'
+);
+```
+
+`memories({ query })` queries this table with safe tokenization and joins back to
+`memories`, omitting archived rows. It is rebuilt during index finalization;
+`remember()` also inserts the new memory row into FTS immediately.
 
 ### tool_calls
 
@@ -177,6 +219,14 @@ CREATE TABLE index_state (
 );
 ```
 
+Sentinel rows use synthetic `jsonl_path` keys:
+`__last_build__` stores the last completed build time, `__app_heartbeat__`
+stores the optional app indexer's liveness heartbeat,
+`__app_last_successful_build__` stores the app's last successful index build,
+`__indexer_owner_app__` marks app ownership, and `__last_source_mtime__` records
+the newest indexed source mtime. Skill-side lazy builds skip work only while the
+app heartbeat and app successful-build marker are both fresh.
+
 ### memories
 
 Human-approved markdown memory records registered in Obelisk. The markdown
@@ -191,14 +241,22 @@ CREATE TABLE memories (
   message_start TEXT,               -- first relevant message UUID, if known
   message_end   TEXT,               -- last relevant message UUID, if known
   path          TEXT,               -- normalized absolute markdown memory file path
+  anchors       TEXT,               -- optional JSON array of recall anchors
   summary       TEXT,               -- retrieval summary of the memory
-  created_at    TEXT                -- ISO 8601 registration time
+  created_at    TEXT,               -- ISO 8601 registration time
+  deleted_at    TEXT,               -- ISO 8601 archive time, if forgotten
+  deleted_reason TEXT               -- human/agent deletion reason, if forgotten
 );
 ```
 
 Indexes: `idx_memories_project(project)`,
 `idx_memories_session(session_id)`, `idx_memories_created(created_at)`.
 
+Active memory means `deleted_at IS NULL`. Recall helpers return active memories
+only. Archived memories are management/audit data, not recall data. Query recall
+uses `memories_fts` joined back to `memories`; when using raw SQL for memory
+recall, include `deleted_at IS NULL`.
+
 ### Key Relationships
 
 ```
@@ -221,8 +279,8 @@ workflows.run_id   <--  workflow_agents.run_id
 
 ## 2. Query API Reference
 
-Read helpers are available as globals inside `--query` scripts. Memory write
-helpers are available only inside `--remember` scripts. Scripts run in an async
+Read helpers are available as globals inside `--query` scripts. Memory mutation
+helpers are available only inside `--attune` scripts. Scripts run in an async
 IIFE with a 30-second timeout.
 
 ### Simple Layer
@@ -240,6 +298,7 @@ Full-text search across all message text using FTS5.
 | `opts.after` | `string` | ISO 8601 lower bound on timestamp |
 | `opts.before` | `string` | ISO 8601 upper bound on timestamp |
 | `opts.cwd` | `string` | Filter by working directory (supports LIKE) |
+| `opts.includeMeta` | `boolean` | Include injected/control-plane messages (default `false`) |
 
 **Scope note:** `sessions.project` is the stored Claude Code project slug,
 `sessions.project_path` is the absolute session path derived from message `cwd`
@@ -248,15 +307,22 @@ Helper `project` filters are fuzzy `LIKE` filters over `sessions.project`. For
 exact project membership, use `sql()` with `s.project = ?` or
 `s.project_path = ?`.
 
-**Returns:** `Array<{ message, session, rank, context }>` where `context` is the
-6 nearest messages by timestamp in the same session. It is temporal neighbor
-context, not a parent chain. `rank` is the FTS5 relevance score used by
-`ORDER BY rank`; lower values sort earlier, so treat the returned order as the
-relevance order unless you are deliberately using FTS5 ranking details.
+**Returns:** `Array<{ message, session, rank, context }>` where `message`
+includes `{ uuid, text, content_type, is_meta, role, timestamp, model, cwd }`
+and `context` is the 6 nearest non-meta messages by timestamp in the same
+session unless `includeMeta: true` is passed. It is temporal neighbor context,
+not a parent chain. `rank` is the FTS5 relevance score used by `ORDER BY rank`;
+lower values sort earlier, so treat the returned order as the relevance order
+unless you are deliberately using FTS5 ranking details.
 
 ```js
 const hits = search('MCTS exploration');
-return hits.map(h => ({ title: h.session.title, text: h.message.text?.slice(0, 200) }));
+return hits.map(h => ({
+  title: h.session.title,
+  content_type: h.message.content_type,
+  is_meta: h.message.is_meta,
+  text: h.message.text?.slice(0, 200),
+}));
 ```
 
 #### `context(uuid)`
@@ -285,8 +351,8 @@ Read-only SQL with parameterized bindings. Returns an array of row objects.
 
 **Returns:** `Array<Object>` -- each row as `{ column: value }`.
 
-Write statements are rejected. Use `--remember` and `remember()` for memory
-registration after user approval.
+Write statements are rejected. Use `--attune` with `remember()` or `forget()`
+for memory mutation after user approval.
 
 ```js
 const rows = sql('SELECT id, title FROM sessions WHERE project = ? ORDER BY ended_at DESC LIMIT 5', 'Users-tomiya-Code-quiet-zero');
@@ -306,9 +372,11 @@ const chain = trace('some-uuid');
 return chain.map(m => ({ role: m.role, text: m.text?.slice(0, 100) }));
 ```
 
-#### `thread(sessionId)`
+#### `thread(sessionId, opts?)`
 
-All messages in a session, ordered by timestamp.
+Session messages ordered by timestamp. Meta messages are omitted by default;
+pass `{ includeMeta: true }` to include injected caveats, command envelopes, and
+other control-plane transcript rows.
 
 **Returns:** `Array<message>`.
 
@@ -317,6 +385,31 @@ const msgs = thread('session-uuid');
 return { count: msgs.length, first: msgs[0]?.text?.slice(0, 100) };
 ```
 
+#### `raw(uuid, opts?)`
+
+Windowed access to the original JSONL line for a message. Use this when indexed
+text, tool inputs, or tool results were truncated and you need the raw source.
+It resolves main-session, subagent, and workflow-agent JSONL paths from the
+indexed message metadata.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | `string` | Message UUID |
+| `opts.offset` | `number` | Character offset into the JSONL line (default 0) |
+| `opts.limit` | `number` | Max characters to return (default 10000) |
+
+**Returns:** `{ text, totalLength, offset, limit, hasMore }` or `null` if the
+source line cannot be found.
+
+```js
+const line = raw('message-uuid', { offset: 0, limit: 4000 });
+return {
+  preview: line?.text,
+  has_more: line?.hasMore,
+  total: line?.totalLength,
+};
+```
+
 #### `subagents(opts?)`
 
 All subagent spawns, with message counts. For backward compatibility, passing a string is treated as `sessionId`.
@@ -417,6 +510,34 @@ const last5 = recent(5);
 return last5.map(s => ({ title: s.title, project: s.project_path, ended: s.ended_at }));
 ```
 
+#### `summaries(opts?)`
+
+Session summary rows, newest first. For backward compatibility, passing a
+string is treated as `sessionId`, and passing a number is treated as `limit`.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `opts.sessionId` | `string` | Restrict to one session |
+| `opts.sessions` | `string[]` | Restrict to a set of session IDs |
+| `opts.project` | `string` | SQL `LIKE` pattern over `sessions.project` |
+| `opts.after` | `string` | ISO 8601 lower bound on summary timestamp |
+| `opts.before` | `string` | ISO 8601 upper bound on summary timestamp |
+| `opts.branch` | `string` | Filter by source session git branch (exact match) |
+| `opts.limit` | `number` | Max results (default 100) |
+
+**Returns:** `Array<summary_row & { session_title, project }>` ordered by
+`timestamp` descending.
+
+```js
+const rows = summaries({ project: '%quiet-zero%', limit: 5 });
+return rows.map(s => ({
+  session: s.session_title,
+  source: s.source,
+  summary: s.content?.slice(0, 240),
+  timestamp: s.timestamp,
+}));
+```
+
 #### `overview(opts?)`
 
 Compact orientation map for choosing the next retrieval scope. It is not an
@@ -457,7 +578,7 @@ from `process.cwd()` against `sessions.project_path`, then from exact
     ],
     memory_total,
     memories: [
-      { id, path, summary, session_id, project, created_at }
+      { id, path, anchors, summary, session_id, project, created_at }
     ]
   } | null,
   projects: [
@@ -491,6 +612,7 @@ return {
   memories: map.current_project?.memories.map(m => ({
     id: m.id,
     path: m.path,
+    anchors: m.anchors,
     summary: m.summary,
   })),
 };
@@ -522,12 +644,12 @@ return qz.map(s => ({ title: s.title, branch: s.git_branch, ended: s.ended_at })
 
 #### `memories(opts?)`
 
-Registered markdown memory records. Like other list helpers, passing a string
-is treated as `sessionId`, and passing a number is treated as `limit`.
+Active registered markdown memory records. Like other list helpers, passing a
+string is treated as `sessionId`, and passing a number is treated as `limit`.
 
 | Param | Type | Description |
 |-------|------|-------------|
-| `opts.query` | `string` | English term filter over `summary` and `path`; hyphens/underscores are treated as spaces |
+| `opts.query` | `string` | English FTS recall query over `summary` and `path`; hyphens/underscores/punctuation are safely tokenized |
 | `opts.project` | `string` | SQL `LIKE` pattern over `memories.project` |
 | `opts.sessionId` | `string` | Restrict to one source session |
 | `opts.sessions` | `string[]` | Restrict to a set of source session IDs |
@@ -536,9 +658,13 @@ is treated as `sessionId`, and passing a number is treated as `limit`.
 | `opts.branch` | `string` | Filter by source session git branch (exact match) |
 | `opts.limit` | `number` | Max results (default 50) |
 
-**Returns:** `Array<memory_row>` ordered by `created_at` descending.
+**Returns:** `Array<memory_row & { rank?: number }>` with archived memories
+omitted. Without `query`, results are ordered by `created_at` descending. With
+`query`, results are ordered by FTS rank first, then `created_at` descending;
+lower rank sorts earlier.
 
-`query` is a lightweight English term filter, not FTS5 ranking. Translate
+`query` uses safe FTS5 tokenization rather than raw `MATCH`, so punctuation-only
+queries return no rows instead of broadening into all memories. Translate
 non-English user requests into concise English query terms before calling
 `memories()`. Use it to avoid pulling all recent memories, then read the
 markdown file at `path` when a memory looks relevant. The runtime rejects
@@ -553,6 +679,7 @@ const prior = memories({
 return prior.map(m => ({
   id: m.id,
   path: m.path,
+  anchors: m.anchors,
   session_id: m.session_id,
   summary: m.summary?.slice(0, 240),
 }));
@@ -562,11 +689,11 @@ return prior.map(m => ({
 
 Register a human-approved markdown memory file. This is a write helper, not a
 recall helper; use it only after the user has approved writing memory. It is
-available only in scripts run with `runtime.mjs --remember`.
+available only in scripts run with `runtime.mjs --attune`.
 
-`--remember` exposes only `remember()`, not `search()`, `sql()`, `memories()`,
-or other retrieval helpers. If source IDs are unknown, find them first with a
-normal `--query` script.
+`--attune` exposes only `remember()` and `forget()`, not `search()`, `sql()`,
+`memories()`, or other retrieval helpers. If source IDs or memory IDs are
+unknown, find them first with a normal `--query` script.
 
 | Param | Type | Description |
 |-------|------|-------------|
@@ -576,12 +703,14 @@ normal `--query` script.
 | `record.message_start` | `string` | First relevant source message UUID, if known |
 | `record.message_end` | `string` | Last relevant source message UUID, if known |
 | `record.project` | `string` | Project slug override. Defaults from `sessions.project` for `session_id` |
+| `record.anchors` | `array` or JSON `string` | Optional recall anchors stored as JSON text. Expected shape is an array of objects, such as `{ kind: 'file', path: 'src/index/builder.ts' }` |
 
 `remember()` validates that `path` exists and is a regular file, and rejects
 obvious CJK text in `summary`. It stores the normalized absolute path in
-`memories.path`.
+`memories.path`. `anchors` is nullable; omit it or pass an empty array when the
+memory has no explicit file or object anchors.
 
-**Returns:** `{ id, path, project, created_at }`.
+**Returns:** `{ id, path, project, anchors, created_at }`.
 
 ```js
 return remember({
@@ -589,10 +718,53 @@ return remember({
   session_id: 'source-session-id',
   message_start: 'first-message-uuid',
   message_end: 'last-message-uuid',
+  anchors: [{ kind: 'file', path: 'src/index/builder.ts' }],
   summary: 'Decision: keep Obelisk as one user-facing entry that queries both memory and raw session evidence. Memory is prior notes, not final authority.',
 });
 ```
 
+#### `forget(record)`
+
+Archive a human-approved memory record. Use it when the user says a memory is
+outdated, wrong, or should be forgotten. It is available only in scripts run
+with `runtime.mjs --attune`.
+
+`forget()` requires a precise memory ID. Do not pass a query string and let the
+helper choose. If the ID is unknown, first use a normal `--query` script with
+`memories()` to identify candidates. If exactly one candidate clearly matches
+the user's request, the request is approval to archive it. If multiple memories
+could match, ask the user which one to forget.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `record.id` | `string` | Memory record ID to archive |
+| `record.reason` | `string` | Required reason for audit and future management views |
+
+`forget()` sets `deleted_at` and `deleted_reason`. It does not delete the
+markdown file at `path`. Active recall helpers omit archived memories.
+
+**Returns:** `{ id, deleted_at, deleted_reason }`, or the same fields plus
+`already_deleted: true` if the record had already been forgotten.
+
+```js
+return forget({
+  id: 'mem-20260610-example',
+  reason: 'Outdated by newer project guidance.',
+});
+```
+
+#### Memory Mutation Approval
+
+Agents may decide whether to use, ignore, or verify memory in a single answer
+without approval. Approval is required only for persistent memory mutations.
+When the user explicitly says a memory is wrong, outdated, should be forgotten,
+or should say something else, that utterance is approval to mutate the exact
+matching memory. If multiple memories could match, ask the user to choose.
+
+Updating is not an in-place edit. Archive the old record with `forget()`, then
+write and register a replacement markdown file with `remember()` under the same
+approval.
+
 ---
 
 ## 3. Common Query Patterns
@@ -667,7 +839,7 @@ 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,
+    type: a.agent_type, desc: a.description, msgs: a.messageCount,
   }));
 }
 return wfs.slice(0, 3);
diff --git a/scripts/db.mjs b/scripts/db.mjs
index b194ad1..c6ab8d9 100644
--- a/scripts/db.mjs
+++ b/scripts/db.mjs
@@ -8,69 +8,34 @@ const { DatabaseSync } = require('node:sqlite');
 const CLAUDE_DIR = path.join(os.homedir(), '.claude');
 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,
-  cwd TEXT, skill TEXT, turn_duration_ms 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, is_error INTEGER DEFAULT 0);
-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,
-  duration_ms INTEGER, total_tokens INTEGER, status TEXT, workflow_name TEXT);
-CREATE TABLE IF NOT EXISTS workflow_agents (
-  agent_id TEXT PRIMARY KEY, run_id TEXT, session_id TEXT,
-  agent_type TEXT, description TEXT,
-  phase TEXT, label TEXT, model TEXT, state TEXT,
-  duration_ms INTEGER, tokens INTEGER, tool_calls INTEGER);
-CREATE TABLE IF NOT EXISTS index_state (
-  jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER);
-CREATE TABLE IF NOT EXISTS summaries (
-  id TEXT PRIMARY KEY, session_id TEXT, timestamp TEXT,
-  source TEXT, content TEXT);
-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);
-CREATE INDEX IF NOT EXISTS idx_summaries_session ON summaries(session_id);
-CREATE TABLE IF NOT EXISTS memories (
-  id TEXT PRIMARY KEY, session_id TEXT, project TEXT,
-  message_start TEXT, message_end TEXT,
-  path TEXT, summary TEXT, created_at TEXT);
-CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
-CREATE INDEX IF NOT EXISTS idx_memories_session ON memories(session_id);
-CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
-`;
+const SCHEMA = fs.readFileSync(new URL('./schema.sql', import.meta.url), 'utf8');
 
 function openDb() {
   const db = new DatabaseSync(DB_PATH);
   db.exec('PRAGMA journal_mode=WAL');
   db.exec('PRAGMA synchronous=NORMAL');
   db.exec(SCHEMA);
+  migrateDb(db);
   return db;
 }
 
+function ensureColumn(db, table, column, definition) {
+  const columns = db.prepare(`PRAGMA table_info(${table})`).all().map(c => c.name);
+  if (!columns.includes(column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+}
+
+function migrateDb(db) {
+  ensureColumn(db, 'messages', 'content_type', 'TEXT');
+  ensureColumn(db, 'messages', 'is_meta', 'INTEGER DEFAULT 0');
+  ensureColumn(db, 'memories', 'anchors', 'TEXT');
+  ensureColumn(db, 'memories', 'deleted_at', 'TEXT');
+  ensureColumn(db, 'memories', 'deleted_reason', 'TEXT');
+}
+
+function rebuildMemoryFts(db) {
+  db.exec("INSERT INTO memories_fts(memories_fts) VALUES('rebuild')");
+}
+
 function trunc(s) {
   return typeof s === 'string' && s.length > TEXT_LIMIT ? s.slice(0, TEXT_LIMIT) : s;
 }
@@ -101,6 +66,30 @@ function extractText(content) {
   return parts.length ? trunc(parts.join('\n')) : null;
 }
 
+function extractContentType(content) {
+  if (typeof content === 'string') return 'text';
+  if (!Array.isArray(content) || !content.length) return 'unknown';
+  const types = new Set();
+  let sawUnknown = false;
+  for (const b of content) {
+    if (!b || typeof b !== 'object') { sawUnknown = true; continue; }
+    if (b.type === 'text') types.add('text');
+    else if (b.type === 'thinking') types.add('thinking');
+    else if (b.type === 'tool_use') types.add('tool_use');
+    else if (b.type === 'tool_result') types.add('tool_result');
+    else sawUnknown = true;
+  }
+  return !sawUnknown && types.size === 1 ? [...types][0] : 'unknown';
+}
+
+const COMMAND_ENVELOPE_RE = /^\s*(<command-name>[^<]+<\/command-name>|<(?:task-notification|system-reminder)\b|<local-command(?:\b|-))/;
+
+function extractMessageIsMeta(record, text = extractText(record?.message?.content)) {
+  const msg = record?.message || {};
+  if (record?.isMeta === true || msg.isMeta === true) return 1;
+  return typeof text === 'string' && COMMAND_ENVELOPE_RE.test(text) ? 1 : 0;
+}
+
 function filePath(name, input) {
   if (!input) return null;
   return ['Read', 'Edit', 'Write', 'NotebookEdit'].includes(name) ? (input.file_path || null) : null;
@@ -129,4 +118,4 @@ function readLines(filePath, callback) {
   }
 }
 
-export { CLAUDE_DIR, DB_PATH, TEXT_LIMIT, openDb, trunc, truncJson, extractText, filePath, isDir, readLines, fs, path, os };
+export { CLAUDE_DIR, DB_PATH, TEXT_LIMIT, openDb, rebuildMemoryFts, trunc, truncJson, extractText, extractContentType, extractMessageIsMeta, filePath, isDir, readLines, fs, path, os };
diff --git a/scripts/indexer.mjs b/scripts/indexer.mjs
index c787e63..bb3479e 100644
--- a/scripts/indexer.mjs
+++ b/scripts/indexer.mjs
@@ -1,4 +1,4 @@
-import { CLAUDE_DIR, openDb, trunc, truncJson, extractText, filePath, isDir, readLines, fs, path } from './db.mjs';
+import { CLAUDE_DIR, openDb, rebuildMemoryFts, trunc, truncJson, extractText, extractContentType, extractMessageIsMeta, filePath, isDir, readLines, fs, path } from './db.mjs';
 
 const PROJECTS_DIR = path.join(CLAUDE_DIR, 'projects');
 const HISTORY_PATH = path.join(CLAUDE_DIR, 'history.jsonl');
@@ -82,7 +82,7 @@ function indexJsonl(db, fi) {
 
   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,cwd,skill) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)'),
+    msg: db.prepare('INSERT OR REPLACE INTO messages (uuid,session_id,type,parent_uuid,timestamp,role,text,content_type,is_meta,model,is_sidechain,agent_id,input_tokens,output_tokens,cwd,skill) 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,is_error) VALUES (?,?,?,?,?,?)'),
     sum: db.prepare('INSERT OR REPLACE INTO summaries (id,session_id,timestamp,source,content) VALUES (?,?,?,?,?)'),
@@ -129,12 +129,14 @@ function indexJsonl(db, fi) {
 
     const msg = obj.message || {};
     const text = extractText(msg.content);
+    const contentType = extractContentType(msg.content);
+    const isMeta = extractMessageIsMeta(obj, text);
     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,
+        msg.role || obj.type, text, contentType, isMeta, msg.model || null,
         obj.isSidechain ? 1 : 0, aid, usage.input_tokens || null, usage.output_tokens || null,
         obj.cwd || null, obj.attributionSkill || null);
     }
@@ -244,12 +246,33 @@ function indexHistory(db) {
 }
 
 const BUILD_DEBOUNCE_MS = 30000;
+const APP_HEARTBEAT_FRESH_MS = 60000;
+
+function shouldSkipBuild(db, { now = Date.now() } = {}) {
+  const appHeartbeat = db.prepare("SELECT mtime FROM index_state WHERE jsonl_path='__app_heartbeat__'").get();
+  const appSuccessfulBuild = db.prepare("SELECT mtime FROM index_state WHERE jsonl_path='__app_last_successful_build__'").get();
+  if (
+    appHeartbeat && now - appHeartbeat.mtime < APP_HEARTBEAT_FRESH_MS &&
+    appSuccessfulBuild && now - appSuccessfulBuild.mtime < APP_HEARTBEAT_FRESH_MS
+  ) {
+    return { skip: true, reason: 'app_successful_build' };
+  }
+  const last = db.prepare("SELECT mtime FROM index_state WHERE jsonl_path='__last_build__'").get();
+  if (last && now - last.mtime < BUILD_DEBOUNCE_MS) {
+    return { skip: true, reason: 'recent_build' };
+  }
+  return { skip: false };
+}
 
 function buildIndex({ force = false } = {}) {
   const db = openDb();
   if (!force) {
-    const last = db.prepare("SELECT mtime FROM index_state WHERE jsonl_path='__last_build__'").get();
-    if (last && Date.now() - last.mtime < BUILD_DEBOUNCE_MS) { db.close(); return; }
+    const skip = shouldSkipBuild(db);
+    if (skip.skip) { db.close(); return; }
+  }
+
+  if (force) {
+    db.prepare("DELETE FROM index_state WHERE jsonl_path != '__last_build__'").run();
   }
 
   const files = discoverJsonlFiles();
@@ -270,6 +293,7 @@ function buildIndex({ force = false } = {}) {
     refreshSessionProjectPaths(db);
     indexHistory(db);
     db.exec("INSERT INTO messages_fts(messages_fts) VALUES('rebuild')");
+    rebuildMemoryFts(db);
     db.prepare("INSERT OR REPLACE INTO index_state (jsonl_path, mtime, lines_processed) VALUES ('__last_build__', ?, 0)").run(Date.now());
     db.exec('COMMIT');
   } catch (e) {
@@ -279,4 +303,4 @@ function buildIndex({ force = false } = {}) {
   db.close();
 }
 
-export { buildIndex, inferProjectPath, refreshSessionProjectPaths };
+export { buildIndex, inferProjectPath, refreshSessionProjectPaths, shouldSkipBuild };
diff --git a/scripts/query.mjs b/scripts/query.mjs
index f8a1ea5..ed3aaa7 100644
--- a/scripts/query.mjs
+++ b/scripts/query.mjs
@@ -1,4 +1,4 @@
-import { openDb, readLines, fs, path } from './db.mjs';
+import { readLines, fs, path } from './db.mjs';
 
 function normalizeOpts(optsOrScalar, scalarKey = 'sessionId') {
   if (optsOrScalar == null) return {};
@@ -45,6 +45,14 @@ function assertEnglishMemoryText(value, label) {
   }
 }
 
+function buildSafeFtsQuery(text) {
+  const tokens = String(text || '').match(/[\p{Letter}\p{Number}]+/gu) || [];
+  return tokens
+    .slice(0, 12)
+    .map(token => `"${token}"`)
+    .join(' ');
+}
+
 function createQueryApi(db) {
   const q = (sql, ...p) => {
     assertReadOnlySql(sql);
@@ -59,7 +67,7 @@ function createQueryApi(db) {
   };
 
   const search = (text, opts = {}) => {
-    const { limit = 20, sessionId, project, after, before, cwd } = opts;
+    const { limit = 20, sessionId, project, after, before, cwd, includeMeta = false } = opts;
     let where = 'WHERE mf.text MATCH ?';
     const p = [text];
     if (sessionId) { where += ' AND mf.session_id=?'; p.push(sessionId); }
@@ -67,19 +75,21 @@ function createQueryApi(db) {
     if (after)     { where += ' AND m.timestamp>?';    p.push(after); }
     if (before)    { where += ' AND m.timestamp<?';    p.push(before); }
     if (cwd)       { where += ' AND m.cwd LIKE ?';     p.push(cwd); }
+    if (!includeMeta) where += ' AND COALESCE(m.is_meta,0)=0';
     p.push(limit);
     const rows = db.prepare(`
-      SELECT m.uuid,m.session_id,m.text,m.role,m.timestamp,m.model,m.cwd,
+      SELECT m.uuid,m.session_id,m.text,m.content_type,m.is_meta,m.role,m.timestamp,m.model,m.cwd,
              s.id as s_id,s.title as s_title,s.project as s_project,s.started_at as s_started,
              rank
       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 metaClause = includeMeta ? '' : 'AND COALESCE(is_meta,0)=0';
       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'
+        `SELECT uuid,text,content_type,is_meta,role,timestamp,model FROM messages WHERE session_id=? AND uuid!=? ${metaClause} 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, cwd: r.cwd },
+        message: { uuid: r.uuid, text: r.text, content_type: r.content_type, is_meta: r.is_meta || 0, role: r.role, timestamp: r.timestamp, model: r.model, cwd: r.cwd },
         session: { id: r.s_id, title: r.s_title, project: r.s_project, started_at: r.s_started },
         rank: r.rank,
         context: ctx,
@@ -110,7 +120,11 @@ function createQueryApi(db) {
     return chain;
   };
 
-  const thread = (sid) => db.prepare('SELECT * FROM messages WHERE session_id=? ORDER BY timestamp').all(sid);
+  const thread = (sid, opts = {}) => {
+    const includeMeta = opts?.includeMeta === true;
+    const metaClause = includeMeta ? '' : 'AND COALESCE(is_meta,0)=0';
+    return db.prepare(`SELECT * FROM messages WHERE session_id=? ${metaClause} ORDER BY timestamp`).all(sid);
+  };
 
   const subagents = (optsOrSid) => {
     const opts = normalizeOpts(optsOrSid);
@@ -267,7 +281,7 @@ function createQueryApi(db) {
       WITH names AS (
         SELECT project FROM sessions WHERE project IS NOT NULL GROUP BY project
         UNION
-        SELECT project FROM memories WHERE project IS NOT NULL GROUP BY project
+        SELECT project FROM memories WHERE project IS NOT NULL AND deleted_at IS NULL GROUP BY project
       ),
       session_stats AS (
         SELECT project, COUNT(*) AS session_count, MAX(COALESCE(ended_at, started_at)) AS last_session_at
@@ -278,7 +292,7 @@ function createQueryApi(db) {
       memory_stats AS (
         SELECT project, COUNT(*) AS memory_count, MAX(created_at) AS last_memory_at
         FROM memories
-        WHERE project IS NOT NULL
+        WHERE project IS NOT NULL AND deleted_at IS NULL
         GROUP BY project
       )
       SELECT
@@ -322,11 +336,11 @@ function createQueryApi(db) {
         ORDER BY COALESCE(ended_at, started_at) DESC
         LIMIT ?
       `).all(currentProject.project, sessionLimit);
-      const memoryTotal = db.prepare('SELECT COUNT(*) AS c FROM memories WHERE project = ?').get(currentProject.project)?.c || 0;
+      const memoryTotal = db.prepare('SELECT COUNT(*) AS c FROM memories WHERE project = ? AND deleted_at IS NULL').get(currentProject.project)?.c || 0;
       const memoriesForProject = db.prepare(`
-        SELECT id, path, summary, session_id, project, created_at
+        SELECT id, path, anchors, summary, session_id, project, created_at
         FROM memories
-        WHERE project = ?
+        WHERE project = ? AND deleted_at IS NULL
         ORDER BY created_at DESC
         LIMIT ?
       `).all(currentProject.project, memoryLimit);
@@ -345,11 +359,11 @@ function createQueryApi(db) {
       FROM (
         SELECT project FROM sessions WHERE project IS NOT NULL GROUP BY project
         UNION
-        SELECT project FROM memories WHERE project IS NOT NULL GROUP BY project
+        SELECT project FROM memories WHERE project IS NOT NULL AND deleted_at IS NULL GROUP BY project
       )
     `).get()?.c || 0;
     const totalSessions = db.prepare('SELECT COUNT(*) AS c FROM sessions').get()?.c || 0;
-    const totalMemories = db.prepare('SELECT COUNT(*) AS c FROM memories').get()?.c || 0;
+    const totalMemories = db.prepare('SELECT COUNT(*) AS c FROM memories WHERE deleted_at IS NULL').get()?.c || 0;
 
     return {
       current: {
@@ -422,25 +436,32 @@ function createQueryApi(db) {
       timestamp: 'mem.created_at',
       branch: 's.git_branch',
     });
-    const terms = String(query || '')
-      .trim()
-      .replace(/[-_]/g, ' ')
-      .split(/\s+/)
-      .filter(Boolean);
-    let where = baseWhere;
-    for (const term of terms) {
-      where += " AND lower(coalesce(mem.summary,'') || ' ' || coalesce(mem.path,'')) LIKE ?";
-      params.push(`%${term.toLowerCase()}%`);
-    }
-    params.push(limit);
+    let where = baseWhere + ' AND mem.deleted_at IS NULL';
     const join = needsJoin ? 'LEFT JOIN sessions s ON s.id=mem.session_id' : '';
-    return db.prepare(`SELECT mem.* FROM memories mem ${join} WHERE ${where} ORDER BY mem.created_at DESC LIMIT ?`).all(...params);
+    const hasQuery = String(query || '').trim().length > 0;
+    const ftsQuery = buildSafeFtsQuery(query);
+    if (!hasQuery) {
+      params.push(limit);
+      return db.prepare(`SELECT mem.* FROM memories mem ${join} WHERE ${where} ORDER BY mem.created_at DESC LIMIT ?`).all(...params);
+    }
+    if (!ftsQuery) return [];
+    params.unshift(ftsQuery);
+    params.push(limit);
+    return db.prepare(`
+      SELECT mem.*, mf.rank AS rank
+      FROM memories_fts mf
+      JOIN memories mem ON mem.rowid = mf.rowid
+      ${join}
+      WHERE memories_fts MATCH ? AND ${where}
+      ORDER BY mf.rank, mem.created_at DESC
+      LIMIT ?
+    `).all(...params);
   };
 
   return { sql: q, search, context, trace, thread, subagents, workflows, workflowTree, fileHistory, failures, sessions, recent, summaries, raw, memories, overview };
 }
 
-function createRememberApi(db) {
+function createAttuneApi(db) {
   const resolveMemoryPath = (memoryPath, sessionId) => {
     let base = null;
     if (sessionId) {
@@ -459,19 +480,54 @@ function createRememberApi(db) {
     return resolved;
   };
 
-  const remember = ({ path: memoryPath, session_id, message_start, message_end, summary, project }) => {
+  const normalizeAnchors = (anchors) => {
+    if (anchors == null) return null;
+    let parsed = anchors;
+    if (typeof anchors === 'string') {
+      const trimmed = anchors.trim();
+      if (!trimmed) return null;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        throw new Error('remember() anchors must be a JSON array');
+      }
+    }
+    if (!Array.isArray(parsed)) throw new Error('remember() anchors must be an array');
+    for (const anchor of parsed) {
+      if (!anchor || typeof anchor !== 'object' || Array.isArray(anchor)) {
+        throw new Error('remember() anchors entries must be objects');
+      }
+    }
+    return parsed.length ? JSON.stringify(parsed) : null;
+  };
+
+  const remember = ({ path: memoryPath, session_id, message_start, message_end, summary, project, anchors }) => {
     if (!memoryPath || !summary) throw new Error('remember() requires path and summary');
     assertEnglishMemoryText(summary, 'remember() summary');
     const normalizedPath = resolveMemoryPath(memoryPath, session_id);
+    const normalizedAnchors = normalizeAnchors(anchors);
     const id = `mem-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const proj = project || db.prepare('SELECT project FROM sessions WHERE id=?').get(session_id)?.project || null;
     const created_at = new Date().toISOString();
-    db.prepare('INSERT OR REPLACE INTO memories (id, session_id, project, message_start, message_end, path, summary, created_at) VALUES (?,?,?,?,?,?,?,?)').run(
-      id, session_id || null, proj, message_start || null, message_end || null, normalizedPath, summary, created_at);
-    return { id, path: normalizedPath, project: proj, created_at };
+    db.prepare('INSERT OR REPLACE INTO memories (id, session_id, project, message_start, message_end, path, anchors, summary, created_at) VALUES (?,?,?,?,?,?,?,?,?)').run(
+      id, session_id || null, proj, message_start || null, message_end || null, normalizedPath, normalizedAnchors, summary, created_at);
+    return { id, path: normalizedPath, project: proj, anchors: normalizedAnchors, created_at };
   };
 
-  return { remember };
+  const forget = ({ id, reason }) => {
+    const deletionReason = String(reason || '').trim();
+    if (!id || !deletionReason) throw new Error('forget() requires id and reason');
+    const row = db.prepare('SELECT id, deleted_at, deleted_reason FROM memories WHERE id=?').get(id);
+    if (!row) throw new Error(`forget() memory not found: ${id}`);
+    if (row.deleted_at) {
+      return { id, deleted_at: row.deleted_at, deleted_reason: row.deleted_reason, already_deleted: true };
+    }
+    const deleted_at = new Date().toISOString();
+    db.prepare('UPDATE memories SET deleted_at=?, deleted_reason=? WHERE id=?').run(deleted_at, deletionReason, id);
+    return { id, deleted_at, deleted_reason: deletionReason };
+  };
+
+  return { remember, forget };
 }
 
-export { createQueryApi, createRememberApi };
+export { createQueryApi, createAttuneApi };
diff --git a/scripts/runtime.mjs b/scripts/runtime.mjs
index fd365e7..9119a3e 100644
--- a/scripts/runtime.mjs
+++ b/scripts/runtime.mjs
@@ -7,7 +7,7 @@ const vm = require('node:vm');
 
 import { DB_PATH, openDb } from './db.mjs';
 import { buildIndex } from './indexer.mjs';
-import { createQueryApi, createRememberApi } from './query.mjs';
+import { createQueryApi, createAttuneApi } from './query.mjs';
 
 function executeScript(api, scriptContent) {
   const sandbox = {
@@ -22,8 +22,8 @@ function executeQuery(db, scriptContent) {
   return executeScript(createQueryApi(db), scriptContent);
 }
 
-function executeRemember(db, scriptContent) {
-  return executeScript(createRememberApi(db), scriptContent);
+function executeAttune(db, scriptContent) {
+  return executeScript(createAttuneApi(db), scriptContent);
 }
 
 function main() {
@@ -49,16 +49,16 @@ function main() {
       .catch(e => { process.stdout.write(JSON.stringify({ error: e.message, stack: e.stack }) + '\n'); db.close(); process.exitCode = 1; });
     return;
   }
-  if (args[0] === '--remember' && args[1]) {
+  if (args[0] === '--attune' && args[1]) {
     buildIndex();
     const db = openDb();
     const script = fs.readFileSync(path.resolve(args[1]), 'utf8');
-    executeRemember(db, script)
+    executeAttune(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  node runtime.mjs --remember <file.js>\n');
+  process.stderr.write('Usage:\n  node runtime.mjs --build\n  node runtime.mjs --search "text"\n  node runtime.mjs --query <file.js>\n  node runtime.mjs --attune <file.js>\n');
   process.exitCode = 1;
 }
 
diff --git a/scripts/schema.sql b/scripts/schema.sql
new file mode 100644
index 0000000..963d795
--- /dev/null
+++ b/scripts/schema.sql
@@ -0,0 +1,85 @@
+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, content_type TEXT,
+  is_meta INTEGER DEFAULT 0, model TEXT,
+  is_sidechain INTEGER DEFAULT 0, agent_id TEXT,
+  input_tokens INTEGER, output_tokens INTEGER,
+  cwd TEXT, skill TEXT, turn_duration_ms 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, is_error INTEGER DEFAULT 0);
+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,
+  duration_ms INTEGER, total_tokens INTEGER, status TEXT, workflow_name TEXT);
+CREATE TABLE IF NOT EXISTS workflow_agents (
+  agent_id TEXT PRIMARY KEY, run_id TEXT, session_id TEXT,
+  agent_type TEXT, description TEXT,
+  phase TEXT, label TEXT, model TEXT, state TEXT,
+  duration_ms INTEGER, tokens INTEGER, tool_calls INTEGER);
+CREATE TABLE IF NOT EXISTS index_state (
+  jsonl_path TEXT PRIMARY KEY, mtime REAL, lines_processed INTEGER);
+CREATE TABLE IF NOT EXISTS summaries (
+  id TEXT PRIMARY KEY, session_id TEXT, timestamp TEXT,
+  source TEXT, content TEXT);
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+  uuid UNINDEXED, session_id UNINDEXED, text, content=messages, content_rowid=rowid);
+CREATE TRIGGER IF NOT EXISTS messages_fts_ai AFTER INSERT ON messages BEGIN
+  INSERT INTO messages_fts(rowid, uuid, session_id, text)
+  VALUES (new.rowid, new.uuid, new.session_id, new.text);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_fts_ad AFTER DELETE ON messages BEGIN
+  INSERT INTO messages_fts(messages_fts, rowid, uuid, session_id, text)
+  VALUES ('delete', old.rowid, old.uuid, old.session_id, old.text);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_fts_au AFTER UPDATE ON messages BEGIN
+  INSERT INTO messages_fts(messages_fts, rowid, uuid, session_id, text)
+  VALUES ('delete', old.rowid, old.uuid, old.session_id, old.text);
+  INSERT INTO messages_fts(rowid, uuid, session_id, text)
+  VALUES (new.rowid, new.uuid, new.session_id, new.text);
+END;
+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);
+CREATE INDEX IF NOT EXISTS idx_summaries_session ON summaries(session_id);
+CREATE TABLE IF NOT EXISTS memories (
+  id TEXT PRIMARY KEY, session_id TEXT, project TEXT,
+  message_start TEXT, message_end TEXT,
+  path TEXT, anchors TEXT, summary TEXT, created_at TEXT,
+  deleted_at TEXT, deleted_reason TEXT);
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  id UNINDEXED, path, summary,
+  content=memories, content_rowid=rowid,
+  tokenize='unicode61 remove_diacritics 1');
+CREATE TRIGGER IF NOT EXISTS memories_fts_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, id, path, summary)
+  VALUES (new.rowid, new.id, new.path, new.summary);
+END;
+CREATE TRIGGER IF NOT EXISTS memories_fts_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, id, path, summary)
+  VALUES ('delete', old.rowid, old.id, old.path, old.summary);
+END;
+CREATE TRIGGER IF NOT EXISTS memories_fts_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, id, path, summary)
+  VALUES ('delete', old.rowid, old.id, old.path, old.summary);
+  INSERT INTO memories_fts(rowid, id, path, summary)
+  VALUES (new.rowid, new.id, new.path, new.summary);
+END;
+CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
+CREATE INDEX IF NOT EXISTS idx_memories_session ON memories(session_id);
+CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);