agent-history

skill
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Local semantic search over your AI coding agent session transcripts, using Ollama embeddings and sqlite-vec

README.md

agent-history

CI
License: MIT

Local, private, zero-cost semantic memory for your AI coding agents — search
everything you and your agents have ever discussed, across every agent on the
machine, by meaning.

You had a long conversation three weeks ago where you worked out why the auth
flow had to be structured a particular way. You remember deciding it. You do
not remember which project, which day, or what the reasoning was. grep is no
help, because you don't remember the words you used.

$ agent-history search "why did we split the auth middleware"
#1  score=0.0325  2026-06-14T22:03  claude-code/assistant  ~/repos/example
    file: /home/you/.claude/projects/-home-you-repos-example/a1b2c3.jsonl
    The reason to split it is that the session refresh needs to run before...

Everything runs on your machine. Embeddings come from your own Ollama
instance; search runs inside SQLite. No API keys, no per-query cost, and
nothing leaves the box — the tool refuses a non-loopback endpoint unless you
explicitly allow it.

What it does

One index across every agent on the machine. Each source has an adapter
that knows where that agent keeps its transcripts and how to read them:

source reads format
Claude Code every ~/.claude*/projects/** profile (and $CLAUDE_CONFIG_DIR) + project memory *.md, including the WSL Windows side JSONL
OpenAI Codex CLI ~/.codex/sessions/** rollouts, including the WSL Windows side JSONL
OpenCode ~/.local/share/opencode/opencode.db SQLite
Hermes ~/.hermes*/state.db, one per profile SQLite
OpenClaw ~/.openclaw/agents/*/sessions/ + workspace markdown JSONL
docs (opt-in) any documentation trees you name — runbooks, ops notes, session summaries *.md / *.txt

Everything found is detected automatically (docs excepted — see
below), merged into one index, searchable
together or filtered with --agent.

Hybrid search. Vector similarity finds meaning; BM25 full-text finds the
exact identifiers embeddings are bad at (os error 11001, a function name);
the rankings are fused. --mode text needs no Ollama at all, and hybrid
degrades to it gracefully when the embedder is down.

The conversation, not just the hit. show prints the conversation a
search hit belongs to, and serve is a local web viewer over the same search
— both read from the index, which matters because the source transcript
often no longer exists.

Context injection (on by default). Relevant past-session excerpts ride
into your new prompts automatically — the "agent already knows your project"
experience, with no LLM anywhere in the loop. You see a 📚 N memories recalled line each time; toggle with /history:inject:
details below.

An archive that agents don't keep. Claude Code deletes transcripts after
30 days by default. The index doesn't. On the machine this was built for, 67%
of the index came from conversations whose files no longer exist.

Quickstart

$ uv tool install git+https://github.com/d3layd/agent-history
$ agent-history index          # first run embeds everything; minutes, once
$ agent-history "that thing we decided about caching"

The first index of a large history takes a while — it embeds every message
once. Every run after is incremental and takes seconds.

Or clone and run the installer, which also checks Ollama, pulls the model if
missing, and offers to wire up automatic indexing:

$ git clone https://github.com/d3layd/agent-history
$ cd agent-history && ./scripts/install.sh

As a Claude Code plugin

/plugin marketplace add d3layd/agent-history
/plugin install history@agent-history

This adds /history:search (runs the search and synthesizes an answer
rather than making you read raw JSONL) and /history:inject (toggle
context injection), plus three hooks: SessionEnd and PreCompact keep the
index current automatically, and UserPromptSubmit powers
context injection, which is on by
default.

The plugin is named history rather than agent-history purely for
ergonomics: Claude Code namespaces every plugin component as
<plugin>:<component> with no way to opt out, so a long plugin name makes for
a long command. The repository and the CLI keep the full agent-history name.

Requirements

  • Python 3.10+, with a sqlite3 module that permits extension loading
    (see below)
  • Ollama reachable over HTTP, with an embedding
    model pulled — needed for indexing and for vector/hybrid search.
    --mode text (BM25 full-text) works without it.
  • uv to install
$ ollama pull nomic-embed-text

The Python side is deliberately small — two direct dependencies, six once
resolved:

direct sqlite-vec, requests
transitive certifi, charset-normalizer, idna, urllib3

No vector database, no ML framework, no ORM. The index is a single SQLite
file.

Two things that are easy to get wrong:

Extension loading. Vectors live in the
sqlite-vec extension, so the
sqlite3 module must allow loading it. Check with:

$ python3 -c "import sqlite3; sqlite3.connect(':memory:').enable_load_extension(True)"

If that raises AttributeError, that Python was built without extension
support and the tool cannot work under it. agent-history doctor reports this
explicitly rather than failing obscurely.

Known: this affects macOS. CI shows uv-managed CPython on macOS lacks
extension support on Python 3.11, 3.12 and 3.13, while 3.10 works. It
is a property of the Python build, not of macOS itself — Homebrew's python3
generally works. On macOS either install under 3.10:

$ uv tool install --python 3.10 git+https://github.com/d3layd/agent-history

or use a Python where the check above succeeds. The same limitation appears
in some Conda and Linux distribution builds.

The Ollama CLI is not required. Only the HTTP endpoint is. Ollama can run on
another OS entirely — the setup this was built on has Ollama native on Windows
with the tool running in WSL, reaching it over forwarded localhost, and no
ollama binary present at all. install.sh will offer to ollama pull the
model when the CLI exists, and tell you to pull it yourself when it doesn't.

No shell is required. Automatic indexing lives in the CLI itself
(agent-history trigger), so detaching, locking and change detection behave
identically on Linux, macOS and Windows. The scripts under scripts/ are
conveniences for installation and scheduling — .sh for Unix, .ps1 for
Windows — and the Unix ones avoid bash 4 builtins so macOS's bash 3.2 works.

Usage

$ agent-history search "query"              # top 8 hybrid matches
$ agent-history search "query" -k 20        # more results
$ agent-history search "query" --full       # full chunk text, not a preview
$ agent-history search "query" --cwd myapp  # only sessions from a directory
$ agent-history search "query" --agent codex   # one source only
$ agent-history search "query" --mode text  # exact match, no Ollama needed
$ agent-history search "query" --mode vector   # embeddings only
$ agent-history search "query" --sort newest   # chronological, not relevance
$ agent-history search "query" --json       # machine-readable
$ agent-history "query"                     # `search` is the default

$ agent-history show <session-or-origin>    # the conversation around a hit
$ agent-history show s1 --around 2026-06-14T22:03  # centred on a timestamp
$ agent-history serve                       # web viewer at http://127.0.0.1:8127

$ agent-history docs add ~/ops-library      # index a documentation tree
$ agent-history inject off                  # injection is on by default
$ agent-history inject toggle               # or /history:inject in Claude Code
$ agent-history strict on                   # compliance profile (see below)

$ agent-history index                       # incremental update (the default)
$ agent-history reembed                     # switch embedding model, keep everything
$ agent-history purge --cwd ~/clients/acme  # permanently delete matching chunks
$ agent-history purge --all --yes           # total destruction
$ agent-history reindex --force             # wipe and rebuild (destructive)
$ agent-history sources                     # what will be scanned
$ agent-history doctor                      # diagnose the installation

A search hit is a chunk; show prints the conversation it came from.
Relevance ranking has a mild recency preference: results whose scores are
effectively tied go to the newer chunk, so superseded information only
outranks its own correction when relevance genuinely separates them.
--sort newest (also a dropdown in the viewer) orders results
chronologically instead — useful for "what's the latest on X". Start
with doctor if anything misbehaves — it reports whether Ollama is reachable,
what was detected, how much is indexed, and flags misconfigured docs roots.

Context injection (on by default)

A UserPromptSubmit hook embeds each prompt you type (locally, via Ollama),
retrieves past-session chunks relevant to it, and injects them as context —
so the agent already knows what you decided three weeks ago without being
told. No LLM is involved anywhere: the prompt is the retrieval query, and
the chunks arrive verbatim. Tools like claude-mem buy this experience with
LLM compression passes; retrieval alone turns out to be enough, at zero token
cost and with the original wording intact.

Because it's local, free, and precision-gated, it's on by default. Each
time it fires you see a notice listing exactly which memories were pulled —
one line per chunk with its date, source, project, and a snippet:

📚 agent-history recalled 3 memories  ·  /history:inject to toggle
  · 2026-07-08 claude-code/assistant xiu — Fixed and deployed — restart the app…
  · 2026-08-06 claude-code/assistant agent-history — README rewrite for the archive…
  · 2026-02-25 codex/user openclaw — ssh into clamps, work on openclaw…

That's shown only to you, never added to the model's context, so you can
watch recall happen while the agent works without it stopping to narrate.
Toggle with /history:inject in Claude Code, or agent-history inject off / on / toggle (and AGENT_HISTORY_INJECT=0 force-disables).

Unsolicited context has to clear a much higher bar than search results you
asked for, so this is precision-first:

  • An absolute distance cutoff rejects weak matches
    (AGENT_HISTORY_INJECT_MAX_DIST, default 17.0 — recalibrate if you change
    embedding model).
  • At most 3 chunks / ~2 KB per prompt; near-duplicates collapse.
  • Your current session's own chunks are excluded — the agent has that context.
  • Directory-aware, two ways. First, cheaply: retrieval prefers your
    current directory — same-project chunks pass the normal cutoff, other-
    project chunks must clear a tighter "near-exact" bar
    (AGENT_HISTORY_INJECT_CROSS_DIST, default 14.0), so obviously-unrelated
    matches are dropped before injection while genuinely strong cross-project
    ones still come through. Second, as a backstop: the injected header names
    your current project and tells the agent to disregard any excerpt from
    elsewhere. The embedder can't know relevance, so this pairs a simple
    distance heuristic with the model's judgement. (Deliberate search stays
    fully cross-project; only automatic injection is scoped.)
  • Trivial prompts ("ok", "go ahead") and slash commands are skipped.
  • When Ollama is down, nothing is injected. Every failure path is a silent
    no-op — the hook can never break a prompt.

Injected recall is never itself re-indexed — the indexer refuses any record
that begins with the injection markers — so recalled memories can't compound
into a memories-about-memories loop.

Indexing documentation trees

Transcripts answer "what was said"; a docs tree answers "what was written
down". Name your documentation roots and both land in the same index:

$ agent-history docs add ~/ops-library     # persisted; hooks pick it up
$ agent-history index
$ agent-history search "gateway restart runbook" --agent docs

docs add stores the root in the data directory, which is sturdier than an
environment variable — hook processes don't reliably inherit shell exports,
Windows especially. docs list and docs remove manage the set;
$AGENT_HISTORY_DOCS_DIRS (os.pathsep-separated) still works and is merged
in.

This is opt-in only — nothing is auto-detected, because guessing at
documentation locations would mean reading directories you never offered.
Markdown and .txt files are indexed recursively; vendored and hidden
directories (node_modules, .git, …) are pruned; symbolic links may not
escape the configured root; files over 2 MB are treated as logs and skipped.

Edited docs are refreshed, not accumulated. Docs are the one mutable
source the store reads, so they get the one delete path it has: when a
re-read document no longer contains some previously indexed text, those
chunks are removed — from the vector index and the full-text index too. The
rule is deliberately conservative: only a document actually re-read this run
is eligible, text still produced by anything this run survives, and a doc
deleted from disk keeps its chunks. Transcripts are append-only in reality
and stay append-only here.

Together with the Hermes and OpenClaw adapters, this lets one agent-history
install replace a hand-rolled transcript-plus-docs indexer — the
Ollama-embeddings-over-SQLite pattern many ops setups grow — with hybrid
search over all of it.

Your index outlives the transcripts

Claude Code deletes your old transcripts by default. The
cleanupPeriodDays setting
defaults to 30 days, and the sweep runs at startup:

"Claude Code deletes session files and other application data older than
this period at startup."

There is no archive directory. Once a transcript is swept, your index is
the only surviving copy of that conversation
.

This is why the tool is worth more than it first appears. On the machine it
was built for, 67% of a mature index — 25,727 chunks from 1,616 files —
came from transcripts that no longer existed.
The single best answer to
"why does SessionEnd not always fire" lived in a session whose file had been
swept months earlier.

The mechanism is measurable. Comparing every indexed transcript against what
was still on disk:

files median age of last message
still on disk 250 7 days
deleted 1,616 51 days

Not one deleted transcript was younger than 30 days. That hard floor is
the retention policy, not chance. Unless you have raised cleanupPeriodDays,
the same is happening to you right now.

Three commands follow from this, in order of how often you should use them:

  • index — incremental, additive, the default. All the hooks ever run.
  • reembed — switching embedding models without losing anything. The
    chunk text lives in the index, so a model change never needs the source
    files: every stored chunk is re-embedded with the new 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.
  • reindex — wipe and rebuild from what is on disk today, permanently
    discarding history whose sources are gone. It now refuses to run when
    orphaned chunks exist, tells you how many conversations you'd lose, and
    requires --force to proceed. There is almost never a reason to: model
    changes have reembed.

Deleting on purpose: purge

reindex --force is a sledgehammer; purge is a scalpel — permanent,
targeted deletion for when you want specific history gone (a client
offboarding, a contract-end destruction obligation, a project you no longer
want recalled):

$ agent-history purge --cwd ~/clients/acme     # preview: counts, deletes nothing
$ agent-history purge --cwd ~/clients/acme --yes   # actually delete
$ agent-history purge --session <id>           # one conversation
$ agent-history purge --agent codex            # one source
$ agent-history purge --all --yes              # total destruction

--cwd, --session, and --agent are AND-combined; without --yes it only
prints how many chunks would go. Deletion removes them from the vector and
full-text indexes too. One caveat from content-hash dedup: identical text is
stored once, attributed to its first-indexed source — so a surgical purge
matches that stored attribution, and --all is the only guaranteed-complete
wipe.

Regulated work: strict mode

Context injection's convenience is a liability when one machine holds more
than one client's history: a chunk from project A can ride into a prompt for
project B on semantic similarity alone, and every agent here sends prompts to
a commercial cloud LLM. For regulated data (CUI and the like), turn on the
compliance profile:

$ agent-history strict on        # or AGENT_HISTORY_STRICT=1

In strict mode injection defaults off, and when you do enable it
(inject on) recall is scoped to the current project — a chunk from
another directory can never be injected. This closes the cross-project
egress path.

Strict mode narrows behaviour; it does not de-scope the data. The index
still holds verbatim text at rest (see Privacy and security),
so encryption-at-rest, access control, and a destruction plan
(purge) remain your responsibility. For
genuinely regulated deployments, index on in-boundary hardware — never pull a
client's data onto an out-of-boundary workstation.

Automatic indexing

The plugin installs three hooks:

  • SessionEnd — index when a session finishes
  • PreCompact — index before context is compacted, so nothing is lost
  • UserPromptSubmit — powers
    context injection (on by default; it
    retrieves, it never indexes)

One honest caveat: SessionEnd only fires on a clean exit. Kill the
terminal and that session is not indexed until something else triggers a run.
Gaps are expected, not a bug. For a safety net, add a cron entry that indexes
only when a session is active and something actually changed:

0 * * * * pgrep -x claude >/dev/null && agent-history trigger cron --if-changed

On Windows, install.ps1 offers to register the equivalent Scheduled Task.

--if-changed compares your sources against a stamp file and exits before
waking Ollama when there is nothing to do, so idle hours cost nothing. For
docs trees it consults the adapter's own pruned file set, so a touched
node_modules readme or an oversized log can never wake the indexer.

How indexing works

sources ──▶ adapter ──▶ filter ──▶ chunk ──▶ embed ──▶ sqlite-vec + FTS5
 (JSONL/SQLite/md)  normalise  drop noise  ~1500ch   Ollama    + SHA-256 dedup

1. Adapters normalise. Each agent stores transcripts differently — some
as append-only JSONL, some in SQLite. An adapter turns whichever it is into a
common Record (agent, origin, session, cwd, timestamp, role, text). Nothing
downstream knows which agent it came from.

2. Filtering does most of the work. The overwhelming majority of a
transcript is tool traffic — file reads, diffs, command output — which is
bulky and semantically useless to search. Measured across a real 293 MB
corpus:

stage count
raw JSONL lines 87,627
user/assistant messages 63,341
dropped: tool calls and results only 54,506
dropped: harness noise (<system-reminder>, heartbeats, …) 321
dropped: under 20 characters 109
kept as records 9,195

That is 11.0 MB of actual conversation out of 293 MB on disk — 3.8%. The
index is small because 96% of what agents write down is not conversation.

3. Chunking. Messages longer than 1500 characters are split with 200
characters of overlap, so a passage spanning a boundary is still findable.
Runs of 300+ base64-ish characters are replaced with [blob] first —
embedding an encoded payload costs time and matches nothing.

4. Embedding and storage. Each chunk goes to Ollama and lands in SQLite:
a chunks table for text and metadata, a vec_chunks virtual table
(sqlite-vec) for the vectors, an
fts_chunks table (FTS5) for full-text, and meta recording which model
built the index.

5. Dedup makes re-runs cheap. Every chunk is keyed by the SHA-256 of its
text. Re-indexing skips anything already embedded, so the expensive step only
ever runs on genuinely new content — identically for file-backed and
database-backed adapters, with no per-source watermark bookkeeping.

Claude Code project memory files (~/.claude*/projects/*/memory/*.md) and
OpenClaw workspace markdown are indexed alongside transcripts: hand-written,
durable, and often the single most useful thing a search surfaces.

Every Claude Code profile is scanned. A second account run with
CLAUDE_CONFIG_DIR=~/.claude-org keeps its own projects/ tree; the Claude
Code adapter reads ~/.claude/projects, every ~/.claude-<name>/projects,
and $CLAUDE_CONFIG_DIR/projects when it points elsewhere, on the Linux side
and in the WSL Windows profile, with no setting needed. The same directory
reached two ways is read once. Search results say which profile a hit came
from: a profile field in --json output (claude, claude-org, ...), and
a tag such as claude-code[claude-org]/user in text output for any profile
other than the default. The profile is read from the stored file path, so
chunks indexed before this change carry it too.

What it costs

Measured on the corpus above — 276 transcript files, 293 MB, 12,819 chunks:

First full index 13 minutes (~16 chunks/s, CPU-bound on Ollama)
Incremental run, nothing new 0.4 s — no Ollama call at all
Incremental run, one new session ~27 s for 399 chunks
Search, warm ~0.2 s
Search, first after boot ~2.9 s (Ollama loading the model)
Index on disk 60 MB — 39 MB vectors, 9 MB text, 4.6 KB/chunk
Hook overhead at session end 5 ms (it detaches immediately)
Plugin context cost ~37 tokens always-on

The vectors dominate the footprint: 768 float32 values is 3 KB per chunk no
matter how short the text.

Architecture

The whole tool is about 2,900 lines. The dependency graph is acyclic and
shallow — config and textproc import nothing internal, everything else
depends downward, and cli is the only module aware of all the others.

        ┌──────────────────────────────────────────────────────────┐
 ENTRY  │  cli.py (~380)  index │ reindex │ reembed │ search │ show│
        │  serve │ docs │ inject │ strict │ purge │ sources │ doctor│
        └──────┬────────────────────────────┬──────────────────────┘
               │                            │
        ┌──────▼─────────┐  ┌───────────────▼───────────────────────┐
 FLOWS  │ index.py (~250)│  │ search.py (130)   hybrid RRF          │
        │  collect→dedup │  │ show.py (90)      conversation view   │
        │  →refresh docs │  │ viewer.py (252)   loopback web UI     │
        │  →embed→store  │  │ inject.py (191)   prompt-time recall  │
        │  reembed: swap │  │ trigger.py (191)  hook-driven indexing│
        └───┬────────┬───┘  └────┬────────────────────┬─────────────┘
            │        │           │                    │
    ┌───────▼───┐    │           │                    │
 IN │ adapters/ │    │           │                    │
    │ 6 sources │    │           │                    │
    │ Record ×N │    │           │                    │
    └───────────┘    │           │                    │
                ┌────▼───────────▼────────────┐ ┌─────▼───────────┐
 OUT            │      store.py (~520)        │ │  embed.py (102) │
                │ schema, dedup, kNN, BM25,   │ │  Ollama client  │
                │ RRF, the docs delete path   │ └─────┬───────────┘
                └──────────────┬──────────────┘       │
                               │                      │
                     SQLite + sqlite-vec + FTS5   HTTP :11434
                               │                      │
        ┌──────────────────────▼──────────────────────▼───────────┐
 BASE   │  config.py (~340) — every path and env var, imports     │
        │  nothing.  textproc.py (32) — chunk + scrub, pure.      │
        └─────────────────────────────────────────────────────────┘

Adapters are the extensibility seam. One answers three questions —
available(), roots(), records() — and yields Record(agent, origin, session_id, cwd, timestamp, role, text). Nothing downstream knows which
agent produced a record, which is why origin is a string: a file path for
the JSONL agents, db:<path>#<table> for the SQLite-backed ones. Two
optional capabilities extend the seam: watch_files() lets an adapter own
its change-detection file set, and mutable = True opts a source into
stale-chunk refresh — docs is the only adapter that sets either. The
SQLite-backed adapters open their sources read-only and select named columns
only: agent databases keep OAuth tokens and system prompts in neighbouring
tables and columns, and SELECT * is how those would end up in a search
index.

config.py is the single source of truth for location. No other module
contains a hardcoded path. It also owns the security posture — 0700
creation, the loopback policy, WSL profile disambiguation.

embed.py is the only code that touches the network.

Storage

chunks(id, agent, origin, session_id, cwd, timestamp, role, text,
       content_hash UNIQUE)
vec_chunks USING vec0(embedding float[768])   -- rowid ⟷ chunks.id
fts_chunks USING fts5(text, content='chunks') -- BM25, external content
meta(key, value)                              -- model, dimension

Three decisions carry most of the weight:

  • content_hash UNIQUE is the entire incremental strategy. No
    watermarks, no mtime tracking, no per-source bookkeeping — and it behaves
    identically for append-only JSONL and for SQLite sources.
  • meta makes the dimension dynamic rather than a hardcoded 768, and
    doubles as the model-mismatch detector.
  • vec_chunks joins by rowid, keeping the vector table a pure vector
    store.

Who does what

A common misreading is that Ollama performs the search. It does not — it
never sees the index. Ollama converts text to vectors, and that is all: once
per chunk at index time, once per query at search time. The
nearest-neighbour search runs inside SQLite, in-process, with no network
involved — and so does the BM25 full-text half of a hybrid query, via FTS5.
That is why --mode text keeps working when Ollama is down, and why hybrid
search degrades to it rather than failing.

Ollama — text → 768 floats 94 ms
sqlite-vec — kNN over 12,819 vectors 27 ms

sqlite-vec is a real vector index, not a BLOB column scanned in Python:
vec_chunks is a virtual table with its own packed storage format, and
MATCH ? AND k = 8 is a kNN operator implemented in C. The accurate
description is an embedded vector database living inside a SQLite file — the
same way SQLite is a real database that happens to be a file rather than a
server.

The limitation that follows from this: sqlite-vec does exhaustive
kNN. There is no HNSW or IVF approximate index, so search cost is linear in
corpus size. At 12,819 vectors that is 27 ms and irrelevant. At a few hundred
thousand it becomes noticeable; at millions you would want a different store.
For a personal transcript index the ceiling is remote, and in exchange there
is no daemon, no server, and no separate process to keep alive.

Configuration

Variable Default Purpose
AGENT_HISTORY_HOME $XDG_DATA_HOME/agent-history Where the index lives
AGENT_HISTORY_MODEL nomic-embed-text Ollama embedding model
OLLAMA_URL http://localhost:11434 Ollama endpoint
AGENT_HISTORY_ALLOW_REMOTE – Set to 1 to permit a non-loopback OLLAMA_URL
AGENT_HISTORY_PROJECTS every ~/.claude*/projects + $CLAUDE_CONFIG_DIR/projects Claude Code transcript root; when set, replaces profile discovery on this side (the WSL Windows side is still scanned)
AGENT_HISTORY_CODEX ~/.codex/sessions Codex rollout root
AGENT_HISTORY_OPENCODE_DB ~/.local/share/opencode/opencode.db OpenCode database
AGENT_HISTORY_HERMES_DIRS ~/.hermes* Hermes profile homes, os.pathsep-separated
AGENT_HISTORY_OPENCLAW_DIRS ~/.openclaw OpenClaw state roots, os.pathsep-separated
AGENT_HISTORY_DOCS_DIRS – Docs trees (prefer agent-history docs add)
AGENT_HISTORY_EXTRA_DIRS – Extra transcript roots, os.pathsep-separated
AGENT_HISTORY_NO_WSL – Set to 1 to skip Windows-side transcripts
AGENT_HISTORY_INJECT – 1/0 forces injection on/off (else on by default, off under strict)
AGENT_HISTORY_INJECT_MAX_DIST 17.0 Injection cutoff for same-directory chunks (L2 distance)
AGENT_HISTORY_INJECT_CROSS_DIST 14.0 Tighter cutoff for other-directory chunks (near-exact only)
AGENT_HISTORY_STRICT – 1 enables the compliance profile (injection off + hard project-scoped)
AGENT_HISTORY_REDACT off (on under strict) on replaces secrets with typed markers at ingest; off forces verbatim even under strict

Switching AGENT_HISTORY_MODEL calls for agent-history reembed —
vectors from different models are not comparable, and the tool detects the
mismatch and tells you rather than silently returning nonsense. reembed
rebuilds the vectors from the text already in the index, so nothing is lost.

Platform support

status
Linux fully supported, CI on Python 3.10–3.13
macOS supported on Python 3.10; 3.11–3.13 lack SQLite extension support (see Requirements)
Windows supported, CI on Python 3.10–3.13 — with one caveat below

On Windows the index is not owner-only. POSIX mode bits do not exist
there, so where Linux and macOS create index.db as 0600 inside a 0700
directory, Windows falls back to whatever the parent directory's ACL grants.
Given the index contains credentials that appeared in your transcripts, put
AGENT_HISTORY_HOME somewhere already protected, or restrict it yourself:

icacls "$env:LOCALAPPDATA\agent-history" /inheritance:r /grant:r "$env:USERNAME:(OI)(CI)F"

Windows uses %LOCALAPPDATA%\agent-history by default rather than
~/.local/share, and os.pathsep-separated variables use ; there rather
than : — a colon would split drive letters.

Install and sync with the PowerShell equivalents:

.\scripts\install.ps1        # checks Ollama, installs, offers a Scheduled Task
.\scripts\sync-local.ps1 -Check

WSL

When running inside WSL, transcripts written by Claude Code or Codex on the
Windows host are picked up automatically, so one index covers both sides
(for Claude Code, every .claude*/projects profile in that Windows account). WSL
cannot tell which Windows account is yours, so a profile is selected only
when exactly one under /mnt/c/Users has that agent's transcripts; if
several do, none is chosen and you are told to name one via
AGENT_HISTORY_EXTRA_DIRS. Set AGENT_HISTORY_NO_WSL=1 to opt out entirely.

Privacy and security

The index is a credential store. It holds the full text of every indexed
message, and conversations with a coding agent routinely contain secrets you
pasted or that a tool printed. Auditing a real 12,819-chunk index built from
ordinary daily use turned up live database URIs with passwords, API keys, and
32 distinct password= assignments. Assume yours is the same.

The posture that follows:

  • Secret redaction is available, and off by default locally. On one
    machine the index is often the only place a credential can still be found,
    and recalling it is a feature, so secrets are indexed verbatim unless you
    ask otherwise. With AGENT_HISTORY_REDACT=on (implied by strict mode),
    recognised secrets are replaced at ingest, before chunking, hashing or
    embedding, with a typed marker such as [REDACTED:github_token], so a hit
    still shows that something was there. Covered: private-key blocks,
    Anthropic / OpenAI / GitHub / AWS / Slack / Stripe / Google keys, JWTs,
    Bearer tokens, the password in scheme://user:password@host URLs, and
    password= / token: / api_key=-style assignments. Matching is
    deliberately conservative (git SHAs, UUIDs, hashes, env-var references and
    prose about passwords are kept), so treat it as a strong reduction, not a
    guarantee. Anything that leaves the machine (#9 bundles, a #25 hub) is
    meant to be redacted regardless of this setting. doctor shows the setting
    and the last run's per-class counts.
  • index.db deserves the same handling as ~/.ssh. It is created 0600
    inside a 0700 directory — deliberately, since the default umask would
    otherwise make it world-readable on a shared machine. Never commit it;
    think twice before a synced or cloud-mounted AGENT_HISTORY_HOME; there is
    no encryption at rest — full-disk encryption is the answer.
  • Nothing is sent off your machine by default. A non-loopback
    OLLAMA_URL is refused unless you set AGENT_HISTORY_ALLOW_REMOTE=1,
    because pointing it elsewhere would stream your entire history there.
  • The viewer binds strictly to 127.0.0.1 and has no flag to change it.
  • SQLite sources are read read-only, named columns only — the same
    databases hold OAuth tokens and system prompts that must never reach the
    index.
  • Docs trees are opt-in, pruned, and contained — symbolic links inside a
    configured root may not reach files outside it.
  • Shared machines: on WSL, a Windows profile is auto-detected only when
    exactly one has transcripts; if several do, none is indexed — pulling a
    colleague's conversations into your index would be worse than indexing
    nothing.

Cleaning an existing index: scrub

Turning redaction on only protects chunks written from then on. When you are
ready to drop stored credentials (move them into a password manager first),
scrub finds secrets already stored and rewrites those chunks in place — new text, new
content hash, full-text row swapped, vector re-embedded — keeping ids and
provenance. It reaches orphaned chunks too, whose transcripts are gone and
which could never be re-derived:

$ agent-history scrub          # preview: per-class counts, changes nothing, no Ollama
$ agent-history scrub --yes    # rewrite (re-embeds only the affected chunks)

Chunk boundaries are computed on the original text and redaction is applied
within them, so a later index produces exactly the scrubbed text and
converges instead of duplicating. A chunk whose redacted text is already
stored is a duplicate and is deleted. Older backups (index.*.backup.db)
are not touched — delete or scrub them yourself. On the author's 92,913-chunk
index, the first scrub found 615 affected chunks and finished in about a
minute.

What it is — and isn't

The "agents forget everything" space splits into two philosophies. Tools like
claude-mem observe sessions, compress them with LLM calls into structured
memories, and inject summaries. agent-history makes the opposite trade: the
original words, kept verbatim, at zero ongoing cost
— no summarization
pass, no token spend, no lossy compression between you and what was actually
said. Context injection shows the trade holds
even for the "agent already knows" experience: retrieval alone gets there.

Deliberately out of scope: AI summarization and knowledge graphs. If you want
compressed, curated memory, run a tool that does that — the two approaches
compose fine, and this one guarantees the source material survives.

Roadmap

The original roadmap — adapters for every agent found on this machine — is
complete. What remains is driven by use, and tracked in the
issues:

  • An optional history_recall MCP tool — recall as a tool the agent
    invokes, so its call renders with Claude Code's native click-to-expand UI
    (full query and results, inspectable). A complement to injection, not a
    replacement: injection stays the ambient, zero-turn default; the tool is
    the deliberate, inspectable path.
  • Self-calibrating injection cutoff so a model swap can't silently
    mis-tune it (#13).
  • CMMC/CUI hardening — a strict-mode secret scrub and the rest of the
    gap list toward a regulated deployment (#16).
  • Multi-machine merge / snapshot / restore over encrypted object
    storage (#9), and a hub deployment: many machines ship redacted records
    to one index that is searched remotely (#25).
  • An approximate vector index if a corpus outgrows exhaustive kNN
    (hundreds of thousands of chunks — remote for a personal index).
  • Further agents as they appear — one adapter module each.

Adding an agent means writing a single module in
src/agent_history/adapters/ that yields Records. The indexer and search
layer don't change.

Development

$ uv sync --group dev
$ uv run pytest                 # no Ollama required

The embedder is stubbed in tests, so the suite is fast and hermetic — it
never touches a real index and never needs a model. CI runs it on Python
3.10–3.13 across Ubuntu, macOS and Windows, which is what keeps the platform
claims honest.

Keeping an installation current:

$ ./scripts/sync-local.sh --check   # report drift, change nothing
$ ./scripts/sync-local.sh           # pull, reinstall what changed, run doctor

The checkout, the uv tool CLI, and the plugin drift independently and
nothing reconciles them on its own — an out-of-date CLI is easy to miss
because it keeps working.

Known limitations

  • Deleting a transcript leaves its chunks in the index — usually the point
    (see above), but it means --cwd
    filters can surface paths that no longer exist.
  • The first index of a large corpus is slow — see
    What it costs. It is a one-time cost.
  • Search quality is bounded by the embedding model. nomic-embed-text is a
    good default; mxbai-embed-large is slower and somewhat better. Changing
    models is a reembed away and loses nothing.

Contributing

main is protected: changes go through a pull request and CI has to be green
before it can merge.

$ git checkout -b my-change
$ uv run pytest
$ git push -u origin my-change
$ gh pr create

Merging a version bump to main tags it and publishes a GitHub release
automatically, using that version's CHANGELOG.md entry as the notes. Merges
that don't touch the version are silent. Keep pyproject.toml, plugin.json
and __init__.py in agreement — CI fails if they drift.

Contact

Issues and pull requests are welcome on GitHub. For anything else:
[email protected].

License

MIT

Reviews (0)

No results found