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
candidaterecord. 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 onVECTROS_MEM_ORPHAN_CAP_DAYSdistinct days (default 7), a background step marks itignored, anddispose.mjs --reopenreverses 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@hostconnection 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 anEXCLUDED_DIRECTORIES/INCLUDED_DIRECTORIESvalue 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
| 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 (auto-ignores candidates left unsettled across several days) 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. 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_MS | 25000 | Time 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.mjswith aVECTROS_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_URLis 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 officialvectros.aihost or it's refused (see Environment variables above). Genuinely forking to a different back end needs the loudVECTROS_ALLOW_INSECURE_BASE_URL=1opt-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
bootstrapcommand 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.