# Show HN: Agent-historian – let your AI agent search its own past sessions

> Source: <https://github.com/adlternative/agent-historian>
> Published: 2026-06-21 02:58:08+00:00

English | [简体中文](/adlternative/agent-historian/blob/main/README.zh-CN.md)

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](https://opencode.ai) and [Claude Code](https://www.anthropic.com/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 with`grep`

/`head`

/`wc`

/`jq`

instead of dumping whole sessions into context.**Zero runtime dependencies.** Uses Node's built-in`node: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 should*check 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 to`agent-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 a**search tool over real transcripts**, not a memory.** Add a memory layer (mem0, etc.)**when you want the agent to carry forward*distilled preferences and durable facts*("the user prefers pnpm", "deploys go through staging") that should persist as structured knowledge.**Use RAG/embeddings** when you need*semantic*recall 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 composes`ochist 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 shell*is*the query language.**Context control belongs to the agent.** Paging/filtering with`head`

/`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 exposes*when*and*how*.*capabilities*; it doesn't tell the agent the workflow. The bundled skill encodes "check history before re-researching" and the`locate → 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](/adlternative/agent-historian/blob/main/skills/agent-history/SKILL.md)
that teaches agents

*when*and

*how*to 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:

```
# Install into every detected agent, globally:
npx skills add adlternative/agent-historian -g

# Or target specific agents:
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 the`HistorySource`

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 to`src/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:

by[claude-historian](https://github.com/Vvkmnn/claude-historian-mcp)[@Vvkmnn](https://github.com/Vvkmnn)— the original inspiration. The core idea ("let the agent search its own past conversations so it stops repeating research"), the*historian*framing, 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
and[claude-mem](https://github.com/thedotmack/claude-mem), which informed the design.[mem0](https://github.com/mem0ai/mem0) - The agents whose local history this reads —
,[OpenCode](https://opencode.ai), and[Claude Code](https://www.anthropic.com/claude-code)— for building tools worth remembering.[Qoder](https://qoder.com)

If your project belongs here and isn't credited, please open an issue.

MIT — see [LICENSE](/adlternative/agent-historian/blob/main/LICENSE).