Chronicle

Chronicle

Use this skill when the user asks about previous conversations, earlier project decisions, prior tool executions, compacted-away details, generated artifacts, daily summaries, usage/workflow tips, or rebuilding the local session index.

Chronicle is separate from memory_tool:

• memory_tool reads and writes explicit notes under /memories/....
• session_store_sql queries the read-only indexed session store containing saved turns, checkpoints, files, refs, tool requests, and artifacts.

Tool

Use session_store_sql.

Actions:

Only call action="reindex" when the user asks to rebuild the index, or when query results look stale and you explain why reindexing is needed.

Local SQLite Query Rules

• Queries are read-only.
• Use exactly one statement.
• Use only SELECT or WITH.
• Use datetime('now', '-1 day') for local date math.
• Do not use DuckDB syntax such as now() - INTERVAL.
• Use search_index MATCH ... for FTS search over indexed turn/checkpoint content.
• Use LIKE for file paths, refs, and Chinese/no-whitespace fallback searches.
• Escape single quotes in user text by doubling them.

Tables

sessions

One row per indexed session.

Important columns:

• id: session id
• cwd: working directory
• repository: repository label when known
• host_type: host/client label
• branch: branch label when known
• summary: session summary when available
• agent_name, agent_description: agent surface metadata
• created_at, updated_at

turns

One row per indexed turn.

Important columns:

• session_id
• turn_index
• user_message
• assistant_response
• timestamp

checkpoints

Compaction/checkpoint summaries.

Important columns:

• session_id
• checkpoint_number
• title
• overview
• history
• work_done
• technical_details
• important_files
• next_steps
• created_at

session_files

Files touched or referenced by tools.

Important columns:

• session_id
• file_path
• tool_name
• turn_index
• first_seen_at

session_refs

Lightweight external references extracted from turns.

Important columns:

• session_id
• ref_type
• ref_value
• turn_index
• created_at

tool_requests

Tool-call audit rows.

Important columns:

• session_id
• turn_index
• tool_call_id
• tool_name
• arguments
• result
• state
• created_at

search_index

FTS table for session text and artifacts.

Important columns:

• content
• session_id
• project_path
• source_type
• source_id
• turn_index
• title
• created_at

Common Queries

Search previous sessions for a topic:

SELECT session_id, source_type, title, substr(content, 1, 300) AS excerpt
FROM search_index
WHERE search_index MATCH '"command_exec" OR "terminal"'
ORDER BY created_at DESC
LIMIT 10

Find recent sessions:

SELECT id, cwd, summary, updated_at
FROM sessions
WHERE updated_at >= datetime('now', '-7 days')
ORDER BY updated_at DESC
LIMIT 20

Find prior command-line tool executions:

SELECT session_id, turn_index, tool_name, arguments, state, created_at
FROM tool_requests
WHERE tool_name IN ('command_exec', 'run_in_terminal')
ORDER BY created_at DESC
LIMIT 20

Find sessions that touched a file:

SELECT s.id, s.summary, f.file_path, f.tool_name, f.first_seen_at
FROM session_files f
JOIN sessions s ON s.id = f.session_id
WHERE f.file_path LIKE '%project.abs%'
ORDER BY f.first_seen_at DESC
LIMIT 20

Find checkpoint summaries:

SELECT session_id, checkpoint_number, title, overview, created_at
FROM checkpoints
ORDER BY created_at DESC
LIMIT 20

Chinese/no-whitespace fallback search:

SELECT session_id, source_type, title, substr(content, 1, 300) AS excerpt
FROM search_index
WHERE content LIKE '%命令行%' OR content LIKE '%工具%'
ORDER BY created_at DESC
LIMIT 10

Token/usage analysis when usage columns are present:

SELECT s.agent_name,
       SUM(e.usage_input_tokens) AS input_tokens,
       SUM(e.usage_output_tokens) AS output_tokens,
       e.usage_model
FROM events e
JOIN sessions s ON s.id = e.session_id
WHERE e.event_type = 'assistant.usage'
GROUP BY s.agent_name, e.usage_model
ORDER BY input_tokens + output_tokens DESC
LIMIT 20

If the local store does not contain usage columns, say that token-level analysis is unavailable in the current index and use proxies such as long sessions, large turns.user_message, repeated session_files, and repeated tool_requests.

Workflows

Search

When the user asks whether something happened before, search the current project/session index with session_store_sql. Prefer FTS search_index for free-text history and join to sessions only after you have candidate session_ids. Also check tool_requests, session_files, and session_refs when the user's question mentions tools, files, PRs, issues, commits, or artifacts.

If no results are found, say that the indexed history does not contain evidence. Do not claim the event never happened outside the indexed scope.

Standup / Summary

For daily or project summaries, first query recent sessions, then enrich with turns, checkpoints, session_files, and session_refs. Keep the summary grounded in the rows returned by session_store_sql.

Workflow Tips

For usage or workflow tips, inspect recent sessions, turn counts, repeated file touches, and repeated tool requests. Provide only recommendations grounded in observed rows.

Reindex

If the user asks to rebuild or refresh the session index, call:

{
  "action": "reindex",
  "description": "Rebuild local Chronicle session index",
  "force": true
}

After reindexing, report the before/after stats and retry the user's intended query if appropriate.