Skip to content

Latest commit

 

History

History

claude-plugin

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

@harperfast/agent-memory Claude Code Plugin

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).

Installation

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

Updates

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.

Server Requirement

Enable the MCP adapter on your Harper agent-memory application (config.yaml):

'@harperfast/agent-memory':
  package: '@harperfast/agent-memory'
  mcp: true

Environment Configuration

Configure your Harper endpoint and user-bound credential:

  1. Export AGENT_MEMORY_URL in your shell or Claude Code settings.json env block so .mcp.json can expand ${AGENT_MEMORY_URL}/mcp:
    export AGENT_MEMORY_URL="https://memory.example.com:9926"
  2. Set AGENT_MEMORY_TOKEN in ~/.config/agent-memory/env (chmod 600 ~/.config/agent-memory/env) or in your environment:
    AGENT_MEMORY_URL="https://memory.example.com:9926"
    AGENT_MEMORY_TOKEN="your-harper-token-or-Basic-credential"
    Using ~/.config/agent-memory/env for AGENT_MEMORY_TOKEN lets bin/headers.mjs (headersHelper) and the lifecycle hooks authenticate requests without exposing AGENT_MEMORY_TOKEN in subshells spawned by Claude's Bash tool.

Optional Environment Variables

  • AGENT_MEMORY_BOOTSTRAP_BUDGET: character budget for SessionStart bootstrap injection (default 4000). 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 (a lastEditor, 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 for SessionStart bootstrap request (default 3000).
  • AGENT_MEMORY_RECALL_BUDGET: character budget for UserPromptSubmit recall injection (default 2000).
  • AGENT_MEMORY_RECALL_TIMEOUT_MS: hard timeout in ms for UserPromptSubmit recall request (default 1500).
  • AGENT_MEMORY_RECALL_LIMIT: maximum memories fetched per prompt (default 5, max 50).
  • AGENT_MEMORY_RECALL=off: disable per-prompt UserPromptSubmit recall. With recall enabled, queries inspect the first 32000 prompt characters, normalize Unicode, strip fenced code blocks and URLs, and keep at most 1000 characters and 32 letter/number terms before being sent as GET /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 /MemoryEvents SSE follower.
  • AGENT_MEMORY_ENV_FILE: path of the env file holding AGENT_MEMORY_TOKEN (default $HOME/.config/agent-memory/env). A harness that gives Claude Code its own HOME must set this (for example to the account's real ~/.config/agent-memory/env), or the hooks find no token; SessionStart then 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-run HOME that is deleted after the run to keep the log.

Diagnostics

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

Memory Routing

  • 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.