Skip to content

AGENTS.md

Latest commit

 

History

History
216 lines (165 loc) · 9.14 KB

AGENTS.md

File metadata and controls

216 lines (165 loc) · 9.14 KB
Raw

AGENTS.md — chronicle for AI coding agents

You are an AI coding agent. This document tells you exactly when and how to use chronicle.

chronicle is a cold-storage warehouse + searchable recall for Claude Code session transcripts. Every old conversation is preserved on a vault and indexed by SQLite FTS5. You can search every past session, pull metadata, and rehydrate any session back into Claude Code's ~/.claude/projects/ so the user can /resume it.

This file is written specifically for you (an LLM-driven agent). It is intentionally terse, structured, and machine-friendly.

When to invoke chronicle

Invoke chronicle proactively (without waiting for explicit instructions) whenever:

  1. The user references prior work that isn't in your current context. "that wellrx thing we did last week" → chronicle recall "wellrx"
  2. The user asks you to resume or pull up a past session. "resume the Frank session" → chronicle recall "callsign:Frank" --limit 3
  3. The user asks "what did we work on with X?" / "find that conversation about Y."
  4. Before answering from your own memory about a project, search chronicle first — it's the source of truth.
  5. You are about to ask the user to remind you of context they already provided in a previous session. Don't ask; search.

Do not invoke chronicle for:

  • Anything in your live context window.
  • Generic web search / external knowledge.
  • Files in the current working tree (use Read / grep).

The one command you usually want

chronicle recall "QUERY" --limit 5 --include-summary

recall emits JSON by default. It runs FTS5 search, ranks by BM25, and returns:

{
  "query": "wellrx foamer",
  "match_count": 3,
  "matches": [
    {
      "uuid": "7f3b...",
      "project_slug": "-Users-daniel-AI-wellrx_REDESIGN",
      "project_cwd": "/Users/daniel/AI/wellrx_REDESIGN",
      "first_ts": "2026-04-21T18:00:11Z",
      "last_ts": "2026-04-21T19:42:08Z",
      "callsign": null,
      "message_count": 142,
      "snippet": "...FSC 600 is a «foamer» (not corrosion/scale)...",
      "summary": "Established WellRX foamer alert thresholds: ...",
      "first_user_text": "Investigate why FSC 600 alerts keep firing on...",
      "vault_path": "/Volumes/storage/chronicle/sessions/2026/04/.../7f3b...jsonl",
      "rehydrate_cmd": "chronicle rehydrate 7f3b...",
      "resume_cmd_hint": "/resume 7f3b..."
    }
  ],
  "next_steps": "Pick a uuid from matches[]..."
}

Use matches[0] (and matches[1..2] if you need triangulation). Either:

  • Just answer the user using summary / first_user_text — no rehydrate needed.
  • Rehydrate when the user wants to actually /resume that session: 
    chronicle rehydrate 7f3b...
# → tell the user: "Session 7f3b... restored. Run /resume 7f3b..."

FTS5 query syntax (you should know this)

chronicle recall accepts SQLite FTS5 MATCH expressions:

query meaning
foamer pressure both terms (implicit AND)
wellrx OR rowan either
wellrx AND NOT chris exclusion
"FSC 600" phrase
foamer NEAR/5 pressure within 5 tokens
callsign:Frank column filter — Frank's sessions only
project_slug:wellrx column filter — project substring
first_user_text:bounty AND tools_used:Bash multiple column filters

Indexed columns: project_slug, project_cwd, callsign, summary_text, first_user_text, last_user_text, tools_used, files_touched.

All commands (cheat sheet)

chronicle recall    QUERY  [--project P] [--limit N] [--include-summary] [--markdown]
chronicle context   UUID                                 # markdown by default, --json for machine
chronicle search    QUERY  [--project P] [--limit N] [--json]
chronicle list      [--project P] [--status S] [--limit N] [--json]
chronicle show      UUID   [--json]
chronicle rehydrate UUID
chronicle stats     [--json]
chronicle agent     [--markdown]                         # this guide as JSON / markdown
chronicle path                                           # vault + db paths
chronicle archive   [--age N] [--keep-recent K] [--all] [--dry-run]
chronicle index     [--rebuild]
chronicle purge     UUID [--delete-vault]

chronicle agent returns this same guide in machine form — call it once at session start if you need to refresh your understanding of the tool.

Exit codes

code meaning
0 ok
1 partial failure (some items skipped — check stderr)
2 vault unavailable (SMB not mounted, no write perms)
3 invalid input (bad args, malformed FTS query)
4 uuid not found in index
5 vault file missing (index has it but the JSONL is gone)

On 2, do not retry — surface to the user and ask them to mount the vault. On 3, re-form your query (escape quotes, drop invalid operators). On 4/5, search again with a different query or fall back to listing recents.

MCP server

For MCP-aware hosts (Claude Desktop, Claude Code with MCP, custom agents), chronicle ships a stdio MCP server. Install:

pip install 'chronicle[mcp]'

Then register in your MCP host config (e.g. ~/.claude.json for Claude Code):

{
  "mcpServers": {
    "chronicle": { "command": "chronicle-mcp" }
  }
}

Tools exposed:

MCP tool what it does
chronicle_recall the one you usually want — FTS5 search + bundled summaries
chronicle_search lean FTS5 search (no summary text)
chronicle_show full metadata for one UUID
chronicle_context paste-ready markdown + structured fields for one UUID
chronicle_list most-recent archived sessions
chronicle_rehydrate copy back to ~/.claude/projects/, returns /resume command for the user
chronicle_stats vault totals
chronicle_agent_guide returns this guide as a structured payload

Patterns

Pattern: user references vague past work

user: did we ever solve that thing with the foamer pressure alerts?
agent: [calls chronicle_recall("foamer pressure alerts")]
agent: [reads matches[0].summary, answers directly with context, cites uuid]

Pattern: user wants to resume

user: pull up that wellrx session from April, the one with Chris's emails
agent: [calls chronicle_recall("wellrx Chris email", limit=3)]
agent: [picks best match, calls chronicle_rehydrate(uuid)]
agent: "Restored. Run /resume <uuid> to continue it."

Pattern: scoping by callsign

user: what was Frank doing last week?
agent: [calls chronicle_recall("callsign:Frank", limit=10)]
agent: [lists topics from each match's first_user_text]

Pattern: scoping by project

user: search the wellrx sessions for SCADA bugs
agent: [calls chronicle_recall("scada bug", project="wellrx")]

Don'ts

  • Don't rehydrate eagerly. Rehydration adds a JSONL back to ~/.claude/projects/ — only do it when the user wants to /resume that specific session. For just reading past context, chronicle_show / chronicle_context is enough.
  • Don't call chronicle archive unless the user explicitly asks. The daily launchd job already handles routine archival.
  • Don't invent UUIDs. UUIDs come from chronicle_recall / chronicle_list results only.
  • Don't chronicle purge --delete-vault without explicit user confirmation — that destroys the only copy of a session.

Self-check at session start (optional)

If you're a new session and want to know if chronicle is available:

chronicle --version          # prints version, exits 0 if installed
chronicle path               # shows vault path + index path + writable: bool
chronicle stats              # prints session count — useful sanity check

If chronicle path shows writable: False, the vault is unreachable. Surface this to the user — you can still query the index (FTS5 returns hits with metadata), but rehydrate will fail with exit 5.