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

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

Full Loop

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

Commands

mengram hook install

Installs all 3 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

This adds 3 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
        }]
      }
    ]
  }
}

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

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)

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

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

​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

Full Loop

Commands

mengram hook install

mengram hook status

mengram hook uninstall

Configuration

Environment Variables

Filtering

Quota Limits

Debugging: verbose markers and heartbeat

Troubleshooting