{"slug": "show-hn-agent-historian-let-your-ai-agent-search-its-own-past-sessions", "title": "Show HN: Agent-historian – let your AI agent search its own past sessions", "summary": "Agent-historian, a new open-source CLI tool, lets AI coding agents search their own past conversation history from the command line, enabling them to recover prior research, commands, errors, and decisions instead of repeating work. The tool supports multiple agents like OpenCode and Claude Code, is read-only, and uses a progressive-disclosure workflow to minimize context window usage.", "body_md": "English | [简体中文](/adlternative/agent-historian/blob/main/README.zh-CN.md)\n\nSearch and read your past **AI coding-agent conversation history** from the\ncommand line — so your agent can recover earlier research, commands, errors,\nand decisions instead of repeating work.\n\nShips a small CLI (`ochist`\n\n) and an **Agent Skill** so agents like\n[OpenCode](https://opencode.ai) and [Claude Code](https://www.anthropic.com/claude-code)\ncan check history *before* doing fresh research.\n\n**Multi-agent.** Reads OpenCode (`opencode.db`\n\n) and Claude Code (`~/.claude/projects/*.jsonl`\n\n) 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`\n\nwidens to everything.**Read-only.** Never modifies any data store.**Context-friendly.** Plain, pipe-friendly output. Agents page with`grep`\n\n/`head`\n\n/`wc`\n\n/`jq`\n\ninstead of dumping whole sessions into context.**Zero runtime dependencies.** Uses Node's built-in`node:sqlite`\n\n(Node ≥ 22.5). No native modules.\n\nAI coding agents are mostly **stateless across sessions**. Every new chat starts\nfrom zero, so the agent happily redoes investigation it already finished\nyesterday — re-reading the same files, re-running the same commands, re-deriving\nthe same conclusions. That wastes your time, your tokens, and your patience.\n\n`agent-historian`\n\ngives the agent (and you) a cheap, local way to ask:\n\n\"Have I solved this before? What command did I run? Which file did we change? What did we decide, and why?\"\n\nIt deliberately **does not try to summarize** sessions with brittle heuristics\n(regex-based \"accomplishment extraction\" breaks on non-English text and on any\nphrasing it didn't anticipate). Instead it lets the agent **read the real text\non demand**, using a progressive-disclosure workflow (`locate → orient → scan → read`\n\n) so only the relevant lines enter the context window.\n\n**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.\n\nThere are several ways to give an agent \"memory.\" `agent-historian`\n\nis\ndeliberately the simplest one — it doesn't build a memory, it **reads the\nground truth you already have on disk**.\n\n| Approach | What it stores | Retrieval | Cost / setup | Faithfulness |\n|---|---|---|---|---|\nagent-historian |\nnothing — reads existing transcripts | lexical (grep/substring), on demand | zero index, zero deps, read-only | exact original text |\nMemory layers (mem0, OpenMemory, MemGPT, \"memory tools\") |\nLLM-distilled facts/summaries it decides to save | semantic recall of summaries |\nneeds a store + write step; can drift/hallucinate | lossy — a model's paraphrase |\nRAG / embeddings (vector DB over chat logs) |\nchunked text + embedding vectors | semantic (vector similarity) | embedding model + vector DB + reindex pipeline | exact chunks, but needs infra & re-indexing |\nBuilt-in `--resume` / `--continue` |\nthe agent's own session files | reload one whole session into context | free, but no search | exact, but all-or-nothing |\nAuto-summary recall (regex/heuristic \"what did I accomplish\") |\nextracted bullet points | keyword over summaries | cheap | brittle; breaks on non-English / unusual phrasing |\n\n**Use** when you want to`agent-historian`\n\n*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.\n\nThey're complementary: `agent-historian`\n\nanswers *\"show me the real thing I did,\"*\nmemory/RAG answer *\"recall the gist of what I know.\"* Many setups use both —\nhistorian for exact recall, a memory layer for distilled facts.\n\n**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`\n\n) and pulls only the exact lines it needs.\n\nThis started as an MCP server, then deliberately moved to a **CLI ( ochist)\nplus an Agent Skill**. Reasons:\n\n**The agent already has a shell.** With a CLI, the agent composes`ochist grep … | head`\n\n,`| wc -l`\n\n,`| grep -i error`\n\n,`| jq`\n\nitself. 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`\n\n/`grep`\n\nlets 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`\n\nrecipe — 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.\n\nMCP is a great fit for *capabilities an agent can't otherwise reach* (remote\nAPIs, privileged actions). Here the data is **local files the agent can already\nread with a shell**, so a CLI + Skill is simpler, cheaper, and more flexible.\n\n`agent-historian`\n\nmostly exists to fill a gap: agents persist rich session data\nlocally, but **don't expose a first-class way to search and read it back**.\nOpenCode has `session list`\n\n(no message/part reader); Claude Code only has\ninteractive `--resume`\n\n; Qoder's SDK can resume/continue but not read history.\n\nThe cleanest end state is for the agents themselves to ship this:\n\n- A read command, e.g.\n`opencode message get <session>`\n\n/`opencode session show`\n\n(and equivalents for Claude Code / Qoder) that prints messages and tool I/O as plain, pipe-friendly text. - An\n**official skill** that teaches the agent to check its own history before re-researching.\n\nIf that happens, you won't need this project — and that would be a *good*\noutcome. Until then, `agent-historian`\n\nprovides a uniform, read-only, cross-agent\nway to do it today. (And if it stays useful as the *cross-agent* layer — one tool\nthat reads OpenCode + Claude Code + Qoder + … through one interface and one\nskill — that's a fine reason for it to stick around too.)\n\n```\nnpm install -g agent-historian      # exposes the `ochist` command\n```\n\nOr run without installing:\n\n```\nnpx agent-historian sources\n```\n\n## From source (for development)\n\n```\ngit clone https://github.com/adlternative/agent-historian.git\ncd agent-historian\nnpm install\nnpm run build\nnpm link          # symlink `ochist` globally\n```\n\nRequires **Node ≥ 22.5** (for built-in `node:sqlite`\n\n).\n\n```\nochist sources                       # which agents are detected\nochist sessions --limit 10           # recent sessions across all agents\nochist grep \"ssh\" --limit 8          # search all history\nochist meta <session>                # reliable metadata card\nochist show <session>                # one-line-per-message outline\nochist part <part_id>                # full text of one message\n```\n\nBy default **all detected agents** are queried. Restrict with `--source`\n\n:\n\n```\nochist sessions --source claudecode\nochist grep \"docker build\" --source opencode\n```\n\n`sessions`\n\nand `grep`\n\ndefault to the **current project** — sessions whose\nworking directory is the current dir or below. Widen as needed:\n\n```\nochist sessions                 # current project (cwd and subdirs)\nochist sessions --global        # every project\nochist sessions --dir ~/code/x  # a specific directory\nochist grep \"ssh\" --global      # search all history\n```\n\n`<session>`\n\n/ `<part_id>`\n\naccept an agent-native id, a slug/prefix, or `latest`\n\n.\nAdd `--json`\n\nto any command for machine-readable output (pipe to `jq`\n\n).\n\n```\nochist grep \"authorized_keys\" --limit 5            # find candidate + part_id\nochist meta silent-star                             # confirm the session\nochist show silent-star | grep -i ssh-copy-id       # locate exact part\nochist part prt_xxxxx                                # read full message\n```\n\nThe repo includes a skill at [ skills/agent-history/SKILL.md](/adlternative/agent-historian/blob/main/skills/agent-history/SKILL.md)\nthat teaches agents\n\n*when*and\n\n*how*to use\n\n`ochist`\n\n— so they check history\nbefore doing fresh research.The standard community installer. No clone needed; works for OpenCode, Claude Code, Cursor, Codex, and more:\n\n```\n# Install into every detected agent, globally:\nnpx skills add adlternative/agent-historian -g\n\n# Or target specific agents:\nnpx skills add adlternative/agent-historian -s agent-history -a opencode -a claude-code -g\n```\n\nIf you already installed the CLI (`npm i -g agent-historian`\n\n/ `npm link`\n\n), it\ncan install its own bundled skill:\n\n```\nochist skill install --global     # → ~/.claude/skills + ~/.config/opencode/skills\nochist skill install              # project-local: ./.claude/skills + ./.agents/skills\nochist skill uninstall --global   # remove\nochist skill path                 # print the bundled skill dir\nmkdir -p ~/.claude/skills        # read by BOTH Claude Code and OpenCode\nln -s \"$(pwd)/skills/agent-history\" ~/.claude/skills/agent-history\n```\n\nRestart the agent; it will discover the `agent-history`\n\nskill and load it on\ndemand when you reference earlier work (\"我之前…\", \"what did we do before\", …).\n\n```\nochist (CLI)\n  └─ sources/registry.ts        selects active sources (auto-detect or --source)\n       ├─ OpenCodeSource        reads opencode.db via node:sqlite\n       ├─ ClaudeCodeSource      reads ~/.claude/projects/*.jsonl\n       └─ <your agent here>     implement HistorySource\n```\n\nEach source normalizes its agent's data into common `Session`\n\n/ `Part`\n\nshapes,\nso the CLI is agent-agnostic. Search is lexical (regex/substring over message\ncontent) — no embeddings, no index, no background process.\n\n**Subagents are handled per agent.** OpenCode subagents are recorded as their\nown sessions (the `agent`\n\nfield is `explore`\n\n/`general`\n\n/…). Claude Code subagent\n(\"sidechain\") transcripts live in `agent-*.jsonl`\n\nfiles that reference their\nparent session; `agent-historian`\n\nfolds their content into the parent session\nand prefixes it with `[subagent …]`\n\n, so nothing is lost or duplicated.\n\n-\nCreate\n\n`src/sources/<agent>.ts`\n\nimplementing the`HistorySource`\n\ninterface from:`src/sources/types.ts`\n\n```\nexport class MyAgentSource implements HistorySource {\n  readonly name = 'myagent';\n  readonly label = 'My Agent';\n  isAvailable() { /* does its data store exist? */ }\n  location() { /* where it reads from */ }\n  listSessions(opts) { /* … */ }\n  loadParts(sessionId?) { /* … */ }\n  loadPartRaw(partId) { /* … */ }\n  resolveSessionId(selector) { /* id | slug | prefix | \"latest\" */ }\n  loadTodos(sessionId) { /* [] if unsupported */ }\n}\n```\n\n-\nRegister it in\n\nby adding it to`src/sources/registry.ts`\n\n`ALL_SOURCES`\n\n. -\n`npm run build`\n\n. That's it — every subcommand now works for your agent.\n\n`agent-historian`\n\nreads each agent's **local** session data: OpenCode's SQLite\ndatabase and the per-session JSONL transcripts that Claude Code, Qoder, and\nsimilar CLIs persist on disk. These on-disk formats are largely **not officially\ndocumented**, so the readers are best-effort and may need updates across agent\nversions. Everything is strictly **read-only** — the tool never writes to any\nagent's data store.\n\nThis project stands on the shoulders of others:\n\nby[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`\n\nreimagines that idea as a multi-agent, CLI-first, skill-driven tool.- The progressive-disclosure / \"page, don't dump\" philosophy is shared with\nmemory tools like\nand[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 —\n,[OpenCode](https://opencode.ai), and[Claude Code](https://www.anthropic.com/claude-code)— for building tools worth remembering.[Qoder](https://qoder.com)\n\nIf your project belongs here and isn't credited, please open an issue.\n\nMIT — see [LICENSE](/adlternative/agent-historian/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-agent-historian-let-your-ai-agent-search-its-own-past-sessions", "canonical_source": "https://github.com/adlternative/agent-historian", "published_at": "2026-06-21 02:58:08+00:00", "updated_at": "2026-06-21 03:07:15.047129+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["OpenCode", "Claude Code", "Anthropic", "Qoder"], "alternates": {"html": "https://wpnews.pro/news/show-hn-agent-historian-let-your-ai-agent-search-its-own-past-sessions", "markdown": "https://wpnews.pro/news/show-hn-agent-historian-let-your-ai-agent-search-its-own-past-sessions.md", "text": "https://wpnews.pro/news/show-hn-agent-historian-let-your-ai-agent-search-its-own-past-sessions.txt", "jsonld": "https://wpnews.pro/news/show-hn-agent-historian-let-your-ai-agent-search-its-own-past-sessions.jsonld"}}