# @getmarrow/mcp

> **Memory and decision intelligence for MCP-compatible agents.**

![npm](https://img.shields.io/npm/v/@getmarrow/mcp)
![npm](https://img.shields.io/npm/dw/@getmarrow/mcp)
![npm bundle size](https://img.shields.io/bundlephobia/minzip/@getmarrow/mcp)
![GitHub](https://img.shields.io/github/license/getmarrow/marrow-mcp)
![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue)
![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)

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 Marrow 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 authorized fleet memory plus sanitized shared signals — through a clean MCP tool surface.**

## Trust and Data Boundaries

Marrow is tenant-aware by design. Private account, fleet, memory, workflow, and proof-pack data stays scoped to the authenticated account and authorized agent-bound keys. Shared/hive learning uses visibility-controlled, sanitized aggregate signals; it is not raw cross-customer decision sharing.

For business pilots, review the live trust notes before production rollout: https://getmarrow.ai/docs#trust-boundaries

---

## Start Here

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

```bash
npx @getmarrow/install --yes
```

The installer detects your MCP client, agent instructions, Node project, and runtime surfaces, then wires the safest passive setup automatically.
It now also includes a governed runner: `npx @getmarrow/install run --agent <agent-id> -- <command>`, which gives MCP and non-MCP agents the same pre-action Marrow risk gate and automatic outcome closure for existing shell, deploy, publish, merge, and migration commands.
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 |
| Governed runner | `npx @getmarrow/install run --agent <id> -- <command>` — pre-action gate + outcome proof around existing commands | Minimal |
| 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:

```json
{
  "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. Token-value proof is also available now: MCP agents can call `marrow_model_usage` or attach `model_usage` to `marrow_commit` so Marrow reports observed model calls, tokens, estimated savings, trend direction, and top models without storing raw prompts or completions.

---

## What's New in v3.9.37

v3.9.37 adds MCP token-value proof status parity.

- `marrow_model_usage` records compact provider/model token counts through `/v1/agent/model-usage`.
- `marrow_commit` accepts optional `model_usage` and returns `token_value_signal` from the backend.
- `marrow_runtime_status` calls `/v1/agent/status?fast=1` for live passive hook, token-capture, outcome-closure, and exact repair-command diagnostics.
- Token usage data is counts and labels only: provider, model, input/output/cached/total tokens, cost, latency, outcome linkage, and optional saved-token estimates.
- Do not send raw prompts, completions, tool logs, secrets, or customer content.

## What's New in v3.9.33

v3.9.33 adds MCP tools for adaptive governance recommendations and explicit policy profiles, while keeping the enterprise readiness contract documented for business pilots.

- `marrow_mode_recommend` returns an explainable `passive`, `pilot`, or `enforce` recommendation for the current project/workflow.
- `marrow_policy_profiles` lists saved account policy profiles, including the default business starter profile.
- `marrow_create_policy_profile` creates or updates explicit rules such as local=passive, staging=pilot, production deploys=enforce.
- `marrow_assign_project_policy_profile` binds an active profile to a project key so future resolves use it automatically.
- `marrow_policy_resolve` resolves the current workflow mode from saved policy profiles, falling back to recommendation.
- Marrow does not silently auto-switch modes. The agent/user must accept or override the recommendation.
- MCP agents can call `GET /v1/agent/enterprise-readiness?agents=20` when an owner asks whether Marrow is ready for a fleet rollout.
- The response is owner-safe and covers tenant isolation, data boundaries, fail behavior, policy controls, scale proof, and a 30-day pilot package.
- The source-of-truth docs include the enterprise trust and scale readiness page at [getmarrow.ai/docs](https://getmarrow.ai/docs/).

```json
{
  "project": {
    "name": "agent-api",
    "type": "node",
    "frameworks": ["edge-service"],
    "signals": ["package_json", "platform_config", "github_actions"]
  },
  "workflow": {
    "action": "deploy production service",
    "type": "deploy",
    "environment": "production"
  }
}
```

## What's New in v3.9.31

v3.9.31 is a docs-sync release. It keeps npm and GitHub README copy aligned with Marrow's current backend-first runtime contract and proof/gate enforcement loop. Runtime behavior is unchanged from v3.9.30.

v3.9.30 brings MCP tools and passive prompt hooks up to Marrow's current backend-first runtime contract and proof/gate enforcement loop:

- UserPromptSubmit context now prefers `intervention.agent_copy`, so agents see the strongest `before you act` instruction before legacy runtime text.
- `marrow_agent_runtime` types now expose `intervention`, `runtime_contract`, `risk_gate_event`, and `behavior_governance` for `/v1/agent/runtime`.
- MCP now supports the backend-first contracts `marrow.before-action-intervention.v1` and `agent-runtime-contract.v3`.
- `marrow_commit` exposes `proof`, `gate_receipt_id`, `action`, `surfaces`, and `auto_gate` fields for gated work.
- MCP commit paths preserve the same fleet agent identity used by `marrow_think`, preventing agent-bound key commit mismatches.
- `marrow_run` and `marrow_auto` attach standard proof packs when they close outcomes automatically.

First-run value proof remains current:

- `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 still shows runtime interruption state, why Marrow is interrupting, required proof, and the quiet/noise policy.
- Legacy `before_you_act_injection` types still 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.

```json
{
  "action": "deploy edge service to production",
  "type": "deploy",
  "surfaces": ["github", "deployment-platform", "production"]
}
```

Full feature history, examples, and API reference live at [getmarrow.ai/docs](https://getmarrow.ai/docs/).

---

### Gated Commit Proof

For risky actions, call `marrow_agent_runtime` before acting and pass the receipt plus proof into `marrow_commit`:

```json
{
  "decision_id": "...",
  "success": true,
  "outcome": "Deploy succeeded and production smoke passed",
  "gate_receipt_id": "runtime.gate_receipt.id",
  "proof": {
    "summary": "Production deploy completed",
    "checks": ["tests passed", "smoke passed"],
    "outcome": "success",
    "blockers": "none",
    "commits_prs_shas": "abc123",
    "rollback_target": "previous release version",
    "handoff_result_file": "/tmp/marrow-handoffs/release/result.md",
    "deployment_and_smoke": "production smoke passed"
  }
}
```

If you provide `action` and omit `gate_receipt_id`, `marrow_commit` can fetch a matching runtime gate receipt automatically.

## 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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "action": "rotate deployment 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](https://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, shared 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:

```json
{
  "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`.

```json
{
  "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.

MCP write paths now keep a bounded in-process retry queue for temporary network/server failures on `think` and `commit`. Auth failures, policy blocks, proof-pack failures, and validation errors are not retried blindly; status returns exact failure reasons and fix commands instead.

**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`, `failure_reasons`, `agent_warnings`, `diagnostics`, and `next_actions` without exposing raw decision text. Common failure reasons include `missing_key`, `invalid_key`, `wrong_agent_id`, `network_blocked`, and `proof_required`.

### 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](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`:

```bash
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:

```json
{
  "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:

```json
{
  "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:

```text
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:

```bash
npx @getmarrow/install --yes
```

Manual MCP path for MCP-native clients:

### Quick Start (Claude Code)

```bash
# 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`:

```bash
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. Can include `model_usage` so Marrow returns token-value proof after work completes.

#### `marrow_model_usage`
Record compact model token/cost/latency counts when your harness exposes them. This powers token savings proof in `/v1/agent/value/proof` and owner reports.

#### `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

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

## Claude Desktop Config

```json
{
  "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. MCP also auto-loads `.marrow/env`, `.marrow/env.local`, `.env`, `.env.local`, `~/.marrow/env`, and `~/.marrow/env.local`. |
| `MARROW_KEY` | No | Alias accepted by MCP for fleet runners and secret managers. |
| `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. |

If hooks are installed but no decisions are being logged, run:

```bash
npx @getmarrow/install doctor
```

Deep doctor with harmless write/outcome verification:

```bash
MARROW_API_KEY=mrw_live_... npx @getmarrow/install doctor --self-test
```

Healthy output should confirm `key valid: yes`, `account active: yes`, `agent identity accepted: yes`, `write test event: passed`, and `outcome closed: passed`. If it fails, Marrow returns the exact reason and fix command.

Stable project-local key file:

```bash
mkdir -p .marrow
printf "MARROW_API_KEY=mrw_live_...\\n" > .marrow/env
chmod 600 .marrow/env
npx @getmarrow/mcp setup
```

---

## 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](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@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](https://getmarrow.ai/docs/#api-reference)