Deposition

License: MIT Zero API calls Python 3.11+

A local-only decision log for AI coding agents. It doesn't remember everything you said — it remembers what you decided, and hands it back next session, for free, with nothing leaving your machine.

The problem

If you use an AI coding agent daily, you've hit at least one of these:

• You re-litigate the same call. You spent 20 minutes convincing your agent to use Postgres over Mongo. New session, new context window — it scaffolds Mongo again, like the conversation never happened. You explain yourself a second time. Maybe a third.
• "I already told you that." Three sessions ago you said "we're not using library X, it's unmaintained." Context got compacted, the session ended, whatever — it's gone, and it comes back up as a live suggestion.
• General memory tools are too loud to read. You tried a memory plugin that "remembers everything." Now every session opens with a wall of recalled tool calls, file reads, and chatter. You stop reading it. The memory exists; it doesn't help.
• Nobody remembers why, including you. A teammate (or future-you) asks "why did we go with X over Y?" and the honest answer is a 20-minute dig through chat history and PR descriptions, for something that was decided in one sentence weeks ago.
• You can't send this transcript anywhere. The conversation has client code, internal names, or just stuff you don't want summarized by someone else's LLM API, even to get memory back. Most memory tools require exactly that call.

Deposition is built around the observation that almost all of the value in "remembering the session" is really just remembering the handful of decisions made in it — not the tool calls, not the back-and-forth, not the dead ends. Catch those, skip the rest, and you get 90% of the benefit at close to 0% of the noise and cost.

See it work

$ deposition.sh query "what database did we pick" --decisions

=== RECALL: "what database did we pick" ===

[1] 2026-08-14 · session demo-session/session · sim=0.55 · themes: -
    DECISION: After weighing consistency needs, we decided to go with
    Postgres for the new service, since we need strong relational guarantees.
    source: demo-session/session.jsonl

That's a real run against the sample transcript in examples/ — try it yourself, it takes about a minute (see Quick start below). No API key, no account, no network call.

Why

Most agent-memory tools call an LLM to summarize every observation, then store the result in a vector database (often with an optional cloud sync). That's powerful, but it costs money on every write, and it tends to surface a lot of context you didn't actually need back.

Deposition takes the opposite bet: skip the summarization call, skip trying to remember everything, and just catch the sentences that look like a decision as they go by.

Deposition vs. the alternatives

	Deposition	claude-mem	Mem0 / Zep / Letta
API calls to run it	None	Yes (LLM summarization)	Yes (extraction/graph)
What it stores	Decisions only	Everything, compressed	Everything (facts/graph)
Setup	1 env var	Plugin install + worker	API key + service
Moving parts	2 scripts	Hooks + worker + DB + UI	Hosted or self-hosted service
Good for	"Stop re-deciding things"	Rich session continuity	Long-running agent memory

Not a ranking — different jobs. If you want an agent with deep, self-editing long-term memory, claude-mem/Letta/Zep/Mem0 are the more capable, more mature tools and you should use them. Deposition is for the narrower job: never re-litigate a decision, with zero cost and zero data leaving your machine.

Quick start: as a Claude Code plugin (recommended)

/plugin marketplace add georgedagher/deposition
/plugin install deposition

That's it -- no env var to set (it defaults to ~/.claude/projects, Claude Code's own transcript directory), no cron job. A Stop hook indexes new decisions after each turn, and a bundled skill teaches Claude to check Deposition before assuming something was never discussed or re-proposing a choice you already made.

Verification status: claude plugin validate passes for both the plugin and marketplace manifests, and a real claude plugin marketplace add + claude plugin install deposition@deposition completes cleanly with the plugin showing enabled -- confirming the manifest, marketplace listing, and hook registration are all structurally correct (this caught and fixed a real bug: an earlier version double-declared the hooks file and failed to load). The underlying ingest/query commands are tested end-to-end (see below). Actually watching the Stop hook fire and the skill get invoked inside a live conversation has not been verified yet in this environment (no authenticated interactive session available where this was built) -- if you hit an issue with that specifically, please open one.

Quick start: standalone CLI

git clone https://github.com/georgedagher/deposition.git && cd deposition
./install.sh                                                  # installs uv if needed
export DEPOSITION_TRANSCRIPT_ROOTS="$HOME/.claude/projects"    # where your agent's .jsonl transcripts live
bin/deposition.sh ingest
bin/deposition.sh query "did we decide on a database yet?"

Multiple roots are colon-separated: DEPOSITION_TRANSCRIPT_ROOTS="/path/one:/path/two".

Want to try it with zero setup first? Point it at the bundled sample instead:

export DEPOSITION_TRANSCRIPT_ROOTS="$(pwd)/examples/sample-transcripts"
bin/deposition.sh ingest && bin/deposition.sh query "database" --decisions

Set up a cron job (or any scheduler) to run ingest periodically -- it's incremental and safe to run every few minutes; unchanged files are skipped.

Configuration

All configuration is environment variables, all optional except DEPOSITION_TRANSCRIPT_ROOTS:

Variable	Default	What it does
DEPOSITION_TRANSCRIPT_ROOTS	(required)	Colon-separated paths to scan for .jsonl transcripts
DEPOSITION_HOME	~/.deposition	Where the index and state file live
DEPOSITION_EXCLUDE_SUBDIRS	(none)	Comma-separated top-level subdir names to skip
DEPOSITION_THEMES_FILE	(none)	Path to a JSON file of {"theme": ["keyword", ...]} for optional tagging -- see examples/themes.example.json
DEPOSITION_DEMAND_TOOLS	Claude Code tool names	Comma-separated tool names whose input counts as "a request", for transcript formats where that matters

How it works

1. Ingest walks DEPOSITION_TRANSCRIPT_ROOTS, finds .jsonl transcript files, and groups consecutive dialogue turns into ~1200-character chunks. Each chunk is scanned with a decision-marker regex (English and Portuguese patterns included); matching sentences are stored as a decisions field alongside a has_decision flag.
2. Chunks are embedded locally (ONNX MiniLM-L6-v2, no network call) and upserted into a Chroma collection on disk.
3. Ingestion is incremental: each file's byte offset is tracked, so re-runs only process what was appended since the last run.
4. Query does a cosine-similarity search over the collection, optionally filtered to has_decision = true (--decisions) or a theme (--theme x, if you configured DEPOSITION_THEMES_FILE).

What this is not

• Not a hosted service -- there's nothing to sign up for.
• Not a rich/self-editing memory architecture -- see Letta/MemGPT if you want that.
• Not tuned for any single agent vendor. It reads generic Claude-style transcript JSONL ({"type": "user"|"assistant", "message": {...}}); if your tool's format differs, bin/deposition_common.py is the one file to adapt.

Status

Early. The core loop (ingest, query, verify) is tested end-to-end against a synthetic transcript (see examples/). Maintenance tooling (deduplication, decision-regex reprocessing without a full re-embed) exists in the original internal version and hasn't been ported yet -- open an issue if you need it sooner. A Claude Code plugin (one-command install, automatic hooks instead of a manual cron job) is planned but not built yet.

Known issue

You'll see Failed to send telemetry event ... capture() takes 1 positional argument but 3 were given in stderr on some chromadb/posthog package combinations. This is chromadb's telemetry client failing a local call and catching its own exception -- verified it is not a network call (the overridden capture() in this dependency chain is a no-op). Cosmetic only; tracked upstream in chromadb, not something Deposition's code causes or can fully suppress from the outside. Safe to ignore.

License

MIT.