Agent memory across your session history: search, read and pan/zoom through AI agent session logs
from the terminal, with token-efficient TOON output for the agents that
read them. Claude Code's
~/.claude/projects/**/*.jsonl is the first supported format; the reader is an event model with
adapters, so another agent's logs are a new adapter file, not a rewrite. An
AXI tool by Jarvus Innovations. MIT. (Formerly published as
agent-session-axi; if you installed it, run agent-session-axi hook uninstall and
npm uninstall -g agent-session-axi before installing this, so the old session hook doesn't stay
behind.)
Privacy: reads local files only; sends nothing. Session logs hold everything a human typed;
this tool never opens a network connection, never modifies a log, and writes only its own
disposable cache under ~/.cache/agent-recall-axi/, plus, only when you run
agent-recall-axi setup hooks, the agent settings files that command names
(setup hooks uninstall reverts it). The rule is specs/behaviors/privacy.md.
Agents that run for days need to read their own and each other's sessions: after a context compaction, to resume where they were; from a supervising session, to audit what a bot did and why; from a human's assistant, to answer "what did I ask for and when". The transcript is the full-resolution memory, and this tool reads it in small, cited pieces.
Two channels ship the same tool from the same tag; you need only one.
npm, for interactive use (Node 22 or newer):
npm i -g agent-recall-axi # puts agent-recall-axi on PATH
npx -y agent-recall-axi --version # or run it without installingSkill, for agents and bots, and it works offline:
npx skills add JarvusInnovations/agent-recall-axi # this project (-g for every project)The skill directory holds SKILL.md and scripts/: a committed, self-contained bundle
(agent-recall-axi.mjs, every dependency inlined) and a bash shim beside it. It needs node 22
or newer and nothing else: no registry, no npm install, no node_modules, so a bot on a host
that cannot reach npm at cold start still has its memory. The shim is not on PATH; run it by
its path, for example ~/.claude/skills/agent-recall-axi/scripts/agent-recall-axi tail latest,
and the tool's own hints name that same path. SKILL.md tells the agent when to reach for it.
The bundle reports the release it was cut from (--version): the default branch is main, which
holds only released trees. Contributors: PRs go to develop; one opened against main is moved
there automatically.
sessions which sessions exist (zoomed out)
turns <session> one row per human prompt
events | tail | around | next | prev rows with stable ids (pan)
show <id> one entry, whole; --full follows persisted outputs (zoom)
find [<session>] <phrase> --file <glob> --tool <name> --kind human … (many ways in)
search <phrase> "have I dealt with this before?" across every project
human <session> what the human said, verbatim
resume-pack <session> the cold-start block: human text, last tool calls, last claims
Every row carries an id like 7a2f1c3e:418 (session prefix, line) that stays valid for the life
of the file, and every listing ends with the exact command to move backward, forward or inward.
Going down the ladder for one session:
agent-recall-axi sessions # this project's sessions, newest first
agent-recall-axi turns 7a2f1c3e # one row per human prompt in that session
agent-recall-axi tail 7a2f1c3e # its last rows
agent-recall-axi around 7a2f1c3e:418 # the rows on either side of one entry
agent-recall-axi show 7a2f1c3e:418 --full # that entry whole, persisted output includedA <session> is a path, a uuid, an 8+ character prefix, or latest. After a compaction,
agent-recall-axi resume-pack latest is the one command to run. agent-recall-axi --help
lists every command, and <command> --help its flags.
agent-recall-axi setup hooks registers a SessionStart hook for Claude Code, Codex and
OpenCode, or repairs one that is already there (--scope project for one repository, --agent for one agent). At session start it
shows the project's sessions; after a compaction or a resume it prints a resume pack.
setup hooks status shows where it is installed and setup hooks uninstall removes only this
tool's entries. Nothing else ever installs a hook. (Up to 0.2.1 these were
hook install|status|uninstall; hooks installed that way keep working and need no reinstall.)
Details: specs/cli.md#setup-hooks.
The desired state is specified in specs/: start with
principles.md, then cli.md (every command),
api.md (the library), data-model.md and
architecture.md. Work to reach it is the plan DAG in
plans/. The project is spec-driven (specops): change specs/ first, then
bring the code into conformance through a plan.
bun install
bun run check && bun run build && bun run test
bun run build:bundle # regenerate the committed skill bundle (check:bundle verifies it)
bun run build:skill # regenerate SKILL.md's command reference (check:skill verifies it)
bun run check:scrub # the public-repo scrub gateCI fails when the bundle or SKILL.md is stale. Releases: RELEASING.md.
This repository is public: fixtures are synthetic, and no real session content, names, hosts or home paths may land anywhere in it; the scrub gate enforces the mechanical part.