Verbative Memory

One fully on-device project memory, shared by every agent: it captures what matters from each finished turn and recalls exactly the right pieces into every prompt. Nothing leaves your machine.

Quick start

Already running the Verbative VS Code extension?Then all of this is already set up: the extension installs the engine, wires automatic capture & recall into every Claude Code CLI session, and puts the switches in its settings. The steps below are for using memory withoutthe extension — other machines, other agents. Both routes share the same engine and the same memories.

1 — Install

terminal

$ pip install verbative-memory

2 — Connect your agent

terminal

$ claude mcp add verbative-memory -- verbative-memory

One command, fully set — automatic capture and recall switch on with it. Both optional, on by default.

Done. The first run downloads the on-device models once — the embedding model, the retrieval reranker, and the capture extractor, about 4.6 GB together (run verbative-memory setupto pre-download them; if the Verbative VS Code extension is installed, its models are reused — nothing downloads twice). Supported agents: Claude Code CLI and Codex, one command each. Claude's MCP entry registers the automatic capture + injection hooks itself on its first session; for Codex, register-hooks --agent=codex wires the MCP server, capture, and the managed AGENTS.md block. Capture and injection are optional and on by default, each agent with its own capture/inject/context settings.

Inside the MCP server: the instructions and every tool your agent gets

On connect, the server hands your agent usage instructionsthrough the MCP handshake itself — so every client (Claude Code CLI, Codex, …) knows how to use memory well without any per-agent setup. This is what it says:

This project has a shared, persistent memory (Verbative Memory). RULE: search memory before asking the user about conventions, decisions, or where things live — it likely knows. PICK THE RETRIEVER - `recall(context)` — assembled context for a task you're starting. - `briefing()` — once at cold start if your host doesn't auto-inject memory. - `search(query)` — one specific fact; filters: type/tags/file/polarity. Cheap — the default for lookups. - `ask(question)` — a composed answer from the slow on-device reader. ONLY for genuine why/how questions; never to fetch a fact or context. - `events` — the exact activity record: "what commands ran", "when was this file edited", "did X ever happen". - `events(flips=true)` — when did a command/test BREAK or get FIXED (pass→fail / fail→pass transitions). - `timeline` — the work history in chronological order, with dates and commits. - `history(subject)` — how one decision/convention evolved over time. - `file_brief(file)` — before editing an unfamiliar file. `file_at` — a file's state at a past moment. - `deep_recall(query)` — ONLY hard multi-hop questions; run broad sweeps in a subagent that returns a synthesis. TRUST - A weak, lone top search score means memory doesn't know — say so, don't guess. - If the record supports several readings (a later-corrected value, an ambiguous reference), report each with its condition; never silently pick one. - Lines marked "(code changed since — verify)": verify against the file, then `feedback` or `revise`. CLOSE THE LOOP - `feedback(id, helpful|wrong|stale)` when a recalled memory proves right or wrong; wrong retires it immediately. - `revise(id, text)` when a memory is outdated but the topic still matters. `get(id)` expands any [m:id]. An on-device model captures durable facts automatically at turn end; use `remember` only for what must be recorded explicitly (a decision the user states, a hard-won dead end).

This format is measured, not guessed: in an agent-in-the-loop A/B, it routed 19 of 20 probe questions to the right tool, versus 15 of 20 for a conventional prose version — and refused to invent answers on every trap question.

The last sentence adapts to your capture setting: with automatic capture off, the instructions instead make the agent the capturer — with a strict capture contract (one self-contained fact per sentence with exact paths and commands, compound statements split, numbers and dates kept, dead ends marked avoid, causal relations recorded, one session-gist line per session).

The tools— all 21 of them:

Record

remember— save one durable fact, decision, or convention; carries rationale, salience, entity relations, and a dead-end marker.
remember_batch— save several facts in one call (end-of-session capture).
revise— replace an outdated memory with the corrected version in one step, keeping its lineage.
feedback— report a memory as helpful, wrong, or stale so the system learns from outcomes.

Retrieve

recall— the assembled, budget-aware memory block for a task (identical to what hooked agents get injected).
briefing— cold-start orientation: core block, pinned rules, active warnings, recent facts.
search— semantic search with filters (type, tags, file, dead-ends-only).
related— knowledge-graph neighbours: facts connected through stored relations, even with no shared wording.
deep_recall— multi-hop search for hard questions: retrieve, spot what's missing, search again, merge.
ask— a question in, a grounded answer out (deep retrieval + the on-device reader).
get — expand one [m:id] to its full record: detail, provenance, supersession history.
list— list current entries, optionally per scope.

Time & activity

timeline— chronological work history, each line with its date and git commit.
events — the exact activity record of every observed tool call; flips=true shows precisely when something broke or got fixed.
history— every version one subject ever had, in order, with what's current.
recap— what changed in memory since a point in time (new, superseded, retired).
file_brief— pre-flight before editing a file: known dead ends, decisions, and its edit history.
file_at— reconstruct a file's historical state at a past memory, date, or step — memory-guided git archaeology.

Manage

pin / forget— keep an entry always in context, or invalidate it.
edit_core— rewrite the always-in-context core memory block.

3 — Automatic capture & recall on the Claude Code CLI (recommended)

terminal

$ verbative-memory register-hooks

Recommended:run it with the defaults, as shown. Every Claude Code CLI CLI session in the project then gets relevant memories injected into each prompt and durable facts captured from each finished turn — no tool calls needed. The same command wires Codex: --agent=codexregisters the MCP server, automatic capture, and a managed memory block — Codex captures after every turn via its notify hook. Capture and injection are two independent switches, per agent: --capture=on|off and --inject=on|off— for Claude they are the same two toggles the VS Code extension shows in its settings. verbative-memory unregister-hooks undoes everything, per agent or for all.

The command line

Everything above runs on its own — you never need a terminal for day-to-day memory. The CLI is there for the settings(shared with the extension's toggles), plus a direct line to your project's memory when you feel like poking it yourself:

terminal

# sign in once — the same account as the extension
$ verbative-memory login you@example.com
✓ Signed in — plan: Code Advanced · memory active

# the switches — capture and injection are independent
$ verbative-memory register-hooks --capture=on --inject=on
✓ Registered Verbative memory hooks in ~/.claude/settings.json
  • SessionStart     → start the local memory engine
  • UserPromptSubmit → inject relevant memories into every prompt
  • Stop             → capture durable facts from each finished turn
  Capture:   on    (--capture=on|off)
  Injection: on    (--inject=on|off)
  Context:   standard (--context=compact|standard|rich)
  Power:     balanced (--power=quiet|balanced|fast)
  Backfill:  balanced (--backfill-power=quiet|balanced|fast)

# answer a question from your project's memory — no agent needed
$ verbative-memory ask "why is the session cookie SameSite=Lax?"
The Safari-only login loop was traced to SameSite on Jul 11: the OAuth
callback needs the session cookie at SameSite=Lax. It was set deliberately
in auth.ts — tightening it back to Strict reintroduces the loop. [m:b41c2e]

# bring your history in — pick which past sessions to memorize
$ verbative-memory backfill
Past sessions of this project — a live picker:
  ↑↓ select · enter memorize · same key pauses/resumes · q quit
  ▸ Jul 22  4.1MB  fix the safari login loop on the auth callback  ▶ 37%
    Jul 21  1.3MB  strip EXIF with sharp before upload             done
    Jul 18  0.8MB  why is the checkout flaky on slow connections
    … show 10 more
  Memorizing runs in the background, GPU-quiet — close anytime, it continues.
  In scripts: backfill 1,3-5 | --last=5 | --all · progress: backfill --status

# everything else
$ verbative-memory --help
verbative-memory       the MCP server (what your agent runs)
  login [email]        sign in — same plan as the extension
  logout               sign out (memory pauses; your files stay)
  register-hooks       auto capture & recall
                       (--agent=claude|codex)
  unregister-hooks     remove the hooks again (per agent or all)
  backfill             browse & memorize past sessions
  ask "<question>"     answer from this project's memory
  status               account, memory, hooks, models, engine
  setup                pre-download the on-device models
  version              print the installed version

How it works

Capture, on-device:a bundled local model reads each finished turn and saves decisions, conventions, file locations — and dead ends, kept as explicit avoid warnings.
Recall, budgeted:semantic search + a reranker put exactly the right memories into each prompt. Precision over volume — never a context dump.
Self-maintaining: new facts reconcile with old ones (contradictions supersede, confirmations strengthen); the pool consolidates in the background.
Your files: plain, human-readable files under .verbative/memory/— git-ignored by default, with an opt-in toggle to version team conventions with your code.
Full control:the extension's Memory tab searches, pins, edits and retires entries; agents get the same agency via the memory tools.

Good to know

One engine, never a duplicate:extension, npx and pip all resolve the same per-project engine and share its models — whoever starts first hosts it, everyone else connects.
Context size: VERBATIVE_MEMORY_CONTEXT=compact|standard|rich (6 / 12 / 24 memories — ≈180 / ≈350 / ≈700 tokens per prompt); in the extension it's a Memory tab setting.
Plan: memory is part of Advanced — try everything free for 14 days. Without Advanced, capture and recall pause; your files stay untouched and readable, and everything resumes when you subscribe.

Advanced: point an agent at the extension's binary directly (no npx)

The extension ships the compiled server at ~/Library/Application Support/Verbative/bin/verbative-hooks/verbative-hooks — shown as <verbative-server> below. Functionally identical to the npx route. Caveat: when the engine is hosted by the extension, a VS Code window with Verbative must be open for that project; the standalone install hosts its own engine.

terminal

$ claude mcp add verbative-memory -- "$HOME/Library/Application Support/Verbative/bin/verbative-hooks/verbative-hooks" __memory-mcp

The extension already runs automatic capture and injection — this adds the on-demand memory tools.

See Memory in action →