MCP Memory Gateway

Local-first context engineering layer for AI agents. Persists decisions, surfaces prevention rules, and injects relevant history into every new session — so agents stop repeating the same mistakes.

Honest disclaimer: This is a context injection system, not RLHF. LLM weights are not updated by thumbs-up/down signals. What actually happens: feedback is validated, promoted to searchable memory, and recalled at session start so agents have project history they'd otherwise lose. That's genuinely valuable — but it's context engineering, not reinforcement learning.

Works with any MCP-compatible agent: Claude, Codex, Gemini, Amp, Cursor.

What It Actually Does

feedback signal → validate → promote to memory → vector index → prevention rules → recall at session start

1. Capture — capture_feedback MCP tool accepts signals with structured context (vague "thumbs down" is rejected)
2. Validate — Rubric engine gates promotion — requires specific failure descriptions, not vibes
3. Remember — Promoted memories stored in JSONL + LanceDB vectors for semantic search
4. Prevent — Repeated failures auto-generate prevention rules (the actual value — agents follow these when loaded)
5. Gate — Pre-action blocking via PreToolUse hooks — physically prevents known mistakes before they happen
6. Recall — recall tool injects relevant past context into current session (this is the mechanism that works)
7. Export — DPO/KTO pairs for optional downstream fine-tuning (separate from runtime behavior)
8. Bridge — JSONL file watcher auto-ingests signals from external sources (Amp plugins, hooks, scripts)

What Works vs. What Doesn't

| ✅ Actually works | ❌ Does not work | |---|---| | recall injects past context — agent reads and uses it | Thumbs up/down changing agent behavior mid-session | | remember persists decisions across sessions | LLM weight updates from feedback signals | | Prevention rules — followed when loaded at session start | Feedback stats improving agent performance automatically | | Pre-action gates — physically block known mistakes | "Learning curve" implying the agent itself learns | | Auto-promotion — 3+ failures become blocking rules | Agents self-correcting without context injection |

Quick Start

# Recommended: essential profile (5 high-ROI tools)
claude mcp add rlhf -- npx -y mcp-memory-gateway serve
codex mcp add rlhf -- npx -y mcp-memory-gateway serve
amp mcp add rlhf -- npx -y mcp-memory-gateway serve
gemini mcp add rlhf "npx -y mcp-memory-gateway serve"

# Or auto-detect all installed platforms
npx mcp-memory-gateway init

# Auto-wire PreToolUse hooks (blocks known mistakes before they happen)
npx mcp-memory-gateway init --agent claude-code
npx mcp-memory-gateway init --agent codex
npx mcp-memory-gateway init --agent gemini

Profiles: Set RLHF_MCP_PROFILE=essential for the lean 5-tool setup (recommended), or leave unset for the full 11-tool pipeline. See MCP Tools for details.

Pre-Action Gates (v0.7.1)

Gates are the enforcement layer. They physically block tool calls that match known failure patterns — no agent cooperation required.

Agent tries git push → PreToolUse hook fires → gates-engine checks rules → BLOCKED (no PR thread check)

How it works

1. init --agent claude-code auto-wires a PreToolUse hook into your agent settings
2. The hook pipes every Bash command through gates-engine.js
3. Gates match tool calls against regex patterns and block/warn
4. Auto-promotion: 3+ same-tag failures → auto-creates a warn gate. 5+ → upgrades to block.

Built-in gates

| Gate | Action | What it blocks | |------|--------|----------------| | push-without-thread-check | block | git push without checking PR review threads first | | package-lock-reset | block | git checkout <branch> -- package-lock.json | | force-push | block | git push --force / -f | | protected-branch-push | block | Direct push to develop/main/master | | env-file-edit | warn | Editing .env files |

Custom gates

Define your own in config/gates/custom.json:

{
  "version": 1,
  "gates": [
    {
      "id": "no-npm-audit-fix",
      "pattern": "npm audit fix --force",
      "action": "block",
      "message": "npm audit fix --force can break dependencies. Review manually."
    }
  ]
}

Gate satisfaction

Some gates have unless conditions. To satisfy a gate before pushing:

# Via MCP tool
satisfy_gate(gateId: "push-without-thread-check", evidence: "0/42 unresolved")

# Via CLI
node scripts/gate-satisfy.js --gate push-without-thread-check --evidence "0 unresolved"

Evidence expires after 5 minutes (configurable TTL).

Dashboard

npx mcp-memory-gateway dashboard

📊 RLHF Dashboard
══════════════════════════════════════════════
  Approval Rate    : 26% → 45% (7-day trend ↑)
  Total Signals    : 190 (15 positive, 43 negative)

🛡️ Gate Enforcement
  Active Gates     : 7 (4 manual, 3 auto-promoted)
  Actions Blocked  : 12 this week
  Actions Warned   : 8 this week
  Top Blocked      : push-without-thread-check (5×)

⚡ Prevention Impact
  Estimated Saves  : 3.2 hours
  Rules Active     : 5 prevention rules
  Last Promotion   : pr-review (2 days ago)

MCP Tools

Essential (high-ROI — start here)

These 5 tools deliver ~80% of the value. Use the essential profile for a lean setup:

RLHF_MCP_PROFILE=essential claude mcp add rlhf -- npx -y mcp-memory-gateway serve

| Tool | Description | |------|-------------| | capture_feedback | Accept up/down signal + context, validate, promote to memory | | recall | Vector-search past feedback and prevention rules for current task | | prevention_rules | Generate prevention rules from repeated mistakes | | feedback_stats | Approval rate, per-skill/tag breakdown, trend analysis | | feedback_summary | Human-readable recent feedback summary |

Full pipeline (advanced)

These tools support fine-tuning workflows, context engineering, and audit trails. Use the default profile to enable all tools:

| Tool | Description | When you need it | |------|-------------|------------------| | export_dpo_pairs | Build DPO preference pairs from promoted memories | Fine-tuning a model on your feedback | | construct_context_pack | Bounded context pack from contextfs | Custom retrieval for large projects | | evaluate_context_pack | Record context pack outcome (closes learning loop) | Measuring retrieval quality | | list_intents | Available action plan templates | Policy-gated workflows | | plan_intent | Generate execution plan with policy checkpoints | Policy-gated workflows | | context_provenance | Audit trail of context decisions | Debugging retrieval decisions | | satisfy_gate | Record evidence that a gate condition is met | Unblocking gated actions (e.g., PR thread check) | | gate_stats | Gate enforcement statistics (blocked/warned counts) | Monitoring gate effectiveness | | dashboard | Full RLHF dashboard (approval rate, gates, prevention) | Overview of system health |

CLI

npx mcp-memory-gateway init              # Scaffold .rlhf/ + configure MCP
npx mcp-memory-gateway init --agent X    # + auto-wire PreToolUse hooks (claude-code/codex/gemini)
npx mcp-memory-gateway init --wire-hooks # Wire hooks only (auto-detect agent)
npx mcp-memory-gateway serve             # Start MCP server (stdio) + watcher
npx mcp-memory-gateway dashboard         # Full RLHF dashboard with gate stats
npx mcp-memory-gateway gate-stats        # Gate enforcement statistics
npx mcp-memory-gateway status            # Learning curve dashboard
npx mcp-memory-gateway watch             # Watch .rlhf/ for external signals
npx mcp-memory-gateway capture           # Capture feedback via CLI
npx mcp-memory-gateway stats             # Analytics + Revenue-at-Risk
npx mcp-memory-gateway rules             # Generate prevention rules
npx mcp-memory-gateway export-dpo        # Export DPO training pairs
npx mcp-memory-gateway risk              # Train/query boosted risk scorer
npx mcp-memory-gateway self-heal         # Run self-healing diagnostics

JSONL File Watcher

The serve command automatically starts a background watcher that monitors feedback-log.jsonl for entries written by external sources (Amp plugins, shell hooks, CI scripts). These entries are routed through the full captureFeedback() pipeline — validation, memory promotion, vector indexing, and DPO eligibility.

# Standalone watcher
npx mcp-memory-gateway watch --source amp-plugin-bridge

# Process pending entries once and exit
npx mcp-memory-gateway watch --once

External sources write entries with a source field:

{"signal":"positive","context":"Agent fixed bug on first try","source":"amp-plugin-bridge","tags":["amp-ui-bridge"]}

The watcher tracks its position via .rlhf/.watcher-offset for crash-safe, idempotent processing.

Architecture

Value tiers

| Tier | Components | Impact | |------|-----------|--------| | Core (use now) | capture_feedback + recall + prevention_rules + enforcement hooks | Captures mistakes, prevents repeats, constrains behavior | | Gates (use now) | Pre-action gates + auto-promotion + satisfy_gate + dashboard | Physically blocks known mistakes before they happen | | Analytics (use now) | feedback_stats + feedback_summary + learning curve dashboard | Measures whether the agent is actually improving | | Fine-tuning (future) | DPO/KTO export, Thompson Sampling, context packs | Infrastructure for model fine-tuning — valuable when you have a training pipeline |

~30% of the codebase delivers ~80% of the runtime value. The rest is forward-looking infrastructure for teams that export training data.

Pipeline

Six-phase pipeline: Capture → Validate → Remember → Prevent → Gate → Export

Agent (Claude/Codex/Amp/Gemini)
  │
  ├── MCP tool call ──→ captureFeedback()
  ├── REST API ────────→ captureFeedback()
  ├── CLI ─────────────→ captureFeedback()
  └── External write ──→ JSONL ──→ Watcher ──→ captureFeedback()
                                        │
                                        ▼
                              ┌─────────────────┐
                              │  Full Pipeline   │
                              │  • Schema valid  │
                              │  • Rubric gate   │
                              │  • Memory promo  │
                              │  • Vector index  │
                              │  • Risk scoring  │
                              │  • RLAIF audit   │
                              │  • DPO eligible  │
                              └─────────────────┘

Agent Runner Contract

• WORKFLOW.md: scope, proof-of-work, hard stops, and done criteria for isolated agent runs
• .github/ISSUE_TEMPLATE/ready-for-agent.yml: bounded intake template for "Ready for Agent" tickets
• .github/pull_request_template.md: proof-first handoff format for PRs

💎 Pro Pack — Production Context Engineering Configs

Curated configuration pack for teams that want a faster production setup without inventing their own guardrails from scratch.

| What You Get | Description | |---|---| | Prevention Rules | 10 curated rules covering PR workflow, git hygiene, tool misuse, memory management | | Thompson Sampling Presets | 4 pre-tuned profiles: Conservative, Exploratory, Balanced, Strict | | Extended Constraints | 10 RLAIF self-audit constraints (vs 6 in free tier) | | Hook Templates | Ready-to-install Stop, UserPromptSubmit, PostToolUse hooks | | Reminder Templates | 8 production reminder templates with priority levels |

$9 on Gumroad →

Current pricing and traction policy: Commercial Truth

Support the Project

If MCP Memory Gateway saves you time, consider supporting development:

• ⭐ Star the repo
• ❤️ Sponsor on GitHub
• ☕ Buy Me a Coffee

License

MIT. See LICENSE.