Claude Code Setup

Marketplace plugin with hooks and Memory Protocol skill for Claude Code

Prerequisite: Install the engram binary first via Homebrew or binary download.

Option A: Marketplace Plugin (Recommended)

Install from Claude Code’s plugin marketplace:

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:

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.

1. Install engram binary

   brew install gentleman-programming/tap/engram
   
2. Run setup command

   engram setup claude-code
   

   Answer yes when asked about adding to permissions allowlist.

3. Verify installation

   claude plugin list
   

   You should see engram in the list.

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

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

With bare MCP, add the 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

session-start.sh

#!/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

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:

{
  "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

The Claude Code plugin hooks use bash scripts. On Windows, Claude Code runs hooks through Git Bash (bundled with Git for Windows) or WSL.

If hooks don’t fire:

1. Install Git for Windows (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:

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 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:

# 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:

{
  "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

claude plugin list

If engram is missing, reinstall:

claude plugin install engram

Hooks not firing

Check that bash is available:

which bash

On Windows, install Git for Windows.

MCP tools not available

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

Server not starting

Manually start:

engram serve

Then restart Claude Code.

Next Steps

• Learn about the Memory Protocol
• Explore MCP Tools
• Set up Git Sync for team memory sharing