agent-history
Health Uyari
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 6 GitHub stars
Code Gecti
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Local semantic search over your AI coding agent session transcripts, using Ollama embeddings and sqlite-vec
agent-history
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
sqlite3module 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. uvto 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 thesqlite-vec extension, so thesqlite3 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 noollama 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. (Deliberatesearchstays
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. ThecleanupPeriodDays 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--forceto proceed. There is almost never a reason to: model
changes havereembed.
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 touchednode_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, anfts_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 withCLAUDE_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 UNIQUEis 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.metamakes the dimension dynamic rather than a hardcoded 768, and
doubles as the model-mismatch detector.vec_chunksjoins 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, andMATCH ? 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, putAGENT_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 viaAGENT_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. WithAGENT_HISTORY_REDACT=on(implied bystrictmode),
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,Bearertokens, the password inscheme://user:password@hostURLs, andpassword=/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.doctorshows the setting
and the last run's per-class counts. index.dbdeserves the same handling as~/.ssh. It is created0600
inside a0700directory — 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-mountedAGENT_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_URLis refused unless you setAGENT_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_recallMCP 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 insrc/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-textis a
good default;mxbai-embed-largeis slower and somewhat better. Changing
models is areembedaway 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
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi