oh-memos-mcp 1.0.0 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to `oh-memos-mcp` are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [2.0.1] — 2026-08-02
+
+### Fixed
+
+- MCP `serverInfo` was hardcoded in `server.ts` and reported
+  `{name: "memos-memory", version: "1.0.1"}` — a name matching neither the
+  package (`oh-memos-mcp`) nor the conventional server key (`oh-memos`), and a
+  version that 2.0.0 shipped stale. Clients display this during the handshake.
+  It is now read from `package.json` at startup, so it cannot drift again.
+
+---
+
+## [2.0.0] — 2026-08-02
+
+### ⚠️ Breaking — tool surface consolidated from 18 to 10
+
+Eleven tools were merged into three dispatching tools. **There is no compatibility
+shim**: the MCP SDK only dispatches registered tools, so calling a removed name now
+returns `Unknown tool`.
+
+If your MCP client config pins tool names (e.g. Claude Code's `alwaysAllow` list),
+you must update it before upgrading.
+
+#### Migration
+
+| 1.x tool | 2.0 replacement |
+|----------|-----------------|
+| `memos_search_context` | `memos_search` — pass the `context` array (recent turns) |
+| `memos_get_graph` | `memos_graph(mode="related")` |
+| `memos_trace_path` | `memos_graph(mode="path")` |
+| `memos_impact` | `memos_graph(mode="impact")` |
+| `memos_export_schema` | `memos_graph(mode="schema")` |
+| `memos_list_cubes` | `memos_admin(action="list_cubes")` |
+| `memos_register_cube` | `memos_admin(action="register_cube")` |
+| `memos_create_user` | `memos_admin(action="create_user")` |
+| `memos_validate_cubes` | `memos_admin(action="validate_cubes")` |
+| `memos_get_stats` | `memos_admin(action="stats")` |
+| `memos_calendar` | `memos_admin(action="calendar")` |
+
+Unchanged: `memos_context_resume`, `memos_search`, `memos_save`, `memos_list_v2`,
+`memos_get`, `memos_suggest`, `memos_delete`.
+
+`alwaysAllow` for 2.0:
+
+```json
+"alwaysAllow": [
+  "memos_context_resume", "memos_search", "memos_save",
+  "memos_list_v2", "memos_get", "memos_suggest",
+  "memos_think", "memos_graph", "memos_admin", "memos_export_wiki"
+]
+```
+
+### Added
+
+- **`memos_think`** — evidence pack for a question. Runs semantic retrieval plus a
+  recent-72h temporal pass, deduplicates, and returns numbered evidence with graph
+  relationships between items, contradiction/evolution candidates, staleness
+  candidates, and gap analysis. Synthesis is deliberately left to the calling model;
+  the server emits no prose. Results can be persisted back as `SYNTHESIS`.
+- **`memos_export_wiki`** — export a cube as an interlinked markdown wiki: one page
+  per memory (YAML frontmatter, `[[wikilink]]` relations), plus `index.md` and a
+  mermaid `graph.md`. Only files carrying the generator marker are ever replaced;
+  foreign files in the output directory are preserved. Defaults to
+  `<project_path>/docs/memory-wiki`.
+- **`SYNTHESIS`** memory type, for answers synthesized from retrieved evidence.
+
+### Changed
+
+- Tool-surface cost dropped ~51%: `tools/list` payload 22.9 KB → 11.2 KB
+  (≈5850 → ≈2856 tokens). Shared `project_path` / `cube_id` parameter descriptions
+  were deduplicated; the full cube-routing rules are now stated once, on
+  `memos_save` and `memos_search`.
+- Runtime error `suggestions` now name the 2.0 call forms, so a model reading a
+  failure message is no longer told to call a tool that does not exist.
+
+### Fixed
+
+- `memos_admin`'s `cube_id` no longer carries a `MEMOS_DEFAULT_CUBE` default.
+  Previously, calling `register_cube` without `cube_id` would silently register the
+  default cube instead of failing.
+
+---
+
+## [1.0.0] — 2026-03-04
+
+Initial npm release. 18 tools, Node-only MCP server for oh-memos — no Python
+required, runs via `npx`.

package/README.md

@@ -1,71 +1,226 @@
 # oh-memos-mcp
 
-MCP Server for MemOS — Intelligent Memory Management for AI Assistants.
+[![npm version](https://img.shields.io/npm/v/oh-memos-mcp.svg)](https://www.npmjs.com/package/oh-memos-mcp)
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Node.js implementation. No Python required.
+MCP Server for **oh-memos** — Intelligent Persistent Memory for AI Assistants.
+
+Pure Node.js. No Python required. Works with `npx` out of the box.
+
+---
+
+## Prerequisites
+
+oh-memos backend API must be running before connecting this MCP server:
+
+- **oh-memos API** on `http://localhost:18000`
+- **Neo4j** on `localhost:7687` (Knowledge Graph)
+- **Qdrant** on `localhost:6333` (Vector Search)
+
+> Start all services: run `scripts\local\start.bat` from the [oh-memos repo](https://github.com/xigou/oh-memos).
+
+---
 
 ## Quick Start
 
+Add to your Claude Code `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "oh-memos": {
+      "command": "npx",
+      "args": ["-y", "oh-memos-mcp"],
+      "env": {
+        "MEMOS_URL": "http://localhost:18000",
+        "MEMOS_USER": "dev_user",
+        "MEMOS_DEFAULT_CUBE": "dev_cube",
+        "MEMOS_CUBES_DIR": "G:/test/oh-memos/data/oh-memos_cubes"
+      }
+    }
+  }
+}
+```
+
+Or use a `.env` file in your working directory (the server auto-discovers it):
+
+```bash
+cp node_modules/oh-memos-mcp/.env.example .env
+# Edit .env with your paths
+npx oh-memos-mcp
+```
+
+---
+
+## Configuration Examples
+
+### Linux / macOS
+
+```json
+{
+  "mcpServers": {
+    "oh-memos": {
+      "command": "npx",
+      "args": ["-y", "oh-memos-mcp"],
+      "env": {
+        "MEMOS_URL": "http://localhost:18000",
+        "MEMOS_USER": "dev_user",
+        "MEMOS_DEFAULT_CUBE": "dev_cube",
+        "MEMOS_CUBES_DIR": "/home/user/oh-memos/data/oh-memos_cubes"
+      }
+    }
+  }
+}
+```
+
+### Windows
+
 ```json
 {
   "mcpServers": {
-    "memos": {
+    "oh-memos": {
       "command": "npx",
       "args": ["-y", "oh-memos-mcp"],
       "env": {
         "MEMOS_URL": "http://localhost:18000",
         "MEMOS_USER": "dev_user",
         "MEMOS_DEFAULT_CUBE": "dev_cube",
-        "MEMOS_CUBES_DIR": "/path/to/data/memos_cubes"
+        "MEMOS_CUBES_DIR": "G:/test/oh-memos/data/oh-memos_cubes"
       }
     }
   }
 }
 ```
 
+### WSL2
+
+```json
+{
+  "mcpServers": {
+    "oh-memos": {
+      "command": "npx",
+      "args": ["-y", "oh-memos-mcp"],
+      "env": {
+        "MEMOS_URL": "http://localhost:18000",
+        "MEMOS_USER": "dev_user",
+        "MEMOS_DEFAULT_CUBE": "dev_cube",
+        "MEMOS_CUBES_DIR": "/mnt/g/test/oh-memos/data/oh-memos_cubes"
+      }
+    }
+  }
+}
+```
+
+### With `alwaysAllow` (skip per-tool confirmation)
+
+```json
+{
+  "mcpServers": {
+    "oh-memos": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "oh-memos-mcp"],
+      "env": {
+        "MEMOS_URL": "http://localhost:18000",
+        "MEMOS_USER": "dev_user",
+        "MEMOS_DEFAULT_CUBE": "dev_cube",
+        "MEMOS_CUBES_DIR": "/path/to/oh-memos/data/oh-memos_cubes",
+        "MEMOS_ENABLE_DELETE": "true"
+      },
+      "alwaysAllow": [
+        "memos_context_resume",
+        "memos_search",
+        "memos_search",
+        "memos_save",
+        "memos_list_v2",
+        "memos_get",
+        "memos_suggest",
+        "memos_admin(action=list_cubes)",
+        "memos_admin(action=stats)",
+        "memos_graph(mode=related)",
+        "memos_graph(mode=path)",
+        "memos_graph(mode=schema)",
+        "memos_admin(action=register_cube)",
+        "memos_admin(action=create_user)",
+        "memos_admin(action=validate_cubes)",
+        "memos_graph(mode=impact)",
+        "memos_admin(action=calendar)",
+        "memos_delete"
+      ]
+    }
+  }
+}
+```
+
+---
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `MEMOS_URL` | Yes | — | MemOS API base URL |
+| `MEMOS_URL` | Yes | — | oh-memos API base URL |
 | `MEMOS_USER` | Yes | — | Default user ID |
 | `MEMOS_DEFAULT_CUBE` | Yes | — | Default memory cube ID |
-| `MEMOS_CUBES_DIR` | Yes | — | Path to cubes storage directory |
-| `NEO4J_HTTP_URL` | No | — | Neo4j HTTP endpoint for graph queries |
+| `MEMOS_CUBES_DIR` | Yes | — | Absolute path to cubes storage directory |
+| `MEMOS_TIMEOUT_TOOL` | No | `300` | Tool call timeout (seconds) |
+| `MEMOS_TIMEOUT_STARTUP` | No | `30` | API startup wait timeout (seconds) |
+| `MEMOS_TIMEOUT_HEALTH` | No | `5` | Health check timeout (seconds) |
+| `MEMOS_API_WAIT_MAX` | No | `60` | Max time to wait for API on startup (seconds) |
+| `MEMOS_ENABLE_DELETE` | No | `false` | Enable `memos_delete` tool |
+| `NEO4J_HTTP_URL` | No | — | Neo4j HTTP endpoint (for direct graph queries) |
 | `NEO4J_USER` | No | — | Neo4j username |
 | `NEO4J_PASSWORD` | No | — | Neo4j password |
-| `MEMOS_ENABLE_DELETE` | No | `false` | Enable delete functionality |
-
-## Tools (18)
-
-- **memos_save** — Save memories with explicit type classification
-- **memos_search** — Semantic search with keyword reranking
-- **memos_search_context** — Context-aware search with conversation history
-- **memos_list_v2** — List memories with compaction
-- **memos_get** — Get full memory details by ID
-- **memos_get_stats** — Memory type statistics
-- **memos_suggest** — Smart search suggestions
-- **memos_context_resume** — Recover context after compaction
-- **memos_trace_path** — Trace reasoning paths between memories
-- **memos_get_graph** — Knowledge graph with relationships
-- **memos_export_schema** — Graph schema and statistics
-- **memos_impact** — Forward blast radius analysis
-- **memos_calendar** — Calendar view (project/student modes)
-- **memos_list_cubes** — List available memory cubes
-- **memos_register_cube** — Register a cube with the API
-- **memos_create_user** — Create a MemOS user
-- **memos_validate_cubes** — Validate and fix cube configs
-- **memos_delete** — Delete memories (disabled by default)
+
+> **Tip**: `.env` file in your working directory is loaded automatically with highest priority.
+> Copy `.env.example` to get started.
+
+---
+
+## Tools (10)
+
+| Tool | Description |
+|------|-------------|
+| `memos_context_resume` | Recover project context after compaction (recent 24h + project state) |
+| `memos_search` | Semantic search with keyword reranking. Pass `context` (recent turns) to enable LLM intent analysis and query expansion |
+| `memos_save` | Save memories with explicit type (BUGFIX, DECISION, MILESTONE, SYNTHESIS…) |
+| `memos_list_v2` | List memories with auto-compaction |
+| `memos_get` | Get full memory details by ID |
+| `memos_suggest` | Smart search query suggestions + `memory_type` decision tree |
+| `memos_think` | Evidence pack for a question: retrieval + contradiction/staleness flags + gap analysis. The caller synthesizes the answer and may persist it as `SYNTHESIS` |
+| `memos_graph` | Knowledge graph queries — `mode`: `related` / `path` / `impact` / `schema` |
+| `memos_admin` | Maintenance — `action`: `list_cubes` / `register_cube` / `create_user` / `validate_cubes` / `stats` / `calendar` |
+| `memos_export_wiki` | Export a cube as an interlinked markdown wiki (page per memory + index + mermaid graph) |
+
+Plus `memos_delete`, hidden from `tools/list` unless `MEMOS_ENABLE_DELETE=true`.
+
+---
+
+## How .env Loading Works
+
+Priority order (highest first):
+
+1. **`process.cwd()/.env`** — your project working directory
+2. **Package root `.env`** — where oh-memos-mcp is installed
+3. **dotenv default search** — walks up from cwd
+
+This means you can place a `.env` in your project root and `npx oh-memos-mcp` will pick it up automatically — no need to repeat env vars in every MCP config.
+
+---
 
 ## Development
 
 ```bash
+git clone https://github.com/xigou/oh-memos.git
+cd oh-memos/mcp-server-node
 npm install
 npm run dev    # Run with tsx (no build needed)
 npm run build  # Compile to dist/
 ```
 
+---
+
 ## Requirements
 
 - Node.js >= 18.0.0
-- MemOS backend API running (Python FastAPI, port 18000)
+- oh-memos backend API running (`scripts\local\start.bat`)

package/dist/config.js

@@ -153,6 +153,7 @@ export const MEMORY_TYPES = new Set([
     "CODE_PATTERN",
     "GOTCHA",
     "PROGRESS",
+    "SYNTHESIS",
 ]);
 // ============================================================================
 // Helper

package/dist/cube-manager.js

@@ -153,6 +153,120 @@ function updateConfigForCube(config, cubeId) {
     }
     return config;
 }
+// Fallback cube config built from environment variables — ported from the Python
+// server's _build_fallback_cube_config. Throws a descriptive error when a required
+// var is missing (caller surfaces it), instead of silently producing a broken cube.
+function requireEnv(key) {
+    const v = process.env[key]?.trim();
+    if (!v)
+        throw new Error(`${key} is required to build a fallback cube config (set ${key} in .env)`);
+    return v;
+}
+function envFloat(key) {
+    const n = Number(requireEnv(key));
+    if (Number.isNaN(n))
+        throw new Error(`${key} must be a number`);
+    return n;
+}
+function envInt(key) {
+    const n = parseInt(requireEnv(key), 10);
+    if (Number.isNaN(n))
+        throw new Error(`${key} must be an int`);
+    return n;
+}
+// Optional boolean switches — fall back to a sane default when unset, so a cube
+// can still be built in environments that don't define every strategy flag
+// (missing BM25_CALL/VEC_COT_CALL/NEO4J_* switches must not fail registration).
+function envBool(key, def) {
+    const v = process.env[key]?.trim().toLowerCase();
+    if (v === undefined || v === "")
+        return def;
+    return v === "true" || v === "1" || v === "yes";
+}
+function buildFallbackCubeConfig(cubeId) {
+    const openaiConfig = {
+        model_name_or_path: requireEnv("MOS_CHAT_MODEL"),
+        temperature: envFloat("MOS_CHAT_TEMPERATURE"),
+        max_tokens: envInt("MOS_MAX_TOKENS"),
+        top_p: envFloat("MOS_TOP_P"),
+        top_k: envInt("MOS_TOP_K"),
+        remove_think_prefix: true,
+        api_key: requireEnv("OPENAI_API_KEY"),
+        api_base: requireEnv("OPENAI_API_BASE"),
+    };
+    const embedderConfig = {
+        backend: requireEnv("MOS_EMBEDDER_BACKEND"),
+        config: {
+            provider: requireEnv("MOS_EMBEDDER_PROVIDER"),
+            api_key: requireEnv("OPENAI_API_KEY"),
+            model_name_or_path: requireEnv("MOS_EMBEDDER_MODEL"),
+            base_url: process.env.MOS_EMBEDDER_API_BASE?.trim() || requireEnv("OPENAI_API_BASE"),
+            embedding_dims: envInt("EMBEDDING_DIMENSION"),
+        },
+    };
+    const neo4jBackend = requireEnv("NEO4J_BACKEND").toLowerCase();
+    let graphConfig;
+    if (neo4jBackend === "neo4j") {
+        graphConfig = {
+            uri: requireEnv("NEO4J_URI"),
+            user: requireEnv("NEO4J_USER"),
+            db_name: requireEnv("NEO4J_DB_NAME"),
+            password: requireEnv("NEO4J_PASSWORD"),
+            auto_create: envBool("NEO4J_AUTO_CREATE", false),
+            use_multi_db: envBool("NEO4J_USE_MULTI_DB", false),
+            user_name: cubeId,
+            embedding_dimension: envInt("EMBEDDING_DIMENSION"),
+        };
+    }
+    else {
+        const qdrantUrl = process.env.QDRANT_URL?.trim() || null;
+        graphConfig = {
+            uri: requireEnv("NEO4J_URI"),
+            user: requireEnv("NEO4J_USER"),
+            db_name: requireEnv("NEO4J_DB_NAME"),
+            password: requireEnv("NEO4J_PASSWORD"),
+            user_name: cubeId,
+            auto_create: false,
+            use_multi_db: false,
+            embedding_dimension: envInt("EMBEDDING_DIMENSION"),
+            vec_config: {
+                backend: "qdrant",
+                config: {
+                    collection_name: `${cubeId}_graph`,
+                    vector_dimension: envInt("EMBEDDING_DIMENSION"),
+                    distance_metric: "cosine",
+                    host: qdrantUrl ? null : requireEnv("QDRANT_HOST"),
+                    port: qdrantUrl ? null : envInt("QDRANT_PORT"),
+                    path: process.env.QDRANT_PATH?.trim() || null,
+                    url: qdrantUrl,
+                    api_key: process.env.QDRANT_API_KEY?.trim() || null,
+                },
+            },
+        };
+    }
+    return {
+        model_schema: "memos.configs.mem_cube.GeneralMemCubeConfig",
+        user_id: MEMOS_USER,
+        cube_id: cubeId,
+        config_filename: "config.json",
+        text_mem: {
+            backend: "tree_text",
+            config: {
+                extractor_llm: { backend: "openai", config: openaiConfig },
+                dispatcher_llm: { backend: "openai", config: openaiConfig },
+                embedder: embedderConfig,
+                graph_db: { backend: neo4jBackend, config: graphConfig },
+                reorganize: envBool("MOS_ENABLE_REORGANIZE", false),
+                search_strategy: {
+                    bm25: envBool("BM25_CALL", false),
+                    cot: envBool("VEC_COT_CALL", false),
+                },
+            },
+        },
+        act_mem: {},
+        para_mem: {},
+    };
+}
 function buildCubeConfig(cubeId) {
     const templatePath = getCubePath(MEMOS_DEFAULT_CUBE);
     if (templatePath !== null) {
@@ -166,15 +280,9 @@ function buildCubeConfig(cubeId) {
             logger.warning(`Failed to read template cube config: ${err}`);
         }
     }
-    // Minimal fallback config (will likely fail API registration without proper fields)
-    return {
-        user_id: MEMOS_USER,
-        cube_id: cubeId,
-        config_filename: "config.json",
-        text_mem: {},
-        act_mem: {},
-        para_mem: {},
-    };
+    // No usable template — build a complete config from env (throws with a clear
+    // message if required vars are missing; caller reports it as a registration error).
+    return buildFallbackCubeConfig(cubeId);
 }
 export function validateAndFixCubeConfig(cubeId, configPath) {
     try {
@@ -249,7 +357,7 @@ export function ensureCubeDirectory(cubeId) {
 // ============================================================================
 export async function verifyCubeLoaded(cubeId) {
     try {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/memories?user_id=${encodeURIComponent(MEMOS_USER)}&mem_cube_id=${encodeURIComponent(cubeId)}`, { method: "GET", timeoutMs: 5 });
+        const response = await fetchWithTimeout(`${MEMOS_URL}/memories?user_id=${encodeURIComponent(MEMOS_USER)}&mem_cube_id=${encodeURIComponent(cubeId)}&limit=1`, { method: "GET", timeoutMs: 5 });
         if (response.ok) {
             const data = await response.json();
             return data.code === 200;
@@ -281,17 +389,8 @@ export async function ensureCubeRegistered(cubeId, force = false) {
         // Get or create cube path
         let cubePath = getCubeApiPath(cubeId);
         if (!cubePath) {
-            // Try to auto-create
+            // Try to auto-create (ensureCubeDirectory handles both template-clone and fallback)
             logger.debug(`Cube '${cubeId}' not found, attempting auto-creation...`);
-            const templatePath = getCubePath(MEMOS_DEFAULT_CUBE);
-            if (!templatePath) {
-                const available = listAvailableCubes();
-                const availableIds = available.map((c) => c.id);
-                if (availableIds.length > 0) {
-                    return [false, `Cube '${cubeId}' not found. Available cubes: ${availableIds.join(", ")}`];
-                }
-                return [false, `Cube '${cubeId}' not found and no cubes available.`];
-            }
             const [newDir, createErr] = ensureCubeDirectory(cubeId);
             if (!newDir) {
                 return [false, `Failed to auto-create cube '${cubeId}': ${createErr}`];

package/dist/handlers/admin.d.ts

@@ -1,8 +1,8 @@
 /**
  * Admin Handlers
  *
- * memos_list_cubes, memos_register_cube, memos_create_user,
- * memos_validate_cubes, memos_delete
+ * memos_admin(action="list_cubes"), memos_admin(action="register_cube"), memos_admin(action="create_user"),
+ * memos_admin(action="validate_cubes"), memos_delete
  */
 import type { TextContent } from "../types.js";
 export declare function handleMemosListCubes(arguments_: Record<string, unknown>): Promise<TextContent[]>;

package/dist/handlers/admin.js

@@ -1,17 +1,17 @@
 /**
  * Admin Handlers
  *
- * memos_list_cubes, memos_register_cube, memos_create_user,
- * memos_validate_cubes, memos_delete
+ * memos_admin(action="list_cubes"), memos_admin(action="register_cube"), memos_admin(action="create_user"),
+ * memos_admin(action="validate_cubes"), memos_delete
  */
 import * as fs from "fs";
 import * as path from "path";
 import { MEMOS_URL, MEMOS_USER, MEMOS_DEFAULT_CUBE, MEMOS_CUBES_DIR, MEMOS_ENABLE_DELETE, MEMOS_TIMEOUT_TOOL, registeredCubes, } from "../config.js";
 import { fetchWithTimeout } from "../api-client.js";
-import { ensureCubeRegistered, getCubePath, getCubesBaseDir, getLocalCubesBaseDir, listAvailableCubes, validateAndFixCubeConfig, verifyCubeLoaded, } from "../cube-manager.js";
+import { ensureCubeDirectory, ensureCubeRegistered, getCubePath, getCubesBaseDir, getLocalCubesBaseDir, listAvailableCubes, validateAndFixCubeConfig, verifyCubeLoaded, } from "../cube-manager.js";
 import { ERR_CUBE_NOT_FOUND, ERR_DELETE_DISABLED, ERR_PARAM_MISSING, apiErrorResponse, cubeRegistrationError, errorResponse, getCubeIdFromArgs, } from "./utils.js";
 // ============================================================================
-// memos_list_cubes
+// memos_admin(action="list_cubes")
 // ============================================================================
 export async function handleMemosListCubes(arguments_) {
     const includeStatus = arguments_.include_status === true;
@@ -42,30 +42,35 @@ export async function handleMemosListCubes(arguments_) {
         }
     }
     result.push(`\n**Default cube**: \`${MEMOS_DEFAULT_CUBE}\``);
-    result.push("\n*Use `memos_list_cubes(include_status=True)` to check registration status.*");
+    result.push('\n*Use `memos_admin(action="list_cubes", include_status=true)` to check registration status.*');
     return [{ type: "text", text: result.join("\n") }];
 }
 // ============================================================================
-// memos_register_cube
+// memos_admin(action="register_cube")
 // ============================================================================
 export async function handleMemosRegisterCube(arguments_) {
     const cubeId = String(arguments_.cube_id ?? "");
     let cubePath = arguments_.cube_path ? String(arguments_.cube_path) : undefined;
     if (!cubeId) {
         return errorResponse("cube_id parameter is required", ERR_PARAM_MISSING, [
-            "Use memos_list_cubes() to find available cubes",
-            '`memos_register_cube(cube_id="dev_cube")`',
+            'Use memos_admin(action="list_cubes") to find available cubes',
+            '`memos_admin(action="register_cube", cube_id="dev_cube")`',
         ]);
     }
     if (!cubePath) {
-        // Try to find cube path (returns Windows/original path for API)
-        const localPath = getCubePath(cubeId);
+        // Try to find cube path, or auto-create if not found
+        let localPath = getCubePath(cubeId);
         if (!localPath) {
-            const available = listAvailableCubes();
-            const hint = available.length > 0
-                ? `\n\n**Available cubes:**\n${available.map((c) => `- \`${c.id}\``).join("\n")}`
-                : "";
-            return [{ type: "text", text: `❌ Cube \`${cubeId}\` not found in cubes directory.\n\nCubes directory: \`${getCubesBaseDir()}\`${hint}` }];
+            // Auto-create cube directory with config
+            const [newDir, createErr] = ensureCubeDirectory(cubeId);
+            if (!newDir) {
+                const available = listAvailableCubes();
+                const hint = available.length > 0
+                    ? `\n\n**Available cubes:**\n${available.map((c) => `- \`${c.id}\``).join("\n")}`
+                    : "";
+                return errorResponse(`Cube \`${cubeId}\` not found and auto-creation failed: ${createErr}`, ERR_CUBE_NOT_FOUND, [`Cubes directory: \`${getCubesBaseDir()}\`${hint}`]);
+            }
+            localPath = newDir;
         }
         // Convert back to Windows path if needed
         const cubesDir = MEMOS_CUBES_DIR;
@@ -114,7 +119,7 @@ export async function handleMemosRegisterCube(arguments_) {
                     hint = "Edit the cube's config.json and change `reranker.backend` to `http_bge` or `noop`.";
                 }
                 else if (errorMsg.toLowerCase().includes("user")) {
-                    hint = "Use `memos_create_user` tool to create the user first.";
+                    hint = 'Use `memos_admin(action="create_user")` to create the user first.';
                 }
                 return errorResponse(`Registration failed: ${errorMsg}`, errorMsg.toLowerCase().includes("not found") ? ERR_CUBE_NOT_FOUND : undefined, hint ? [hint] : []);
             }
@@ -128,7 +133,7 @@ export async function handleMemosRegisterCube(arguments_) {
     }
 }
 // ============================================================================
-// memos_create_user
+// memos_admin(action="create_user")
 // ============================================================================
 export async function handleMemosCreateUser(arguments_) {
     const userId = String(arguments_.user_id ?? MEMOS_USER);
@@ -173,7 +178,7 @@ export async function handleMemosCreateUser(arguments_) {
     }
 }
 // ============================================================================
-// memos_validate_cubes
+// memos_admin(action="validate_cubes")
 // ============================================================================
 export async function handleMemosValidateCubes(arguments_) {
     const fixIssues = arguments_.fix !== false; // Default true

package/dist/handlers/arg-contract.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Parameter contract — disclose arguments the schema silently discarded.
+ *
+ * zod strips keys it does not declare. That is a sane default for a validator
+ * and a bad one for a memory server: a call carrying `path="/mnt/g/foo"`
+ * instead of `project_path` validates cleanly, loses the key, falls back to the
+ * default cube, searches the wrong project, and returns nothing. The model then
+ * reads that empty result as "this project has no memories" — a wrong answer
+ * with no error anywhere in the chain. (This is how `dev_cube` accumulated
+ * memories belonging to other projects.)
+ *
+ * So: capture the argument keys as they arrive at the transport, before zod
+ * touches them, and say plainly which ones were dropped.
+ *
+ * The call is never rejected. An unknown key has always been accepted, and
+ * turning a recoverable mistake into a hard failure trades a slightly wrong
+ * answer for no answer at all. Disclosure lets the model correct itself on the
+ * next call; rejection just ends the conversation with the memory store.
+ */
+export declare function recordRawArgKeys(requestId: unknown, args: unknown): void;
+export interface ArgContractResult {
+    /** Keys the caller sent that the schema does not declare (and so discarded). */
+    ignored: string[];
+    /** Whether any ignored key looks like it was meant to route the cube. */
+    affectsRouting: boolean;
+    /** Human-readable warning, or null when everything was declared. */
+    warning: string | null;
+}
+export declare function checkArgContract(toolName: string, requestId: unknown): ArgContractResult;
+//# sourceMappingURL=arg-contract.d.ts.map