> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Setup

> Marketplace plugin with hooks and Memory Protocol skill for Claude Code

<Note>
  **Prerequisite**: Install the `engram` binary first via [Homebrew](/installation#homebrew-macos-linux) or [binary download](/installation#download-binary).
</Note>

## Option A: Marketplace Plugin (Recommended)

Install from Claude Code's plugin marketplace:

```bash theme={null}
claude plugin marketplace add Gentleman-Programming/engram
claude plugin install engram
```

That's it. The plugin registers the MCP server, hooks, and Memory Protocol skill automatically.

## Option B: Setup via Engram Binary

Install the same plugin from the embedded binary:

```bash theme={null}
engram setup claude-code
```

During setup, you'll be asked whether to add engram tools to `~/.claude/settings.json` permissions allowlist. This prevents Claude Code from prompting for confirmation on every memory operation.

<Steps>
  <Step title="Install engram binary">
    ```bash theme={null}
    brew install gentleman-programming/tap/engram
    ```
  </Step>

  <Step title="Run setup command">
    ```bash theme={null}
    engram setup claude-code
    ```

    Answer **yes** when asked about adding to permissions allowlist.
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    claude plugin list
    ```

    You should see `engram` in the list.
  </Step>
</Steps>

## Option C: Bare MCP (No Hooks)

Just the 13 memory tools, no session management:

Add to `.claude/settings.json` (project) or `~/.claude/settings.json` (global):

```json theme={null}
{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}
```

With bare MCP, add the [Memory Protocol](/concepts/memory-protocol) to your `CLAUDE.md` so the agent remembers to use Engram after context resets.

## What the Plugin Provides

| Feature                            | Bare MCP | Plugin |
| ---------------------------------- | -------- | ------ |
| 13 memory tools                    | ✓        | ✓      |
| Session tracking (auto-start)      | ✗        | ✓      |
| Auto-import git-synced memories    | ✗        | ✓      |
| Compaction recovery                | ✗        | ✓      |
| Memory Protocol skill              | ✗        | ✓      |
| Previous session context injection | ✗        | ✓      |

## Plugin Structure

```
plugin/claude-code/
├── .claude-plugin/plugin.json     # Plugin manifest
├── .mcp.json                      # Registers engram MCP server
├── hooks/hooks.json               # SessionStart + Stop lifecycle hooks
└── scripts/
    ├── session-start.sh           # Server, session, import, context
    ├── post-compaction.sh         # Context + recovery instructions
    ├── subagent-stop.sh           # Passive capture on subagent completion
    └── session-stop.sh            # End-of-session event logging
```

## How the Plugin Works

### SessionStart Hook (startup)

Runs `scripts/session-start.sh`:

1. Ensures `engram serve` is running
2. Creates a session via HTTP API
3. Auto-imports git-synced chunks from `.engram/manifest.json` (if present)
4. Injects Memory Protocol + previous session context

<CodeGroup>
  ```bash session-start.sh theme={null}
  #!/bin/bash
  ENGRAM_PORT="${ENGRAM_PORT:-7437}"
  ENGRAM_URL="http://127.0.0.1:${ENGRAM_PORT}"

  # Read hook input from stdin
  INPUT=$(cat)
  SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
  CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
  PROJECT=$(basename "$CWD")

  # Ensure server is running
  if ! curl -sf "${ENGRAM_URL}/health" --max-time 1 > /dev/null 2>&1; then
    engram serve &>/dev/null &
    sleep 0.5
  fi

  # Create session
  curl -sf "${ENGRAM_URL}/sessions" -X POST \
    -H "Content-Type: application/json" \
    -d "{\"id\":\"${SESSION_ID}\",\"project\":\"${PROJECT}\",\"directory\":\"${CWD}\"}" \
    > /dev/null 2>&1

  # Auto-import git-synced chunks
  if [ -f "${CWD}/.engram/manifest.json" ]; then
    engram sync --import 2>/dev/null
  fi

  # Inject Memory Protocol + context to stdout
  cat <<'PROTOCOL'
  ## Engram Persistent Memory — ACTIVE PROTOCOL
  ...
  PROTOCOL
  ```
</CodeGroup>

### SessionStart Hook (compact)

Runs `scripts/post-compaction.sh`:

1. Injects previous session context
2. Tells the agent: "FIRST ACTION REQUIRED — call `mem_session_summary` before doing anything else"

This ensures no work is lost when context is compressed.

### SubagentStop Hook

Runs `scripts/subagent-stop.sh`:

Passive capture trigger — extracts learnings from subagent completion.

### Stop Hook

Runs `scripts/session-stop.sh`:

Logs end-of-session event for tracking.

## MCP Server Registration

The plugin includes `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp", "--tools=agent"]
    }
  }
}
```

Note the `--tools=agent` flag — this exposes the agent-facing tools (vs. `--tools=all` for debugging).

## Memory Protocol Skill

The plugin includes a skill at `skills/memory/SKILL.md` that teaches:

* **When to save** — Mandatory after bugfixes, decisions, discoveries, patterns
* **When to search** — Reactive ("remember") + proactive (overlapping work)
* **Session close** — Mandatory `mem_session_summary` before ending
* **After compaction** — 3-step recovery: persist summary → load context → continue

Claude Code loads skills automatically — no manual prompt engineering needed.

## Platform-Specific Notes

### Windows

<Warning>
  The Claude Code plugin hooks use **bash scripts**. On Windows, Claude Code runs hooks through Git Bash (bundled with [Git for Windows](https://gitforwindows.org/)) or WSL.
</Warning>

If hooks don't fire:

1. Install [Git for Windows](https://gitforwindows.org/) (includes Git Bash)
2. Ensure `bash` is in your `PATH`
3. Restart Claude Code

Alternatively, use **Option C (Bare MCP)** which works natively on Windows without any shell dependency.

### macOS / Linux

Plugin hooks work out of the box. Bash is always available.

## Git Sync Auto-Import

If your project has `.engram/manifest.json`, the plugin automatically imports team memories on session start:

```bash theme={null}
if [ -f "${CWD}/.engram/manifest.json" ]; then
  engram sync --import 2>/dev/null
fi
```

Clone a repo → run Claude Code → team's memories are loaded.

See [Git Sync](/features/git-sync) for details.

## Compaction Recovery

When Claude Code compacts (summarizes long conversations to free context), the plugin:

1. **Auto-saves checkpoint** — Calls `/sessions/{id}/end` with the summary
2. **Injects previous context** — Fetches recent session data and adds to compaction prompt
3. **Reminds new agent** — Adds instruction: "FIRST ACTION REQUIRED: Call `mem_session_summary`..."

Implemented via `post-compaction.sh` hook:

```bash theme={null}
# Fetch context
CONTEXT=$(curl -sf "${ENGRAM_URL}/context?project=${PROJECT}" | jq -r '.context // empty')

# Inject context + recovery instruction to stdout
echo "$CONTEXT"
cat <<'INSTRUCTION'
FIRST ACTION REQUIRED: Call mem_session_summary with the compacted summary content.
This preserves what was accomplished before compaction.
INSTRUCTION
```

## Permissions Allowlist

When using `engram setup claude-code`, you can add engram tools to the permissions allowlist in `~/.claude/settings.json`:

```json theme={null}
{
  "allowedTools": [
    "mem_save",
    "mem_search",
    "mem_context",
    "mem_session_summary",
    "mem_update",
    "mem_delete",
    "mem_timeline",
    "mem_get_observation",
    "mem_suggest_topic_key",
    "mem_save_prompt",
    "mem_stats",
    "mem_session_start",
    "mem_session_end"
  ]
}
```

This prevents Claude Code from asking "Allow tool use?" on every memory operation.

## Troubleshooting

### Plugin not listed

```bash theme={null}
claude plugin list
```

If engram is missing, reinstall:

```bash theme={null}
claude plugin install engram
```

### Hooks not firing

Check that bash is available:

```bash theme={null}
which bash
```

On Windows, install [Git for Windows](https://gitforwindows.org/).

### MCP tools not available

Check `.claude/settings.json` or `~/.claude/settings.json` for the `engram` MCP server entry.

### Server not starting

Manually start:

```bash theme={null}
engram serve
```

Then restart Claude Code.

## Next Steps

* Learn about the [Memory Protocol](/concepts/memory-protocol)
* Explore [MCP Tools](/features/mcp-tools)
* Set up [Git Sync](/features/git-sync) for team memory sharing