Read history
read_historyRead-only
Read recent repository history entries, search them semantically, or open one entry in full to review past work and decisions.
Instructions
Read recent history entries, search them, or read one entry whole.
- Without ``query``: up to ``limit`` newest entries; ``since`` (ISO8601
prefix) keeps entries at or after it.
- With ``query``: the semantically nearest entries with cosine distance;
the index is built on first use and rebuilt when history.md or the
embedding configuration changes.
- ``offset`` skips that many of the newest (or nearest) entries first.
- With ``entry_id``: that entry with its full text, also an archived one;
the other arguments are ignored.
A listing stays under Claude Code's 50,000-character result limit: outcome
up to 600 characters, intent and action up to 300, files and tags up to 20
items, and ``truncated`` gives a shortened entry's full lengths. If that is
still too long, previews shrink and the last entries are left out
(``omitted``; ``instruction`` says how to read them).
With user library sync, the entries the user's machines shared for this
repository are merged in, one per entry hash; ``machine`` keeps one
machine label's entries, or ``local`` this checkout's own.
Without a project, it reads the installation's fallback journal (#292):
the entries kept for the same claimed directory, ``query`` as a text match.
Returns JSON: {entries, total, mode, omitted?, instruction?, workspace,
pid, history_last_error?}; mode is recency, semantic or entry. Entries
(machine: null for this checkout's own):
- recency and entry: {id, timestamp, intent, action, outcome, files, tags, metadata, machine}.
- semantic: {id, distance, timestamp, intent, action, outcome, tags, machine}.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | Optional text to search the history for. | |
| since | No | Optional ISO8601 prefix; only entries at or after it. | |
| offset | No | Entries to skip first, newest or nearest first. | |
| machine | No | Optional machine label, or `local` for this checkout's own entries. | |
| entry_id | No | Optional id of one entry to return whole; the other arguments are then ignored. | |
| workspace | No | Absolute path of your working directory, the project this session works in. Pass it whenever you have one: one server can serve several sessions. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |