Assay
Assay is a local memory layer for Claude Code. It remembers the decisions you make while building with an AI agent. It keeps them in SQLite on your machine and gives them back in later sessions, with citations.
Every agent session starts from zero. Yesterday's decisions sit in old transcripts, so the agent re-derives them or quietly contradicts them. Assay keeps a record of what you decided, when, and how sure you were, so the next session can start from there.
This repo holds both parts of the system:
| Part | What it does | Needs |
|---|
Assay plugin (plugin/, src/) | Captures decisions inline, stores them locally, recalls them in later sessions | macOS on Apple Silicon, Node 22.x |
Librarian (librarian/), optional | A background scribe that files what you capture into topics, tracks what replaced what, and briefs each new session | macOS, Claude Code CLI, claude-mem |
The Assay plugin
- Capture. A decision is one sentence inside an
<assay-decision> tag, written by you or by the agent. At the end of every turn, a Stop hook reads the session transcript and stores each new tag in ~/.assay/decisions.db. Nothing leaves your machine.
- Recall. In a later session,
/assay-decision returns your recent decisions with their ids. /assay-brief <topic> returns up to five recent decisions that mention the topic, each cited by id.
- Interface. 3 MCP tools (
assay_decision_recall, assay_decision_expand, assay_brief_render) and 3 slash commands (/assay-decision, /assay-brief, /assay-decision-deposit). A fourth tool, __IMPORTANT, only carries the capture instructions agents see at session start.
- Optional context. If claude-mem is running, recall attaches related session observations from it. Without it, everything else still works.
The plugin tells agents to stay silent by default. An agent tags a decision only when you ask it to save one, when a decision replaces an earlier one, or to record a Librarian ruling. You can write a tag yourself at any time, or run /assay-decision-deposit. The format:
<assay-decision kind="decision|conflict" confidence="0..1" layer="label" supersedes="id-prefix">One sentence.</assay-decision>
kind is decision or conflict. The other three attributes are optional. USAGE.md has worked examples.
The Librarian
Optional, macOS only. The plugin captures decisions. The Librarian keeps them in order.
It runs as a launchd job every 20 minutes and shortly after each turn ends. It reads new claude-mem observations and new plugin decisions. A deterministic prefilter files the obvious ones. A headless claude -p worker files the rest under topics ("authorities") in an append-only journal, ~/.assay/librarian.db. When something looks superseded or contradictory, it raises a flag for you to rule on, and it records a supersession only when your ruling confirms one. At the start of each new session, a hook injects a glossary of what is still true.
- Self-audited. The Librarian checks its own coverage and filing accuracy. POSTMORTEM.md covers a data-loss bug it caught in itself, the fix, and the regression tests. PRECISION-AUDIT.md covers how filing accuracy is measured.
- Security. The worker runs
claude -p --permission-mode bypassPermissions, unattended, as your user, over text your sessions touched. Read the security model before installing. install.sh installs nothing until you type bypassPermissions.
Status
Alpha, version 2.0.0-alpha.3. Known limits:
- Recall is by recency, not meaning.
assay_decision_recall returns your most recent decisions. The query does not select or rank them yet. Brief matches topic words as plain substrings. Semantic recall is on the roadmap.
- Nothing comes back until you have 5 decisions. Below that, recall and brief return a cold-start message.
supersedes is stored, not resolved. The chain in a recall result holds only the decision itself for now. Today, supersession is tracked by the Librarian's flag and ruling loop.- The Stop hook reads the whole transcript, including tool output. A complete tag inside a file an agent reads is captured too.
- Platform. The plugin ships a prebuilt SQLite driver (better-sqlite3) for macOS on Apple Silicon and Node 22.x. Claude Code runs the plugin with the
node on your PATH. On Linux, Windows, Intel Macs, or any other Node version, the Stop hook and MCP server fail to load.
- The Librarian is macOS only (launchd, BSD
stat, shlock) and runs an unattended agent with every permission. See its security model and LIMITATIONS.md.
- Not on npm. The package name
@assaylabs/assay is not published. Install from the marketplace or from source.
Install
The plugin
In Claude Code:
/plugin marketplace add levievanshantz/assay
/plugin install assay@assaylabs
You need macOS on Apple Silicon and Node 22.x as the node on your PATH. claude-mem is optional. Without it, recall and brief still work and report context_tier: "unavailable".
The Librarian (optional, macOS)
You need claude-mem 13.x, run for at least one session, plus the other requirements in librarian/SETUP.md. The plugin can be installed before or after. Read the security model, then:
git clone https://github.com/levievanshantz/assay
cd assay/librarian
./install.sh
install.sh shows what the scheduled worker will run and asks you to type bypassPermissions. Any other answer exits with nothing installed.
To watch the pipeline before installing anything, run ./demo.sh inside librarian/demo. It uses synthetic data and a stand-in worker, so it makes no model calls.
From source
For development, or to check the claims yourself. Needs Node 22.x.
git clone https://github.com/levievanshantz/assay
cd assay
npm ci
npm test # builds, then runs 44 tests
npm run smoke # 19 integration cases
npm run demo # capture, recall and brief in a temp sandbox
These runs use a temporary HOME, so your real ~/.assay is not touched.
The Librarian's suite needs macOS and Python 3.9 or newer:
cd librarian
python3 -m unittest discover tests -v # 22 tests
Two of the 20 run the real plugin Stop hook and skip unless Node 22 on Apple Silicon is available. CONTRIBUTING.md lists every check.
How it works
Claude Code session A later session
------------------- ---------------
a tag is written /assay-decision, /assay-brief
| |
| Stop hook, end of every turn | MCP server (stdio)
v v
+-----------------------------------------------------------+
| ~/.assay/decisions.db SQLite, on your machine |
| decisions, decision_transitions, decision_evidence |
+-----------------------------------------------------------+
|
| optional, macOS
v
Librarian sweep (launchd, every 20 min and after each turn)
reads decisions.db and claude-mem
files into ~/.assay/librarian.db, raises flags for you to rule on
|
v
SessionStart hook injects a glossary of what is still true
- Capture. The Stop hook reads the transcript file as raw text. It decodes each complete tag and rejects bad ones (unknown kind, empty body, over 2,000 characters). It skips anything already stored and inserts the rest with status
tentative. It never blocks the session. Fatal errors go to ~/.assay/errors.jsonl.
- Recall. The MCP server reads the same database. Recall and brief are plain SQL over it, with optional claude-mem context.
- File. The Librarian treats the decisions database as one of its two inputs. After each run, a coverage audit checks that every item got a disposition. If any did not, the run rolls back and retries.
Design detail lives in ARCHITECTURE.md and librarian/ARCHITECTURE.md.
Repo layout
| Path | What it is |
|---|
plugin/ | The Claude Code plugin as installed: manifest, hooks, skills, built bundles, vendored better-sqlite3 |
plugin-src/ | Entry points bundled into plugin/scripts/ |
src/ | TypeScript source: tag parser, SQLite store, Stop hook, MCP server, claude-mem client |
tests/ | node:test suite |
scripts/ | Plugin build, smoke pack, end-to-end demo |
evals/ | Capability eval gate for the claims in CAPABILITIES.md |
bin/assay.mjs | Developer CLI, for example node bin/assay.mjs check-consistency |
docs/ | Guides: onboarding and tagging |
librarian/ | The Librarian: installer, sweep, worker prompt, tests, demo, and its own docs |
.claude-plugin/marketplace.json | The assaylabs marketplace that lists the plugin |
Docs
| Doc | What it covers |
|---|
| ARCHITECTURE.md | How the plugin is built and why |
| CAPABILITIES.md | The plugin's contract: each claim, its pass line, and the eval that checks it |
| USAGE.md | Tag attributes, commands, output fields, troubleshooting |
| ROADMAP.md | What comes next |
| PROOF.md | The evidence record for 2.0.0-alpha.2 (May 2026) |
| CONTRIBUTING.md | Setup, both test suites, PR checklist |
| librarian/README.md | The Librarian: what it is, requirements, security model |
| librarian/SETUP.md | Install, verify, uninstall, troubleshooting |
| librarian/OPERATING.md | The daily loop: glossary, flags, rulings |
| librarian/ARCHITECTURE.md | The Librarian's design, from zero to deep |
| librarian/DECISIONS.md |
History
- v1 (March 2026). An MCP server for team knowledge retrieval. Archived at github.com/levievanshantz/assay-v1.
- v2 (May 2026). Rebuilt as a Claude Code plugin focused on decisions. Published as
assay-decisions at 2.0.0-alpha.2.
- Librarian (July 2026). Built in a private working repo. It was imported here as one snapshot, so its history in this repo starts at the import.
- One repo (September 2026). Both parts now live here. 2.0.0-alpha.3 moves fixes that had been applied by hand to an installed copy back into source, with tests.
License
MIT. See LICENSE.
Credits
- claude-mem: the session memory the Librarian files from, and the optional context source for recall.
- QMD: inspiration for local-first hybrid retrieval.
- OpenAI Codex served as an adversarial reviewer during the build. See PROOF.md.
