Mama Context

MAMA Context - Auto-Injection Skill

Overview

This skill provides automatic background context injection using MAMA's hook system. It runs silently and surfaces relevant past decisions via the UserPromptSubmit hook (~150ms latency with HTTP embedding server).

Philosophy: Gentle hints, not intrusive walls of text. Claude sees topic + time, decides if relevant.

How It Works

The skill uses a multi-hook system for comprehensive context injection:

UserPromptSubmit Hook (active, ~150ms — no plugin-side script; handled by Claude Code host)

• Triggers: On every user message submission
• Purpose: Inject relevant decisions as context before Claude responds
• Latency: ~150ms (HTTP embedding server keeps model in memory)
• Token budget: 40 tokens (teaser format)

SessionStart Hook (scripts/sessionstart-hook.js)

• Triggers: Once per session
• Purpose: Initialize MAMA, pre-warm embedding model
• Timeout: 15s

PreToolUse Hook (scripts/pretooluse-hook.js) - disabled (script retained)

• Previously: Injected contracts before Edit/Write operations
• Status: Disabled for performance. Script retained for future use.

PostToolUse Hook (scripts/posttooluse-hook.js) - disabled (script retained)

• Previously: Tracked code changes, suggested decision saves
• Status: Disabled for performance. Script retained for future use.

PreCompact Hook (scripts/precompact-hook.js)

• Triggers: Before context compaction
• Purpose: Preserve unsaved decisions in compacted context
• Timeout: 10s

Teaser Format (40 tokens)

💡 MAMA: 2 related
   • authentication_strategy (85%, 3 days ago)
   • mesh_detail (78%, 1 week ago)
   /mama:search <topic> for details

Why teaser?

• Hooks fire on user messages (UserPromptSubmit) → Must be lightweight
• Claude infers relevance from topic + similarity + time
• Full details available via /mama:search if needed
• Avoids token bloat (250 tokens → 40 tokens)

Status Transparency

Every injection shows current tier status:

Tier 1 (Full Features):

🔍 System Status: ✅ Full Features Active (Tier 1)
   - Vector Search: ✅ ON (Transformers.js, 3ms latency)
   - Search Quality: HIGH (80% accuracy)

Tier 2 (Degraded):

🔍 System Status: ⚠️ DEGRADED MODE (Tier 2)
   - Vector Search: ❌ OFF (embedding model failed)
   - Search Quality: BASIC (40% accuracy, exact match only)

⚠️ Fix: Check embedding model installation

Configuration

Disable Skill:

# Environment variable
export MAMA_DISABLE_HOOKS=true

# Or in config file (~/.mama/config.json)
{
  "disable_hooks": true
}

Adjust Thresholds:

{
  "similarity_threshold": 0.7,
  "token_budget": 40,
  "rate_limit_ms": 1000
}

Note: similarity_threshold: 0.7 applies to explicit searches (/mama:search). The disabled pretooluse-hook.js uses a looser SIMILARITY_THRESHOLD = 0.6 (kept from its original contract-injection design). The active UserPromptSubmit hook delegates search to the MCP server, which uses its own default threshold. Hook thresholds are intentionally separate from the config value shown above.

When Claude Should Use This

✅ Automatic (no action needed):

• Context appears when relevant decisions exist
• Claude notices hints and can request details
• User sees transparent status (Tier 1/2)

❌ Don't explicitly invoke this skill:

• It's always-on (background process)
• Hooks handle triggering automatically
• Use /mama:search for explicit lookups

Technical Details

Hook Integration:

• UserPromptSubmit: Active (~150ms, no plugin-side script; handled by Claude Code host via MCP)
• SessionStart: scripts/sessionstart-hook.js (initialization)
• PreToolUse: scripts/pretooluse-hook.js (disabled, script retained)
• PostToolUse: scripts/posttooluse-hook.js (disabled, script retained)
• PreCompact: scripts/precompact-hook.js (decision preservation)

Performance:

• Hook latency: ~150ms (HTTP embedding server, model stays in memory)
• Cold start: ~1500ms (embedding model initialization, first session only)
• Warm: ~50ms (HTTP embedding request)
• Timeout: 1800ms (graceful degradation if exceeded)

Search Algorithm:

• Vector search: Transformers.js (3ms embedding)
• Hybrid scoring: 20% recency + 50% importance + 30% semantic
• Graph expansion: Follows supersedes edges
• Recency boost: Gaussian decay (30-day half-life)

Acceptance Criteria Mapping

• ✅ AC1: Declared in plugin.json, references hook outputs
• ✅ AC2: Similarity thresholds (70%) + token budgets (40 teaser / 250 full)
• ✅ AC3: Disable via config (MAMA_DISABLE_HOOKS)
• ✅ AC4: Status indicator (Tier 1/2, accuracy, fix instructions)
• ✅ AC5: Smoke test - fires during normal coding session

Example Output

User edits a file related to authentication:

Skill injects (via UserPromptSubmit hook):

💡 MAMA: 1 related
   • auth_strategy (90%, 2 days ago)
   /mama:search auth_strategy for full decision

🔍 System Status: ✅ Full Features Active (Tier 1)

Claude sees the hint and can:

1. Ignore (if not relevant)
2. Suggest /mama:search auth_strategy to user
3. Continue with general advice

For Developers

Testing:

# Test SessionStart hook (the only testable standalone hook)
node packages/claude-code-plugin/scripts/sessionstart-hook.js

# UserPromptSubmit hook is triggered automatically by Claude Code
# on every user message — no manual invocation needed.

Architecture:

User submits prompt
    ↓
UserPromptSubmit Hook (~150ms, 1800ms timeout)
    ↓
Decision search (generate embedding, search, score)
    ↓
Context injection to Claude (40-token teaser)
    ↓
Claude sees context

Key Principles

1. Lightweight: 40 tokens teaser format
2. Transparent: Always show tier status and latency
3. Non-intrusive: Hints, not walls of text
4. Opt-out: User control via config (MAMA_DISABLE_HOOKS)
5. Graceful degradation: Tier 2 fallback if embeddings unavailable
6. Multi-hook system: UserPromptSubmit (active) + SessionStart + PreCompact + PreToolUse/PostToolUse (disabled)

Related

• Story M3.2 (this skill)
• Story M2.2 (PreToolUse hook — disabled, scripts retained)
• Story M2.4 (Transparency banner)
• Architecture: docs/MAMA-ARCHITECTURE.md (Decision 4 - Hook Implementation)