# Claude Code agent memory ## Explanation — what & why `@vectros-ai/claude-code-agent-memory` is a set of [Claude Code](https://claude.com/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 ```bash 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: ```bash 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: ```bash node report.mjs # what the loop is doing, and what's still pending node dispose.mjs --list # list one session's pending candidates node dispose.mjs \ c1=stored: \ 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. `` 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