Claude Code Integration

Overview

Mengram integrates with Claude Code hooks to create a full memory loop that survives /clear, auto-compaction, machine switches, and team handoffs — the SessionStart hook fires after every compact and re-injects your context:

Session context — loads your cognitive profile when a session starts, so Claude knows who you are
Auto-recall — searches relevant memories on every prompt and injects them as context
Auto-save — captures conversations in the background to build up memory over time
Policy gate — before a workflow-shaped Bash command runs, checks it against the workflows memory has learned; if the match has a weak record, Claude has to ask you first

Zero manual effort. One command to install.

Quick Setup

Option A — plugin from the marketplace (recommended)

# 1. Save your API key once (free key at https://mengram.io)
mkdir -p ~/.mengram && echo '{"api_key": "om-your-key-here"}' > ~/.mengram/config.json

# 2. Install the plugin
claude plugin marketplace add alibaizhanov/mengram
claude plugin install mengram@mengram

The plugin ships the hooks, the MCP server (30 tools), and a skill. Hooks read the key from ~/.mengram/config.json (an exported MENGRAM_API_KEY env var wins if set). First-run self-check: until the plugin verifies one successful API round-trip, failures show a one-line message telling you exactly what’s broken. After the first success, failures are silent — an outage never spams you or blocks Claude Code.

Option B — CLI hooks

pip install mengram-ai
mengram setup

This creates your account (if needed), saves your API key, and installs all 4 hooks automatically. Restart Claude Code — done.

Skip the cold start — import your history

Your past Claude Code sessions are already on disk. Feed them in and memory starts full, not empty:

pip install mengram-ai
mengram import claude-code

Secrets (API keys, tokens) are redacted client-side before upload. Then ask Claude: “what do you know about my projects?”

How It Works

1. Session Start — Profile Loaded

When you open Claude Code (or after context compaction), the SessionStart hook fires:

Session starts
  → mengram auto-context runs
  → Loads your Cognitive Profile from Mengram (GET /v1/profile)
  → Prints it to stdout — Claude sees it as context

Claude now knows: your name, preferences, tech stack, current projects

2. Every Prompt — Relevant Memories Recalled

When you type a prompt, the UserPromptSubmit hook fires before Claude responds:

You type: "how did we deploy to Railway?"
  → mengram auto-recall runs
  → Searches Mengram for relevant memories (POST /v1/search)
  → Returns additionalContext that Claude sees:

  [Mengram Memory — relevant context from past sessions]
  Railway Deployment:
    - Auto-deploys from main branch
    - Uses gunicorn with 1 worker
    - DATABASE_URL uses Session Mode port 5432

Claude responds WITH context from your past sessions

3. After Response — Conversation Saved

After Claude responds, the Stop hook fires asynchronously in the background:

Claude finishes responding
  → mengram auto-save runs (background, non-blocking)
  → Every 3rd response, sends [user + assistant] to POST /v1/add
  → API extracts entities, facts, episodes, procedures
  → Memory grows over time

4. Before a Bash command — the policy gate

Outcome history should change what the agent is allowed to do, not only how results rank. When Claude is about to run a command that looks like a workflow (git push, deploy, migrate, kubectl, terraform, rm -rf …), the PreToolUse hook fires:

Claude wants to run: git push origin main
  → mengram auto-policy runs
  → Finds the learned workflow this matches (GET /v1/procedures/search)
  → Reads its record: untested · 61% expected · 88% reliable

  88% reliable   → silent, the command runs as it would have
  untested       → "ask": you see why, Claude gets the steps on record
  61% expected   → "ask": this version has never run; 61% is inherited from the one it replaced
  58% reliable   → "ask": below the bar (default 70%)

The prompt you see is a normal Claude Code permission prompt, labelled [settings], with the reason: “Mengram: learned workflow ‘deploy to Railway’ has never been run. Review the plan before it runs.” Claude receives the workflow’s steps, preconditions and last failure as context, so if you decline it can show you the plan instead of guessing. The gate never denies. Memory can ask; it does not get to forbid. Commands that are not workflow-shaped (ls, cat, grep) never trigger a lookup, so the hook costs nothing on ordinary work. Why the record fills itself here and not offline. The gate is only as good as the counts behind it. With the cloud, auto-save extracts workflows from your sessions, a failed run records the violated assumption on a new version, and every procedure carries success_count / fail_count / last_failure without you writing anything. The same gate runs fully offline against a memfmt folder (MENGRAM_MEMORY_DIR=./memory), but there the counts are whatever you typed.

Setting	Default	What it does
`MENGRAM_POLICY_MIN_RELIABLE`	`70`	Percent below which a workflow with a record is confirmed
`MENGRAM_POLICY_PATTERN`	deploy / push / migrate / kubectl / …	Regex for “workflow-shaped”; `.*` gates every Bash command
`MENGRAM_MEMORY_DIR`	unset	Read a memfmt folder instead of the cloud (no key, no network)
`mengram hook install --no-policy`	—	Install the other three hooks without the gate

Full Loop

┌──────────────────────────────────────────────┐
│  Session starts                              │
│  ↓ SessionStart → profile loaded             │
│                                              │
│  You type a prompt                           │
│  ↓ UserPromptSubmit → relevant memory found  │
│                                              │
│  Claude responds (with memory context)       │
│  ↓ PreToolUse → weak workflow? ask first     │
│  ↓ Stop → conversation saved (background)    │
│                                              │
│  Next prompt → recall again...               │
└──────────────────────────────────────────────┘

Commands

mengram hook install

Installs all 4 hooks into ~/.claude/settings.json.

mengram hook install                    # default: save every 3rd response
mengram hook install --every 5          # save every 5th response
mengram hook install --user-id myuser   # custom user_id
mengram hook install --no-policy        # skip the policy gate

This adds 4 hooks to your Claude Code settings:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "mengram auto-context",
          "timeout": 15
        }]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [{
          "type": "command",
          "command": "mengram auto-recall",
          "timeout": 10
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "mengram auto-save --every 3",
          "timeout": 30,
          "async": true
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "mengram auto-policy",
          "timeout": 10
        }]
      }
    ]
  }
}

mengram hook status

Check status of all hooks.

mengram hook status

Output:

Mengram Hooks

  Auto-save:      installed (every 3 responses)
  Auto-recall:    installed
  Session context: installed
  Policy gate:    installed
  API Key:        om-...Kb8 (set)
  API:            connected (free plan)
  Settings:       /Users/you/.claude/settings.json

mengram hook uninstall

Remove all Mengram hooks.

mengram hook uninstall

Configuration

Option	Default	Description
`--every N`	3	Save every Nth response. Lower = more memories, higher = less noise
`--user-id`	`"default"`	Mengram user_id for multi-user isolation

Environment Variables

Variable	Required	Description
`MENGRAM_API_KEY`	Yes	Your Mengram API key (starts with `om-`)
`MENGRAM_URL`	No	Custom API URL (default: `https://mengram.io`)
`MENGRAM_USER_ID`	No	Default user_id (overridden by `--user-id`)
`MENGRAM_POLICY_MIN_RELIABLE`	No	Policy gate bar, percent (default `70`)
`MENGRAM_POLICY_PATTERN`	No	Regex for commands the policy gate looks at
`MENGRAM_MEMORY_DIR`	No	memfmt folder for the policy gate’s offline mode

Filtering

Auto-save skips:

Short responses (< 100 characters) — trivial confirmations
Interrupted requests
Responses when no API key is set

Auto-recall skips:

Very short prompts (< 10 characters)
Slash commands (/help, /clear, etc.)
Simple confirmations (yes, no, ok)

Policy gate skips:

Any tool other than Bash
Commands that are not workflow-shaped (ls, cat, grep, python -c …) — no lookup, no cost
Matches whose record is at or above the bar — the command runs untouched
Semantic near-misses: a matched workflow must share at least one real word with the command before it can interrupt you

Quota Limits

When you hit your monthly plan limits, each hook surfaces a clear warning instead of failing silently:

Hook	What happens	Message shown
Auto-recall	Search quota exceeded	Claude sees: `[Mengram] Memory search quota exceeded — recall is disabled`
Auto-context	Profile load fails	Session start shows: `[Mengram] Memory profile load failed — quota exceeded`
Auto-save	Save quota exceeded	Terminal shows: `[Mengram] Memory save failed — Your conversations are NOT being saved`

All messages include an upgrade link. Claude Code is never blocked — hooks continue gracefully. Non-quota errors (network timeouts, transient failures) are silently swallowed so they never interrupt your workflow. To check your current usage: mengram stats or visit mengram.io/dashboard.

Debugging: verbose markers and heartbeat

Verbose markers (CLI hooks): add --verbose to any hook command in your hooks config and every exit path emits a one-line status marker — [mengram:auto-recall] found 3 memories, [mengram:auto-save] throttled (2/3). Answers “is it working?” in one session restart. Off by default (byte-for-byte silent). Heartbeat (plugin): set MENGRAM_HEARTBEAT=25 (env) or "heartbeat": 25 in ~/.mengram/config.json and every 25th successful save shows one line: [mengram] heartbeat: 150 conversations saved to memory so far. With the heartbeat on, silence means something is wrong.

Troubleshooting

Hooks not firing?

Restart Claude Code after installing
Check mengram hook status to verify all 4 hooks are installed
Keys are read from MENGRAM_API_KEY env or ~/.mengram/config.json (env wins) — check cat ~/.mengram/config.json

Memories not appearing?

Auto-save processes in the background — check after ~30 seconds
Verify API connectivity: mengram hook status
Check your memories at mengram.io/dashboard

Recall seems slow?

Auto-recall has a 10-second timeout — if the API is slow, it’s skipped gracefully
Claude Code continues normally even if a hook fails

Seeing quota warnings?

You’ve hit your monthly plan limit — memory is disabled until the limit resets or you upgrade
Run mengram stats to check usage
Upgrade at mengram.io/dashboard

Run mengram setup to automatically save your API key to your shell profile and install all hooks in one step.

Getting Started

Concepts

SDKs

Integrations

Reference

Claude Code Integration

Overview

Quick Setup

Option A — plugin from the marketplace (recommended)

Option B — CLI hooks

Skip the cold start — import your history

How It Works

1. Session Start — Profile Loaded

2. Every Prompt — Relevant Memories Recalled

3. After Response — Conversation Saved

4. Before a Bash command — the policy gate

Full Loop

Commands

mengram hook install

mengram hook status

mengram hook uninstall

Configuration

Environment Variables

Filtering

Quota Limits

Debugging: verbose markers and heartbeat

Troubleshooting

​Overview

​Quick Setup

​Option A — plugin from the marketplace (recommended)

​Option B — CLI hooks

​Skip the cold start — import your history

​How It Works

​1. Session Start — Profile Loaded

​2. Every Prompt — Relevant Memories Recalled

​3. After Response — Conversation Saved

​4. Before a Bash command — the policy gate

​Full Loop

​Commands

​mengram hook install

​mengram hook status

​mengram hook uninstall

​Configuration

​Environment Variables

​Filtering

​Quota Limits

​Debugging: verbose markers and heartbeat

​Troubleshooting

Overview

Quick Setup

Option A — plugin from the marketplace (recommended)

Option B — CLI hooks

Skip the cold start — import your history

How It Works

1. Session Start — Profile Loaded

2. Every Prompt — Relevant Memories Recalled

3. After Response — Conversation Saved

4. Before a Bash command — the policy gate

Full Loop

Commands

mengram hook install

mengram hook status

mengram hook uninstall

Configuration

Environment Variables

Filtering

Quota Limits

Debugging: verbose markers and heartbeat

Troubleshooting