Claude Code agent memory

Explanation — what & why

@vectros-ai/claude-code-agent-memory is a set of Claude Code hooks that gives a coding agent cross-session memory backed by Vectros, without your ever having to ask for it. It is not a peer transport primitive the way the SDK, CLI, and MCP server are — it is a packaged consumer built on top of them, specific to Claude Code, and it uses two of them directly: the CLI to bootstrap a credential, and the agentic-SDLC blueprint to provision the schemas it reads and writes.

The design is two tiers, not one: the team's shared, reviewed knowledge, and each agent's own private working notes. Both are typed Vectros records, searchable by meaning, ownership-fenced so a private note stays private and never leaks into another session's recall.

Three properties make it different from asking an agent to "remember to check the knowledge base":

• Recall is involuntary, not a prompted step. A prompt is a suggestion the model follows when it remembers to and skips the moment it is sure it already knows, or the task gets interesting. This package puts recall in front of the agent instead: a fast search before every turn, a debounced background pass that re-evaluates mid-task with a small nested model, and the agent's own tool access for when it decides to dig further.
• Capture proposes; it never writes. A background worker distills candidate lessons out of a session's transcript once enough of it has accumulated, but a captured candidate is never written into the knowledge base automatically. It sits in a review queue, structurally unsearchable, until the agent (with real tools and repo context) explicitly disposes of it — store it as a real memory, point it at existing documentation, or discard it with a reason.
• Everything fails open. A missing credential, an unreachable API, or a malformed config value degrades the affected hook to a no-op rather than breaking the turn it fired on.

How-to

Install

npm install -g @vectros-ai/claude-code-agent-memory
claude-code-agent-memory init

init deploys the hook runtime to ~/.claude/vectros-memory (override with VECTROS_MEMORY_HOME) and wires it into Claude Code by appending matcher blocks to your global ~/.claude/settings.json — it never touches a matcher block it did not itself write, and never touches project-scoped settings. Safe to re-run; already-wired entries are recognized and skipped, not duplicated. Use --dry-run to preview the change with no writes. Restart Claude Code afterward so the new hooks take effect.

Provision the schemas it needs

The package makes no calls that name a specific blueprint — its only hard requirement is that a candidate and a memory schema exist in your store, with the lookup fields candidates.mjs calls against. The suggested way to get there is the bundled agentic-SDLC blueprint, which provisions both alongside its own knowledge-base schemas:

npm i -g @vectros-ai/cli
vectros login
vectros bootstrap --blueprint agentic-sdlc --no-seed --yes

This provisions the whole agentic-SDLC knowledge base, not just the two schemas the hooks read and write. The rest is harmless if you never touch it, and you are not locked into it: any provisioning path that produces a candidate and a memory schema works identically, including a blueprint you fork and trim down to just those two.

Resolve a credential

init pins whichever @vectros-ai/cli identity was active at that moment into the runtime directory's credentials.json — deliberately, so these hooks stop tracking the CLI's active identity from then on (a later vectros bootstrap/switch elsewhere, even for an unrelated tenant, would otherwise silently redirect every hook onto it too). Set VECTROS_API_KEY directly, or point the pin elsewhere with VECTROS_KEYRING_ALIAS and re-run init.

Operate the loop

Two scripts run directly from the runtime directory rather than through the installed CLI:

node report.mjs                                     # what the loop is doing, and what's still pending
node dispose.mjs <sessionId> --list                  # list one session's pending candidates
node dispose.mjs <sessionId> \
  c1=stored:<record-uuid> \
  c2=documented:path/to/docs.md#anchor \
  c3=ignored:already covered by existing docs

A stored: disposition is read back from the store before it is accepted, so a bad id is refused rather than silently mis-filed. A disposed candidate is never re-offered. <sessionId> also accepts an unambiguous prefix of the id, the same short form a nudge line displays.

Reference

CLI commands

Command	Purpose
init [--dry-run]	Deploy the hook runtime and wire it into ~/.claude/settings.json.
set-token	Store an optional CLAUDE_CODE_OAUTH_TOKEN (read from stdin) so the capture/recall-eval workers' nested claude -p calls run under your own Claude subscription instead of ANTHROPIC_API_KEY.

Runtime-directory scripts

Deployed alongside the hooks in VECTROS_MEMORY_HOME; run with node <script>.mjs from that directory.

Script	Purpose
report.mjs	Recall/capture/disposition activity, the undistilled transcript tail, and (--compare) whether the local review queue and the record corpus agree.
dispose.mjs <sessionId>	List and settle pending candidates; --reopen <cN> reverses a wrong disposition.
reap.mjs [--apply]	Prunes stale/phantom session data from the runtime directory. Dry run by default.
orphan-cap-worker.mjs [--apply]	Runs the orphan-cap backstop on demand. Dry run by default.

Environment variables

Variable	Default	Purpose
VECTROS_MEMORY_HOME	<claude config dir>/vectros-memory	Where the runtime deploys.
CLAUDE_CONFIG_DIR	~/.claude	Claude Code's own config directory.
VECTROS_API_BASE_URL	https://api.vectros.ai	Override the API base.
VECTROS_KEYRING_ALIAS	(the pin init wrote)	Pick a specific @vectros-ai/cli identity explicitly; beats both the pin and the CLI's ambient active identity.

Notes & limits

• Pre-1.0 / beta. The thresholds the recall/capture loop uses are sensible defaults, not a hand-tuned system; every one lives in a deployed config.mjs with a VECTROS_MEM_<KEY> env-var override.
• An applied consumer, not a general integration surface. Reach for the SDK or MCP server directly if you are building something other than a Claude Code memory loop — this package's request shape is fixed to what the hooks need.
• The candidate queue is store-only. Its schema declares indexMode: 'NONE', so an unreviewed proposal can never be returned by a search or a grounded answer under any query, by declaration — the same isolation the propose/commit split depends on.
• The backend coupling is a plain REST contract. VECTROS_API_BASE_URL is already an environment-variable override, and the calls the hooks make are a small, generic surface (create, look up, and patch a few record types) — forking to point at something else is a real option, not a rewrite, if you want a different back end under it.
• Requires an invite-only Vectros account today. See the developer portal for early access.

Where to go next

• cli.md — the bootstrap command this package's setup relies on.
• blueprints.md — the agentic-SDLC blueprint's format and what it provisions.
• The agentic-SDLC blueprint walkthrough — the knowledge base this package's shared tier is built on.
• GitHub — the package source, full quickstart, and CLI reference.