memory-agent-mcp 1.2.1 → 1.3.0

package/README.md

@@ -12,6 +12,14 @@ MCP wrapper for [Memory01](https://memory.node01.org) — agentic memory for AI
 - **Subscribe**: Subscription plans (Starter $2/500, Pro $9/mo, Enterprise $20/mo)
 - **Health / Stats / Sample**: Free utilities
 
+## 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
@@ -87,6 +95,9 @@ Add to your `opencode.json`:
 
 ## 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.
 

package/index.js

@@ -39,6 +39,9 @@ import {
 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";
@@ -274,6 +277,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           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.",
@@ -489,6 +511,105 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         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 });
+          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 });
+
+        // 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 });
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ok: true,
+              new_token: isNew,
+              write_token: token,
+              recovery_code: recoveryCode,
+              credential_files: savedFiles,
+              bootstrap: bootstrapResult.data,
+              guide: {
+                init_done: "Memory01 initialized. Token and recovery code saved to standard files (chmod 600). Base memories bootstrapped. credentials-location base memory stored.",
+                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.",
+              full_guide: "https://memory.node01.org/agents.md",
+            }, null, 2),
+          }],
+        };
+      }
+
       case "recover": {
         const { agentId, recoveryCode } = args;
         if (!agentId || !recoveryCode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-agent-mcp",
-  "version": "1.2.1",
+  "version": "1.3.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",