The MCP Memory Gateway is a context engineering server that captures agent feedback, enforces pre-action gates to block known mistakes, and injects relevant past context into AI coding agent sessions for improved reliability and continuity.
Feedback & Memory
Capture feedback (
capture_feedback,capture_memory_feedback): Record up/down signals with context, reasoning, and rubric scores; vague feedback is rejected with a clarification promptRecall past context (
recall,commerce_recall): Vector-search relevant past feedback, memories, and prevention rules for the current taskView summaries & analytics (
feedback_summary,feedback_stats,dashboard): Approval rate trends, gate enforcement stats, and prevention impact overviewsGenerate prevention rules (
prevention_rules,get_reliability_rules): Auto-generate blocking rules from repeated failure patterns
Pre-Action Gates & Safety
Satisfy gates (
satisfy_gate): Record evidence that a gate condition is met (e.g., PR threads checked) with a 5-minute TTLGate statistics (
gate_stats): See blocked/warned counts and top triggered gates
Session Continuity
Session handoff (
session_handoff): Write a primer capturing git state, last task, next step, and blockersSession primer (
session_primer): Restore context at session start from the most recent handoff
Workflow Planning & Diagnosis
List & plan intents (
list_intents,plan_intent): View available workflows and generate checkpointed execution plans with policy gatesDiagnose failures (
diagnose_failure): Root-cause analysis for failed or suspect workflow stepsBootstrap agents (
bootstrap_internal_agent): Normalize GitHub/Slack/Linear triggers into startup context with recall packs and worktree sandboxesDelegation handoffs (
start_handoff,complete_handoff): Manage sequential agent delegation with verification outcomes
Context Engineering
Context packs (
construct_context_pack,evaluate_context_pack): Build and evaluate bounded context packs for large projects, closing the retrieval learning loopContext provenance (
context_provenance): Audit trail of recent context and retrieval decisionsEstimate uncertainty (
estimate_uncertainty): Bayesian uncertainty estimates for risky tags before acting
Business Metrics
Business metrics (
get_business_metrics): Retrieve Revenue, Conversion, and Customer metrics from the Semantic LayerSemantic entity descriptions (
describe_semantic_entity,describe_reliability_entity): Canonical definitions and state of Customer, Revenue, or Funnel entities
Export & Fine-Tuning
Export DPO pairs (
export_dpo_pairs): Build preference pairs from promoted memories for model fine-tuningExport Databricks bundle (
export_databricks_bundle): Export RLHF logs and proof artifacts as a Databricks-ready analytics bundleGenerate skills (
generate_skill): Auto-generate Claude skill files (SKILL.md) from clustered failure patterns
MCP Memory Gateway
Pre-action gates that physically block AI coding agents from repeating known mistakes. Capture feedback, auto-promote repeated failures into prevention rules, and enforce them via PreToolUse hooks. This is a reliability layer for one sharp agent, without another planner or swarm.
Honest disclaimer: this is not RLHF weight training. It is context engineering plus enforcement. Feedback becomes searchable memory, prevention rules, and gates that block known-bad actions before they execute.
Works with Claude Code, Codex, Gemini, Amp, Cursor, OpenCode, and any MCP-compatible agent. Verification evidence lives in docs/VERIFICATION_EVIDENCE.md.
Why it exists
Most memory tools only help an agent remember. MCP Memory Gateway also enforces.
recallinjects the right context at session start.search_lessonsshows promoted lessons plus the corrective action, linked rules, and linked gates.search_rlhfsearches raw RLHF state across feedback logs, ContextFS memory, and prevention rules.Pre-action gates physically block tool calls that match known failure patterns.
Session handoff and primer keep continuity across sessions without adding an extra orchestrator.
Free and self-hosted users can invoke search_lessons directly through MCP, and via the CLI with npx mcp-memory-gateway lessons.
Tech Stack
Core runtime
Node.js
>=18.18.0Module system: CommonJS CLI/server runtime
Primary entry points: CLI, MCP stdio server, authenticated HTTP API, OpenAPI adapters
Interfaces
MCP stdio: adapters/mcp/server-stdio.js
HTTP API: src/api/server.js
OpenAPI surfaces: openapi/openapi.yaml, adapters/chatgpt/openapi.yaml
CLI:
npx mcp-memory-gateway ...
Storage and retrieval
Local memory: JSONL logs in
.claude/memory/feedbackor.rlhf/*Context assembly: ContextFS packs and provenance logs
Default retrieval path: deterministic filesystem search over JSONL + ContextFS
Semantic/vector lane: LanceDB + Apache Arrow + local embeddings via Hugging Face Transformers
Enforcement and automation
PreToolUse enforcement: scripts/gates-engine.js
Hook wiring:
init --agent claude-code|codex|geminiBrowser automation / ops:
playwright-coreSocial analytics store:
better-sqlite3
Billing and hosting
Billing: Stripe
Hosted API / landing page: Railway
Worker lane: Cloudflare Workers in
workers/
Quick Start
# Install MCP server for your agent
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 supported agents
npx mcp-memory-gateway init
# Auto-wire PreToolUse hooks
npx mcp-memory-gateway init --agent claude-code
npx mcp-memory-gateway init --agent codex
npx mcp-memory-gateway init --agent gemini
# Health and core workflows
npx mcp-memory-gateway doctor
npx mcp-memory-gateway lessons
npx mcp-memory-gateway dashboardWhat Actually Works
Actually works | Does not work |
| Thumbs up/down changing model weights |
| Agents magically remembering what happened last session |
| Feedback stats automatically improving behavior by themselves |
Pre-action gates block known-bad tool calls before execution | Agents self-correcting without context injection or gates |
Auto-promotion turns repeated failures into warn/block rules | Calling this “RLHF” in the strict training sense |
Rejection ledger shows why vague feedback was rejected | Vague signals silently helping the system |
How it works
Capture structured feedback with context, tags, and optional reasoning traces.
Validate signals and reject vague or unsafe entries before promotion.
Promote useful feedback into searchable memory and principle/rule material.
Auto-generate prevention rules from repeated failures.
Enforce those rules through PreToolUse hooks before risky tool calls run.
Expose the full state through MCP tools, the API, dashboards, and verification reports.
The serve command also runs a background watcher for external JSONL writes from hooks, CI, or companion tools.
Core Tools
Essential profile
These tools are the shortest path to value:
Tool | Purpose |
| Accept up/down signal + context, validate, promote to memory |
| Recall relevant past failures and rules for the current task |
| Search promoted lessons with corrective action, rules, and gates |
| Search raw RLHF state across feedback logs, ContextFS, and rules |
| Generate prevention rules from repeated mistakes |
| Inspect promotion rate, active gates, and rejection ledger |
| Approval rate and failure-domain summary |
| Human-readable recent feedback summary |
| Bayesian uncertainty estimate for risky tags |
Use the lean install when you want recall, gates, and lesson search first:
RLHF_MCP_PROFILE=essential claude mcp add rlhf -- npx -y mcp-memory-gateway serveFree and self-hosted users can invoke search_lessons directly through MCP to inspect corrective action per lesson. For broader retrieval across feedback logs, ContextFS memory, and prevention rules, use search_rlhf through MCP or the authenticated GET /v1/search API.
Dispatch profile
For phone-safe remote ops, use the read-only dispatch surface:
RLHF_MCP_PROFILE=dispatch claude mcp add rlhf -- npx -y mcp-memory-gateway serve
npx mcp-memory-gateway dispatchGuide: docs/guides/dispatch-ops.md
Pre-Action Gates
Gates are the enforcement layer. They do not ask the agent to cooperate.
Agent tries git push
→ PreToolUse hook fires
→ gates-engine checks rules
→ BLOCKED (for example: no PR thread check)Built-in examples include:
push-without-thread-checkpackage-lock-resetforce-pushprotected-branch-pushenv-file-edit
Define custom gates in config/gates/custom.json.
Architecture
Pipeline: Capture → Validate → Remember → Distill → Prevent → Gate → Export
For deeper packaging and topology details:
Operator Contract
If you are running autonomous agents against this repo or another repo that uses this workflow, keep these entry points visible:
WORKFLOW.md: scope, proof-of-work, hard stops, and done criteria for agent runs
.github/ISSUE_TEMPLATE/ready-for-agent.yml: bounded intake template for ready-for-agent work
.github/pull_request_template.md: proof-first PR handoff format
Commercial and Proof Surfaces
License
MIT. See LICENSE.