Skip to main content

​
Overview

Mengram integrates with Claude Code hooks to create a full memory loop:
  1. Session context — loads your cognitive profile when a session starts, so Claude knows who you are
  2. Auto-recall — searches relevant memories on every prompt and injects them as context
  3. Auto-save — captures conversations in the background to build up memory over time
Zero manual effort. One command to install.

​
Quick Setup

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. Or manually: export MENGRAM_API_KEY=om-your-key → mengram hook install.

​
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

OptionDefaultDescription
--every N3Save every Nth response. Lower = more memories, higher = less noise
--user-id"default"Mengram user_id for multi-user isolation

​
Environment Variables

VariableRequiredDescription
MENGRAM_API_KEYYesYour Mengram API key (starts with om-)
MENGRAM_URLNoCustom API URL (default: https://mengram.io)
MENGRAM_USER_IDNoDefault 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:
HookWhat happensMessage shown
Auto-recallSearch quota exceededClaude sees: [Mengram] Memory search quota exceeded — recall is disabled
Auto-contextProfile load failsSession start shows: [Mengram] Memory profile load failed — quota exceeded
Auto-saveSave quota exceededTerminal 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.

​
Troubleshooting

Hooks not firing?
  • Restart Claude Code after installing
  • Check mengram hook status to verify all 3 hooks are installed
  • Make sure MENGRAM_API_KEY is set in your shell profile (.zshrc / .bashrc)
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.