Skip to main content
Two install paths. The plugin is the recommended one: it registers all 12 hooks, 17 skills, and auto-wires the MCP server in one step. The connect path wires MCP through ~/.claude.json and can mirror the same hooks into ~/.claude/settings.json.
1

Start agentmemory

REST comes up on 3111, the viewer on 3113.
2

Install the plugin inside Claude Code

The plugin registers 12 hooks, 17 skills, and auto-wires the @agentmemory/mcp stdio server through its .mcp.json, so the 54 MCP tools need no extra config step.
3

Restart Claude Code

Restart, or run /mcp inside a session to pick up the new server.
4

Verify

Then run one prompt and open the viewer at http://localhost:3113: the Sessions tab should show a live session with observations.
For remote or protected deployments, launch Claude Code with AGENTMEMORY_URL and AGENTMEMORY_SECRET exported. The plugin passes both through to its bundled MCP server; when AGENTMEMORY_URL is empty the shim uses http://localhost:3111.

​
Alternative: connect

The adapter detects ~/.claude/, backs up ~/.claude.json to ~/.agentmemory/backups/, then merges this entry and verifies it after writing:
~/.claude.json
The ${VAR:-default} form matters: Claude Code fails to parse an MCP entry whose required env var is unset and has no default, and would silently drop the server. With defaults, one wired entry serves both local and remote deployments.

​
What --with-hooks writes

--with-hooks merges the bundled hook manifest into the top-level hooks field of ~/.claude/settings.json, with ${CLAUDE_PLUGIN_ROOT} resolved to the absolute path of the installed package’s plugin/ directory. It runs even when MCP is already wired, so you can add hooks later without --force. Twelve events fire: SessionStart, UserPromptSubmit, PreToolUse (matcher Edit|Write|Read|Glob|Grep), PostToolUse, PostToolUseFailure, PreCompact, SubagentStart, SubagentStop, Notification, TaskCompleted, Stop, SessionEnd. Each posts to the REST API on 3111, so every prompt, tool call, failure, and session boundary lands as an observation. Re-installs strip only entries whose command points under the bundled scripts/ directory; your own hook entries survive.
The merged hook entries reference absolute paths that embed the installed agentmemory version. Re-run agentmemory connect claude-code --with-hooks after every agentmemory upgrade to refresh them, or the hooks silently break.

​
Capture model

With hooks (plugin or --with-hooks), capture is automatic: no tool calls needed, everything routes through the lifecycle events above. MCP tools remain available for explicit recall and save. The CLAUDE_MEMORY_BRIDGE=true flag additionally mirrors your strongest memories into Claude Code’s native MEMORY.md file; see Exports.

​
Troubleshooting

The installer walks up from the installed package looking for plugin/scripts/ and plugin/hooks/. This fails when the npx cache is broken or the package was installed without its files payload. Reinstall with npm install -g @agentmemory/agentmemory and re-run the connect command. MCP wiring is unaffected by this skip.
The adapter re-reads ~/.claude.json after writing and refuses to report success if mcpServers.agentmemory is missing. This indicates another process rewrote the file concurrently. Close Claude Code, restore from the printed backup path if needed, and re-run connect claude-code --force.
Claude Code’s cleanupPeriodDays (default 30, in ~/.claude/settings.json) deletes JSONL transcripts older than that window. agentmemory import-jsonl can only import what still exists under ~/.claude/projects/. Wire the hooks so each turn is captured live, and raise cleanupPeriodDays if you want a deeper import backlog.
Adapter source: src/cli/connect/claude-code.ts. Hook manifest: plugin/hooks/hooks.json.
Last modified on August 15, 2026