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, and ownership-fenced: a private note is stored under its owner and returned only to that owner's credential.

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 to the knowledge base. A background worker distills candidate lessons out of a session's transcript once enough of it has accumulated and posts each one to your Vectros store as an unreviewed candidate record. A captured candidate is never written into the searchable knowledge base automatically: it sits in a review queue, unindexed, 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. A candidate nobody settles is never stored: once it has been offered on VECTROS_MEM_ORPHAN_CAP_DAYS distinct days (default 7), a background step marks it ignored, and dispose.mjs --reopen reverses that.
  • Candidates pass a local content scan before they are sent (0.14.0 and later). Secrets in known formats (cloud access keys, API keys and tokens, JWTs, user:pass@host connection strings, private-key blocks) are replaced with [REDACTED] and the rest of the lesson is sent. A candidate that contains a US Social Security number-shaped or payment-card-shaped number, or that a small model call made through your own Claude Code judges to describe a real, identifiable individual or organization, is withheld: it is never sent and stays in the local capture log. If the model call is unavailable, the candidate is held and retried later. This is a best-effort local scan: it does not recognize every secret or personal-data format, and it is not a compliance control.
  • The hooks fail open; the content scan and the exclusion settings do not. A missing credential, an unreachable API, or a malformed tuning value degrades the affected hook to a no-op rather than breaking the turn it fired on. The content scan is an exception for transmission: when its model call is unavailable the candidate is held rather than sent. The other exception is an unusable config.json (unreadable, not valid JSON, or an EXCLUDED_DIRECTORIES/INCLUDED_DIRECTORIES value that is not a list of directories): a list that cannot be honoured is not safe to ignore, so memory is switched off for every session until the file is fixed, and the session says so.

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. The hooks run from the deployed copy, not from the installed package, so after you update the package run claude-code-agent-memory init again to deploy the new version.

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

CommandPurpose
init [--dry-run]Deploy the hook runtime and wire it into ~/.claude/settings.json.
set-tokenStore 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.

ScriptPurpose
report.mjsRecall/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 (auto-ignores candidates left unsettled across several days) on demand. Dry run by default.

Environment variables

VariableDefaultPurpose
VECTROS_MEMORY_HOME<claude config dir>/vectros-memoryWhere the runtime deploys.
CLAUDE_CONFIG_DIR~/.claudeClaude Code's own config directory.
VECTROS_API_BASE_URLhttps://api.vectros.aiOverride the API base. Validated before every hook fetch attaches your credential — must be an official vectros.ai/*.vectros.ai host (or http:// to localhost). An untrusted value is refused and the hook falls back to the default rather than using it.
VECTROS_ALLOW_INSECURE_BASE_URL—Set 1 to bypass that check for a trusted local proxy — logs a warning every time. Not recommended: it sends your key and prompt text to whatever host VECTROS_API_BASE_URL names, unvalidated.
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.
VECTROS_MEM_CLASSIFIER_TIMEOUT_MS25000Time budget, in milliseconds, for the content scan's model call on each candidate.
VECTROS_MEM_CLASSIFIER_MODEL(the capture model)The model the content scan's model call uses.
VECTROS_MEMORY_OFF—Set 1 in a session's environment to switch memory off for that session: no recall, no capture. To scope it to one project, set it in that project's .claude/settings.local.json env block.

To exclude directories instead, list them in config.json under EXCLUDED_DIRECTORIES (sessions in or under them are excluded) or INCLUDED_DIRECTORIES (when present and non-empty, only sessions under them run); the package README has the matching rules.

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 is stored but not indexed and a search or grounded answer does not return it — the separation the propose/commit split depends on.
  • The backend coupling is a plain REST contract, but the base URL is validated, not freely repointable. VECTROS_API_BASE_URL is an environment-variable override, and the calls the hooks make are a small, generic surface (create, look up, and patch a few record types) — but since 0.13.1 an override must resolve to an official vectros.ai host or it's refused (see Environment variables above). Genuinely forking to a different back end needs the loud VECTROS_ALLOW_INSECURE_BASE_URL=1 opt-out, not a plain override.
  • 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.