@getmarrow/mcp

Memory and decision intelligence for MCP-compatible agents.

Marrow gives your agent a memory that compounds.

With @getmarrow/mcp, any MCP-compatible client can log intent before acting, inspect live loop state during work, and commit outcomes back to the hive when the work is done. That means your agent stops operating like an amnesiac and starts carrying forward real decision history.

Your agent stops repeating the same mistakes. It learns from prior sessions — and from the wider Marrow hive — through a clean MCP tool surface.

Start Here

For most agents and new users, start with the universal installer:

npx @getmarrow/install --yes

The installer detects your MCP client, agent instructions, Node project, and runtime surfaces, then wires the safest passive setup automatically. MCP clients can also call marrow_first_value to show the first five-minute proof payload directly inside the agent.

Use this MCP package directly when you want manual MCP server/hook setup for Claude Code, Claude Desktop, Cursor, or another MCP-compatible client. Use @getmarrow/sdk when you are building a custom Node/TypeScript integration in code.

Auto-Logging

Marrow auto-logs at three layers — transparent to your agent, invisible to you:

| Layer | How | Agent effort | |-------|-----|-------------| | Server-side | Every authenticated API call auto-logged as a decision | Zero | | SDK | marrow.think() / marrow.commit() — explicit control | Minimal | | MCP hooks | npx @getmarrow/mcp setup — PostToolUse + UserPromptSubmit hooks | Zero |

Passive mode in action: Run npx @getmarrow/mcp setup once. Every tool call your agent makes (Bash, file edits, MCP calls) is auto-logged in the background. Marrow intelligence is auto-injected into your agent's context. Fail-silent, 2-second timeout, never blocks your prompt.

Disable: MARROW_AUTO_HOOK=false. Debug: MARROW_HOOK_DEBUG=true.

Improvement Since Onboarding

marrow_dashboard and marrow_digest now return an improvement block comparing your agents' current performance against their day-1 baseline — a frozen snapshot of the first week of activity. Baseline captures automatically once an account reaches 7 days OR 20 decisions (whichever first).

Four measured deltas, all from real decision data:

• attempts_per_success — baseline week vs current week
• time_to_success_seconds — median think → successful commit
• drift_rate — % of decisions without a matching prior pattern
• success_rate — baseline vs current outcome fraction

Sample response:

{
  "improvement": {
    "status": "active",
    "days_since_baseline": 20,
    "decisions_since_baseline": 2124,
    "baseline_captured_at": "2026-04-23T15:07:41.919Z",
    "trigger_reason": "time_7d",
    "time_to_success_seconds": { "baseline": 244, "current": 24, "delta_pct": -90.16 }
  }
}

Accounts with <7 days of activity AND <20 decisions get an onboarding payload showing days/decisions until baseline fires. No heuristics, no estimates — every number comes from the agent's own decision history. Token-usage savings remain on the enterprise roadmap.

What's New in v3.9.29

v3.9.29 adds first-run value proof and stronger before-you-act prompt context for MCP agents:

• marrow_first_value returns the five-minute proof payload: capture status, runtime gate, first useful lesson, value proof, and the exact try-this-now prompt.
• UserPromptSubmit hook context now shows runtime interruption state, why Marrow is interrupting, required proof, and the quiet/noise policy.
• before_you_act_injection types now expose state, why_now, noise_policy, required_proof, missing_proof, and owner_approval_required.

Previous agent-native runtime behavior remains current:

• UserPromptSubmit hooks call the one-call runtime by default, so agents receive status, risk gate, lessons, proof requirements, and exact next action before acting.
• When Marrow marks before_you_act_injection.must_use_before_action=true, the prompt injection labels the Marrow action gate as required and tells the agent to stop if the lesson/proof cannot be applied.
• marrow_agent_runtime now includes structured before_you_act_injection data for fleet lessons and deployment playbooks.
• PostToolUse continues to close outcomes automatically for successful and failed tool calls.
• Degraded passive capture points agents to exact installer/MCP/SDK repair commands.

{
  "action": "deploy Cloudflare Worker to production",
  "type": "deploy",
  "surfaces": ["github", "cloudflare", "production"]
}

Full feature history, examples, and API reference live at getmarrow.ai/docs.

Human-Directed Attribution Status

The Marrow API supports privacy-preserving provenance fields on direct POST /v1/decisions calls: source_kind, human_directed, source_confidence, instruction_ref, instruction_hash, and source_meta. These fields classify instruction source class without identifying the human or storing raw prompts/PII.

Current MCP tools and passive hooks remain backward compatible and do not yet expose first-class provenance parameters or automatically mark prompts as human_directed. MCP provenance wiring is deferred; direct API users should follow the live API reference at https://getmarrow.ai/docs.

Agent Value Report

marrow_value_report lets MCP agents pull owner-ready proof of Marrow value without a dashboard. The existing passive hooks remain the default install path: PostToolUse logs meaningful tool outcomes and UserPromptSubmit injects relevant context plus decision briefs for risky prompts.

Value Report Tool

MCP tool: marrow_value_report.

Use it when an agent needs to explain whether Marrow is active, useful, and improving the fleet.

{
  "period": "7d",
  "agentId": "jarvis-agent"
}

The response includes summary, decisions, success rate, saves, active agents, top risks, recommendations, and improvement data. It does not expose raw action, context, or outcome text.

Passive Decision Briefs

Agents no longer need to remember to call marrow_decision_brief for common deploy, publish, merge, audit, patch, secret, or production prompts. They still can call it explicitly when they need stronger control.

Decision Brief Tool

MCP tool: marrow_decision_brief.

Use it before deploys, publishes, merges, audits, patches, secret changes, or production work. One call returns the agent's operating brief: risk, workflow/playbook steps, handoff requirements, freshness/source-of-truth checks, minimum verification checks, proof-pack fields, and next actions.

{
  "action": "publish SDK and MCP packages to npm and update docs",
  "type": "deploy",
  "role": "deploy",
  "surfaces": ["github", "npm", "docs", "production"]
}

Marrow returns aggregated prior failure categories only. It does not expose raw action, context, or outcome text from past decisions.

marrow_decision_brief is additive. It gives the pre-action operating brief, then the agent still logs intent with marrow_think/passive auto-logging and commits the verified outcome with marrow_commit.

Passive decision briefs are enabled by default. Set MARROW_PASSIVE_BRIEF=false to disable them, or MARROW_PASSIVE_BRIEF=always to brief every prompt.

Workflow Gate Tool

MCP tool: marrow_workflow_gate.

Use it before deploys, publishes, merges, DB migrations, key rotation, destructive commands, or production work.

{
  "action": "rotate Cloudflare deploy token and verify production",
  "riskTolerance": "medium",
  "requiresApproval": true
}

The response returns allow, warn, review_required, or block, plus prior lessons and deployment playbooks when available.

Passive value summaries are enabled by default in auto mode. Set MARROW_PASSIVE_VALUE_SUMMARY=false to disable them, or MARROW_PASSIVE_VALUE_SUMMARY=always to include them on every prompt hook.

Full feature history, examples, and API reference live at getmarrow.ai/docs.

Agent-Narrated Marrow Contribution

Marrow now tells the agent exactly what it contributed to each decision, so the agent can surface that contribution to the user in plain English — no dashboard required.

Three new fields:

• marrow_think returns marrow_contributed describing what intelligence Marrow surfaced for this decision (warnings consulted, hive patterns, similar decisions, workflow templates, loop detection, collective insight).
• marrow_commit returns marrow_contributed describing concrete signals on the commit itself (pattern reused, warning avoided, workflow step).
• marrow_session_end returns session_summary aggregating Marrow's contribution across the session, plus a one-line narrative for the agent to surface as it wraps up.

Each object includes has_signal: boolean — when true, the agent narrates Marrow's role in 1 sentence; when false, it stays quiet. The built-in marrow-always-on system prompt now instructs agents on tone and timing for these narrations.

Sample think response:

{
  "decision_id": "...",
  "intelligence": { "...": "..." },
  "marrow_contributed": {
    "warnings_consulted": 2,
    "hive_patterns_surfaced": 12,
    "similar_decisions_found": 8,
    "workflow_templates_available": 1,
    "loop_detected": false,
    "collective_intelligence": true,
    "team_context_present": false,
    "has_signal": true
  }
}

The user installed Marrow to make their agent better. They should hear, in plain English, what Marrow actually did. Their agent's reply IS the dashboard.

Agent-Narrated Milestones

marrow_commit returns a narrative field. When a milestone fires (first commit, baseline capture, decision 100/500/1000/5000, weekly recap), the backend returns a human-readable string the agent relays to the user. Otherwise it returns null.

{
  "committed": true,
  "narrative": "Baseline captured. Your first-week averages: 42s per task, 1.3 attempts per success."
}

Narratives are aggregated metrics only — no user data, no decision content, no heuristics.

Velocity Metrics

marrow_dashboard and marrow_digest include three measured velocity metrics:

• attempts_per_success — avg decisions before an agent lands a success
• time_to_success_seconds — median seconds from marrow_think to successful marrow_commit
• drift_rate — % of decisions that didn't link to a known pattern

Each reports {current, previous, delta_pct, direction} so operators see whether agents are trending toward or away from improvement.

All metrics are computed from real decision data — no estimates, no heuristics.

Passive Mode

Running npx @getmarrow/mcp setup installs a PostToolUse hook into .claude/settings.json. After setup, every tool call your agent makes (Bash, file edits, MCP calls) is auto-logged to Marrow in the background — no agent discipline required.

Disable via: MARROW_AUTO_HOOK=false

For troubleshooting hook behavior, set MARROW_HOOK_DEBUG=true to re-enable one-line stderr diagnostics.

PostToolUse now marks automatic outcome closure explicitly. Successful tool calls commit success, tool errors commit failure, and /v1/agent/status can tell the agent whether the outcome hook is missing. If status is degraded, run npx @getmarrow/install --yes or npx @getmarrow/mcp setup to repair passive capture.

Operator visibility + auto-intelligence tools.

Operator Tools

marrow_dashboard

Operator dashboard in one call. Account health, top failures, workflow status, recent activity, Marrow's saves metric. Now includes velocity metrics (see v3.3.0 section above).

marrow_digest

Periodic summary with success rate trend vs previous period. Optional period parameter (default 7d). Now includes velocity summary (see v3.3.0 section above).

marrow_agent_status

Agent-native proof that Marrow is connected and collecting useful signal. Optional period and agentId parameters; when omitted, the tool filters by MARROW_AGENT_ID. Returns active, state, signals, quality, proof, and next_actions without exposing raw decision text.

marrow_decision_brief

One pre-action call before meaningful work. Returns risk, workflow, handoff, freshness, quality, role_playbook, failure_alerts, proof_pack, source_of_truth, fleet_reliability, and next_actions.

Use this before risky work so the agent does not need to stitch together multiple backend calls. It does not replace outcome logging.

marrow_session_end

Explicitly end a session and optionally auto-commit any open decision. Prevents orphaned decisions.

marrow_accept_detected

Convert a detected recurring pattern into an enforced workflow. Pattern ID comes from orient() response's suggested_workflows.

Intelligence Fields in marrow_think Response

marrow_think surfaces three additional fields when the backend provides them:

• onboarding_hint — contextual tip for new accounts
• intelligence.collective — anonymized insights aggregated across all Marrow accounts (k-anonymity ≥5 accounts per insight)
• intelligence.team_context — recent decisions from other sessions in the same account, so multi-agent teams stay aware of each other's work

Available Templates

24 pre-built workflow templates across 8 industries. Browse via marrow_list_templates and install with marrow_install_template.

• Insurance (4): claims-triage, fraud-review, underwriting-decision, complaint-escalation
• Healthcare (4): patient-triage, clinical-documentation, prior-authorization, coding-audit
• E-commerce (3): order-fulfillment, refund-approval, return-processing
• Legal (3): contract-review, case-triage, document-discovery
• SaaS (6): code-review-deploy, incident-response, feature-rollout, ticket-triage, escalation-flow, lead-qualify
• Fintech (2): etl-pipeline, approval-flow
• Media (1): content-publish
• Enterprise (1): change-management

Full catalog with descriptions: https://getmarrow.ai/docs/#template-marketplace

marrow_list_templates({ industry: 'insurance' })
marrow_install_template({ slug: 'claims-triage' })

Claude Code Compatibility

Marrow MCP works natively with Claude Code. The server runs as a long-running process and handles the full MCP protocol correctly.

One-Command Agent Setup

Inject Marrow instructions directly into your project's CLAUDE.md:

npx @getmarrow/mcp setup

After setup, your agent uses Marrow automatically every session, and Claude Code PostToolUse hooks auto-log tool calls in the background — no human prompting required.

Auto-Enroll by Default

The marrow-always-on prompt is served to all MCP clients automatically. Set MARROW_AUTO_ENROLL=false to opt out.

Security Hardening

• Input validation — all URL path parameters are sanitized to prevent path traversal
• SSRF protection — MARROW_BASE_URL must use HTTPS
• Crash protection — malformed JSON on stdin no longer kills the server
• Error handling — proper error logging throughout
• HTTP status checking — API errors return clear messages

Auto-Warn on Orient

The marrow_orient tool now accepts autoWarn: true and warns you BEFORE you start a task that recently failed:

{
  "name": "marrow_orient",
  "arguments": {
    "autoWarn": true,
    "task": "Fix authentication error"
  }
}

Response includes warnings:

⚠️ HIGH: This task type failed 4x with approach='retry-without-fix'.
         Try approach='apply-patch-first' (89% success rate)

Loop Detection on Think

The marrow_think tool now accepts checkLoop: true and detects if you're about to retry a failed approach:

{
  "name": "marrow_think",
  "arguments": {
    "action": "Retry auth with method='internal'",
    "checkLoop": true
  }
}

Response includes loop warnings:

🚨 LOOP DETECTED: You're retrying a failed approach.
   Previous failure: 'retry-without-fix' approach not supported.
   Suggested: Use 'apply-patch-first' approach instead.

Rate Limiting

• marrow_orient: 30 requests/minute per account
• marrow_think: 60 requests/minute per account
• Automatic 429 responses when limit exceeded

Enhanced PII Protection

• Automatic stripping of emails, phone numbers, API keys from all responses
• Applied to recentLessons, warnings, and outcome fields
• Deep object stripping for complex data structures

The Problem

Most agents still operate with shallow memory.

They might keep a short context window, maybe write a note or two, then lose the important part:

• what they were trying to do
• what they actually did
• whether it worked
• what pattern that should teach the next run

That creates a familiar failure loop:

• the same mistakes repeat
• work gets marked done without structured outcome memory
• agents drift between sessions
• hosts have no clean way to inspect whether the work loop is actually closed

Marrow fixes this.

Through MCP, your agent can:

• orient at session start
• log intent before meaningful action
• inspect loop state before handoff or completion
• commit outcomes back to memory cleanly

How It Works

Marrow exposes a simple operating loop through MCP:

orient -> think -> act -> check -> commit

That gives agents an actual memory discipline:

• orient → pick up recent lessons and current loop state
• think → log intent and receive decision intelligence
• act → perform the meaningful work
• check → inspect whether the loop is still open or missing something
• commit → log the outcome and close the loop

The value compounds with use. Each decision your agent logs makes the hive smarter — failure rates drop, patterns emerge, and the next session starts with real intelligence instead of a blank slate. Teams running multiple agents see this compound fastest, but even a single agent builds meaningful history within a few sessions.

Install

Default path for new users:

npx @getmarrow/install --yes

Manual MCP path for MCP-native clients:

Quick Start (Claude Code)

# 1. Add the MCP server
claude mcp add marrow -e MARROW_API_KEY="$MARROW_API_KEY" -- npx @getmarrow/mcp

# 2. Set up auto-enrollment (agent uses Marrow automatically)
npx @getmarrow/mcp setup

That's it. Your agent will use Marrow automatically in every session.

Manual Setup

Run it directly with npx:

MARROW_API_KEY="$MARROW_API_KEY" npx @getmarrow/mcp

Or register it in your MCP client config using environment variables or your client's secret storage. Avoid putting API keys in command arguments or static config files.

MCP Tools

Core Loop Tools

marrow_orient

Call this first at session start. Returns failure warnings from your history so you avoid known mistakes immediately.

marrow_think

Log intent before meaningful action. Returns pattern insights, similar past decisions, and a recommended next step.

marrow_commit

Log the outcome after acting. Closes the decision loop.

marrow_run

Zero-ceremony wrapper. Handles orient → think → commit in a single call.

marrow_auto

Fire-and-forget logging. Pass what you're about to do (and optionally the outcome). Marrow handles everything in the background.

Memory Management Tools

marrow_list_memories

List memories with optional filters:

• status — Filter by status (active, outdated, deleted)
• query — Search query
• limit — Max results
• agentId — Include memories shared with this agent

marrow_get_memory

Get a single memory by ID.

marrow_update_memory

Update memory text, tags, or metadata.

marrow_delete_memory

Soft delete a memory.

marrow_mark_outdated

Mark a memory as outdated.

marrow_supersede_memory

Atomically replace a memory with a new version.

marrow_share_memory

Share a memory with specific agents.

marrow_export_memories

Export memories to JSON or CSV format.

marrow_import_memories

Import memories with merge (dedup) or replace mode.

marrow_retrieve_memories

Full-text search with filters:

• query — Search query (required)
• limit — Max results
• from / to — Date range (ISO-8601)
• tags — Comma-separated tags
• source — Source filter
• status — Status filter
• shared — Include shared memories

Query Tools

marrow_ask

Query the collective hive in plain English. Ask about failure patterns, what worked, what broke, or get a recommendation.

marrow_status

Check Marrow platform health and status.

Claude Code Config

claude mcp add marrow -e MARROW_API_KEY="$MARROW_API_KEY" -- npx @getmarrow/mcp

Claude Desktop Config

{
  "mcpServers": {
    "marrow": {
      "command": "npx",
      "args": ["@getmarrow/mcp"],
      "env": {
        "MARROW_API_KEY": "${MARROW_API_KEY}"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MARROW_API_KEY | Yes | Your API key from getmarrow.ai. Prefer environment variables or client secret storage. | | MARROW_BASE_URL | No | Custom API URL (default: https://api.getmarrow.ai). Must use HTTPS. | | MARROW_SESSION_ID | No | Session identifier for multi-agent setups | | MARROW_FLEET_AGENT_ID | No | Agent identifier sent as X-Marrow-Agent-Id for fleet attribution | | MARROW_AUTO_ENROLL | No | Auto-enrollment prompt (default: true). Set to false to disable. | | MARROW_AUTO_HOOK | No | PostToolUse auto-logging kill switch. Set to false to disable the hook without editing settings. | | MARROW_PASSIVE_BRIEF | No | Passive decision-brief mode for the prompt hook. Defaults to auto; set false to disable or always to brief every prompt. | | MARROW_HOOK_DEBUG | No | When set to true, write-side and prompt-context hooks emit one-line stderr diagnostics. | | MARROW_CONTEXT_HOOK_DEBUG | No | When set to true, only the UserPromptSubmit context hook emits one-line stderr diagnostics. |

The Always-On Prompt

Marrow includes a built-in prompt called marrow-always-on that instructs agents to use Marrow automatically. It's served by default — no configuration needed.

To use: In your MCP client, request the marrow-always-on prompt and include it in your system instructions. For Claude Code, run npx @getmarrow/mcp setup instead — it handles this automatically.

Why This Matters

Without Marrow:

• Agents repeat the same failures session after session
• Successful patterns get lost when the context window clears
• There's no structured trail of what was tried and what worked
• Every new session starts from zero

With Marrow:

• Failure patterns surface before you repeat them
• Successful outcomes compound across sessions
• Every decision has a trail: intent → action → outcome
• The hive gets smarter with every logged decision

Marrow tells you what went wrong last time before you do it again.

License

MIT

Related Packages

• @getmarrow/install — Default front door for new users. Detects local agent/runtime surfaces, writes safe config, runs self-tests, and reports first-value proof.
• @getmarrow/sdk — TypeScript/Node.js SDK for programmatic access to Marrow. Use this for custom agent integrations outside of MCP.

📖 Full API reference with all endpoints: https://getmarrow.ai/docs/#api-reference