@getmarrow/mcp 2.3.3 → 2.3.5

package/README.md

@@ -1,26 +1,95 @@
 # @getmarrow/mcp
 
-> **Your go-to memory provider for all agents, for any AI model.**
+> **Memory and decision intelligence for MCP-compatible 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.
+Marrow gives your agent a memory that compounds.
 
-**One tool call. Your agent stops starting from zero.**
+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.**
+
+---
+
+## What's New in v2.3.4
+
+### Loop enforcement is now part of the MCP workflow
+
+This release adds the MCP-side loop workflow so agents can operate through a real decision cycle instead of dumping disconnected thoughts into memory.
+
+New / updated tools:
+- `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 loop state mid-session before handoff or completion
+- `marrow_commit` / `commit` — close the loop cleanly with outcome logging
+
+What changed in practice:
+- session-local loop state 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`)
+- the MCP package now lines up properly with the newer SDK loop-enforcement model
 
 ---
 
 ## Install
 
+Run it directly with `npx`:
+
 ```bash
-npm install -g @getmarrow/mcp
+npx @getmarrow/mcp
+```
+
+Or register it in your MCP client config.
+
+---
+
+## 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
 ```
 
-Get your API key at [getmarrow.ai](https://getmarrow.ai)
+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 result is memory that is useful during execution, not just after the fact.
 
 ---
 
-## Setup — Claude Desktop
+## Quick Start
 
-Add to your `claude_desktop_config.json`:
+### Claude Desktop
 
 ```json
 {
@@ -29,259 +98,197 @@ Add to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["@getmarrow/mcp"],
       "env": {
-        "MARROW_API_KEY": "your_key_from_getmarrow.ai"
+        "MARROW_API_KEY": "mrw_your_key_here"
       }
     }
   }
 }
 ```
 
-Restart Claude. That's it — Marrow is now available as a tool in every conversation.
+### Generic MCP host
 
----
+If your MCP host supports command-based servers, point it at:
 
-## 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
-```
+- command: `npx`
+- args: `@getmarrow/mcp`
+- env: `MARROW_API_KEY=...`
 
 ---
 
-## 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.
-
----
+## When to Use MCP vs SDK
 
-## Quick Start Pattern
+Use **`@getmarrow/mcp`** when:
+- your agent already speaks MCP
+- you want Marrow exposed as tools
+- you want loop state visible during the session
+- you want hosts/orchestrators to inspect whether work is ready for completion
 
-```
-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
-```
+Use **`@getmarrow/sdk`** when:
+- you are integrating Marrow directly into application/runtime code
+- you want wrapper-level enforcement around deploy, publish, outbound sends, or external writes
+- you want programmatic control through `beforeAction()`, `afterAction()`, `wrap()`, and `check()`
 
-**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.
+In short:
+- **MCP** = tool-driven integration for agents
+- **SDK** = code-level integration for runtimes and apps
 
 ---
 
 ## Tools
 
-### `marrow_orient` — ⚡ Call this first
+### `marrow_orient` / `orient`
+Start the session with Marrow context.
 
-**Call at the start of every session, before any other tool.** Returns failure warnings from your hive history so you avoid known mistakes immediately.
+Returns:
+- loop state
+- recommended next step
+- recent lessons (when available)
+- canonical session-start nudge
 
-```json
-{
-  "taskType": "implementation"  // optional: filter to specific task type
-}
-```
+Typical use:
+- first meaningful step in a session
+- before planning or execution begins
 
-**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
-}
-```
+### `marrow_think` / `think`
+Log intent and get decision intelligence back.
 
-If `shouldPause` is true, query your lessons before proceeding. If `warnings` is empty, you're clear.
+Returns:
+- `decision_id`
+- pattern intelligence
+- loop metadata
+- warnings / next-step guidance
 
----
+Typical use:
+- before meaningful action
+- before deploy / publish / send / external write work
+- when shifting from planning into execution
 
-### `marrow_think` — The core tool
+### `marrow_check` / `check`
+Inspect the current loop state.
 
-Call this before every significant action. Returns collective intelligence from the hive.
+Returns:
+- whether the loop is still open
+- current recommended next step
+- whether the session looks ready for completion
+- warnings if outcome/context is still missing
 
-**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
-}
-```
+Typical use:
+- before handoff
+- before “done”
+- before outbound updates after meaningful work
 
-**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"
-}
-```
+### `marrow_commit` / `commit`
+Commit outcome to the hive and close the loop.
+
+Returns:
+- committed / accepted state
+- updated loop state
+- recommended next step after closure
 
-**Example prompt to Claude:**
+Typical use:
+- after meaningful work finishes
+- after a deploy / publish / send / write succeeds or fails
+- before a clean handoff or completion
 
-> 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.
+### `patterns`
+Inspect accumulated decision patterns.
 
-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
+Typical use:
+- identifying repeated failures
+- learning what tends to work for a task type
+- orienting around recent drift or recurring mistakes
 
 ---
 
-### `marrow_commit` — Explicit commit
+## Example Workflow
 
-Commit an outcome explicitly when you need more control. `marrow_think` auto-commits on the next call, so this is optional.
+### Example: deployment task
 
-**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"
-}
-```
+1. Call `marrow_orient`
+2. Call `marrow_think` with something like:
+   - action: `Deploy auth refactor to staging`
+   - type: `implementation`
+3. Perform the deploy
+4. Call `marrow_check`
+5. Call `marrow_commit` with outcome:
+   - success: `true`
+   - outcome: `Staging deploy passed smoke tests`
+
+This gives the next session or next agent real context:
+- what was attempted
+- whether it worked
+- what patterns Marrow saw around it
+- whether the loop was actually closed
 
 ---
 
-### `marrow_status` — Platform health
+## What Your Agent Gets Back
 
-Check your agent's current performance across the hive.
+Marrow MCP tools expose more than a raw ID.
 
-**Returns:**
-```json
-{
-  "success_rate": 0.87,
-  "decision_velocity": 142,
-  "patterns_discovered": 23,
-  "hive_consensus": 0.91
-}
-```
+Depending on the tool, agents can receive:
+- recent lessons
+- similar past outcomes
+- warnings about recurring failure patterns
+- current loop state
+- recommended next step
+- session guidance to close the loop cleanly
 
----
+That makes the MCP server useful during execution, not just as a logging endpoint.
 
-## 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`.
-```
+## Why Marrow Through MCP?
 
-**What happens in practice:**
+Without Marrow:
+- the agent starts every session half-amnesiac
+- failures repeat because there is no durable decision trail
+- completion gets declared without structured outcome memory
+- hosts cannot easily inspect whether the work loop is actually closed
 
-User: *"Refactor the payment service to add retry logic"*
+With Marrow MCP:
+- the agent can orient before acting
+- meaningful work can be tracked in-session
+- hosts can inspect loop state before completion or handoff
+- outcomes become structured memory instead of vague summaries
+- memory becomes operational, not decorative
 
-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.
+## Session Hint
 
----
+At session start, Marrow nudges clients with the canonical reminder:
 
-## Why Marrow for MCP?
+> Tip: log plans, decisions, and outcomes to Marrow so your agent improves over time.
 
-- **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
+For agents that have not logged any decisions yet this session, Marrow can also steer them toward `marrow_think` before acting.
 
 ---
 
-## Get Started
-
-```bash
-npm install -g @getmarrow/mcp
-```
+## Security / Key Handling
 
-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
+Use environment variables for your API key.
 
-**Your agent inherits the experience of every agent that came before it.**
+Correct:
+- `MARROW_API_KEY` passed through MCP host config or runtime environment
 
----
+Do not:
+- hardcode production API keys into source files
+- commit real keys into config
+- paste secrets into README examples
 
-*Compatible with Claude Desktop, Claude API, and any MCP-compatible framework.*
+Placeholder examples like `mrw_your_key_here` are documentation only.
 
 ---
 
-## Privacy & Data
+## Get an API Key
 
-**What Marrow collects:**
-- The `action` string and `type` you pass to `marrow_think` and `marrow_commit`
-- The `outcome` you report — used to train collective intelligence
-- Decision metadata: timestamps, success/failure, confidence scores
+Sign up at [getmarrow.ai](https://getmarrow.ai)
 
-**What Marrow does NOT collect:**
-- No PII (names, emails, user IDs, IP addresses)
-- No conversation content or message history
-- No code, credentials, or file contents
-- No agent identity beyond your anonymous API key hash
-
-**How data is anonymized:**
-- All inputs are stripped of PII patterns before storage (emails, phone numbers, UUIDs matching user ID formats, IP addresses)
-- Your API key is stored as a SHA-256 hash — never in plaintext
-- Hive intelligence is aggregated across agents — individual decisions are never exposed to other users
-- You can opt out of hive contribution at any time by setting `contributeToHive: false` in your MCP config
+---
 
-**Hive data model:**
-- Decisions you log contribute anonymously to collective patterns
-- No one can trace a pattern back to your agent or your account
-- Enterprise plans include private org hive mode — your data never leaves your org
+## Related Package
 
-**Data retention:**
-- Decision data: 30 days on Free tier, 90 days on Pro, unlimited on Enterprise
-- You can delete all your data at any time via the dashboard or API
+If you want direct runtime integration instead of MCP tools:
 
-For full details, see our [Privacy Policy](https://getmarrow.ai/privacy).
+- [`@getmarrow/sdk`](https://www.npmjs.com/package/@getmarrow/sdk)

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;
+}