Repository navigation
Releases
v0.19.0
Two read-only commands for checking what the index holds.
Added
agent-history doctor --coverage— what is on disk versus what reached
the index, per source (Claude Code roots incl. the WSL→Windows profile and
extra dirs, Codex, OpenCode, Hermes, OpenClaw, docs): counts on disk and
indexed, indexed files now gone from disk, and newest source mtime against
newest indexed timestamp with a lag warning (--lag-hours, default 6). It
flags suspect transcripts — 0-byte, last line not valid JSON (torn by a
crash), and near-empty session stubs — showing the remote-control
bridgeSessionIdwhere it can be found so they can be re-fetched, and lists
the surfaces no adapter can see. Only this machine's chunks count, so a
hub's copies never make a local source look covered, and indexed sources
whose whole directory is gone are still listed. Strictly read-only
(mode=ro);--jsonfor scripts; exits 1 when something needs attention
or there is no index. (#28)agent-history sessionslists the most recently active sessions,
newest first — one line each with last-active time (local), agent (tagged
with a non-default Claude Code profile,claude-code[claude-org], and
@machinefor another machine's sessions in a hub index), session id,
directory, and the first user prompt.-n/--limit(default 20),--agent,--cwd
substring,--json. Memory files, docs, and Claude Code subagent
transcripts (by path or by their 0.18 subagent label) are hidden by
default (they share session ids without being
conversations; a subagent's chunks would otherwise bump its parent's
activity and replace its first prompt);--allincludes them (#28).
v0.18.1
Fixed
- Secrets that straddle a chunk boundary are now redacted by
scruband
ship --backfill-from-index(#35).
Stored chunks are rejoined into whole records (same origin, session,
timestamp, role, machine and subagent; consecutive ids and an exact 200-char overlap,
or the provenance columns where present), redacted whole, then cut back into
their windows. Secrets longer than the overlap that straddle a chunk
boundary (JWTs, PEM keys, long bearer tokens) are no longer missed.
Backfill now ships the stitched record, so the hub dedups it against the
same message shipped from an on-disk transcript. Chunks that cannot be
stitched fall back to per-chunk redaction plus a safety net: a 40+ char
base64 run touching a chunk edge becomes[REDACTED:fragment].
Backfilled records keep their subagent labels and fork links.
v0.18.0
The release line, with near-real-time sync merged in. Builds that reported
0.17.0 were pre-release snapshots of different branches; this is the first
version where main, the release branch and the installs agree.
Added
- Every Claude Code config profile is indexed. Sessions from a second
account (CLAUDE_CONFIG_DIR=~/.claude-org, or any~/.claude-<name>) were
invisible unless the directory was added by hand. The Claude Code adapter
now scans every~/.claude*/projects, plus$CLAUDE_CONFIG_DIR/projects,
on the Linux side and in the WSL Windows profile, reading each directory
once however it is reached. Project memory files in those profiles are
indexed too.AGENT_HISTORY_PROJECTSstill overrides discovery and
AGENT_HISTORY_EXTRA_DIRSstill adds to it. - Results say which profile a hit came from: a
profilefield in
search --jsonand in the MCPhistory_recallresults (a name such as
claude-org, never a path), and aclaude-code[claude-org]tag in text
output. It is read from the stored origin, so no schema change or reindex is
needed, and hits from a hub that predates this are tagged on the client. - Parent link for fresh-context sessions (Claude Code): a session whose
first user message begins with the lineParent session id: <uuid>(what
Claude desktop'sstart_sessionbriefs should carry) is linked to that
parent exactly like a fork (fork_of/forks, late-linked if the parent
arrives later). Only the first line of the first main-thread user message
counts, the id must be a lowercase UUID, self-references and subagent files
are ignored, and a realforkedFromor an existing link to another parent
is never overwritten. No new wire keys. See README, "Session identity". - Subagent labels and fork handling (Claude Code): subagent transcripts
(<session>/subagents/agent-<id>.jsonl) still index under the parent
session, but their chunks now carryagent_id,agent_typeandsidechain
(new nullable columns, added in place). Search shows[sub:job-researcher a74d]after the role,showprefixes the same label, and MCP results
include the fields. They ship as optional wire keys (format stays 1). Lines a
forked session copied from its parent (forkedFrom) are no longer indexed
under the fork when the parent's own transcript is indexed too (when it is
not, or it is empty or unreadable, they are kept: they are the only copy;ship-jobsdropsforkedFrom-tagged copies; a job that records the resumed parent's own session id injob.jsonstill ships that parent's own transcript, as plain--resumedid before this change); the fork is linked to its parent in session metadata
(fork_of/forks) instead.
A fork with no new turns yet has no chunks of its own, so no link is
recorded until its first new turn is indexed (a link would need an empty
session row that listings would show).ship-jobsships the subagent
labels too. Accepted, untested risks (privacy over completeness): a fork's
copies are dropped when the parent is only partly truncated but still has at
least one own entry, and a forked job's copied history reaches no session
when the parent is never shipped from the job box. The labels on the wire are checked against the hub's rules (64 characters of letters, digits and._:@-, plus/and space for types) and redacted. agent-history relabel [--apply]: fillsagent_idandsidechainon
subagent chunks indexed before labels existed, from the
.../subagents/agent-<id>.jsonlorigin, andagent_typewhen that file
still exists. Preview by default; local index only. A hub keeps the
unlabelled copies of chunks it already received (shipping dedups by content
hash, so a purge and reship does not help): runagent-history relabel
(preview first) on the hub;agent_typestays empty for hub rows. Only
files under an adapter transcript root are read, and only for this
machine's rows.agent-history ship-jobs: shipsclaude -pjob transcripts (Claude
Code session files and the stream-jsontranscript.jsonl) from
AGENT_HISTORY_JOBS_DIR, tagged with the job id, owning Duet channel and
Studio task key in the batch name, a per-linejobobject and a header
record. Jobs read back on an unchanged hub withhistory_recall(text
mode, by job id) andhistory_show(session=<job id>).ship-jobs --final <job_id>and thedeploy/claude-jobs/ship-final
wrapper: the job runner's last step, exit 0 only when the hub has confirmed
every record of the job, seal included. User units for a 2-minute timer in
deploy/claude-jobs/.ship's batches accept a file-name prefix and extra (redacted) wire fields.agent-history confirm-indexed --job <job_id>: the index gate after
ship-final. Exit 0 when the job's header, seal and every session it lists
are findable by job id (the same search and show the MCP tools use); 1 not
yet or partial; 2 config or credential error. Reads the hub over the
existing read-onlyserve-sshkey (or--localon the hub), refuses to run
asclaude-jobs, and can
write its JSON result to a receipt file.- Job records carry
claude_session_id(header and seal:claude_session_ids)
and a newclaudealias kind, sohistory_show(session=<Claude session uuid>)resolves to the job on an upgraded hub;history_recalland
history_showresults listclaude_session_ids. The seal lists every
session (Sessions:) and uuid (Claude sessions:). agent-history boat-export --job <job_id> <vm_id>...: pulls each Boat
VM's~/.claude/projectsinto the job directory (vms/<vm_id>/), verifies
the copy against the VM's sha256 list, leaves the VM stopped, and ships it
withship-jobs --final. Exit 0 (safe to delete) only once arrival is
confirmed and the runner'sconfirm-indexedresult in
<jobs>/<job_id>/index-confirmed.jsoncovers the VM; exit 4 = arrived,
awaiting index confirmation. Never deletes a VM.--checkre-confirms
without Boat. VM transcripts read back as<job_id>/vm/<vm_id>and carry
the VM's Claude session uuid.- Session notes, kept apart from transcripts in
notes.db:agent-history notes add | search | sweep | ship | index | hook, the MCP tool
history_note, andhistory_recall(notes="exclude" | "include" | "only")
(defaultexclude, so existing callers see no change). Every note links to
one source (claude.ai URL, Duet channel + message id, or Claude Code session- machine + job id) and is refused without it; notes are append-only
(triggers refuse UPDATE/DELETE) and redacted at write and again on the hub.
notes sweepwrites a note for sessions idle 5 minutes (or at session end),
covering only what is new since the last note. The summary comes from
claude -p --model haikuwith the machine's own Claude login (never
ANTHROPIC_API_KEY), on redacted text, with a marked fallback (first prompt - last message) when the call fails.
- machine + job id) and is refused without it; notes are append-only
agent-history notes scrub <note_id> --pattern <text|-> --reason …: the one
admin exception to append-only. Replaces a leaked secret in one note, its
full-text entry, embedding and archived copy, and appends an audit record
that never holds the secret; the triggers still block every other UPDATE
and DELETE.notes auditlists the trail.history_recordwrites notes, not transcript chunks. Same name,
arguments and answer (plusnote_id), with optionalduet_channel_id+
duet_message_idorsession_id+session_machine(+job_id) for a
source link; without one the record links to its own chat session. The
defaulthistory_recallandsurface="claude-ai-chat"still return records
in their old shape, andhistory_show(session="claude-ai-chat-…")reads a
chat's record trail from the notes store. The hub indexer diverts any
old-format record line to notes, andagent-history notes migrate-records
(dry run unless--yes, with a rollback file) moves existing ones.redactcatches bare 1Password service-account tokens (ops_…) and Scribe
agent keys (scrb_agt_…) with noNAME=in front. The hub's index unit indexes
inbox/<machine>/notes/into the notes store.- Near-real-time sync.
agent-history-notify(a hook for Stop,
SubagentStop, PreCompact, SessionEnd) spools the changed transcript and
starts a detachedagent-history sync: single-flight, debounced (first
change runs at once, a burst collapses into one trailing pass per
AGENT_HISTORY_SYNC_INTERVAL, default 15s), incremental (reads only the
bytes appended since the offset kept inship.db), indexing and shipping
just those records.sync --sweep --onceis the cron safety net. The
detached syncer reads~/.config/agent-history/envfor the hub settings. ship --migrate-keys: aliases already-shipped records under their new
path-independent keys. Run it once before moving transcripts.
Changed
- Shipped-record identity no longer includes the transcript's file path
(except for memory/doc pseudo-sessions), so moving a session between
project directories re-sends nothing. Records shipped by 0.17.0 are
recognised through a one-time alias migration (automatic on the next
ship/sync). ship-jobsandboat-exportcompute record digests with the same
path-independent hash, so their shipped-check matches whatshiprecords.
Fixed
import --dry-runcrashed on an undefinedchunk_text.
v0.16.0
Added
- Secret redaction at ingest, opt-in locally (#23). With
AGENT_HISTORY_REDACT=on, or understrictmode, recognised secrets are
replaced with typed markers like[REDACTED:aws_access_key]before anything
is chunked, hashed or embedded: private-key blocks, Anthropic, OpenAI,
GitHub, AWS, Slack, Stripe and Google keys, JWTs,Bearertokens, URL
passwords, andpassword=/token:-style assignments. Matches are found on
the whole record but applied inside the original chunk boundaries, so
chunks without a secret keep their exact text and hash. Off by default
because a local index is often the only place a credential can still be
recalled; anything that leaves the machine is meant to be redacted
regardless.doctorreports the setting and the last index run's
per-class counts. agent-history scrub [--yes]redacts secrets already in an index:
preview by default, then rewrites affected chunks in place (text, content
hash, full-text row, re-embedded vector), including orphaned chunks, and
deletes any that become duplicates. Idempotent; refuses while areembed
is staged.
v0.15.0
Changed
- Injection prefers the current directory, cheaply. Retrieval now uses a
two-tier distance gate keyed on the prompt's working directory: chunks from
the current project (the directory or a sub/parent of it) pass the normal
cutoff, while chunks from other projects must clear a tighter
"near-exact" cutoff (AGENT_HISTORY_INJECT_CROSS_DIST, default 14.0). So
obviously-unrelated other-project matches are dropped up front by simple
inference — no model call — while a genuinely strong cross-project match
still comes through.strictmode continues to hard-scope to the current
directory; deliberatesearchis unaffected and stays fully cross-project.
v0.14.0
Changed
- Injected context is now project-aware. Retrieval is similarity-only and
spans every project on the machine, so an excerpt from an unrelated project
can rank high on a given prompt. The injected header now names the current
project (from the hook's cwd) and tells the agent to check each excerpt
against the current task and disregard ones from a different project —
making the strong model the segmentation layer the embedder can't be. A
stopgap until real per-project scoping lands (#16 / roadmap); deliberate
searchstays fully cross-project.
v0.13.0
Changed
- The injection notice now lists which memories were pulled, not just a
count. Each recalled chunk gets a one-line entry — date, agent/role,
project, and a short snippet — so you can see what rode into a prompt at a
glance, passively, without the agent stopping to narrate it. Still a
user-onlysystemMessage(never added to the model's context), still ends
with the/history:injecttoggle.
Fixed
- A trigger test that compared a new file's mtime against the stamp could
flake on coarse-granularity filesystems; it now forces the mtime
deterministically.
v0.12.0
Changed
- Context injection is now ON by default. Retrieval-only recall is
local, free, and precision-gated, so it earns its place without an opt-in
step. Disable per-machine withagent-history inject off(writes an
off-marker) orAGENT_HISTORY_INJECT=0;=1forces it on. Existing
inject oninstalls are unaffected.
Added
-
Visible recall count. The injection hook now emits a
systemMessage
—📚 agent-history: N memories recalled · /history:inject to toggle— so
ambient injection is no longer invisible. It is shown to the user only,
never added to the model's context. -
/history:injectcommand andagent-history inject toggle— flip
injection on/off without hand-editing anything.inject statusshows the
current state and how to change it. -
agent-history purge— permanent, surgical deletion, the counterpart
reindex --forcenever was. Target with--cwd,--session,--agent
(AND-combined) or--allfor total destruction; prints the count and
requires--yesto act (previews otherwise). Removes chunks from the
vector and full-text indexes too. Fills the media-sanitization gap for
contract-end data destruction. (Dedup caveat: identical text is stored
once under its first source, so surgical purges match stored attribution;
--allis the only guaranteed-complete wipe.) -
agent-history strict— a compliance profile for regulated (e.g. CUI)
work. In strict mode injection defaults off, and when explicitly
enabled retrieves only from the current project (same cwd) — closing the
cross-project injection path where a chunk from one client could ride into
a prompt for another. Set viastrict onorAGENT_HISTORY_STRICT=1.
(Strict mode narrows behaviour; the index remains sensitive-at-rest and
its storage controls still apply.)
Fixed
- Injection can no longer feed itself. The indexer refuses to index any
record that begins with this tool's own recall markers (the local hook's
header or the fleet injectors'AUTO-RECALLED CONTEXT), so a persisted
injection block can never be re-indexed and re-injected into a
memories-about-memories loop. One choke point in the indexer covers every
adapter.
v0.11.0
Added
- Recency-aware results. Relevance ranking now breaks near-ties toward
the newer chunk (scores compared in rounded buckets — deliberately mild,
no decay curves to miscalibrate), so a superseded answer only outranks
its own correction when relevance genuinely separates them. And both the
CLI (--sort newest) and the viewer (a sort dropdown) can order results
chronologically outright — for "what's the latest on X" rather than
"what's the best match for X". Pure text-mode results keep exact BM25
order under relevance sort.
v0.10.0
Added
agent-history reembed— switch embedding models without losing
anything. The chunk text lives in the index, so a model change never
needed the source transcripts: every stored chunk is re-embedded with the
configured model, staged alongside the old vectors (searches keep working
throughout), and swapped in atomically at the end. Interrupted by a crash
or an Ollama outage, it resumes where it stopped; a staging run for a
different model is discarded and restarted. It holds the indexing lock for
the duration, so a hook firing mid-run cannot insert vectors the swap
would discard.reindexnow refuses to destroy orphaned history. When chunks exist
whose source files are gone — for a mature index, most of it — a wipe
discards the only surviving copy.reindexcounts them, refuses, and
points atreembed;--forceoverrides. It also fails closed when the
index exists but cannot be opened: an index this Python cannot rebuild is
one it must not delete.
Changed
- README rewritten as one coherent document: supported sources up front,
quickstart, full command reference, and theindex/reembed/reindex
triad replacing the old "reindex is destructive" guidance.