memory-agent-mcp 1.1.7 → 1.2.0

package/README.md

@@ -4,12 +4,13 @@ MCP wrapper for [Memory01](https://memory.node01.org) — agentic memory for AI
 
 ## Features
 
-- **Store**: Free memory storage (first call returns a write_token)
+- **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**: Service health check (free)
-- **Stats**: Global memory statistics (free)
-- **Sample**: Free demo (store + search)
+- **Health / Stats / Sample**: Free utilities
 
 ## Installation
 
@@ -27,11 +28,13 @@ Optional environment variables:
 - `MEMORY_PRIVATE_KEY` (optional: private key for x402 payment signing — enables paid operations beyond free tier)
 
 ### Free tier (no wallet needed)
-- Store memories: free
+- 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
@@ -46,9 +49,17 @@ environment variables.
 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.
-- If you lose the token, you cannot recover your memories. Create a new agent_id and start fresh.
-- If your IP changes, the token stops working. Create a new token.
-- Treat the write_token like a password. Never log it in plaintext.
+- 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:
+```
+key: "credentials-location"
+value: "Token and recovery code saved at /path/to/file (chmod 600). Do not store secrets in memory."
+```
 
 ### Agent docs
 Read the agent-facing guide first: https://memory.node01.org/agents.md
@@ -74,10 +85,22 @@ Add to your `opencode.json`:
 ## Tools
 
 ### store
-Store a memory. First call returns a write_token — save it! All future operations require it.
+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.
+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.

package/index.js

@@ -3,8 +3,12 @@
  * 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)
+ *   - 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)
@@ -184,7 +188,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     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.",
+        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: {
@@ -194,13 +198,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             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.",
+        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: {
@@ -210,6 +215,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             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"],
         },
@@ -242,6 +248,55 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         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: "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"],
+        },
+      },
     ],
   };
 });
@@ -252,16 +307,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     switch (name) {
       case "store": {
-        const { agentId, key, value, writeToken, sessionId, metadata } = args;
+        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");
-        if (value.length > 10240) throw new McpError(ErrorCode.InvalidParams, "value max 10KB");
+        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 };
         if (writeToken) body.write_token = writeToken;
+        if (base) body.base = true;
         if (sessionId) body.session_id = sessionId;
         if (metadata) body.metadata = metadata;
 
@@ -288,7 +345,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "search": {
-        const { agentId, query, writeToken, topK = 10, sessionId, cursor } = args;
+        const { agentId, query, writeToken, topK = 10, sessionId, cursor, includeBase } = args;
         if (!agentId || !writeToken) {
           throw new McpError(ErrorCode.InvalidParams, "agentId and writeToken are required");
         }
@@ -298,6 +355,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         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);
@@ -405,6 +463,56 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      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 };
+        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 });
+        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 "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 });
+        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 });
+        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}`);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memory-agent-mcp",
-  "version": "1.1.7",
-  "description": "MCP wrapper for Memory01 agentic memory service - persistent memory for AI agents, free to store and search",
+  "version": "1.2.0",
+  "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": {
@@ -12,13 +12,16 @@
     "test": "node test.js"
   },
   "keywords": [
-    "mcp",
-    "memory",
     "agent",
-    "x402",
     "ai",
     "base",
-    "storage"
+    "base-memory",
+    "mcp",
+    "memory",
+    "recovery",
+    "storage",
+    "upsert",
+    "x402"
   ],
   "author": "node01.org",
   "license": "MIT",