Skip to main content
Prerequisite: Install the engram binary first via Homebrew or binary download.
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us