@getmarrow/mcp 2.3.4 → 2.3.5

package/README.md

@@ -1,54 +1,294 @@
-# marrow-mcp
+# @getmarrow/mcp
 
-MCP server for [Marrow](https://getmarrow.ai) — decision intelligence for AI agents.
+> **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.**
+
+---
 
 ## What's New in v2.3.4
 
-### Loop-enforcement tools for real agent operating discipline
+### Loop enforcement is now part of the MCP workflow
 
-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.
+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 tool flow:
+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 current loop state and recommended next step mid-session
+- `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 now persists across MCP tool calls
+- 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`)
-- package is publish-ready as `@getmarrow/mcp`
+- `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
+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
+```
+
+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.
+
+---
 
 ## Quick Start
 
+### Claude Desktop
+
 ```json
-// claude_desktop_config.json
 {
   "mcpServers": {
     "marrow": {
       "command": "npx",
       "args": ["@getmarrow/mcp"],
-      "env": { "MARROW_API_KEY": "mrw_your_key_here" }
+      "env": {
+        "MARROW_API_KEY": "mrw_your_key_here"
+      }
     }
   }
 }
 ```
 
+### Generic MCP host
+
+If your MCP host supports command-based servers, point it at:
+
+- command: `npx`
+- args: `@getmarrow/mcp`
+- env: `MARROW_API_KEY=...`
+
+---
+
+## When to Use MCP vs SDK
+
+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
+
+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()`
+
+In short:
+- **MCP** = tool-driven integration for agents
+- **SDK** = code-level integration for runtimes and apps
+
+---
+
 ## Tools
 
-- **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_orient` / `orient`
+Start the session with Marrow context.
+
+Returns:
+- loop state
+- recommended next step
+- recent lessons (when available)
+- canonical session-start nudge
+
+Typical use:
+- first meaningful step in a session
+- before planning or execution begins
+
+### `marrow_think` / `think`
+Log intent and get decision intelligence back.
 
-## Session hint
+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_check` / `check`
+Inspect the current loop state.
+
+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
+
+Typical use:
+- before handoff
+- before “done”
+- before outbound updates after meaningful work
+
+### `marrow_commit` / `commit`
+Commit outcome to the hive and close the loop.
+
+Returns:
+- committed / accepted state
+- updated loop state
+- recommended next step after closure
+
+Typical use:
+- after meaningful work finishes
+- after a deploy / publish / send / write succeeds or fails
+- before a clean handoff or completion
+
+### `patterns`
+Inspect accumulated decision patterns.
+
+Typical use:
+- identifying repeated failures
+- learning what tends to work for a task type
+- orienting around recent drift or recurring mistakes
+
+---
+
+## Example Workflow
+
+### Example: deployment task
+
+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
+
+---
+
+## What Your Agent Gets Back
+
+Marrow MCP tools expose more than a raw ID.
+
+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.
+
+---
+
+## Why Marrow Through MCP?
+
+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
+
+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
+
+---
+
+## Session Hint
 
 At session start, Marrow nudges clients with the canonical reminder:
 
 > Tip: log plans, decisions, and outcomes to Marrow so your agent improves over time.
 
-## Get an API key
+For agents that have not logged any decisions yet this session, Marrow can also steer them toward `marrow_think` before acting.
+
+---
+
+## Security / Key Handling
+
+Use environment variables for your API key.
+
+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
+
+Placeholder examples like `mrw_your_key_here` are documentation only.
+
+---
+
+## Get an API Key
 
 Sign up at [getmarrow.ai](https://getmarrow.ai)
+
+---
+
+## Related Package
+
+If you want direct runtime integration instead of MCP tools:
+
+- [`@getmarrow/sdk`](https://www.npmjs.com/package/@getmarrow/sdk)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/mcp",
-  "version": "2.3.4",
+  "version": "2.3.5",
   "description": "MCP server for Marrow — decision intelligence for AI agents",
   "main": "dist/index.js",
   "bin": {