Integrates Harper agent-memory with Claude Code via remote HTTP MCP (/mcp), automatic session bootstrap (SessionStart), budgeted per-prompt recall (UserPromptSubmit), and live change notices (/MemoryEvents).
For the whole path (provisioning a user, installing into each Claude profile and Codex, verifying, updating and
rolling back), follow docs/onboarding.md. By hand, add the HarperFast/agent-memory
marketplace and install the plugin:
/plugin marketplace add HarperFast/agent-memory
/plugin install agent-memory@agent-memory
The plugin has no fixed version: Claude Code versions it by the repository's commit, so every commit to main is a
new version. Bring an install up to date with
claude plugin marketplace update agent-memory && claude plugin update agent-memory@agent-memory, or turn on
auto-update for the marketplace in /plugin (off by default for third-party marketplaces). New sessions load the
update; a running session keeps the version it started with.
Enable the MCP adapter on your Harper agent-memory application (config.yaml):
'@harperfast/agent-memory':
package: '@harperfast/agent-memory'
mcp: trueConfigure your Harper endpoint and user-bound credential:
- Export
AGENT_MEMORY_URLin your shell or Claude Codesettings.jsonenvblock so.mcp.jsoncan expand${AGENT_MEMORY_URL}/mcp:export AGENT_MEMORY_URL="https://memory.example.com:9926"
- Set
AGENT_MEMORY_TOKENin~/.config/agent-memory/env(chmod 600 ~/.config/agent-memory/env) or in your environment:UsingAGENT_MEMORY_URL="https://memory.example.com:9926" AGENT_MEMORY_TOKEN="your-harper-token-or-Basic-credential"
~/.config/agent-memory/envforAGENT_MEMORY_TOKENletsbin/headers.mjs(headersHelper) and the lifecycle hooks authenticate requests without exposingAGENT_MEMORY_TOKENin subshells spawned by Claude'sBashtool.
AGENT_MEMORY_BOOTSTRAP_BUDGET: character budget forSessionStartbootstrap injection (default4000). The hook sends the server its per-entry framing (entryOverhead,sectionItemOverhead) so the server packs only what the injection can hold: every packed entry whose metadata is within the hook's sizing (see DESIGN.md › Bootstrap hook) is injected, in order. That needs an agent-memory server with those parameters (newer than 0.1.5). An older server ignores them, and larger metadata (alastEditor, long principal ids, many scopes, escaped characters) can cost more; the injection is then an in-order prefix of the response, always within the budget.AGENT_MEMORY_BOOTSTRAP_TIMEOUT_MS: timeout in ms forSessionStartbootstrap request (default3000).AGENT_MEMORY_RECALL_BUDGET: character budget forUserPromptSubmitrecall injection (default2000).AGENT_MEMORY_RECALL_TIMEOUT_MS: hard timeout in ms forUserPromptSubmitrecall request (default1500).AGENT_MEMORY_RECALL_LIMIT: maximum memories fetched per prompt (default5, max50).AGENT_MEMORY_RECALL=off: disable per-promptUserPromptSubmitrecall. With recall enabled, queries inspect the first32000prompt characters, normalize Unicode, strip fenced code blocks and URLs, and keep at most1000characters and32letter/number terms before being sent asGET /Memory/?q=<query>. Queries may appear in server/proxy access logs and be sent to the server's embedding provider. Code-only, URL-only and punctuation-only prompts skip recall, and so do prompts with no distinctive term (1, 2, 3,yes,please continue): a term counts if it has at least 4 characters (2 in Chinese, Japanese or Korean script) and is not a conversational word. Queued change notices are still delivered on those prompts.AGENT_MEMORY_DISABLE_FOLLOWER=1: disable the per-session detached/MemoryEventsSSE follower.AGENT_MEMORY_ENV_FILE: path of the env file holdingAGENT_MEMORY_TOKEN(default$HOME/.config/agent-memory/env). A harness that gives Claude Code its ownHOMEmust set this (for example to the account's real~/.config/agent-memory/env), or the hooks find no token;SessionStartthen injects a notice saying so.AGENT_MEMORY_CACHE_DIR: directory for session state, the offline cache and the diagnostics log (default$HOME/.cache/agent-memory/claude-plugin). Point it outside a per-runHOMEthat is deleted after the run to keep the log.
Every SessionStart and UserPromptSubmit (and the MCP headers helper, when it finds no credential) appends one line to <AGENT_MEMORY_CACHE_DIR>/diagnostics.jsonl with its outcome (injected, empty, deduped, over_budget, http_<status>, timeout, error, skipped, disabled or unconfigured, plus a reason where one applies), the request latency in ms and hit counts. Lines never contain prompt text, memory ids or content, URLs or credentials. The file rotates to diagnostics.jsonl.1 at 256 KiB. Summarize it with the plugin's own script (the plugin root is where Claude Code installed it, such as ~/.claude/plugins/cache/agent-memory/agent-memory/<version>):
node "<plugin root>/bin/diagnostics.mjs" # counts by outcome and latency percentiles
node "<plugin root>/bin/diagnostics.mjs" --tail 20 # plus the last 20 lines; --json for machine output- Send to
agent-memory(MCP tools:remember,revise,recall,get,withdraw,pin,unpin,confirm,watch): team-relevant findings, architectural decisions, domain invariants, and shared engineering lessons. - Keep in Claude's native file memory (
~/.claude/projects/.../memory/): machine-specific file paths, local worktree/harness state, and personal workflow preferences. - Single-home rule: never write the same fact to both stores.