@getmarrow/mcp 2.0.0 → 2.0.1

package/README.md

@@ -1,16 +1,26 @@
 # @getmarrow/mcp
 
-**Your go-to memory provider for all agents, for any AI model.**
+> **Your go-to memory provider for all agents, for any AI model.**
 
-Add Marrow to any Claude agent in 30 seconds. The hive makes every decision smarter.
+Give Claude (or any MCP-compatible agent) a memory that compounds across every session, every user, every run. Marrow connects your agent to a hive of collective intelligence — what worked, what failed, patterns discovered across thousands of agent runs.
+
+**One tool call. Your agent stops starting from zero.**
+
+---
 
 ## Install
 
 ```bash
-npm install @getmarrow/mcp
+npm install -g @getmarrow/mcp
 ```
 
-## Claude Config
+Get your API key at [getmarrow.ai](https://getmarrow.ai)
+
+---
+
+## Setup — Claude Desktop
+
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
@@ -18,23 +28,176 @@ npm install @getmarrow/mcp
     "marrow": {
       "command": "npx",
       "args": ["@getmarrow/mcp"],
-      "env": { "MARROW_API_KEY": "mrw_your_key" }
+      "env": {
+        "MARROW_API_KEY": "mrw_your_api_key"
+      }
     }
   }
 }
 ```
 
+Restart Claude. That's it — Marrow is now available as a tool in every conversation.
+
+---
+
+## Setup — Any MCP-Compatible Agent
+
+```bash
+export MARROW_API_KEY=mrw_your_api_key
+npx @getmarrow/mcp
+# Listens on stdin, outputs JSON-RPC on stdout
+# Drop into any MCP framework
+```
+
+---
+
+## How It Works
+
+Your agent calls `marrow_think` before acting. Marrow queries the hive — collective intelligence from every agent that's ever done something similar — and returns what worked, what patterns emerged, what playbooks exist. When your agent is done, that experience gets committed back to the hive. Every agent gets smarter. Forever.
+
+---
+
 ## Tools
 
-### `marrow_think`
-Call before every significant action. Returns collective intelligence from the hive — what worked before, discovered patterns, proven playbooks. Pass `previous_outcome` to commit your last action and keep the hive learning.
+### `marrow_think` — The core tool
+
+Call this before every significant action. Returns collective intelligence from the hive.
+
+**Input:**
+```json
+{
+  "action": "What the agent is about to do",
+  "type": "implementation | security | architecture | process | general",
+  "previous_outcome": "What happened last time (auto-commits previous session)",
+  "previous_success": true
+}
+```
+
+**Returns:**
+```json
+{
+  "decision_id": "save this for the next call",
+  "intelligence": {
+    "similar": [
+      { "outcome": "Used incremental approach. Shipped in 2 days, 0 rollbacks.", "confidence": 0.91 }
+    ],
+    "patterns": [
+      { "pattern": "Breaking changes require feature flags. Direct deploys cause 3x more incidents.", "frequency": 84 }
+    ],
+    "templates": [
+      { "steps": ["Plan", "Spec", "Build", "Test", "Deploy"], "success_rate": 0.89 }
+    ],
+    "success_rate": 0.87,
+    "priority_score": 0.7,
+    "insight": "Pattern detected: security tasks trending in hive this week"
+  },
+  "stream_url": "/v1/stream?format=sse"
+}
+```
+
+**Example prompt to Claude:**
+
+> Before starting this refactor, call `marrow_think` with action "Refactoring auth module to support OAuth 2.0" and type "implementation". Use the intelligence to guide your approach.
+
+Claude will automatically:
+1. Call `marrow_think`
+2. Read what worked for other agents doing similar refactors
+3. Apply those patterns to its approach
+4. On the next `marrow_think` call, commit this outcome back to the hive
+
+---
+
+### `marrow_commit` — Explicit commit
+
+Commit an outcome explicitly when you need more control. `marrow_think` auto-commits on the next call, so this is optional.
+
+**Input:**
+```json
+{
+  "decision_id": "from previous marrow_think",
+  "success": true,
+  "outcome": "Auth refactor complete. OAuth 2.0 working. Zero breaking changes. 2 day turnaround.",
+  "caused_by": "optional: previous decision_id to link causally"
+}
+```
+
+---
+
+### `marrow_status` — Platform health
+
+Check your agent's current performance across the hive.
+
+**Returns:**
+```json
+{
+  "success_rate": 0.87,
+  "decision_velocity": 142,
+  "patterns_discovered": 23,
+  "hive_consensus": 0.91
+}
+```
+
+---
+
+## Real Example — Claude Coding Agent
+
+**System prompt addition:**
+```
+Before starting any significant task, call marrow_think with a description of what you're about to do.
+After completing a task, the next marrow_think call will automatically record the outcome.
+Use the intelligence returned to guide your approach — especially `similar` and `patterns`.
+```
+
+**What happens in practice:**
+
+User: *"Refactor the payment service to add retry logic"*
+
+Claude calls `marrow_think`:
+```json
+{ "action": "Adding retry logic to payment service", "type": "implementation" }
+```
+
+Marrow returns:
+```json
+{
+  "intelligence": {
+    "similar": [
+      { "outcome": "Exponential backoff with jitter. 3 retries max. Idempotency key required. Zero double-charges in 6 months.", "confidence": 0.96 }
+    ],
+    "patterns": [
+      { "pattern": "Retry without idempotency key causes duplicate transactions in 23% of cases", "frequency": 156 }
+    ]
+  }
+}
+```
+
+Claude now knows — from thousands of other agents' experience — exactly what to do and what to avoid. Without Marrow, it would have guessed.
+
+---
+
+## Why Marrow for MCP?
+
+- **Zero setup friction** — one config entry, works instantly
+- **Model agnostic** — Claude, GPT, Gemini, any MCP-compatible model
+- **Compounds automatically** — every session adds to the hive, no manual curation
+- **Private by default** — your agent's decisions are anonymized before entering the hive
+- **Persistent across sessions** — memory survives context resets, model upgrades, new conversations
+
+---
+
+## Get Started
+
+```bash
+npm install -g @getmarrow/mcp
+```
 
-### `marrow_commit`
-Explicit commit when you need more control. `marrow_think` auto-commits on the next call.
+1. Get your API key at [getmarrow.ai](https://getmarrow.ai)
+2. Add the MCP server config above
+3. Tell your agent to call `marrow_think` before acting
+4. Watch collective intelligence flow in from the first call
 
-### `marrow_status`
-Full platform health — your success rate, hive activity, patterns detected.
+**Your agent inherits the experience of every agent that came before it.**
 
-## Get a Key
+---
 
-[portal.getmarrow.ai](https://portal.getmarrow.ai)
+*Compatible with Claude Desktop, Claude API, and any MCP-compatible framework.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/mcp",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Your go-to memory provider for all agents, for any AI model.",
   "bin": {
     "marrow-mcp": "dist/cli.js"