memory-agent-mcp 0.0.0-stage → 1.0.1

package/PLAN.md

@@ -0,0 +1,42 @@
+# Memory MCP Wrapper — Plan & Status
+
+## Goal
+Build and publish `memory-agent-mcp` npm package following `vibe-token-mcp` pattern.
+
+## Status: ✅ BUILT & TESTED
+
+## Completed
+- [x] Create package.json
+- [x] Create index.js with MCP tools: store, search, subscribe, health, stats, sample
+- [x] Create README.md
+- [x] Install dependencies (@modelcontextprotocol/sdk, viem)
+- [x] Test MCP server startup (stdio)
+- [x] Test tools/list (6 tools registered)
+- [x] Test health tool (returns service status)
+- [x] Test sample tool (handles IP token conflict gracefully)
+
+## TODO
+- [ ] Test store tool with fresh IP (or handle existing token)
+- [ ] Test search tool (free tier + paid)
+- [ ] Test subscribe tool (x402 payment)
+- [ ] Fix sample tool to handle existing write_token
+- [ ] Publish to npm as `memory-agent-mcp`
+- [ ] Add to x402-list MCP registry
+- [ ] Create README for npm page
+- [ ] Test end-to-end with real payment
+
+## Tools
+| Tool | Description | Payment |
+|------|-------------|---------|
+| store | Store a memory (free) | Free |
+| search | Semantic search (30/day free, then $0.01) | Free tier + x402 |
+| subscribe | Subscribe to plan | x402 ($2/$9/$20) |
+| health | Service health | Free |
+| stats | Global stats | Free |
+| sample | Demo store+search | Free |
+
+## Next Steps
+1. Publish to npm
+2. Add memory-mcp to OpenCode config
+3. Test with real wallet
+4. Update llms.txt and openapi.json to mention MCP

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# memory-agent-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP wrapper for [Memory01](https://memory.node01.org) — agentic memory for AI agents.
+
+## Features
+
+- **Store**: Free memory storage (first call returns a write_token)
+- **Search**: Semantic search across 50+ languages (free tier: 30/day, then $0.01 USDC)
+- **Subscribe**: Subscription plans (Starter $2/500, Pro $9/mo, Enterprise $20/mo)
+- **Health**: Service health check (free)
+- **Stats**: Global memory statistics (free)
+- **Sample**: Free demo (store + search)
+
+## Installation
+
+```bash
+npm install -g memory-agent-mcp
+```
+
+## Configuration
+
+Set these environment variables:
+
+- `MEMORY_BASE_URL` (default: https://memory.node01.org)
+- `MEMORY_PAYTO` (USDC wallet address on Base for paid calls)
+- `MEMORY_PRIVATE_KEY` (private key for x402 payment signing)
+
+## Usage with OpenCode
+
+Add to your `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "memory": {
+      "type": "local",
+      "command": ["npx", "-y", "memory-agent-mcp"],
+      "environment": {
+        "MEMORY_PAYTO": "0x...",
+        "MEMORY_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### store
+Store a memory. First call returns a write_token — save it! All future operations require it.
+
+### search
+Search memories semantically. Free tier: 30 searches/day. After that, $0.01 USDC per search.
+
+### subscribe
+Subscribe to a plan for more searches.
+
+### health
+Check service health.
+
+### stats
+Get global statistics.
+
+### sample
+Free demo: store and search a sample memory.

package/index.js

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+/**
+ * memory-agent-mcp — MCP stdio server for Memory01 agentic memory service
+ *
+ * Provides tools to interact with the Memory01 API:
+ *   - store(agentId, key, value, writeToken?, sessionId?, metadata?) -> Store a memory (free)
+ *   - search(agentId, query, writeToken, topK?, sessionId?, cursor?) -> Search memories (free tier 30/day, then $0.01)
+ *   - subscribe(agentId, writeToken, plan) -> Subscribe to a plan (x402)
+ *   - health() -> Service health check (free)
+ *   - stats() -> Global memory stats (free)
+ *   - sample() -> Free sample (store + search demo)
+ *
+ * Usage:
+ *   npx memory-agent-mcp
+ *   or: node index.js
+ *
+ * Configure with environment variables:
+ *   MEMORY_BASE_URL    (default: https://memory.node01.org)
+ *   MEMORY_PAYTO       (required for paid calls - USDC wallet address)
+ *   MEMORY_PRIVATE_KEY (required for x402 payment signing)
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createWalletClient, http, parseEther } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+
+// ============================= Config =============================
+const MEMORY_BASE_URL = process.env.MEMORY_BASE_URL || "https://memory.node01.org";
+const MEMORY_PAYTO = process.env.MEMORY_PAYTO;
+const MEMORY_PRIVATE_KEY = process.env.MEMORY_PRIVATE_KEY;
+
+if (!MEMORY_PAYTO) {
+  console.error("MEMORY_PAYTO environment variable required for paid calls");
+  process.exit(1);
+}
+
+if (!MEMORY_PRIVATE_KEY) {
+  console.error("MEMORY_PRIVATE_KEY environment variable required for x402 payment signing");
+  process.exit(1);
+}
+
+const privateKey = MEMORY_PRIVATE_KEY.startsWith("0x") ? MEMORY_PRIVATE_KEY : `0x${MEMORY_PRIVATE_KEY}`;
+const account = privateKeyToAccount(privateKey);
+
+// ============================= x402 Payment Helper =============================
+async function payAndRetry(endpoint, body, priceUsd = "0.01") {
+  const walletClient = createWalletClient({
+    account,
+    chain: base,
+    transport: http(),
+  });
+
+  // First call to get 402
+  const response = await fetch(`${MEMORY_BASE_URL}${endpoint}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Accept": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (response.status !== 402) {
+    const data = await response.json();
+    return { data, status: response.status };
+  }
+
+  const paymentRequired = await response.json();
+  const accepts = paymentRequired.accepts || [];
+  const exactOption = accepts.find(
+    (a) => a.scheme === "exact" && a.network === "eip155:8453"
+  );
+
+  if (!exactOption) {
+    throw new Error("No exact payment option for Base network found");
+  }
+
+  const facilitatorUrl = paymentRequired.extensions?.["pay-with-x"]?.facilitator || "https://facilitator.payai.network";
+
+  const paymentPayload = {
+    x402Version: paymentRequired.x402Version || 2,
+    scheme: "exact",
+    network: "eip155:8453",
+    payload: {
+      authorization: {
+        from: account.address,
+        to: exactOption.payTo,
+        value: priceUsd,
+        validAfter: Math.floor(Date.now() / 1000),
+        validBefore: Math.floor(Date.now() / 1000) + 300,
+        nonce: Math.floor(Math.random() * 1000000),
+      },
+    },
+  };
+
+  const signature = await walletClient.signTypedData({
+    domain: {
+      name: "x402 Payment",
+      version: "1",
+      chainId: 8453,
+      verifyingContract: exactOption.payTo,
+    },
+    types: {
+      ExactPayment: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "uint256" },
+      ],
+    },
+    primaryType: "ExactPayment",
+    message: {
+      from: account.address,
+      to: exactOption.payTo,
+      value: priceUsd,
+      validAfter: Math.floor(Date.now() / 1000),
+      validBefore: Math.floor(Date.now() / 1000) + 300,
+      nonce: Math.floor(Math.random() * 1000000),
+    },
+  });
+
+  paymentPayload.payload.authorization.signature = signature;
+
+  const settleResponse = await fetch(`${facilitatorUrl}/settle`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(paymentPayload),
+  });
+
+  if (!settleResponse.ok) {
+    const err = await settleResponse.text();
+    throw new Error(`Payment settlement failed: ${settleResponse.status} ${err}`);
+  }
+
+  const settleResult = await settleResponse.json();
+  const paymentHeader = settleResult.paymentHeader || settleResult.header || settleResult.payment;
+
+  // Retry with payment header
+  const finalResponse = await fetch(`${MEMORY_BASE_URL}${endpoint}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      "X-Payment": paymentHeader,
+    },
+    body: JSON.stringify(body),
+  });
+
+  const data = await finalResponse.json();
+  return { data, status: finalResponse.status };
+}
+
+// ============================= Free API Calls =============================
+async function callFree(endpoint, method = "GET", body = null) {
+  const opts = { method, headers: { "Accept": "application/json" } };
+  if (body) {
+    opts.headers["Content-Type"] = "application/json";
+    opts.body = JSON.stringify(body);
+  }
+  const response = await fetch(`${MEMORY_BASE_URL}${endpoint}`, opts);
+  return { data: await response.json(), status: response.status };
+}
+
+// ============================= MCP Server =============================
+const server = new Server(
+  { name: "memory-agent-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "store",
+        description: "Store a memory (free). First call returns a write_token — save it! All future operations require it. Memories are scoped per write_token.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            agentId: { type: "string", description: "Your agent identifier" },
+            key: { type: "string", description: "Memory key (max 256 chars)" },
+            value: { type: "string", description: "Memory value (max 10KB)" },
+            writeToken: { type: "string", description: "Write token from first store (omit on first call)" },
+            sessionId: { type: "string", description: "Optional session ID to scope memories" },
+            metadata: { type: "object", description: "Optional metadata (max 2KB)" },
+          },
+          required: ["agentId", "key", "value"],
+        },
+      },
+      {
+        name: "search",
+        description: "Search memories semantically (free tier: 30/day, then $0.01 USDC). Returns matching memories with relevance scores. Supports 50+ languages, cross-lingual search.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            agentId: { type: "string", description: "Your agent identifier" },
+            query: { type: "string", description: "Search query (max 500 chars). Omit for session-only chronological listing." },
+            writeToken: { type: "string", description: "Write token (required)" },
+            topK: { type: "number", description: "Max results (default 10, max 50)", default: 10 },
+            sessionId: { type: "string", description: "Optional: scope to session. Omit query for chronological listing." },
+            cursor: { type: "string", description: "Pagination cursor from previous response" },
+          },
+          required: ["agentId", "writeToken"],
+        },
+      },
+      {
+        name: "subscribe",
+        description: "Subscribe to a memory plan (x402). Starter: $2/500 credits. Pro: $9/mo unlimited. Enterprise: $20/mo unlimited+priority.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            agentId: { type: "string", description: "Your agent identifier" },
+            writeToken: { type: "string", description: "Write token (required)" },
+            plan: { type: "string", enum: ["starter", "pro", "enterprise"], description: "Plan to subscribe to" },
+          },
+          required: ["agentId", "writeToken", "plan"],
+        },
+      },
+      {
+        name: "health",
+        description: "Check Memory01 service health (free). Returns service status, free tier info, plans.",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "stats",
+        description: "Get global memory statistics (free). Returns total agents, entries, searches.",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "sample",
+        description: "Get a free sample: store a demo memory and search it. Shows the shape of responses without paying.",
+        inputSchema: { type: "object", properties: {} },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "store": {
+        const { agentId, key, value, writeToken, sessionId, metadata } = args;
+        if (!agentId || !key || !value) {
+          throw new McpError(ErrorCode.InvalidParams, "agentId, key, and value are required");
+        }
+        if (key.length > 256) throw new McpError(ErrorCode.InvalidParams, "key max 256 chars");
+        if (value.length > 10240) throw new McpError(ErrorCode.InvalidParams, "value max 10KB");
+        if (metadata && JSON.stringify(metadata).length > 2048) throw new McpError(ErrorCode.InvalidParams, "metadata max 2KB");
+
+        const body = { agent_id: agentId, key, value };
+        if (writeToken) body.write_token = writeToken;
+        if (sessionId) body.session_id = sessionId;
+        if (metadata) body.metadata = metadata;
+
+        const result = await callFree("/api/memory/store", "POST", body);
+        if (result.status >= 400) {
+          throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(result.data)}`);
+        }
+
+        const r = result.data;
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ok: r.ok,
+              stored: r.stored,
+              write_token: r.write_token,
+              message: r.message,
+              key: r.key,
+              stored_at: r.stored_at,
+              updated_at: r.updated_at,
+            }, null, 2),
+          }],
+        };
+      }
+
+      case "search": {
+        const { agentId, query, writeToken, topK = 10, sessionId, cursor } = args;
+        if (!agentId || !writeToken) {
+          throw new McpError(ErrorCode.InvalidParams, "agentId and writeToken are required");
+        }
+        if (query && query.length > 500) throw new McpError(ErrorCode.InvalidParams, "query max 500 chars");
+
+        const body = { agent_id: agentId, write_token: writeToken, top_k: topK };
+        if (query) body.query = query;
+        if (sessionId) body.session_id = sessionId;
+        if (cursor) body.cursor = cursor;
+
+        // Try free first
+        const freeResult = await callFree("/api/memory/search", "POST", body);
+
+        if (freeResult.status === 402) {
+          // Free tier exhausted, pay
+          const paidResult = await payAndRetry("/api/memory/search", body, "0.01");
+          if (paidResult.status >= 400) {
+            throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(paidResult.data)}`);
+          }
+          const r = paidResult.data;
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                results: r.results,
+                free_tier: r.free_tier,
+                tier: r.tier,
+                searched_at: r.searched_at,
+                next_cursor: r.next_cursor,
+                cursor_expires_in: r.cursor_expires_in,
+              }, null, 2),
+            }],
+          };
+        }
+
+        if (freeResult.status >= 400) {
+          throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(freeResult.data)}`);
+        }
+
+        const r = freeResult.data;
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              results: r.results,
+              free_tier: r.free_tier,
+              tier: r.tier,
+              searched_at: r.searched_at,
+              next_cursor: r.next_cursor,
+              cursor_expires_in: r.cursor_expires_in,
+            }, null, 2),
+          }],
+        };
+      }
+
+      case "subscribe": {
+        const { agentId, writeToken, plan } = args;
+        if (!agentId || !writeToken || !plan) {
+          throw new McpError(ErrorCode.InvalidParams, "agentId, writeToken, and plan are required");
+        }
+
+        const body = { agent_id: agentId, write_token: writeToken, plan };
+        const priceMap = { starter: "2.00", pro: "9.00", enterprise: "20.00" };
+        const paidResult = await payAndRetry("/api/memory/subscribe", body, priceMap[plan] || "2.00");
+
+        if (paidResult.status >= 400) {
+          throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(paidResult.data)}`);
+        }
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(paidResult.data, null, 2),
+          }],
+        };
+      }
+
+      case "health": {
+        const result = await callFree("/api/health");
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+
+      case "stats": {
+        const result = await callFree("/api/memory/stats");
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+
+      case "sample": {
+        // Store a demo memory, then search it
+        const storeResult = await callFree("/api/memory/store", "POST", {
+          agent_id: "sample-agent",
+          key: "demo",
+          value: "This is a sample memory for testing Memory01 service",
+        });
+
+        const searchResult = await callFree("/api/memory/search", "POST", {
+          agent_id: "sample-agent",
+          write_token: storeResult.data.write_token,
+          query: "sample memory",
+        });
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              store: storeResult.data,
+              search: searchResult.data,
+            }, null, 2),
+          }],
+        };
+      }
+
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    if (error instanceof McpError) throw error;
+    console.error(`Tool ${name} error:`, error);
+    throw new McpError(ErrorCode.InternalError, String(error));
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("memory-agent-mcp running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "memory-agent-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "MCP wrapper for Memory01 agentic memory service - free to store, paid to search",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "memory-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "agent",
+    "x402",
+    "ai",
+    "base",
+    "storage"
+  ],
+  "author": "node01.org",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "viem": "^2.57.16"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}