English | 简体中文
Search and read your past AI coding-agent conversation history from the command line — so your agent can recover earlier research, commands, errors, and decisions instead of repeating work.
Ships a small CLI (ochist
) and an Agent Skill so agents like OpenCode and Claude Code can check history before doing fresh research.
Multi-agent. Reads OpenCode (opencode.db
) and Claude Code (~/.claude/projects/*.jsonl
) out of the box, plus additional locally detected agents. Pluggable: add a new agent by implementing one interface.Project- or global-scoped. Searches default to the current project (current directory and below);--global
widens to everything.Read-only. Never modifies any data store.Context-friendly. Plain, pipe-friendly output. Agents page withgrep
/head
/wc
/jq
instead of dumping whole sessions into context.Zero runtime dependencies. Uses Node's built-innode:sqlite
(Node ≥ 22.5). No native modules.
AI coding agents are mostly stateless across sessions. Every new chat starts from zero, so the agent happily redoes investigation it already finished yesterday — re-reading the same files, re-running the same commands, re-deriving the same conclusions. That wastes your time, your tokens, and your patience.
agent-historian
gives the agent (and you) a cheap, local way to ask:
"Have I solved this before? What command did I run? Which file did we change? What did we decide, and why?"
It deliberately does not try to summarize sessions with brittle heuristics
(regex-based "accomplishment extraction" breaks on non-English text and on any
phrasing it didn't anticipate). Instead it lets the agent read the real text
on demand, using a progressive-disclosure workflow (locate → orient → scan → read
) so only the relevant lines enter the context window.
Developers who switch between projects and sessions and want their agent to remember prior work instead of starting over.AI coding agents(OpenCode, Claude Code, Qoder, …) that shouldcheck history before doing fresh research— wired up via the bundled Agent Skill.Tool builders who want a small, dependency-free, read-only way to query local agent transcripts across multiple tools through one interface.
There are several ways to give an agent "memory." agent-historian
is deliberately the simplest one — it doesn't build a memory, it reads the ground truth you already have on disk.
| Approach | What it stores | Retrieval | Cost / setup | Faithfulness |
|---|---|---|---|---|
| agent-historian | ||||
| nothing — reads existing transcripts | lexical (grep/substring), on demand | zero index, zero deps, read-only | exact original text | |
| Memory layers (mem0, OpenMemory, MemGPT, "memory tools") | ||||
| LLM-distilled facts/summaries it decides to save | semantic recall of summaries | |||
| needs a store + write step; can drift/hallucinate | lossy — a model's paraphrase | |||
| RAG / embeddings (vector DB over chat logs) | ||||
| chunked text + embedding vectors | semantic (vector similarity) | embedding model + vector DB + reindex pipeline | exact chunks, but needs infra & re-indexing | |
Built-in --resume / --continue |
||||
| the agent's own session files | reload one whole session into context | free, but no search | exact, but all-or-nothing | |
| Auto-summary recall (regex/heuristic "what did I accomplish") | ||||
| extracted bullet points | keyword over summaries | cheap | brittle; breaks on non-English / unusual phrasing |
Use when you want toagent-historian
find and re-read what actually happened— the exact command, error, diff, or decision — across past sessions and across multiple agents, with no infra and no risk of a model rewriting history. It's asearch tool over real transcripts, not a memory.** Add a memory layer (mem0, etc.)**when you want the agent to carry forwarddistilled preferences and durable facts("the user prefers pnpm", "deploys go through staging") that should persist as structured knowledge.Use RAG/embeddings when you needsemanticrecall over a large corpus and can afford an embedding model + vector store + re-indexing.
They're complementary: agent-historian
answers "show me the real thing I did," memory/RAG answer "recall the gist of what I know." Many setups use both — historian for exact recall, a memory layer for distilled facts.
No embeddings, no index, no background process— search is plain lexical matching that runs on demand, so there's nothing to build, sync, or keep warm.** Read-only**— it never writes a "memory," so it can't drift from or corrupt the source of truth.** Progressive disclosure**— instead of stuffing summaries into context, the agent pages through results (locate → orient → scan → read
) and pulls only the exact lines it needs.
This started as an MCP server, then deliberately moved to a CLI ( ochist) plus an Agent Skill. Reasons:
The agent already has a shell. With a CLI, the agent composesochist grep … | head
,| wc -l
,| grep -i error
,| jq
itself. An MCP server would have to anticipate and hard-code every such option as tool parameters. The shellisthe query language.Context control belongs to the agent. Paging/filtering withhead
/grep
lets the agent pull only what it needs. An MCP tool tends to return a fixed blob; you re-implement pagination server-side and still over- or under-fetch.Zero resident cost. An MCP server is a long-lived process attached to the session (and its tool schemas occupy context every turn). The CLI runs only when invoked — no daemon, no idle token overhead.A Skill teaches MCP exposeswhenandhow.capabilities; it doesn't tell the agent the workflow. The bundled skill encodes "check history before re-researching" and thelocate → orient → scan → read
recipe — guidance MCP can't carry.Portable & inspectable. One binary works in any agent that can run shell commands, plus humans can run the exact same commands and see the exact output. No transport, no protocol, no per-client wiring.Easy to extend. Adding an agent or a flag is a normal code change; there's no tool-schema/permission round-trip.
MCP is a great fit for capabilities an agent can't otherwise reach (remote APIs, privileged actions). Here the data is local files the agent can already read with a shell, so a CLI + Skill is simpler, cheaper, and more flexible.
agent-historian
mostly exists to fill a gap: agents persist rich session data
locally, but don't expose a first-class way to search and read it back.
OpenCode has session list
(no message/part reader); Claude Code only has
interactive --resume
; Qoder's SDK can resume/continue but not read history.
The cleanest end state is for the agents themselves to ship this:
- A read command, e.g.
opencode message get <session>
/opencode session show
(and equivalents for Claude Code / Qoder) that prints messages and tool I/O as plain, pipe-friendly text. - An official skill that teaches the agent to check its own history before re-researching.
If that happens, you won't need this project — and that would be a good
outcome. Until then, agent-historian
provides a uniform, read-only, cross-agent way to do it today. (And if it stays useful as the cross-agent layer — one tool that reads OpenCode + Claude Code + Qoder + … through one interface and one skill — that's a fine reason for it to stick around too.)
npm install -g agent-historian # exposes the `ochist` command
Or run without installing:
npx agent-historian sources
From source (for development) #
git clone https://github.com/adlternative/agent-historian.git
cd agent-historian
npm install
npm run build
npm link # symlink `ochist` globally
Requires Node ≥ 22.5 (for built-in node:sqlite
).
ochist sources # which agents are detected
ochist sessions --limit 10 # recent sessions across all agents
ochist grep "ssh" --limit 8 # search all history
ochist meta <session> # reliable metadata card
ochist show <session> # one-line-per-message outline
ochist part <part_id> # full text of one message
By default all detected agents are queried. Restrict with --source
:
ochist sessions --source claudecode
ochist grep "docker build" --source opencode
sessions
and grep
default to the current project — sessions whose working directory is the current dir or below. Widen as needed:
ochist sessions # current project (cwd and subdirs)
ochist sessions --global # every project
ochist sessions --dir ~/code/x # a specific directory
ochist grep "ssh" --global # search all history
<session>
/ <part_id>
accept an agent-native id, a slug/prefix, or latest
.
Add --json
to any command for machine-readable output (pipe to jq
).
ochist grep "authorized_keys" --limit 5 # find candidate + part_id
ochist meta silent-star # confirm the session
ochist show silent-star | grep -i ssh-copy-id # locate exact part
ochist part prt_xxxxx # read full message
The repo includes a skill at skills/agent-history/SKILL.md that teaches agents
whenand
howto use
ochist
— so they check history before doing fresh research.The standard community installer. No clone needed; works for OpenCode, Claude Code, Cursor, Codex, and more:
npx skills add adlternative/agent-historian -g
npx skills add adlternative/agent-historian -s agent-history -a opencode -a claude-code -g
If you already installed the CLI (npm i -g agent-historian
/ npm link
), it can install its own bundled skill:
ochist skill install --global # → ~/.claude/skills + ~/.config/opencode/skills
ochist skill install # project-local: ./.claude/skills + ./.agents/skills
ochist skill uninstall --global # remove
ochist skill path # print the bundled skill dir
mkdir -p ~/.claude/skills # read by BOTH Claude Code and OpenCode
ln -s "$(pwd)/skills/agent-history" ~/.claude/skills/agent-history
Restart the agent; it will discover the agent-history
skill and load it on demand when you reference earlier work ("我之前…", "what did we do before", …).
ochist (CLI)
└─ sources/registry.ts selects active sources (auto-detect or --source)
├─ OpenCodeSource reads opencode.db via node:sqlite
├─ ClaudeCodeSource reads ~/.claude/projects/*.jsonl
└─ <your agent here> implement HistorySource
Each source normalizes its agent's data into common Session
/ Part
shapes, so the CLI is agent-agnostic. Search is lexical (regex/substring over message content) — no embeddings, no index, no background process.
Subagents are handled per agent. OpenCode subagents are recorded as their
own sessions (the agent
field is explore
/general
/…). Claude Code subagent
("sidechain") transcripts live in agent-*.jsonl
files that reference their
parent session; agent-historian
folds their content into the parent session
and prefixes it with [subagent …]
, so nothing is lost or duplicated.
Create
src/sources/<agent>.ts
implementing theHistorySource
interface from:src/sources/types.ts
export class MyAgentSource implements HistorySource {
readonly name = 'myagent';
readonly label = 'My Agent';
isAvailable() { /* does its data store exist? */ }
location() { /* where it reads from */ }
listSessions(opts) { /* … */ }
loadParts(sessionId?) { /* … */ }
loadPartRaw(partId) { /* … */ }
resolveSessionId(selector) { /* id | slug | prefix | "latest" */ }
loadTodos(sessionId) { /* [] if unsupported */ }
}
Register it in
by adding it tosrc/sources/registry.ts
ALL_SOURCES
. -
npm run build
. That's it — every subcommand now works for your agent.
agent-historian
reads each agent's local session data: OpenCode's SQLite database and the per-session JSONL transcripts that Claude Code, Qoder, and similar CLIs persist on disk. These on-disk formats are largely not officially documented, so the readers are best-effort and may need updates across agent versions. Everything is strictly read-only — the tool never writes to any agent's data store.
This project stands on the shoulders of others:
byclaude-historian@Vvkmnn— the original inspiration. The core idea ("let the agent search its own past conversations so it stops repeating research"), thehistorianframing, and the on-demand transcript-search approach all trace back to it.agent-historian
reimagines that idea as a multi-agent, CLI-first, skill-driven tool.- The progressive-disclosure / "page, don't dump" philosophy is shared with memory tools like andclaude-mem, which informed the design.mem0 - The agents whose local history this reads — ,OpenCode, andClaude Code— for building tools worth remembering.Qoder
If your project belongs here and isn't credited, please open an issue.
MIT — see LICENSE.