> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Persistent Memory to Claude Code

> Install Agent Memory for Claude Code using the plugin marketplace or CLI — memory persists across all sessions with automatic hook-based capture.

Claude Code is the primary supported agent. Agent Memory integrates directly via Claude Code's plugin system and hooks, capturing every tool use automatically — no prompting, no manual saves. Once connected, Claude Code remembers your architecture decisions, file conventions, and past debugging work across every future session.

## Installation

<Tabs>
  <Tab title="Plugin Marketplace (recommended)">
    The plugin marketplace path gives you the full experience: 12 lifecycle hooks, 15 skills, and the MCP server wired together in two commands.

    <Steps>
      <Step title="Start the memory server">
        In a separate terminal, start Agent Memory before launching Claude Code:

        ```bash theme={null}
        agentmemory
        ```

        The server starts on port 3111. Keep this terminal open.
      </Step>

      <Step title="Install the plugin inside Claude Code">
        Inside a Claude Code session, run:

        ```
        /plugin marketplace add rohitg00/agentmemory
        /plugin install agentmemory
        ```

        This single install registers all 12 hooks, 15 skills, and auto-wires the `@agentmemory/mcp` server via the plugin's `.mcp.json` — you get all 53 MCP tools without any extra configuration.
      </Step>

      <Step title="Verify">
        Confirm the server is reachable:

        ```bash theme={null}
        curl http://localhost:3111/agentmemory/health
        ```

        The real-time memory viewer is available at `http://localhost:3113`.
      </Step>
    </Steps>

    <Note>
      Make sure `agentmemory` is running before starting Claude Code. The plugin connects to it on session start.
    </Note>
  </Tab>

  <Tab title="CLI">
    If you prefer to wire Agent Memory from outside Claude Code, the CLI adapter writes the MCP config directly to `~/.claude.json`:

    ```bash theme={null}
    agentmemory connect claude-code
    ```

    This adds an `mcpServers.agentmemory` entry to `~/.claude.json` pointing at `@agentmemory/mcp`. Claude Code picks it up on next launch or after running `/mcp` inside a session.

    <Note>
      The CLI path wires MCP only. Hooks require the plugin install or the `--with-hooks` flag (see below).
    </Note>
  </Tab>
</Tabs>

## Install Native Skills (optional)

Run this after connecting to install 15 custom skills that let Claude Code trigger memory operations directly by name:

```bash theme={null}
npx skills add rohitg00/agentmemory -y
```

This installs 15 skills:

* **8 action skills** you can invoke directly: `/recall`, `/remember`, `/recap`, `/handoff`, `/forget`, `/commit-context`, `/commit-history`, `/session-history`
* **7 reference skills** Claude Code loads on demand: MCP tools reference, REST API reference, config guide, agents guide, hooks guide, architecture overview, and a skill-authoring guide

These skills teach Claude Code when and how to call the underlying memory tools — without them, the agent still has access to the tools but may not use them as proactively.

## How Hooks Work with Claude Code

When you install via the plugin marketplace, Agent Memory registers as a pre/post tool use hook inside Claude Code. Claude Code fires these hooks automatically around every tool call — you do nothing differently.

Here is what gets captured without any manual effort:

<CardGroup cols={2}>
  <Card title="File reads and writes" icon="file">
    Every `Read`, `Write`, and `Edit` tool call is recorded with file path, project context, and the agent's reasoning.
  </Card>

  <Card title="Bash commands" icon="terminal">
    Shell executions are captured with their output, so Agent Memory learns which commands you run for which tasks.
  </Card>

  <Card title="Web and codebase searches" icon="magnifying-glass">
    Search queries and their results build a picture of what your agent looked for and what it found.
  </Card>

  <Card title="Conversation turns" icon="comments">
    Session start and end events create session boundaries, so memories are grouped by the work you were doing.
  </Card>
</CardGroup>

Claude Code fires 12 lifecycle hooks in total: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`, `SubagentStart`, `SubagentStop`, `Notification`, `TaskCompleted`, `PostToolUseFailure`, and `SessionEnd`. Agent Memory listens to all of them.

## CLAUDE\_MEMORY\_BRIDGE

Enable bi-directional sync between Agent Memory and your `CLAUDE.md` file:

```bash theme={null}
CLAUDE_MEMORY_BRIDGE=true agentmemory
```

With the bridge enabled, Agent Memory writes key decisions and patterns to `CLAUDE.md` as they accumulate, and reads from it as additional context during recall. This means your `CLAUDE.md` stays current automatically instead of going stale.

## Available MCP Tools

When connected via the plugin or `~/.claude.json`, Claude Code has access to these tools. It calls them automatically via hooks — or you can invoke them directly in your prompt:

| Tool                  | What it does                                                 |
| --------------------- | ------------------------------------------------------------ |
| `memory_recall`       | Full-text and semantic search across all past observations   |
| `memory_save`         | Explicitly save an insight, decision, or pattern             |
| `memory_smart_search` | Hybrid BM25 + embedding search with RRF fusion and reranking |
| `memory_file_history` | Retrieve all past observations about a specific file         |
| `memory_patterns`     | Surface recurring patterns across sessions                   |
| `memory_sessions`     | List recent sessions with summaries                          |
| `memory_timeline`     | Chronological view of observations                           |
| `memory_profile`      | Full project profile: key concepts, files, and patterns      |

The plugin exposes all 53 tools when the Agent Memory server is reachable. To limit the tool surface for smaller context windows, set `AGENTMEMORY_TOOLS=core` when starting the server.

## Hooks-Only Wiring (MCP-Standalone Path)

If you used `agentmemory connect claude-code` instead of the plugin install, Claude Code cannot resolve `${CLAUDE_PLUGIN_ROOT}` and hook scripts need absolute paths. Run this to wire hooks using absolute paths from the currently installed package:

```bash theme={null}
agentmemory connect claude-code --with-hooks
```

This merges hook entries into `~/.claude/settings.json` with absolute paths. Re-run this command after upgrading Agent Memory to refresh the paths — user-defined hook entries in the file are preserved.

<Warning>
  The MCP-standalone path (manual `~/.claude.json` wiring) without `--with-hooks` means hooks will not fire. You get MCP tools but no automatic capture. The plugin marketplace install is the recommended approach precisely because it handles both.
</Warning>

## Verification

After connecting, open a new Claude Code session. You should see a line like `Loaded N memories` in the session context. To confirm hooks are working:

```bash theme={null}
agentmemory status
```

Run a few tool-use operations in Claude Code (read a file, run a command), then check status again. The hook count should be incrementing. You can also watch memories arrive live at `http://localhost:3113`.