@getmarrow/mcp 2.8.0 → 2.9.1

package/README.md

@@ -10,51 +10,45 @@ With `@getmarrow/mcp`, any MCP-compatible client can log intent before acting, i
 
 ---
 
-## What's New in v2.6.0
-
-- **Portability audit** — zero workspace coupling confirmed. No `OPENCLAW_*` env vars, no private paths, no agent-name assumptions.
-- **Session identity** — `MARROW_SESSION_ID` and `X-Marrow-Session-Id` header for multi-agent/multi-user setups
-- **`marrow-always-on` prompt** — install once in your MCP client for automatic orient → think → commit behavior
-- **TypeScript clean** — `tsc --noEmit` zero errors
-
-## What's New in v2.5.0
-
-- **`marrow_run` tool** — single-call memory logging. Pass description + success + outcome. Marrow handles orient → think → commit internally.
-- **`MARROW_SESSION_ID` env var** — tag all requests with a session identifier
-- **Auto-commit on session close** — if session ends with an open loop, Marrow commits automatically
-- **Orient warnings in think response** — startup warnings now surface in `marrow_think` intelligence, not just stderr
-
----
-
-## 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
-npx @getmarrow/mcp
-```
-
-Or register it in your MCP client config.
+## What's New in v2.8.0
+
+**Backend API Enhancements** — New MCP tools for memory lifecycle management:
+
+### Cross-Agent Memory Sharing
+Share memories across agents in your account:
+- `marrow_share_memory` — Share a memory with specific agents
+- Memories shared with your agents automatically appear in `marrow_list_memories`
+
+### Memory Export/Import
+Backup and restore memories:
+- `marrow_export_memories` — Export to JSON or CSV format
+- `marrow_import_memories` — Import with merge (dedup) or replace mode
+
+### Advanced FTS Filters
+Precision search in `marrow_retrieve_memories`:
+- `from` / `to` — Date range filters
+- `tags` — Filter by tags (AND logic)
+- `source` — Filter by source (e.g., `session_bootstrap`, `think`)
+- `status` — Filter by status (`active`, `outdated`, `deleted`)
+
+### New MCP Tools
+- `marrow_list_memories` — List memories with pagination
+- `marrow_get_memory` — Get single memory by ID
+- `marrow_update_memory` — Update memory text, tags, or metadata
+- `marrow_mark_outdated` — Mark memory as outdated
+- `marrow_supersede_memory` — Atomically replace memory with new version
+- `marrow_delete_memory` — Soft delete memory
+- `marrow_export_memories` — Export to JSON or CSV
+- `marrow_import_memories` — Import memories
+- `marrow_share_memory` — Share with agents
+- `marrow_retrieve_memories` — FTS search with filters
+
+### Security Hardening
+- Account isolation enforced (no cross-account leakage)
+- Agent ID validation on all tools
+- Audit logging for export/import operations
+- Rate limiting on export (5/hour)
+- SHA-256 dedup on import
 
 ---
 
@@ -99,290 +93,152 @@ That gives agents an actual memory discipline:
 - **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
+## Install
 
-### Claude Desktop
+Run it directly with `npx`:
 
-```json
-{
-  "mcpServers": {
-    "marrow": {
-      "command": "npx",
-      "args": ["@getmarrow/mcp"],
-      "env": {
-        "MARROW_API_KEY": "mrw_your_key_here"
-      }
-    }
-  }
-}
+```bash
+npx @getmarrow/mcp
 ```
 
-### Generic MCP host
-
-If your MCP host supports command-based servers, point it at:
-
-- command: `npx`
-- args: `@getmarrow/mcp`
-- env: `MARROW_API_KEY=...`
-
----
-
-## Automatic Prompts (Zero-Config)
-
-When added to a compatible MCP client, Marrow automatically exposes a `marrow-always-on` prompt that instructs your agent to use the memory loop without any manual setup.
-
-In Claude Desktop — the prompt appears in the prompt picker. Select it once and your agent orients, thinks, and commits automatically every session.
-
-In compatible clients — the prompt can be auto-injected into the system context so the loop fires without the user doing anything.
-
-This is how Marrow works right after install with zero user instruction.
+Or register it in your MCP client config.
 
 ---
 
-## 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
-
----
+## MCP Tools
 
-## Tools
+### Core Loop Tools
 
-### `marrow_orient` / `orient`
-Start the session with Marrow context.
+#### `marrow_orient`
+**Call this first** at session start. Returns failure warnings from your history so you avoid known mistakes immediately.
 
-Returns:
-- loop state
-- recommended next step
-- recent lessons (when available)
-- canonical session-start nudge
+#### `marrow_think`
+Log intent before meaningful action. Returns pattern insights, similar past decisions, and a recommended next step.
 
-Typical use:
-- first meaningful step in a session
-- before planning or execution begins
+#### `marrow_commit`
+Log the outcome after acting. Closes the decision loop.
 
-### `marrow_think` / `think`
-Log intent and get decision intelligence back.
+#### `marrow_run`
+Zero-ceremony wrapper. Handles orient → think → commit in a single call.
 
-Returns:
-- `decision_id`
-- pattern intelligence
-- loop metadata
-- warnings / next-step guidance
+#### `marrow_auto`
+Fire-and-forget logging. Pass what you're about to do (and optionally the outcome). Marrow handles everything in the background.
 
-Typical use:
-- before meaningful action
-- before deploy / publish / send / external write work
-- when shifting from planning into execution
+### Memory Management Tools
 
-### `marrow_check` / `check`
-Inspect the current loop state.
+#### `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
 
-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
+#### `marrow_get_memory`
+Get a single memory by ID.
 
-Typical use:
-- before handoff
-- before "done"
-- before outbound updates after meaningful work
+#### `marrow_update_memory`
+Update memory text, tags, or metadata.
 
-### `marrow_commit` / `commit`
-Commit outcome to the hive and close the loop.
+#### `marrow_delete_memory`
+Soft delete a memory.
 
-Returns:
-- committed / accepted state
-- updated loop state
-- recommended next step after closure
+#### `marrow_mark_outdated`
+Mark a memory as outdated.
 
-Typical use:
-- after meaningful work finishes
-- after a deploy / publish / send / write succeeds or fails
-- before a clean handoff or completion
+#### `marrow_supersede_memory`
+Atomically replace a memory with a new version.
 
-### `marrow_run` — Zero-ceremony wrapper
+#### `marrow_share_memory`
+Share a memory with specific agents.
 
-Single call. Handles orient → think → commit automatically.
+#### `marrow_export_memories`
+Export memories to JSON or CSV format.
 
-Input:
-```json
-{
-  "description": "What the agent did",
-  "success": true,
-  "outcome": "One-line summary of what happened",
-  "type": "implementation"
-}
-```
+#### `marrow_import_memories`
+Import memories with merge (dedup) or replace mode.
 
-Returns: `{ decision_id, success_rate, insight, intelligence }`
+#### `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
 
-Use this when you want memory logging without managing the loop manually.
+### Query Tools
 
-### `patterns`
-Inspect accumulated decision patterns.
+#### `marrow_ask`
+Query the collective hive in plain English. Ask about failure patterns, what worked, what broke, or get a recommendation.
 
-Typical use:
-- identifying repeated failures
-- learning what tends to work for a task type
-- orienting around recent drift or recurring mistakes
+#### `marrow_status`
+Check Marrow platform health and status.
 
 ---
 
-## Zero-Ceremony Mode
-
-Use `marrow_run` instead of chaining `marrow_think` + `marrow_commit`:
+## Claude Desktop Config
 
 ```json
 {
-  "tool": "marrow_run",
-  "input": {
-    "description": "Refactored auth service to add retry logic",
-    "success": true,
-    "outcome": "Auth refactored. Exponential backoff added. Tests passing.",
-    "type": "implementation"
+  "mcpServers": {
+    "marrow": {
+      "command": "npx",
+      "args": ["@getmarrow/mcp"],
+      "env": {
+        "MARROW_API_KEY": "mrw_your_api_key"
+      }
+    }
   }
 }
 ```
 
-Marrow handles the full loop internally.
-
 ---
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `MARROW_API_KEY` | Yes | Your Marrow API key (starts with `mrw_`) |
-| `MARROW_BASE_URL` | No | Override API base URL (default: `https://api.getmarrow.ai`) |
-| `MARROW_SESSION_ID` | No | Session identifier — sent as `X-Marrow-Session-Id` on all requests |
-
----
-
-## 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
+| `MARROW_API_KEY` | Yes | Your API key from getmarrow.ai |
+| `MARROW_BASE_URL` | No | Custom API URL (default: `https://api.getmarrow.ai`) |
+| `MARROW_SESSION_ID` | No | Session identifier for multi-agent setups |
 
 ---
 
-## What Your Agent Gets Back
-
-Marrow MCP tools expose more than a raw ID.
+## The Always-On Prompt
 
-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
+Marrow includes a built-in prompt called `marrow-always-on` that instructs agents to use Marrow automatically. Install it once and it works for every session.
 
-That makes the MCP server useful during execution, not just as a logging endpoint.
+**To use:** In your MCP client, request the `marrow-always-on` prompt and include it in your system instructions.
 
 ---
 
-## Why Marrow Through MCP?
+## Why This Matters
 
 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
-
----
-
-## Privacy, Sanitization, and Data Ownership
-
-Marrow should make agents smarter **without turning user sessions into careless raw-data collection**.
+- 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
 
-Key trust properties:
-- sensitive inputs can be sanitized before storage when possible
-- privacy-preserving learning matters more than retaining raw personal data forever
-- MCP hosts should pass API keys through environment variables, not embed them in source or config blobs committed to git
-- the product direction is anonymized pattern learning, not exposing private user context across the hive
-- users should be able to export and own their memory data instead of being trapped in a closed system
+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
 
-In short:
-- better agent memory
-- stronger privacy posture
-- clearer user ownership
+**Marrow tells you what went wrong last time before you do it again.**
 
 ---
 
-## Session Hint
+## License
 
-At session start, Marrow nudges clients with the canonical reminder:
-
-> Tip: log plans, decisions, and outcomes to Marrow so your agent improves over time.
-
-For agents that have not logged any decisions yet this session, Marrow can also steer them toward `marrow_think` before acting.
+MIT
 
 ---
 
-## 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:
+## Related Packages
 
-- [`@getmarrow/sdk`](https://www.npmjs.com/package/@getmarrow/sdk)
+- **[@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.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;GAGG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}