mem-mcp 0.0.0-stage → 1.3.4

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
+- [x] Publish to npm as `memory-agent-mcp` (v1.0.1)
+- [ ] Add to x402-list MCP registry
+- [ ] Create README for npm page
+- [x] Test end-to-end (health + sample passed)
+
+## 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,156 @@
-# Temporary Holding Version
+# mem-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 + recovery_code)
+- **Upsert**: Re-store with the same key updates in place (no duplicates)
+- **Search**: Semantic search across 50+ languages (free tier: 30/day, then $0.01 USDC)
+- **Base memories**: Small (max 2KB) contextual memories (preferences, style, details). Excluded from normal search by default; include with `include_base=true`. Bootstrap creates conventional ones.
+- **Recovery**: Recovery code issued at first store lets you re-bind your token to a new IP if your host changes IP.
+- **Subscribe**: Subscription plans (Starter $2/500, Pro $9/mo, Enterprise $20/mo)
+- **Health / Stats / Sample**: Free utilities
+
+## Auto-update
+
+MCP clients do not auto-update servers. To always use the latest version:
+
+- **Recommended config**: use `npx -y memory-agent-mcp@latest` in your MCP config. npx checks the registry on each launch (cached, fast).
+- **Global install**: run `npm install -g memory-agent-mcp@latest` periodically, or `npm update -g memory-agent-mcp`. Use the `memory-mcp` binary in your MCP config for offline startup.
+- The server prints a note on startup if a newer version is available.
+
+## One-command setup
+
+After installing, tell your agent:
+
+> Install `memory-agent-mcp` and call the `init` tool with your agentId. It will set everything up and explain the rest.
+
+The `init` tool creates the token, saves credentials to `~/.memory01_token` / `~/.memory01_recovery` (chmod 600), bootstraps base memories, and returns a full guide.
+
+## Installation
+
+```bash
+npm install -g memory-agent-mcp
+```
+
+## Configuration
+
+No configuration required for free usage! The service works out of the box.
+
+Optional environment variables:
+
+- `MEMORY_BASE_URL` (default: https://memory.node01.org)
+- `MEMORY_PRIVATE_KEY` (optional: private key for x402 payment signing — enables paid operations beyond free tier)
+
+### Free tier (no wallet needed)
+- Store memories: free (up to 50KB per value; 2KB for base memories)
+- Search: 30 free searches/day
+- Health check: free
+- Stats: free
+- Sample: free
+- Bootstrap base memories: free
+- Get a single memory: free
+
+### Paid operations (requires MEMORY_PRIVATE_KEY)
+- Search beyond 30/day: $0.01 USDC
+- Subscribe to plans: $2/$9/$20
+
+### Security note
+If you set MEMORY_PRIVATE_KEY, use a dedicated wallet with limited funds.
+Never commit your private key to version control. Use a .env file or
+environment variables.
+
+### Token binding (IP + agent_id)
+Your write_token is bound to the **(IP, agent_id)** pair that created it.
+- Multiple agents can share the same IP (NAT, serverless, office, VPN): each agent_id gets its own token.
+- If you call `store` without a token for an `(IP, agent_id)` pair that already has one, you get `403 token_required`. Include the token you saved.
+- First `store` also returns a `recovery_code` (shown once). Save it offline (chmod 600). If your IP changes, use `recover` with the recovery code to get a new token for the new IP. Regenerate the recovery code (from the original IP) if lost.
+- Treat the write_token and recovery_code like passwords. Never log them in plaintext. Never store secrets in memory — store only a pointer (see "Base memory" pattern).
+
+### Base memory pattern
+Base memories are small contextual memories (preferences, style, details). They are excluded from normal search to keep task search focused. Use `include_base=true` to load them (e.g. at session start). Sensitive ones like `credentials-location` are never searchable — retrieve via `get`.
+
+Store a pointer, never secrets. Standard credential file locations (chmod 600):
+- Linux/macOS: `~/.memory01_token` and `~/.memory01_recovery`
+- Windows: `%USERPROFILE%\.memory01_token` and `%USERPROFILE%\.memory01_recovery`
+
+```
+key: "credentials-location"
+value: "Token at ~/.memory01_token, recovery at ~/.memory01_recovery (chmod 600). Do not store secrets in memory."
+```
+
+### Agent docs
+Read the agent-facing guide first: https://memory.node01.org/agents.md
+
+## Usage with OpenCode
+
+Add to your `opencode.json`:
+
+```json
+// Option A — global install (offline, fast, no network):
+{
+  "mcp": {
+    "memory": {
+      "type": "local",
+      "command": ["memory-mcp"],
+      "environment": {
+        "MEMORY_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+
+// Option B — always latest (checks registry on launch):
+{
+  "mcp": {
+    "memory": {
+      "type": "local",
+      "command": ["npx", "-y", "memory-agent-mcp@latest"],
+      "environment": {
+        "MEMORY_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+Note: the binary is `memory-mcp` (not `memory-agent-mcp`). Use `memory-mcp` if globally
+installed, `npx -y memory-agent-mcp@latest` otherwise. MEMORY_PRIVATE_KEY is optional —
+the free tier (store + 30 searches/day + bootstrap + get) works without it.
+```
+
+## Tools
+
+### init
+Initialize Memory01 in one call: creates token, saves credentials to standard files (chmod 600), bootstraps base memories, stores credentials-location pointer. Returns full guide. Call once per agent.
+
+### store
+Store a memory (free). First call returns a write_token and recovery_code — save both! All future operations require the write_token. Re-storing with the same key updates in place (upsert). Supports `base: true` for small (2KB) contextual memories.
+
+### search
+Search memories semantically. Free tier: 30 searches/day. After that, $0.01 USDC per search. Use `includeBase: true` to include searchable base memories.
+
+### bootstrap
+Initialize conventional base memories (credentials-location, user-preferences, user-details, code-style) if missing. Idempotent. Free.
+
+### get
+Retrieve a single memory by key (useful for sensitive base memories like credentials-location). Free.
+
+### recover
+Recover a write_token on a new IP using a recovery code. Use when your host's IP changed.
+
+### regenerate_recovery
+Issue a new recovery code (invalidates the old one). Requires the original write_token from the original IP.
+
+### 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/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["geco"]
+}

package/index.js

@@ -0,0 +1,699 @@
+#!/usr/bin/env node
+/**
+ * mem-mcp — MCP stdio server for Memory01 agentic memory service
+ *
+ * Provides tools to interact with the Memory01 API:
+ *   - store(agentId, key, value, writeToken?, sessionId?, metadata?, base?) -> Store a memory (free; base=true for 2KB contextual memories)
+ *   - search(agentId, query, writeToken, topK?, sessionId?, cursor?, includeBase?) -> Search memories (free tier 30/day, then $0.01)
+ *   - bootstrap(agentId, writeToken, keys?) -> Initialize conventional base memories (free, idempotent)
+ *   - get(agentId, writeToken, key) -> Retrieve a single memory by key (free)
+ *   - recover(agentId, recoveryCode) -> Recover a write_token on a new IP (free)
+ *   - regenerateRecovery(writeToken) -> Issue a new recovery code (free)
+ *   - 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 (all optional):
+ *   MEMORY_BASE_URL    (default: https://memory.node01.org)
+ *   MEMORY_PRIVATE_KEY (optional: enables paid operations beyond free tier)
+ *
+ * Free operations work without any configuration:
+ *   store, health, stats, sample, and 30 free searches/day.
+ * Paid operations (search beyond free tier, subscribe) require
+ * MEMORY_PRIVATE_KEY set to a wallet with USDC on Base.
+ */
+
+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";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+// ============================= Config =============================
+const MEMORY_BASE_URL = process.env.MEMORY_BASE_URL || "https://memory.node01.org";
+const CLIENT_VERSION = "1.3.4";
+const MEMORY_PRIVATE_KEY = process.env.MEMORY_PRIVATE_KEY;
+
+
+const HAS_WALLET = !!MEMORY_PRIVATE_KEY;
+if (!HAS_WALLET) {
+  console.error("NOTE: No MEMORY_PRIVATE_KEY set. Free operations (store, health, stats, sample, 30 free searches/day) will work. Paid operations (search after free tier, subscribe) will require a wallet.");
+}
+
+let account = null;
+if (HAS_WALLET) {
+  const privateKey = MEMORY_PRIVATE_KEY.startsWith("0x") ? MEMORY_PRIVATE_KEY : `0x${MEMORY_PRIVATE_KEY}`;
+  account = privateKeyToAccount(privateKey);
+}
+
+// ============================= x402 Payment Helper =============================
+async function payAndRetry(endpoint, body, priceUsd = "0.01") {
+  if (!HAS_WALLET) {
+    throw new Error("Payment required but no wallet configured. Set MEMORY_PRIVATE_KEY env var to enable paid operations. Free tier: 30 searches/day.");
+  }
+  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 and recovery_code — save both! All future operations require the write_token. Re-storing with the same key updates in place (upsert). Supports base:true for small (2KB) contextual memories.",
+        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)" },
+            base: { type: "boolean", description: "Mark as base memory (max 2KB). Excluded from normal search unless includeBase=true." },
+          },
+          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. Use includeBase:true to include base memories.",
+        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" },
+            includeBase: { type: "boolean", description: "Include searchable base memories in results (default false)" },
+          },
+          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: {} },
+      },
+      {
+        name: "bootstrap",
+        description: "Initialize conventional base memories (credentials-location, user-preferences, user-details, code-style) if missing. Idempotent. Free.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            agentId: { type: "string", description: "Your agent identifier" },
+            writeToken: { type: "string", description: "Write token (required)" },
+            keys: { type: "array", items: { type: "string" }, description: "Optional list of base keys to create (defaults to all conventional)" },
+          },
+          required: ["agentId", "writeToken"],
+        },
+      },
+      {
+        name: "get",
+        description: "Retrieve a single memory by key (free). Useful for sensitive base memories like credentials-location.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            agentId: { type: "string", description: "Your agent identifier" },
+            writeToken: { type: "string", description: "Write token (required)" },
+            key: { type: "string", description: "Memory key to retrieve" },
+          },
+          required: ["agentId", "writeToken", "key"],
+        },
+      },
+      {
+        name: "init",
+        description: "Initialize Memory01 for this agent in one call: creates a write_token (first store), saves token+recovery_code to standard files (~/.memory01_token, ~/.memory01_recovery, chmod 600), bootstraps conventional base memories, and stores a credentials-location pointer. Returns full guide. Call once per agent; idempotent-ish (if token exists, pass writeToken).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            agentId: { type: "string", description: "Your agent identifier (required)" },
+            writeToken: { type: "string", description: "Existing write token (omit on first run)" },
+            key: { type: "string", description: "Optional first memory key (default: 'init')" },
+            value: { type: "string", description: "Optional first memory value" },
+          },
+          required: ["agentId"],
+        },
+      },
+      {
+        name: "guide",
+        description: "Get a concise guide on how to use Memory01: init flow, base memories, recovery, upsert, limits. Call this first if unsure. Full guide: https://memory.node01.org/agents.md",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "recover",
+        description: "Recover a write_token on a new IP using a recovery code (free). Use when your host's IP changed.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            agentId: { type: "string", description: "Your agent identifier" },
+            recoveryCode: { type: "string", description: "Recovery code (rc_...) issued at first store" },
+          },
+          required: ["agentId", "recoveryCode"],
+        },
+      },
+      {
+        name: "regenerate_recovery",
+        description: "Issue a new recovery code (invalidates the old one). Requires the original write_token from the original IP. Free.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            writeToken: { type: "string", description: "Write token from the original IP (required)" },
+          },
+          required: ["writeToken"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "store": {
+        const { agentId, key, value, writeToken, sessionId, metadata, base } = 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");
+        const valueLimit = (args.base ? 2048 : 51200);
+        if (value.length > valueLimit) throw new McpError(ErrorCode.InvalidParams, `value max ${args.base ? '2KB (base)' : '50KB'}`);
+        if (metadata && JSON.stringify(metadata).length > 2048) throw new McpError(ErrorCode.InvalidParams, "metadata max 2KB");
+
+        const body = { agent_id: agentId, key, value, client_version: CLIENT_VERSION };
+        if (writeToken) body.write_token = writeToken;
+        if (base) body.base = true;
+        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,
+              update_hint: r.update_hint,
+            }, null, 2),
+          }],
+        };
+      }
+
+      case "search": {
+        const { agentId, query, writeToken, topK = 10, sessionId, cursor, includeBase } = 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, client_version: CLIENT_VERSION };
+        if (query) body.query = query;
+        if (sessionId) body.session_id = sessionId;
+        if (cursor) body.cursor = cursor;
+        if (includeBase) body.include_base = true;
+
+        // 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,
+                update_hint: r.update_hint,
+              }, 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,
+              update_hint: r.update_hint,
+            }, 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, client_version: CLIENT_VERSION };
+        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),
+          }],
+        };
+      }
+
+      case "bootstrap": {
+        const { agentId, writeToken, keys } = args;
+        if (!agentId || !writeToken) {
+          throw new McpError(ErrorCode.InvalidParams, "agentId and writeToken are required");
+        }
+        const body = { agent_id: agentId, write_token: writeToken, client_version: CLIENT_VERSION };
+        if (keys) body.keys = keys;
+        const result = await callFree("/api/memory/bootstrap", "POST", body);
+        if (result.status >= 400) {
+          throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(result.data)}`);
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
+      }
+
+      case "get": {
+        const { agentId, writeToken, key } = args;
+        if (!agentId || !writeToken || !key) {
+          throw new McpError(ErrorCode.InvalidParams, "agentId, writeToken, and key are required");
+        }
+        const result = await callFree("/api/memory/get", "POST", { agent_id: agentId, write_token: writeToken, key, client_version: CLIENT_VERSION });
+        if (result.status >= 400) {
+          throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(result.data)}`);
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
+      }
+
+      case "init": {
+        const { agentId, writeToken: providedToken, key = "init", value = "Memory01 initialized." } = args;
+        if (!agentId) {
+          throw new McpError(ErrorCode.InvalidParams, "agentId is required");
+        }
+
+        const home = os.homedir();
+        const tokenFile = path.join(home, ".memory01_token");
+        const recoveryFile = path.join(home, ".memory01_recovery");
+
+        // Step 1: get or create token
+        let token = providedToken;
+        let recoveryCode = null;
+        let isNew = false;
+        let storeResult = null;
+
+        if (!token) {
+          const r = await callFree("/api/memory/store", "POST", { agent_id: agentId, key, value, client_version: CLIENT_VERSION });
+          if (r.status === 403 && r.data && r.data.error === "token_required") {
+            throw new McpError(ErrorCode.InvalidParams, "A token already exists for this (IP, agent_id). Pass writeToken to init, or use recover if your IP changed.");
+          }
+          if (r.status >= 400) {
+            throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(r.data)}`);
+          }
+          token = r.data.write_token;
+          recoveryCode = r.data.recovery_code;
+          isNew = true;
+          storeResult = r.data;
+        }
+
+        // Step 2: write credential files (chmod 600)
+        const savedFiles = [];
+        if (isNew && token) {
+          try {
+            fs.writeFileSync(tokenFile, token + "\n", { mode: 0o600 });
+            savedFiles.push(tokenFile);
+          } catch (e) {
+            console.error("Could not write token file:", e);
+          }
+        }
+        if (isNew && recoveryCode) {
+          try {
+            fs.writeFileSync(recoveryFile, recoveryCode + "\n", { mode: 0o600 });
+            savedFiles.push(recoveryFile);
+          } catch (e) {
+            console.error("Could not write recovery file:", e);
+          }
+        }
+
+        // Step 3: bootstrap base memories (idempotent)
+        const bootstrapResult = await callFree("/api/memory/bootstrap", "POST", { agent_id: agentId, write_token: token, client_version: CLIENT_VERSION });
+
+        // Step 4: upsert credentials-location base memory pointing to the files
+        const credValue = `Token at ${tokenFile}, recovery at ${recoveryFile} (chmod 600). Do not store secrets in memory.`;
+        await callFree("/api/memory/store", "POST", { agent_id: agentId, write_token: token, key: "credentials-location", value: credValue, base: true, client_version: CLIENT_VERSION });
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ok: true,
+              new_token: isNew,
+              write_token: token,
+              recovery_code: recoveryCode,
+              credential_files: savedFiles,
+              bootstrap: bootstrapResult.data,
+              update_hint: storeResult && storeResult.update_hint,
+              guide: {
+                init_done: "Memory01 initialized. Token and recovery code saved to standard files (chmod 600). Base memories bootstrapped. credentials-location base memory stored.",
+                best_practices: [
+                  "Save write_token to ~/.memory01_token and recovery_code to ~/.memory01_recovery (chmod 600). Never store secrets in memory.",
+                  "Use upsert: re-store with the same key updates in place.",
+                  "Base memories (max 2KB) for context; use includeBase:true to load at session start.",
+                  "Bootstrap conventional keys: credentials-location (sensitive), user-preferences, user-details, code-style.",
+                  "Recovery: if IP changes, use recover(agentId, recoveryCode).",
+                  "Free tier: 30 searches/day, then $0.01 USDC. Store is always free.",
+              ],
+              next_steps: [
+                  "Use store(key, value) to save memories. Re-store with same key to update (upsert).",
+                  "Use search(query) for semantic search (free: 30/day). Use includeBase:true to load context at session start.",
+                  "Recovery: if your IP changes, call recover(agentId, recoveryCode) from the new host.",
+                  "Regenerate recovery code from original IP with regenerate_recovery(writeToken) if lost.",
+                  "Full guide: https://memory.node01.org/agents.md",
+                ],
+                standard_paths: { token: tokenFile, recovery: recoveryFile },
+              },
+            }, null, 2),
+          }],
+        };
+      }
+
+      case "guide": {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              init: "1) store a memory with agentId+key+value (omit writeToken on first call). 2) Save write_token AND recovery_code to ~/.memory01_token and ~/.memory01_recovery (chmod 600). 3) Store a base memory key='credentials-location' pointing to those files. 4) Use bootstrap to create conventional base memories.",
+              tools: ["store", "search", "bootstrap", "get", "recover", "regenerate_recovery", "subscribe", "health", "stats", "sample", "guide"],
+              base_memories: "Small (max 2KB) contextual memories. Excluded from normal search by default. Use includeBase:true to load them (e.g. at session start). Conventional keys: credentials-location (sensitive), user-preferences, user-details, code-style.",
+              recovery: "Token bound to (IP, agent_id). If IP changes, use recover(agentId, recoveryCode) to get a new token. Regenerate recovery code from original IP if lost. Save recovery_code offline.",
+              upsert: "Re-store with the same key updates in place (no duplicates). updated_at refreshed, stored_at preserved.",
+              limits: "key max 256, value max 50KB (2KB for base), metadata max 2KB, session_id max 128, top_k 1-20. Free: 30 searches/day, then $0.01 USDC.",
+              best_practices: [
+                "Save write_token to ~/.memory01_token and recovery_code to ~/.memory01_recovery (chmod 600). Never store secrets in memory.",
+                "Use upsert: re-store with the same key updates in place.",
+                "Base memories (max 2KB) for context; excluded from normal search, includeBase=true to load at session start.",
+                "Bootstrap conventional keys: credentials-location (sensitive), user-preferences, user-details, code-style.",
+                "Recovery: if IP changes, use recover(agentId, recoveryCode). Regenerate from original IP if lost.",
+                "Free tier: 30 searches/day, then $0.01 USDC. Store is always free.",
+                "Dense facts: memory is an index, not a file store.",
+                "Session scoping: use sessionId to scope to a project.",
+              ],
+              full_guide: "https://memory.node01.org/agents.md",
+            }, null, 2),
+          }],
+        };
+      }
+
+      case "recover": {
+        const { agentId, recoveryCode } = args;
+        if (!agentId || !recoveryCode) {
+          throw new McpError(ErrorCode.InvalidParams, "agentId and recoveryCode are required");
+        }
+        const result = await callFree("/api/memory/recover", "POST", { agent_id: agentId, recovery_code: recoveryCode, client_version: CLIENT_VERSION });
+        if (result.status >= 400) {
+          throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(result.data)}`);
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
+      }
+
+      case "regenerate_recovery": {
+        const { writeToken } = args;
+        if (!writeToken) {
+          throw new McpError(ErrorCode.InvalidParams, "writeToken is required");
+        }
+        const result = await callFree("/api/memory/recovery/regenerate", "POST", { write_token: writeToken, client_version: CLIENT_VERSION });
+        if (result.status >= 400) {
+          throw new McpError(ErrorCode.InternalError, `API error: ${JSON.stringify(result.data)}`);
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result.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));
+  }
+});
+
+// ============================= Version Check =============================
+async function checkLatestVersion() {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch("https://registry.npmjs.org/memory-agent-mcp/latest", { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) return;
+    const data = await res.json();
+    const latest = data.version;
+    const current = "1.3.1";
+    if (latest && latest !== current) {
+      console.error(`NOTE: memory-agent-mcp ${current} is installed; latest is ${latest}. Run 'npm install -g memory-agent-mcp@latest' to update.`);
+    }
+  } catch (e) {
+    // best-effort, ignore
+  }
+}
+
+async function main() {
+  checkLatestVersion(); // best-effort, non-blocking
+  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,43 @@
 {
   "name": "mem-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.4",
+  "description": "MCP wrapper for Memory01 agentic memory service - persistent memory for AI agents, free to store and search. Base memories, recovery codes, upsert, 50+ languages.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "memory-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "base",
+    "base-memory",
+    "mcp",
+    "memory",
+    "recovery",
+    "storage",
+    "upsert",
+    "x402"
+  ],
+  "author": "node01.org",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "viem": "^2.57.16"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geco/memory-agent-mcp.git"
+  },
+  "homepage": "https://github.com/geco/memory-agent-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/geco/memory-agent-mcp/issues"
+  }
+}