@getmarrow/sdk 2.5.4 → 2.5.6

package/README.md

@@ -1,10 +1,156 @@
 # @getmarrow/sdk
 
-> **Your go-to memory provider for all agents, for any AI model.**
+> **Memory and decision intelligence for agents that need to get better over time.**
 
-Marrow gives your AI agent a memory that compounds. Every decision your agent makes gets shared with the Marrow hive. Every other agent's experience flows back into yours. The more agents use Marrow, the smarter every single one of them gets.
+Most agents still work like this:
+- they plan something
+- they do something
+- they forget what happened
+- then they repeat the same mistake next session
 
-**Your agent stops making the same mistakes. It learns from thousands of others — instantly.**
+That’s fine for a toy. It’s a problem for anything real.
+
+`@getmarrow/sdk` gives your agent a memory that compounds. It lets you log intent before meaningful work, pull back useful decision intelligence, and commit the outcome afterward so the next run starts smarter instead of blank.
+
+**Marrow turns agent memory from a passive log into an operating loop.**
+
+---
+
+## The Problem
+
+Without durable decision memory:
+- agents repeat bad calls
+- successful patterns get lost
+- work gets marked “done” without outcome context
+- external actions happen with no structured trail
+- every new session wastes time rediscovering what already failed
+
+A bigger context window doesn’t solve this.
+You need a system that remembers:
+- what the agent was trying to do
+- what it actually did
+- whether it worked
+- what pattern that should teach the next attempt
+
+---
+
+## The Solution
+
+Marrow gives you a simple SDK for decision memory and loop discipline.
+
+With `@getmarrow/sdk`, your agent can:
+- **orient** at session start
+- **think** before meaningful action
+- **check** whether the loop is still open
+- **wrap** important actions so intent and outcome stay connected
+- **commit** the result back into memory
+
+That gives you a usable operating loop:
+
+```text
+orient -> think -> act -> check -> commit
+```
+
+Not just memory for memory’s sake —
+memory that improves execution.
+
+---
+
+## How It Works
+
+### 1. Orient
+Start the session with context from prior decisions.
+
+```typescript
+await marrow.orient();
+```
+
+This gives the agent a cleaner starting point instead of acting cold.
+
+### 2. Think
+Log intent before meaningful work.
+
+```typescript
+const decision = await marrow.think({
+  action: 'Deploy auth refactor to staging',
+  type: 'implementation',
+});
+```
+
+Now the work has a decision trail and Marrow can return relevant intelligence.
+
+### 3. Act
+Do the actual work.
+
+For low-friction usage, wrap the action directly:
+
+```typescript
+await marrow.wrap(
+  {
+    action: 'Call deployment API',
+    type: 'implementation',
+    external: true,
+    result: 'Staging deploy succeeded',
+  },
+  async () => deployToStaging()
+);
+```
+
+### 4. Check
+Inspect whether the loop is still open.
+
+```typescript
+const state = marrow.check();
+console.log(state.recommendedNext);
+```
+
+This is what tells the agent whether it’s actually ready to move on.
+
+### 5. Commit
+Close the loop with outcome memory.
+
+```typescript
+await marrow.commit({
+  decision_id: decision.decision_id,
+  success: true,
+  outcome: 'Deployment passed smoke tests',
+});
+```
+
+Now the next session doesn’t start from scratch.
+
+---
+
+## Why This Matters
+
+A normal memory system stores notes.
+
+Marrow stores **decision history**:
+- what was attempted
+- what happened
+- what patterns are emerging
+- what the agent should do better next time
+
+That’s the difference between:
+- an agent that “has memory”
+- and an agent that actually **improves**
+
+---
+
+## Privacy, Sanitization, and Data Ownership
+
+Marrow is designed to be useful **without treating user data casually**.
+
+Key trust properties:
+- sensitive inputs can be sanitized before storage when possible
+- privacy-preserving pattern learning matters more than hoarding raw user data
+- API keys should be passed through environment variables, not hardcoded in source
+- the product direction is anonymized learning, not leaking raw private context across agents
+- users should be able to export and own their memory data instead of feeling trapped inside a black box
+
+In plain English:
+- Marrow should help agents learn from patterns
+- while minimizing unnecessary exposure of personal or sensitive information
 
 ---
 
@@ -115,245 +261,3 @@ console.log(marrow.check().state.recommendedNext);
 ### Session start copy
 - `Tip: log plans, decisions, and outcomes to Marrow so your agent improves over time.`
 - `You have not logged any decisions yet this session. Before acting, call marrow_think.`
-
-## The Problem
-
-Every AI agent starts from zero. No memory of what worked. No memory of what failed. Every session, your agent makes the same mistakes — because it has no way to learn from its own history, let alone anyone else's.
-
-**Marrow fixes this.**
-
----
-
-## How It Works
-
-One call before your agent acts. One call when it's done. Marrow handles everything in between — querying collective intelligence from the hive, recording outcomes, detecting patterns, building your agent's memory over time.
-
-```typescript
-import { MarrowClient } from '@getmarrow/sdk';
-
-const marrow = new MarrowClient(process.env.MARROW_API_KEY!);
-
-// ── Before your agent acts ──────────────────────────────────
-const { decisionId, intelligence } = await marrow.think({
-  action: 'Summarizing user research findings and drafting report',
-  type: 'implementation'
-});
-
-console.log(intelligence.similar);
-// → [{ outcome: "Used bullet points + TL;DR header. User engagement +40%.", confidence: 0.94 }]
-// ↑ What worked for other agents doing the same thing
-
-console.log(intelligence.successRate);
-// → 0.87
-// ↑ How agents like you are performing on this type of task
-
-console.log(intelligence.patterns);
-// → [{ patternId: "a1b2c3", decisionType: "implementation", frequency: 47, confidence: 0.9 }]
-// ↑ Patterns the hive has discovered across thousands of runs
-
-console.log(intelligence.insight);
-// → "Workflow gap detected — audit missing after build"
-// ↑ Actionable intelligence from pattern engine
-
-console.log(intelligence.insights);
-// → [{ type: "workflow_gap", summary: "audit not logged after build", action: "Run audit", severity: "critical", count: 3 }]
-// ↑ Structured actionable insights: failure patterns, workflow gaps, hive trends
-
-console.log(intelligence.clusterId);
-// → "818df2fa-6365-49f6-b478-bc3dcb748469"
-// ↑ Semantic cluster ID — similar actions grouped together
-
-// ── Your agent does its work ────────────────────────────────
-// (armed with collective intelligence from the hive)
-
-// ── After your agent acts ───────────────────────────────────
-const next = await marrow.think({
-  action: 'Next task',
-  previousSuccess: true,
-  previousOutcome: 'Report delivered. User approved on first pass, no revisions needed.'
-});
-// ↑ Auto-commits the previous session, opens a new one
-// The hive just got smarter from your agent's experience
-```
-
-That's it. Two lines that transform your agent from amnesiac to experienced.
-
----
-
-## What Your Agent Gets Back
-
-Every `think()` call returns collective intelligence from the entire Marrow hive:
-
-```typescript
-intelligence: {
-  similar        // What worked for other agents in this exact situation
-  patterns       // Patterns discovered across thousands of agent runs
-  templates      // Proven step-by-step playbooks for this action type
-  shared         // Knowledge other agents have explicitly shared
-  causalChain    // What sequence of decisions led to similar outcomes
-  successRate    // How well agents like yours are performing (0-1)
-  priorityScore  // How urgent/impactful this decision is
-}
-```
-
----
-
-## Real Examples
-
-### AI coding agent
-```typescript
-const marrow = new MarrowClient(process.env.MARROW_API_KEY);
-let decisionId = null;
-
-async function beforeTask(description: string) {
-  const { decisionId: id, intelligence } = await marrow.think({
-    action: description,
-    type: 'implementation',
-    previousSuccess: lastTaskSucceeded,
-    previousOutcome: lastTaskOutcome,
-  });
-  decisionId = id;
-  
-  // Use hive intelligence to guide the task
-  if (intelligence.similar.length > 0) {
-    console.log(`Similar task succeeded with: ${intelligence.similar[0].outcome}`);
-  }
-  return intelligence;
-}
-```
-
-### Research agent
-```typescript
-const { intelligence } = await marrow.think({
-  action: 'Analyzing competitor pricing strategy',
-  type: 'architecture',
-});
-
-// intelligence.templates gives you the proven research framework
-// other agents used for the same type of analysis
-const framework = intelligence.templates[0]?.steps;
-```
-
-### Customer support agent
-```typescript
-// Each ticket resolution feeds the hive
-const { intelligence } = await marrow.think({
-  action: 'Resolving billing dispute — customer charged twice',
-  type: 'process',
-  previousSuccess: true,
-  previousOutcome: 'Refund issued in 2 minutes. Customer gave 5-star rating.'
-});
-
-// Next agent handling a similar dispute gets this outcome surfaced
-// intelligence.similar → "Issue refund immediately, explain in plain language. 5-star result."
-```
-
----
-
-## API Reference
-
-### `marrow.think(params)`
-
-**The core method.** Call before every agent action. Automatically commits your previous session if you pass `previousOutcome`.
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `action` | `string` | What your agent is about to do |
-| `type` | `string` | `'implementation'` \| `'security'` \| `'architecture'` \| `'process'` \| `'general'` |
-| `context` | `object` | Optional extra context to share with the hive |
-| `previousSuccess` | `boolean` | Did the last action succeed? |
-| `previousOutcome` | `string` | What happened — the hive learns from this |
-| `previousCausedBy` | `string` | Link to a prior decision for causal tracking |
-
-**Returns:**
-```typescript
-{
-  decisionId: string        // Pass back on next think() to auto-commit this one
-  intelligence: {
-    similar: Array<{ outcome: string, confidence: number }>
-    patterns: Array<{ pattern: string, frequency: number }>
-    templates: Array<{ steps: object[], success_rate: number }>
-    shared: Array<{ outcome: string }>
-    causalChain: object | null
-    successRate: number
-    priorityScore: number
-  }
-  streamUrl: string         // Subscribe for live hive updates via SSE
-  previousCommitted: boolean
-}
-```
-
-### `marrow.commit(params)`
-
-Explicit commit when you need more control. `think()` auto-commits on the next call, so this is optional.
-
-```typescript
-await marrow.commit({
-  success: true,
-  outcome: 'Task completed successfully — latency under 200ms',
-  causedBy: previousDecisionId, // optional: link decisions causally
-});
-```
-
----
-
-## Why Marrow?
-
-| Without Marrow | With Marrow |
-|---|---|
-| Agent starts from zero every session | Agent inherits collective intelligence from the hive |
-| Same mistakes repeated across runs | Patterns detected, failures don't repeat |
-| No visibility into agent performance | Real-time success rate, velocity, trend data |
-| Memory dies when context ends | Persistent memory that compounds forever |
-| Works for one model only | Claude, GPT, Gemini, Llama — any model |
-
----
-
-## Get Started
-
-```bash
-npm install @getmarrow/sdk
-```
-
-1. Get your API key at [getmarrow.ai](https://getmarrow.ai)
-2. Add `marrow.think()` before your agent's first action
-3. Pass `previousOutcome` on every subsequent call
-4. Watch your agent's success rate climb
-
-**Your agent gets smarter with every run. So does every other agent on the hive.**
-
----
-
-*Works with Claude, GPT-4, Gemini, Llama, Mistral, and any model with a system prompt.*
-
----
-
-## Privacy & Data
-
-**What Marrow collects:**
-- The `action` string and `type` you pass to `think()` and `commit()`
-- The `outcome` you report — used to train collective intelligence
-- Decision metadata: timestamps, success/failure, confidence scores
-
-**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 client 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
-
-**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
-
-For full details, see our [Privacy Policy](https://getmarrow.ai/privacy).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/sdk",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "Your go-to memory provider for all agents, for any AI model.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",