# Chronicle

> Analyze indexed Aily chat session history for prior decisions, tool executions, project summaries, usage tips, and session-store reindexing.

- Skill: `ailyproject/chronicle` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ailyproject/chronicle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ailyproject/chronicle/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ailyproject (https://skillmd.com/u/ailyproject)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ailyproject/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:

| Action | Purpose | Required input |
|---|---|---|
| `query` | Execute one read-only SQL query | `description`, `query` |
| `reindex` | Rebuild the local index from saved session history | `description`, optional `force` |

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:

```sql
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:

```sql
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:

```sql
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:

```sql
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:

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

Chinese/no-whitespace fallback search:

```sql
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:

```sql
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_id`s. 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:

```json
{
  "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.