@getmarrow/mcp 2.3.2 → 2.3.4

package/README.md

@@ -1,255 +1,54 @@
-# @getmarrow/mcp
+# marrow-mcp
 
-> **Your go-to memory provider for all agents, for any AI model.**
+MCP server for [Marrow](https://getmarrow.ai) — decision intelligence for AI agents.
 
-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.
+## What's New in v2.3.4
 
-**One tool call. Your agent stops starting from zero.**
+### Loop-enforcement tools for real agent operating discipline
 
----
+This release adds the MCP surface for Marrow's live loop workflow so agents can orient, think, act, check, and commit inside a single session instead of treating memory as an afterthought.
 
-## Install
+New/updated tool flow:
+- `marrow_orient` / `orient` — start the session with loop state, recent lessons, and a recommended next step
+- `marrow_think` / `think` — log intent and get pattern intelligence + loop metadata back
+- `marrow_check` / `check` — inspect current loop state and recommended next step mid-session
+- `marrow_commit` / `commit` — close the loop cleanly with outcome logging
 
-```bash
-npm install -g @getmarrow/mcp
-```
-
-Get your API key at [getmarrow.ai](https://getmarrow.ai)
-
----
+What changed in practice:
+- session-local loop state now persists across MCP tool calls
+- agents get a canonical session-start nudge toward `marrow_think`
+- commit now correctly returns a closed-loop state (`done` / `outcome_logged`)
+- package is publish-ready as `@getmarrow/mcp`
 
-## Setup — Claude Desktop
-
-Add to your `claude_desktop_config.json`:
+## Quick Start
 
 ```json
+// claude_desktop_config.json
 {
   "mcpServers": {
     "marrow": {
       "command": "npx",
       "args": ["@getmarrow/mcp"],
-      "env": {
-        "MARROW_API_KEY": "your_key_from_getmarrow.ai"
-      }
+      "env": { "MARROW_API_KEY": "mrw_your_key_here" }
     }
   }
 }
 ```
 
-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=your_key_from_getmarrow.ai  # get your key at getmarrow.ai/dashboard
-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.
-
----
-
-## Quick Start Pattern
-
-```
-Session start → marrow_orient()   ← reads from hive, surfaces warnings
-Before each action → marrow_think()  ← queries + opens memory session  
-After each action → marrow_commit()  ← writes result back to hive
-```
-
-**orient() is what makes Marrow compound.** Without it, you're writing to a database no one reads. With it, your agent automatically avoids mistakes it's made before.
-
----
-
 ## Tools
 
-### `marrow_orient` — ⚡ Call this first
-
-**Call at the start of every session, before any other tool.** Returns failure warnings from your hive history so you avoid known mistakes immediately.
-
-```json
-{
-  "taskType": "implementation"  // optional: filter to specific task type
-}
-```
-
-**Response:**
-```json
-{
-  "warnings": [
-    {
-      "type": "process",
-      "failureRate": 0.26,
-      "message": "process has 26% failure rate over 27 decisions — review lessons before acting"
-    }
-  ],
-  "shouldPause": false  // true if any failure rate >40% — stop and query lessons first
-}
-```
-
-If `shouldPause` is true, query your lessons before proceeding. If `warnings` is empty, you're clear.
-
----
+- **marrow_orient** / `orient` — Start the session with loop state, recent lessons, and a recommended next step
+- **marrow_think** / `think` — Log a decision and get pattern intelligence, loop metadata, and useful next-step guidance back
+- **marrow_commit** / `commit` — Commit task outcome to the hive and close the loop
+- **marrow_check** / `check` — Inspect current loop state for this MCP session
+- **patterns** — Get accumulated decision patterns
 
-### `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 }
-    ],
-    "similar_count": 3,
-    "patterns": [
-      { "pattern_id": "a1b2c3", "decision_type": "implementation", "frequency": 84, "confidence": 0.9 }
-    ],
-    "patterns_count": 2,
-    "templates": [
-      { "steps": ["Plan", "Spec", "Build", "Test", "Deploy"], "success_rate": 0.89 }
-    ],
-    "success_rate": 0.87,
-    "priority_score": 0.7,
-    "insight": "Workflow gap detected — barvis_audit missing after build",
-    "insights": [
-      {
-        "type": "workflow_gap",
-        "summary": "audit not logged after build (3 consecutive times)",
-        "action": "Run audit before reporting done",
-        "severity": "critical",
-        "count": 3
-      }
-    ],
-    "cluster_id": "818df2fa-6365-49f6-b478-bc3dcb748469"
-  },
-  "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
-```
+## Session hint
 
-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
+At session start, Marrow nudges clients with the canonical reminder:
 
-**Your agent inherits the experience of every agent that came before it.**
+> Tip: log plans, decisions, and outcomes to Marrow so your agent improves over time.
 
----
+## Get an API key
 
-*Compatible with Claude Desktop, Claude API, and any MCP-compatible framework.*
+Sign up at [getmarrow.ai](https://getmarrow.ai)

package/dist/client.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Marrow API client — thin HTTP wrapper
+ */
+export type MarrowLoopRecommendation = 'orient' | 'think' | 'act' | 'commit' | 'done';
+export interface MarrowLoopState {
+    orientedAt: string | null;
+    lastThinkAt: string | null;
+    lastOutcomeAt: string | null;
+    hasIntentLog: boolean;
+    hasOutcomeLog: boolean;
+    actionCountSinceLastThink: number;
+    externalActionCountSinceLastThink: number;
+    lastDecisionId: string | null;
+    pendingDecisionId: string | null;
+    recommendedNext: MarrowLoopRecommendation;
+    loopState: 'idle' | 'oriented' | 'intent_logged' | 'acting' | 'outcome_logged';
+    message: string | null;
+    hints: string[];
+}
+export declare class MarrowClient {
+    private apiKey;
+    private baseUrl;
+    private currentDecisionId;
+    private loopState;
+    constructor();
+    check(): {
+        ok: boolean;
+        recommendedNext: MarrowLoopRecommendation;
+        state: {
+            hints: string[];
+            orientedAt: string | null;
+            lastThinkAt: string | null;
+            lastOutcomeAt: string | null;
+            hasIntentLog: boolean;
+            hasOutcomeLog: boolean;
+            actionCountSinceLastThink: number;
+            externalActionCountSinceLastThink: number;
+            lastDecisionId: string | null;
+            pendingDecisionId: string | null;
+            recommendedNext: MarrowLoopRecommendation;
+            loopState: "idle" | "oriented" | "intent_logged" | "acting" | "outcome_logged";
+            message: string | null;
+        };
+        warnings: string[];
+    };
+    orient(params?: {
+        task_type?: string;
+    }): Promise<Record<string, unknown>>;
+    think(params: {
+        action: string;
+        type: string;
+        previous_decision_id?: string;
+        previous_success?: boolean;
+        previous_outcome?: string;
+    }): Promise<Record<string, unknown>>;
+    commit(params: {
+        decision_id: string;
+        success: boolean;
+        outcome: string;
+    }): Promise<Record<string, unknown>>;
+    recordAction(meta?: {
+        external?: boolean;
+    }): {
+        ok: boolean;
+        recommendedNext: MarrowLoopRecommendation;
+        state: {
+            hints: string[];
+            orientedAt: string | null;
+            lastThinkAt: string | null;
+            lastOutcomeAt: string | null;
+            hasIntentLog: boolean;
+            hasOutcomeLog: boolean;
+            actionCountSinceLastThink: number;
+            externalActionCountSinceLastThink: number;
+            lastDecisionId: string | null;
+            pendingDecisionId: string | null;
+            recommendedNext: MarrowLoopRecommendation;
+            loopState: "idle" | "oriented" | "intent_logged" | "acting" | "outcome_logged";
+            message: string | null;
+        };
+        warnings: string[];
+    };
+    patterns(): Promise<Record<string, unknown>[]>;
+    private post;
+    private get;
+}

package/dist/client.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Marrow API client — thin HTTP wrapper
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarrowClient = void 0;
+const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
+const SESSION_START_HINT = 'Tip: log plans, decisions, and outcomes to Marrow so your agent improves over time.';
+const POST_ORIENT_NUDGE = 'You have not logged any decisions yet this session. Before acting, call marrow_think.';
+const PRE_EXIT_REMINDER = 'Before ending the session, log the outcome to Marrow so the loop closes cleanly.';
+function nowIso() {
+    return new Date().toISOString();
+}
+class MarrowClient {
+    apiKey;
+    baseUrl;
+    currentDecisionId = null;
+    loopState = {
+        orientedAt: null,
+        lastThinkAt: null,
+        lastOutcomeAt: null,
+        hasIntentLog: false,
+        hasOutcomeLog: false,
+        actionCountSinceLastThink: 0,
+        externalActionCountSinceLastThink: 0,
+        lastDecisionId: null,
+        pendingDecisionId: null,
+        recommendedNext: 'orient',
+        loopState: 'idle',
+        message: SESSION_START_HINT,
+        hints: [SESSION_START_HINT],
+    };
+    constructor() {
+        const key = process.env.MARROW_API_KEY;
+        if (!key) {
+            throw new Error('MARROW_API_KEY environment variable is required');
+        }
+        this.apiKey = key;
+        this.baseUrl = process.env.MARROW_BASE_URL || DEFAULT_BASE_URL;
+    }
+    check() {
+        if (!this.loopState.orientedAt) {
+            this.loopState.recommendedNext = 'orient';
+            this.loopState.loopState = 'idle';
+            this.loopState.message = SESSION_START_HINT;
+            this.loopState.hints = [SESSION_START_HINT];
+        }
+        else if (this.loopState.hasOutcomeLog) {
+            this.loopState.recommendedNext = 'done';
+            this.loopState.loopState = 'outcome_logged';
+            this.loopState.message = 'Loop closed. Ready for the next task.';
+            this.loopState.hints = ['Loop closed. Ready for the next task.'];
+        }
+        else if (!this.loopState.hasIntentLog) {
+            this.loopState.recommendedNext = 'think';
+            this.loopState.loopState = 'oriented';
+            this.loopState.message = POST_ORIENT_NUDGE;
+            this.loopState.hints = [SESSION_START_HINT, POST_ORIENT_NUDGE];
+        }
+        else if (!this.loopState.hasOutcomeLog && this.loopState.actionCountSinceLastThink > 0) {
+            this.loopState.recommendedNext = 'commit';
+            this.loopState.loopState = 'acting';
+            this.loopState.message = PRE_EXIT_REMINDER;
+            this.loopState.hints = [PRE_EXIT_REMINDER];
+        }
+        else if (!this.loopState.hasOutcomeLog) {
+            this.loopState.recommendedNext = 'act';
+            this.loopState.loopState = 'intent_logged';
+            this.loopState.message = 'Intent logged. Act, then log the outcome.';
+            this.loopState.hints = ['Intent logged. Act, then log the outcome.'];
+        }
+        else {
+            this.loopState.recommendedNext = 'done';
+            this.loopState.loopState = 'outcome_logged';
+            this.loopState.message = 'Loop closed. Ready for the next task.';
+            this.loopState.hints = ['Loop closed. Ready for the next task.'];
+        }
+        return {
+            ok: true,
+            recommendedNext: this.loopState.recommendedNext,
+            state: { ...this.loopState, hints: [...this.loopState.hints] },
+            warnings: [...this.loopState.hints],
+        };
+    }
+    async orient(params) {
+        const patterns = await this.get(`/v1/agent/patterns${params?.task_type ? `?type=${encodeURIComponent(params.task_type)}` : ''}`);
+        let lessons = [];
+        try {
+            const lessonRes = await this.get('/v1/agent/think/history?type=lesson&limit=5');
+            lessons = (lessonRes.data
+                || lessonRes.items
+                || lessonRes.decisions
+                || []);
+        }
+        catch {
+            lessons = [];
+        }
+        this.loopState.orientedAt = nowIso();
+        const loop = this.check();
+        const failurePatterns = (patterns.data?.failure_patterns
+            || patterns.failure_patterns
+            || []);
+        return {
+            session_start_hint: SESSION_START_HINT,
+            nudge: this.loopState.hasIntentLog ? null : POST_ORIENT_NUDGE,
+            recommended_next: loop.recommendedNext,
+            loop: loop.state,
+            warnings: failurePatterns
+                .filter((item) => Number(item.failureRate || item.failure_rate || 0) > 0.15)
+                .map((item) => ({
+                type: String(item.decisionType || item.decision_type || 'general'),
+                failure_rate: Number(item.failureRate || item.failure_rate || 0),
+                message: `${String(item.decisionType || item.decision_type || 'general')} has ${Math.round(Number(item.failureRate || item.failure_rate || 0) * 100)}% failure rate over ${Number(item.count || 0)} decisions — check lessons before proceeding`,
+            })),
+            lessons: lessons.map((lesson) => ({
+                summary: String(lesson.action || lesson.summary || ''),
+                severity: 'info',
+            })),
+            text: [SESSION_START_HINT, POST_ORIENT_NUDGE, `Recommended next step: ${loop.recommendedNext}.`].join(' '),
+        };
+    }
+    async think(params) {
+        if (params.previous_decision_id !== undefined && !params.previous_decision_id.trim()) {
+            throw new Error('decision_id must be a non-empty string');
+        }
+        const result = await this.post('/v1/agent/think', params);
+        const data = result.data || result;
+        const intelligence = data.intelligence || {};
+        const decisionId = typeof data.decision_id === 'string' && data.decision_id.trim()
+            ? data.decision_id
+            : null;
+        this.loopState.orientedAt = this.loopState.orientedAt || nowIso();
+        this.loopState.lastThinkAt = nowIso();
+        this.loopState.hasIntentLog = true;
+        this.loopState.hasOutcomeLog = false;
+        this.loopState.actionCountSinceLastThink = 0;
+        this.loopState.externalActionCountSinceLastThink = 0;
+        this.currentDecisionId = decisionId;
+        this.loopState.pendingDecisionId = decisionId;
+        this.loopState.lastDecisionId = decisionId;
+        const loop = this.check();
+        return {
+            ...result,
+            data: {
+                ...data,
+                accepted_as: 'intent',
+                warnings: loop.warnings,
+                recommended_next: loop.recommendedNext,
+                loop: loop.state,
+                summary: [
+                    'Intent logged to Marrow.',
+                    intelligence.insight ? `Pattern hint: ${String(intelligence.insight)}` : null,
+                    `Recommended next step: ${loop.recommendedNext}.`,
+                ].filter(Boolean).join(' '),
+            },
+        };
+    }
+    async commit(params) {
+        const decisionId = params.decision_id.trim();
+        if (!decisionId) {
+            throw new Error('decision_id must be a non-empty string');
+        }
+        if (!this.currentDecisionId) {
+            throw new Error('No active decision. Call marrow_think first.');
+        }
+        if (decisionId !== this.currentDecisionId) {
+            throw new Error(`decision_id mismatch: expected ${this.currentDecisionId}`);
+        }
+        const result = await this.post('/v1/agent/commit', {
+            ...params,
+            decision_id: decisionId,
+        });
+        const data = result.data || result;
+        this.loopState.lastOutcomeAt = nowIso();
+        this.loopState.hasIntentLog = false;
+        this.loopState.hasOutcomeLog = true;
+        this.loopState.actionCountSinceLastThink = 0;
+        this.loopState.externalActionCountSinceLastThink = 0;
+        this.loopState.pendingDecisionId = null;
+        this.loopState.lastDecisionId = decisionId;
+        this.currentDecisionId = null;
+        const loop = this.check();
+        return {
+            ...result,
+            data: {
+                ...data,
+                accepted_as: 'outcome',
+                recommended_next: loop.recommendedNext,
+                loop: loop.state,
+                summary: 'Outcome logged to Marrow. Loop closed.',
+            },
+        };
+    }
+    recordAction(meta) {
+        this.loopState.actionCountSinceLastThink += 1;
+        if (meta?.external)
+            this.loopState.externalActionCountSinceLastThink += 1;
+        return this.check();
+    }
+    async patterns() {
+        const res = await this.get('/v1/patterns');
+        return res?.data || [];
+    }
+    async post(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = (await res.text()).slice(0, 200);
+            throw new Error(`Marrow API error (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async get(path) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+        });
+        if (!res.ok) {
+            const text = (await res.text()).slice(0, 200);
+            throw new Error(`Marrow API error (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+}
+exports.MarrowClient = MarrowClient;