Skip to main content
3ngram ships three shell scripts that integrate with Claude Code hooks to automate memory capture across your coding sessions. No manual debriefs needed.
Hook scripts are specific to Claude Code. Other MCP clients (Claude Desktop, Cursor, ChatGPT) don’t support hooks, use prompt templates instead.

​
Quick start

  1. Copy the hooks block from scripts/hooks/hooks.example.json into your Claude Code settings (~/.claude/settings.json or project .claude/settings.json):
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/3ngram/scripts/hooks/3ngram-briefing.sh",
            "statusMessage": "3ngram: Loading session briefing..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/3ngram/scripts/hooks/3ngram-capture.sh"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/3ngram/scripts/hooks/3ngram-debrief.sh"
          }
        ]
      }
    ]
  }
}
  1. Replace /path/to/3ngram with the actual path to your 3ngram clone.
  2. Set two environment variables: 
export ENGRAM_MCP_URL="https://mcp.3ngram.ai/mcp"  # or http://localhost:8001/mcp
export ENGRAM_MCP_TOKEN="your-mcp-token"

​
Hook reference

​
SessionStart: Briefing

Script: 3ngram-briefing.sh Fetches your open commitments, blockers, overdue items, stale work (7+ days inactive), and recent decisions from 3ngram. Renders a token-budgeted briefing block injected into the session context. All five MCP calls run in parallel for speed. Falls back to a reminder message if the server is unreachable. Suppressed in secondary git worktrees to avoid duplicate briefings.

​
PostToolUse: Capture

Script: 3ngram-capture.sh Filters every tool-use event against rules in capture-filter.json. By default, only git commit commands are captured. Each captured event is persisted as a memory via the MCP remember tool. The script automatically:
  • Derives the project name from the git remote URL
  • Extracts conventional commit tags (feat, fix, etc.) for memory tagging
  • Classifies feat/refactor commits as decisions, everything else as context
  • Strips <private> tags from content before sending
  • Skips 3ngram’s own MCP tool calls to prevent circular capture

​
SessionEnd: Debrief

Script: 3ngram-debrief.sh Extracts files modified and git commits from the session payload and persists a structured summary memory. Skips sessions with no file changes and no commits. Falls back to reading the transcript file if the inline payload lacks detail.

​
Environment variables

VariableRequiredDefaultDescription
ENGRAM_MCP_URLYeshttp://localhost:8001/mcpMCP server HTTP endpoint
ENGRAM_MCP_TOKENYes(none)Bearer token for MCP auth
ENGRAM_SCOPENo(none)Scope tag for multi-tenant setups
ENGRAM_HOOK_DEBUGNo0Set to 1 to dump raw payloads to /tmp/3ngram-hook-debug/
BRIEFING_FULL_COUNTNo5Number of items shown with full content in briefings
BRIEFING_MAX_TOKENSNo2000Token budget cap for briefing output

​
Capture filter rules

The file scripts/hooks/capture-filter.json controls which tool events get captured. Default config captures only git commits: 
{
  "rules": [
    {
      "tool": "Bash",
      "command_pattern": "git commit",
      "capture": true,
      "topic_template": "commit: {project}",
      "content_fields": ["command", "stdout"]
    }
  ],
  "defaults": {
    "capture": false
  }
}
Each rule matches on:
  • tool: Tool name (e.g. Bash, Write)
  • command_pattern: Substring match against the command (Bash tool)
  • path_pattern: Substring match against the file path (Write tool)
  • capture: Whether to persist the event as a memory
  • topic_template: Memory topic, supports {project} placeholder
  • content_fields: Which fields from the tool input/response to include
Set defaults.capture to true to capture all events (noisy, not recommended).

​
Troubleshooting

Set ENGRAM_HOOK_DEBUG=1 to dump raw payloads to /tmp/3ngram-hook-debug/. Check capture-*.json for PostToolUse events and debrief-*.json for SessionEnd payloads. Common issues:
  • “hook error” on every tool use: All scripts require jq. Install it with your package manager.
  • Briefing shows fallback message: MCP server unreachable, ENGRAM_MCP_TOKEN unset, or jq missing.
  • No debrief captured: Sessions with zero file modifications and zero git commits are skipped.