oh-memos-mcp 3.1.7 → 3.1.9

package/CHANGELOG.md

@@ -4,7 +4,71 @@ All notable changes to `oh-memos-mcp` are documented here.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
----
+---
+
+## [3.1.9] - 2026-09-16
+
+配套 API / Docker 镜像版本为 3.1.9。保存先确认原文与向量已持久化，再返回记忆 ID；
+LLM 解析由 API 在后台自动完成，即使模型调用耗时数分钟，也不阻塞 MCP 保存回执。
+
+- 识别 `vector_saved` 与 `enrichment_status`，明确显示向量已保存和后台解析状态，兼容旧 API。
+- 未确认向量保存或缺少实际 ID 时返回 MCP `isError: true`，且不写入去重缓存。
+- 请求和响应正文超时归类为 `API_TIMEOUT`，不再误报 API 离线；结果未知的 POST 不自动重放。
+- 显式传递 `memory_type`；Wiki 导入同样拒绝未确认的向量写入。
+- 完整详情使用原始创建时间，避免将后台解析的更新时间误标为创建时间。
+
+验证：582 项 Node 测试、旧版及 v2 MCP 协议检查通过。配套 API 的 118 项 Python 回归通过。
+真实 MCP 首次保存 596ms 返回，LLM 约 225 秒后补齐同一 ID 的元数据；重复保存 362ms，
+原文、ID 和已有解析结果均保留。
+
+## [3.1.8] - 2026-08-27
+
+仅 MCP server（npm `oh-memos-mcp`）。Python 包与容器镜像无改动，仍为 3.1.5。
+
+### 🏷️ `memos_get` 报 root 无权限，而 root 从未被传入
+
+`memos_get` 打自己项目的 cube 时回：
+
+```
+❌ [API_ERROR] Get failed: User 'root' does not have access to cube
+   'jincaizhaopin_cube'. Please register the cube first or request access.
+```
+
+但 `MEMOS_USER=dev_user`，root 不在任何调用参数里。
+
+root 来自后端的默认回退：`start_api.py` 的 `get_memory(mem_cube_id, memory_id,
+user_id=None)` 把 `user_id` 声明为可选，缺失时 `core.py` 的 `get()` 回退到
+`self.user_id`（MOS 实例自己的用户，即 root）。而 `ensureCubeRegistered` 注册的是
+`MEMOS_USER`，于是 root 对该 cube 无授权，`_validate_cube_access` 抛 ValueError，
+被 ValueError handler 映射成 400。
+
+**`handleMemosGet` 是唯一漏传 `user_id` 的调用点** —— save / list / search /
+stats / calendar / siblings 全都传了，admin 的 delete 路径也拼了查询串。
+
+`apiCallWithRetry` 的 400 分支救不回来：它把 400 当「cube 未加载」，重注册后重试
+—— 但重注册仍按 `MEMOS_USER` 注册，重试请求仍然不带 `user_id`，第二次照样落到 root。
+
+实测对照（同一个不存在的 id，`jincaizhaopin_cube`）：
+
+```
+不带 user_id        -> User 'root' does not have access to cube 'jincaizhaopin_cube'
+带 user_id=dev_user -> Memory with ID ... not found        ← 正常语义
+```
+
+为什么以前没人踩到：cube 的**归属**决定是否触发。root 名下的 cube（`dev_cube`、
+`claude_cube`、`memos_cube` 等）不受影响；只有 owner 是 `MEMOS_USER` 的项目 cube
+才会报错 —— 也就是每一个用 `project_path` 自动派生出来的 cube。
+
+同源缺陷也修了 `wiki-import.ts` 的 `getStoredMemory`。那里更隐蔽：该消息既不含
+`not found` 也不是 404，会被当成真实故障，把整页 import 判成失败而不是「记忆不存在」。
+
+`apiErrorResponse` 另加了对 `does not have access` 的识别。该消息同时含 `user` 和
+cube 字样，却不匹配任何既有分支，此前只能给通用的「查 health / 看日志」。新提示先
+指向 `user_id`，因为最常见的成因是调用方漏传它，而不是用户或 cube 不存在。
+
+回归测试 `get-user-id-param.test.ts` 的 fetch stub **按 `user_id` 是否存在分流**
+应答，复刻上面的实测对照。无条件回 not-found 的 stub 守不住这个缺陷 —— 变异验证
+（把 params 改回 `{}`）时三条断言必须全红，写测试时实际拿它验过。
 
 ## [3.1.7] - 2026-08-27
 
@@ -50,7 +114,7 @@ export function canvasName(prefix: string, goal: string): string {
 
 ### 🧪 测试
 
-canvas-format 单测 41 → 50，canvas e2e 31 → 36 项。
+canvas-format 单测 41 → 50，canvas e2e 34 → 40 项。
 
 核心断言是**不动点**而不是长度：`slugify(canvasName(p, g)) === canvasName(p, g)`，
 跨 3 个前缀 × 6 种 goal（超长、纯 CJK、尾部连字符诱饵、前 60 字符相同的两个变体）。
@@ -66,7 +130,7 @@ e2e 补的 5 项跨 open/list/show/delete 与磁盘：`open` 报的名字必须
 它们守的是「如果有人改用『让 `canvasPath` 对有损名字抛错』来修这个缺陷，
 这条回归会被抓到」，不是这次的不变量。
 
-门禁：vitest 520 passed、tsc、canvas e2e 36 项、pack 契约 104 文件、
+门禁：vitest 520 passed、tsc、canvas e2e 40 项、pack 契约 104 文件、
 schema budget +0.8%、semantic 快照 17 工具、protocol legacy + v2、
 lite smoke、host-env smoke、spread smoke。
 
@@ -137,7 +201,7 @@ commit message 或记忆正文引用的 `001-N3` 会变得指向两个不同画
 
 ### 🧪 测试
 
-canvas 单测 41 → 45（format）、28 → 44（store），canvas e2e 15 → 31 项。
+canvas 单测 41 → 45（format）、28 → 44（store），canvas e2e 18 → 34 项。
 两个修复都做了反向验证，还原实现后对应用例确实变红：转义 3 项、水位线 1 项（含 delete 侧那次抬升）。
 
 e2e 补了「旧 cube（无水位线）删除后不复用前缀」这条真实升级路径 ——
@@ -150,7 +214,7 @@ e2e 补了「旧 cube（无水位线）删除后不复用前缀」这条真实
 两处冻结的哈希同步重算：`schema-semantic-baseline.json` 与
 `protocol-contract.test.ts` 的 `EXPECTED_SCHEMA_HASHES`。
 
-门禁：vitest 511 passed、tsc、canvas e2e 31 项、pack 契约 104 文件、
+门禁：vitest 511 passed、tsc、canvas e2e 34 项、pack 契约 104 文件、
 schema budget +0.8%（限 5%）、semantic 快照 17 工具、protocol v2、lite smoke。
 
 ---

package/README.md

@@ -240,9 +240,36 @@ be deleted without a prompt; add it only if you have decided you want that.
 | `MEMOS_PROVIDER` | No | `local` when `MEMOS_MODE=lite`, else `api` | Storage backend. Set explicitly only to override the mode-derived default |
 | `MEMOS_LOG_LEVEL` | No | `info` | `debug` / `info` / `warning` / `error`. Logs go to stderr so they never corrupt the stdio JSON-RPC stream |
 
-`MEMOS_URL` is required for Full mode and unused in Lite.
-
-### Retrieval behaviour (3.1.x)
+`MEMOS_URL` is required for Full mode and unused in Lite.
+
+### Save acknowledgement and background parsing
+
+In Full mode with the `tree_text` backend, `memos_save` returns after the
+original text and its vector have been confirmed in storage. LLM extraction
+continues in the background, even when a model call takes several minutes.
+The response contains the stored ID; the API adds `vector_saved: true`,
+`enrichment_status: "pending"`, and `queued: false`. Here `queued` describes
+the memory write, which has already completed.
+
+Parsing adds the key, tags, background, and extracted facts to that same record.
+It preserves the original text, vector, ID, creation time, and explicit source
+metadata. Graph conflict handling links these originals instead of merging or
+deleting them. Identical retries target the same ID.
+
+Two background consumers process persisted tasks. A failed parse leaves the
+saved memory available and retries after 30 and 60 seconds; three completed
+failed attempts stop automatic retries. Interrupted attempts can resume after
+restart, including local projects restored from the cube registry. Parse status
+and the exception type are stored as `enrichment_*` metadata.
+
+This API path does not depend on `MOS_TYPED_SAVE_FAST` or the memory scheduler.
+Existing library, chat/document ingestion, and Lite behavior remain available.
+Upgrade/restart the API and reconnect MCP clients after rebuilding the Node
+server. Older APIs without the additive fields remain compatible. An explicit
+unconfirmed vector result is rejected; response timeouts report `API_TIMEOUT`
+and do not automatically replay writes.
+
+### Retrieval behaviour (3.1.x)
 
 These change what search returns. All are off or conservative by default, so
 upgrading never silently changes ranking.
@@ -250,7 +277,7 @@ upgrading never silently changes ranking.
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `MEMOS_SPREAD_ACTIVATION` | No | `false` | One-hop graph spreading activation. When on, a search also returns memories reachable from its direct hits over `CAUSE` / `CONDITION` / `RELATE` edges, annotated ` · via CAUSE from <first 8 chars of the source id>`. Full mode only — it queries Neo4j directly, so `NEO4J_HTTP_URL`, `NEO4J_USER`, and `NEO4J_PASSWORD` must all resolve |
-| `MEMOS_SHOW_WORKING_MEMORY` | No | `false` | Show the scheduler's `WorkingMemory` tier. The backend writes each memory twice — one short-term copy plus one long-term graph node with identical content — so leaving this off is what stops every memory appearing in pairs. Debugging only |
+| `MEMOS_SHOW_WORKING_MEMORY` | No | `false` | Show the scheduler's `WorkingMemory` tier. Chat/document and legacy ingestion can create short-term copies alongside long-term memories; hiding this tier avoids displaying those pairs. Vector-first content saves create one original record. Debugging only |
 | `MEMOS_AUTO_CAPTURE` | No | `false` | Accept auto-captured memories. Auto-captured records are also ranked below explicit saves |
 
 > **Spreading activation degrades silently without Neo4j credentials.** Retrieval

package/dist/api-client.d.ts

@@ -3,6 +3,19 @@
  *
  * HTTP fetch wrapper with timeout, retry, and health check.
  */
+/** A response deadline does not prove the API is offline or a write failed. */
+export declare function isApiTimeoutError(error: unknown): boolean;
+/** Return true when an exception means the HTTP peer could not be reached. */
+export declare function isApiUnreachableError(error: unknown): boolean;
+/** Return true only when no request body could have reached the peer. */
+export declare function isSafeApiAliasFallbackError(error: unknown): boolean;
+/** Add the IPv4 loopback alias for clients whose resolver prefers IPv6. */
+export declare function apiUrlCandidates(url: string): string[];
+/** Join an API path to the configured base without losing its prefix/query. */
+export declare function apiUrl(path?: string, base?: string): string;
+export declare function apiHealthUrl(base?: string, detail?: boolean): string;
+/** Remove credentials and query values before an endpoint is shown to a client. */
+export declare function apiUrlForDisplay(url?: string): string;
 export declare function fetchWithTimeout(url: string, options?: RequestInit & {
     timeoutMs?: number;
 }): Promise<Response>;

package/dist/api-client.js

@@ -3,25 +3,296 @@
  *
  * HTTP fetch wrapper with timeout, retry, and health check.
  */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { release as osRelease } from "node:os";
 import { MEMOS_URL, MEMOS_API_WAIT_MAX, MEMOS_TIMEOUT_HEALTH, MEMOS_TIMEOUT_TOOL, logger, registeredCubes, } from "./config.js";
 // ============================================================================
 // Fetch with Timeout
 // ============================================================================
+const API_NETWORK_ERROR_CODES = [
+    "ECONNREFUSED",
+    "ECONNABORTED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENETDOWN",
+    "ENETUNREACH",
+    "EHOSTDOWN",
+    "EHOSTUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EADDRNOTAVAIL",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CONNECT_TIMEOUT",
+];
+// These failures happen before an HTTP request can be delivered. They are the
+// only network errors safe to replay for a non-idempotent method.
+const API_ALIAS_SAFE_ERROR_CODES = [
+    "ECONNREFUSED",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EADDRNOTAVAIL",
+    "UND_ERR_CONNECT_TIMEOUT",
+];
+let discoveredWslHosts;
+function isWslRuntime() {
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP)
+        return true;
+    if (process.platform !== "linux")
+        return false;
+    const kernel = osRelease().toLowerCase();
+    return kernel.includes("microsoft") || kernel.includes("wsl");
+}
+function normalizeDiscoveredHost(value) {
+    const host = value.trim().replace(/^\[|\]$/g, "").replace(/%[^/]+$/, "");
+    if (!host ||
+        host === "localhost" ||
+        host === "::1" ||
+        host === "0.0.0.0" ||
+        /^127(?:\.[0-9]+){3}$/.test(host)) {
+        return undefined;
+    }
+    return host.includes(":") ? `[${host}]` : host;
+}
+function discoverWslHosts() {
+    if (discoveredWslHosts)
+        return discoveredWslHosts;
+    const hosts = new Set(["host.docker.internal"]);
+    try {
+        const resolvConf = readFileSync("/etc/resolv.conf", "utf8");
+        for (const line of resolvConf.split(/\r?\n/)) {
+            const match = /^\s*nameserver\s+(\S+)/.exec(line);
+            const host = match ? normalizeDiscoveredHost(match[1]) : undefined;
+            if (host)
+                hosts.add(host);
+        }
+    }
+    catch {
+        // WSL integrations may not expose resolv.conf; keep the other candidates.
+    }
+    try {
+        const routeOutput = String(execFileSync("ip", ["route", "show", "default"], {
+            encoding: "utf8",
+            timeout: 500,
+            stdio: ["ignore", "pipe", "ignore"],
+        }));
+        const match = /(?:^|\s)default\s+via\s+(\S+)/.exec(routeOutput);
+        const host = match ? normalizeDiscoveredHost(match[1]) : undefined;
+        if (host)
+            hosts.add(host);
+    }
+    catch {
+        // The ip utility is optional; resolv.conf and host.docker.internal suffice.
+    }
+    discoveredWslHosts = [...hosts];
+    return discoveredWslHosts;
+}
+function replaceUrlHost(url, host) {
+    try {
+        const parsed = new URL(url);
+        parsed.hostname = host;
+        return parsed.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A response deadline does not prove the API is offline or a write failed. */
+export function isApiTimeoutError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const details = error;
+    if (details.name === "AbortError" || details.name === "TimeoutError")
+        return true;
+    if (details.code === "UND_ERR_HEADERS_TIMEOUT" || details.code === "UND_ERR_BODY_TIMEOUT")
+        return true;
+    return details.cause !== undefined && details.cause !== error && isApiTimeoutError(details.cause);
+}
+/** Return true when an exception means the HTTP peer could not be reached. */
+export function isApiUnreachableError(error) {
+    if (isApiTimeoutError(error))
+        return false;
+    if (typeof error === "object" && error !== null) {
+        const details = error;
+        if (typeof details.code === "string" &&
+            API_NETWORK_ERROR_CODES.includes(details.code)) {
+            return true;
+        }
+        if (details.cause !== undefined && isApiUnreachableError(details.cause)) {
+            return true;
+        }
+    }
+    const message = String(error).toLowerCase();
+    return (message.includes("fetch failed") ||
+        message.includes("network error") ||
+        message.includes("socket hang up") ||
+        message.includes("connect timeout") ||
+        API_NETWORK_ERROR_CODES.some((code) => message.includes(code.toLowerCase())));
+}
+/** Return true only when no request body could have reached the peer. */
+export function isSafeApiAliasFallbackError(error) {
+    if (typeof error === "object" && error !== null) {
+        const details = error;
+        if (typeof details.code === "string" &&
+            API_ALIAS_SAFE_ERROR_CODES.includes(details.code)) {
+            return true;
+        }
+        if (details.cause !== undefined && isSafeApiAliasFallbackError(details.cause)) {
+            return true;
+        }
+    }
+    const message = String(error).toLowerCase();
+    return API_ALIAS_SAFE_ERROR_CODES.some((code) => message.includes(code.toLowerCase()));
+}
+/** Add the IPv4 loopback alias for clients whose resolver prefers IPv6. */
+export function apiUrlCandidates(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return [url];
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return [url];
+    const host = parsed.hostname.toLowerCase();
+    if (host !== "localhost" && host !== "127.0.0.1")
+        return [url];
+    const alias = new URL(url);
+    alias.hostname = host === "localhost" ? "127.0.0.1" : "localhost";
+    const candidates = [url, alias.toString()];
+    if (isWslRuntime()) {
+        for (const discoveredHost of discoverWslHosts()) {
+            const candidate = replaceUrlHost(url, discoveredHost);
+            if (candidate && !candidates.includes(candidate))
+                candidates.push(candidate);
+        }
+    }
+    return candidates;
+}
+const preferredLoopbackHosts = new Map();
+function orderedApiUrlCandidates(url) {
+    const candidates = apiUrlCandidates(url);
+    if (candidates.length < 2)
+        return candidates;
+    try {
+        const parsed = new URL(url);
+        const preferredHost = preferredLoopbackHosts.get(parsed.origin);
+        if (!preferredHost)
+            return candidates;
+        const preferred = new URL(url);
+        preferred.hostname = preferredHost;
+        const preferredUrl = preferred.toString();
+        return [preferredUrl, ...candidates.filter((candidate) => candidate !== preferredUrl)];
+    }
+    catch {
+        return candidates;
+    }
+}
+/** Join an API path to the configured base without losing its prefix/query. */
+export function apiUrl(path = "", base = MEMOS_URL) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    try {
+        const parsedBase = new URL(base);
+        const parsedPath = new URL(normalizedPath, "http://memos.local");
+        const basePath = parsedBase.pathname.replace(/\/+$/, "").replace(/^\/+/, "");
+        const childPath = parsedPath.pathname.replace(/^\/+/, "");
+        const joinedPath = [basePath, childPath].filter(Boolean).join("/");
+        parsedBase.pathname = joinedPath ? `/${joinedPath}` : "/";
+        // Base query values (for example a gateway token) apply to every endpoint;
+        // a path-specific value wins when both use the same key.
+        const query = new URLSearchParams(parsedBase.search);
+        for (const [key, value] of parsedPath.searchParams)
+            query.set(key, value);
+        parsedBase.search = query.toString();
+        parsedBase.hash = "";
+        return parsedBase.toString();
+    }
+    catch {
+        // Keep the old string behavior for a malformed base; the first fetch then
+        // reports the useful URL error to the caller.
+        const cleanBase = base.replace(/[?#].*$/, "").replace(/\/+$/, "");
+        const cleanPath = normalizedPath.replace(/^\/+/, "");
+        return `${cleanBase}/${cleanPath}`;
+    }
+}
+export function apiHealthUrl(base = MEMOS_URL, detail = false) {
+    const suffix = detail ? "/health/detail" : "/health";
+    return apiUrl(suffix, base);
+}
+/** Remove credentials and query values before an endpoint is shown to a client. */
+export function apiUrlForDisplay(url = MEMOS_URL) {
+    try {
+        const parsed = new URL(url);
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        const displayed = parsed.toString();
+        return parsed.pathname === "/" && displayed.endsWith("/")
+            ? displayed.slice(0, -1)
+            : displayed;
+    }
+    catch {
+        return url
+            .replace(/[?#].*$/, "")
+            .replace(/:\/\/[^/@\s]+@/, "://");
+    }
+}
 export async function fetchWithTimeout(url, options = {}) {
     const timeoutMs = (options.timeoutMs ?? MEMOS_TIMEOUT_TOOL) * 1000;
     const { timeoutMs: _, ...fetchOptions } = options;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const method = String(fetchOptions.method ?? "GET").toUpperCase();
+    const candidates = orderedApiUrlCandidates(url);
+    const isIdempotent = method === "GET" || method === "HEAD";
+    let originalOrigin;
     try {
-        const response = await fetch(url, {
-            ...fetchOptions,
-            signal: controller.signal,
-        });
-        return response;
+        originalOrigin = new URL(url).origin;
+    }
+    catch {
+        // The first fetch will report the malformed URL.
     }
-    finally {
-        clearTimeout(timer);
+    let lastError;
+    for (const candidate of candidates) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(candidate, {
+                ...fetchOptions,
+                signal: controller.signal,
+            });
+            if (originalOrigin) {
+                const selectedOrigin = new URL(candidate).origin;
+                if (selectedOrigin === originalOrigin) {
+                    preferredLoopbackHosts.delete(originalOrigin);
+                }
+                else {
+                    preferredLoopbackHosts.set(originalOrigin, new URL(candidate).hostname);
+                }
+            }
+            return response;
+        }
+        catch (error) {
+            lastError = error;
+            const canTryAlias = candidate !== candidates.at(-1) &&
+                (isIdempotent
+                    ? isApiUnreachableError(error)
+                    : isSafeApiAliasFallbackError(error));
+            if (!canTryAlias) {
+                if (originalOrigin) {
+                    preferredLoopbackHosts.delete(originalOrigin);
+                }
+                throw error;
+            }
+            logger.debug("MemOS API endpoint failed, trying loopback alias");
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
+    throw lastError;
 }
 // ============================================================================
 // API Readiness Check
@@ -32,7 +303,7 @@ export async function waitForApiReady(maxWait, interval = 2.0) {
     const start = Date.now();
     while (Date.now() - start < maxWaitMs) {
         try {
-            const response = await fetchWithTimeout(`${MEMOS_URL}/users`, {
+            const response = await fetchWithTimeout(apiUrl("/users"), {
                 timeoutMs: MEMOS_TIMEOUT_HEALTH,
             });
             if (response.ok) {
@@ -57,7 +328,15 @@ function buildUrl(base, params) {
             urlParams.append(k, String(v));
     }
     const qs = urlParams.toString();
-    return qs ? `${base}?${qs}` : base;
+    if (!qs)
+        return base;
+    const hashIndex = base.indexOf("#");
+    const beforeHash = hashIndex === -1 ? base : base.slice(0, hashIndex);
+    const hash = hashIndex === -1 ? "" : base.slice(hashIndex);
+    const separator = beforeHash.includes("?")
+        ? (beforeHash.endsWith("?") || beforeHash.endsWith("&") ? "" : "&")
+        : "?";
+    return `${beforeHash}${separator}${qs}${hash}`;
 }
 async function doFetch(method, url, options) {
     const finalUrl = buildUrl(url, options.params);
@@ -80,7 +359,11 @@ async function doFetch(method, url, options) {
         const data = (await response.json());
         return { status: response.status, data };
     }
-    catch {
+    catch (error) {
+        // Body reads can fail after response headers arrive. Preserve deadlines
+        // as exceptions so an ambiguous POST is not replayed or reported offline.
+        if (isApiTimeoutError(error))
+            throw error;
         return { status: response.status, data: null };
     }
 }

package/dist/cube-manager.js

@@ -5,9 +5,9 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { MEMOS_URL, MEMOS_USER, MEMOS_DEFAULT_CUBE, MEMOS_CUBES_DIR, MEMOS_TIMEOUT_STARTUP, REGISTRATION_RETRY_INTERVAL, registeredCubes, lastRegistrationAttempt, logger, isDefaultCubeFromEnv, } from "./config.js";
+import { MEMOS_USER, MEMOS_DEFAULT_CUBE, MEMOS_CUBES_DIR, MEMOS_TIMEOUT_STARTUP, REGISTRATION_RETRY_INTERVAL, registeredCubes, lastRegistrationAttempt, logger, isDefaultCubeFromEnv, } from "./config.js";
 import { detectCubeFromPath } from "./keyword-enhancer.js";
-import { fetchWithTimeout } from "./api-client.js";
+import { apiUrl, apiUrlForDisplay, fetchWithTimeout, isApiUnreachableError, } from "./api-client.js";
 // ============================================================================
 // Windows/WSL Path Conversion
 // ============================================================================
@@ -368,7 +368,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)}&limit=1`, { method: "GET", timeoutMs: 5 });
+        const response = await fetchWithTimeout(apiUrl(`/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;
@@ -412,7 +412,7 @@ export async function ensureCubeRegistered(cubeId, force = false) {
             }
         }
         // Register with API
-        const response = await fetchWithTimeout(`${MEMOS_URL}/mem_cubes`, {
+        const response = await fetchWithTimeout(apiUrl("/mem_cubes"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -441,8 +441,8 @@ export async function ensureCubeRegistered(cubeId, force = false) {
     }
     catch (err) {
         const msg = String(err);
-        if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed") || msg.includes("ECONNRESET")) {
-            return [false, `Cannot connect to MemOS API at ${MEMOS_URL}. Is the server running?`];
+        if (isApiUnreachableError(err)) {
+            return [false, `Cannot connect to MemOS API at ${apiUrlForDisplay()}. Is the server running?`];
         }
         return [false, `Failed to register cube '${cubeId}': ${err}`];
     }

package/dist/handlers/admin.js

@@ -6,8 +6,8 @@
  */
 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 { MEMOS_USER, MEMOS_DEFAULT_CUBE, MEMOS_CUBES_DIR, MEMOS_ENABLE_DELETE, MEMOS_TIMEOUT_TOOL, registeredCubes, } from "../config.js";
+import { apiUrl, apiUrlForDisplay, fetchWithTimeout } from "../api-client.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";
 // ============================================================================
@@ -43,7 +43,7 @@ export async function handleMemosListCubes(arguments_) {
                     "",
                     `Cubes directory: \`${cubesDir}\``,
                     "",
-                    `To create a new cube, use the MemOS web interface at ${MEMOS_URL}/docs`,
+                    `To create a new cube, use the MemOS web interface at ${apiUrlForDisplay(apiUrl("/docs"))}`,
                     "or create a cube directory with a config.json file.",
                 ].join("\n") }];
     }
@@ -107,7 +107,7 @@ export async function handleMemosRegisterCube(arguments_) {
         }
     }
     try {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/mem_cubes`, {
+        const response = await fetchWithTimeout(apiUrl("/mem_cubes"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -157,7 +157,7 @@ export async function handleMemosCreateUser(arguments_) {
     const userId = String(arguments_.user_id ?? MEMOS_USER);
     const userName = String(arguments_.user_name ?? userId);
     try {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/users`, {
+        const response = await fetchWithTimeout(apiUrl("/users"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -292,7 +292,7 @@ export async function handleMemosDelete(arguments_) {
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
     if (deleteAll) {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/memories/${cubeId}?user_id=${encodeURIComponent(MEMOS_USER)}`, { method: "DELETE" });
+        const response = await fetchWithTimeout(apiUrl(`/memories/${cubeId}?user_id=${encodeURIComponent(MEMOS_USER)}`), { method: "DELETE" });
         if (response.ok) {
             const data = await response.json();
             if (data.code === 200) {
@@ -321,7 +321,7 @@ export async function handleMemosDelete(arguments_) {
     for (const mid of idsToDelete) {
         let memContent = "*(Unknown content)*";
         try {
-            const getResp = await fetchWithTimeout(`${MEMOS_URL}/memories/${cubeId}/${mid}?user_id=${encodeURIComponent(MEMOS_USER)}`, { method: "GET" });
+            const getResp = await fetchWithTimeout(apiUrl(`/memories/${cubeId}/${mid}?user_id=${encodeURIComponent(MEMOS_USER)}`), { method: "GET" });
             if (getResp.ok) {
                 const gData = await getResp.json();
                 if (gData.code === 200 && gData.data) {
@@ -335,7 +335,7 @@ export async function handleMemosDelete(arguments_) {
         catch {
             memContent = "*(Fetch failed)*";
         }
-        const deleteResp = await fetchWithTimeout(`${MEMOS_URL}/memories/${cubeId}/${mid}?user_id=${encodeURIComponent(MEMOS_USER)}`, { method: "DELETE" });
+        const deleteResp = await fetchWithTimeout(apiUrl(`/memories/${cubeId}/${mid}?user_id=${encodeURIComponent(MEMOS_USER)}`), { method: "DELETE" });
         if (deleteResp.ok) {
             const data = await deleteResp.json();
             if (data.code === 200) {

package/dist/handlers/calendar.js

@@ -3,8 +3,8 @@
  *
  * memos_admin(action="calendar") - project mode and student mode
  */
-import { MEMOS_URL, MEMOS_USER } from "../config.js";
-import { apiCallWithRetry } from "../api-client.js";
+import { MEMOS_USER } from "../config.js";
+import { apiCallWithRetry, apiUrl } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { apiErrorResponse, cubeRegistrationError, getCubeIdFromArgs } from "./utils.js";
 // ============================================================================
@@ -201,7 +201,7 @@ export async function handleMemosCalendar(arguments_) {
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
     if (mode === "project") {
-        const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId, limit: 200 } }, ensureCubeRegistered);
+        const result = await apiCallWithRetry("GET", apiUrl("/memories"), cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId, limit: 200 } }, ensureCubeRegistered);
         if (result.success && result.data) {
             const resultData = result.data.data ?? {};
             const memories = [];
@@ -229,7 +229,7 @@ export async function handleMemosCalendar(arguments_) {
     if (week !== undefined) {
         [startDate, endDate] = getWeekDates(startDate, week);
     }
-    const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId, limit: 100 } }, ensureCubeRegistered);
+    const result = await apiCallWithRetry("GET", apiUrl("/memories"), cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId, limit: 100 } }, ensureCubeRegistered);
     if (result.success && result.data) {
         const resultData = result.data.data ?? {};
         let memories = [];

package/dist/handlers/graph.js

@@ -3,8 +3,8 @@
  *
  * memos_graph(mode="path"), memos_graph(mode="related"), memos_graph(mode="schema"), memos_graph(mode="impact")
  */
-import { MEMOS_URL, MEMOS_USER, NEO4J_HTTP_URL, NEO4J_USER, NEO4J_PASSWORD, logger, registeredCubes, } from "../config.js";
-import { fetchWithTimeout } from "../api-client.js";
+import { MEMOS_USER, NEO4J_HTTP_URL, NEO4J_USER, NEO4J_PASSWORD, logger, registeredCubes, } from "../config.js";
+import { apiUrl, fetchWithTimeout } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { formatProvenance } from "../graph-provenance.js";
 import { buildGraphImportPlan, renderGraphImportPlan, } from "../graphify-import.js";
@@ -99,7 +99,7 @@ export async function handleMemosTracePath(arguments_) {
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
     try {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/product/graph/trace_path`, {
+        const response = await fetchWithTimeout(apiUrl("/product/graph/trace_path"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -243,7 +243,7 @@ export async function handleMemosGetGraph(arguments_) {
     // Search for relevant memories first
     let memories = [];
     try {
-        const searchResponse = await fetchWithTimeout(`${MEMOS_URL}/search`, {
+        const searchResponse = await fetchWithTimeout(apiUrl("/search"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -262,7 +262,7 @@ export async function handleMemosGetGraph(arguments_) {
                 registeredCubes.delete(cubeId);
                 const [retrySuccess] = await ensureCubeRegistered(cubeId, true);
                 if (retrySuccess) {
-                    const retrySearch = await fetchWithTimeout(`${MEMOS_URL}/search`, {
+                    const retrySearch = await fetchWithTimeout(apiUrl("/search"), {
                         method: "POST",
                         headers: { "Content-Type": "application/json" },
                         body: JSON.stringify({
@@ -499,7 +499,7 @@ export async function handleMemosExportSchema(arguments_) {
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
     try {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/graph/schema`, {
+        const response = await fetchWithTimeout(apiUrl("/graph/schema"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({

package/dist/handlers/index.d.ts

@@ -7,4 +7,5 @@
 import type { TextContent } from "../types.js";
 export declare function dispatchTool(name: string, arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleApiUnreachable(): Promise<TextContent[]>;
+export declare function handleApiTimeout(): Promise<TextContent[]>;
 //# sourceMappingURL=index.d.ts.map

package/dist/handlers/index.js

@@ -14,7 +14,8 @@ import { handleMemosImportWiki } from "./wiki-import.js";
 import { handleMemosCanvas } from "./canvas.js";
 import { handleMemosDistillSkill, handleMemosListSkillCandidates, handleMemosReviewSkillCandidate, handleMemosInstallSkillCandidate } from "./skill.js";
 import { handleMemosListCubes, handleMemosRegisterCube, handleMemosCreateUser, handleMemosValidateCubes, handleMemosDelete, handleMemosCapabilities, } from "./admin.js";
-import { MEMOS_URL, MEMOS_PROVIDER } from "../config.js";
+import { MEMOS_PROVIDER } from "../config.js";
+import { apiHealthUrl, apiUrlForDisplay } from "../api-client.js";
 import { errorResponse } from "./utils.js";
 export async function dispatchTool(name, arguments_) {
     if (MEMOS_PROVIDER === "local" && ["memos_think", "memos_graph", "memos_export_wiki", "memos_import_wiki", "memos_admin", "memos_delete"].includes(name)) {
@@ -99,13 +100,19 @@ export async function handleApiUnreachable() {
     return [{
             type: "text",
             text: [
-                `❌ [API_UNREACHABLE] Cannot connect to MemOS API at ${MEMOS_URL}`,
+                `❌ [API_UNREACHABLE] Cannot connect to MemOS API at ${apiUrlForDisplay()}`,
                 "",
                 "💡 Suggestions:",
-                "- Check if MemOS API is running: `curl http://localhost:18000/health`",
+                `- Check if MemOS API is running: \`curl ${apiUrlForDisplay(apiHealthUrl())}\``,
                 "- Start with: `scripts/local/start.bat`",
                 "- Check port availability",
             ].join("\n"),
         }];
 }
+export async function handleApiTimeout() {
+    return errorResponse(`MemOS API at ${apiUrlForDisplay()} did not respond before the request deadline.`, "API_TIMEOUT", [
+        "A write may still have completed. Check memos_search or memos_list_v2 before retrying.",
+        "Check API logs for storage delays; LLM parsing runs in background after vector confirmation.",
+    ]);
+}
 //# sourceMappingURL=index.js.map

package/dist/handlers/memory.js

@@ -4,11 +4,11 @@
  * memos_save, memos_list_v2, memos_get, memos_admin(action="stats")
  */
 import * as crypto from "crypto";
-import { MEMOS_URL, MEMOS_USER, MEMOS_CUBES_DIR, logger } from "../config.js";
+import { MEMOS_USER, MEMOS_CUBES_DIR, logger } from "../config.js";
 import { getMemoryProvider } from "../providers/provider-factory.js";
-import { apiCallWithRetry } from "../api-client.js";
+import { apiCallWithRetry, apiUrl } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
-import { parseMemoryWriteResponse } from "../memory-write-response.js";
+import { parseMemoryWriteResponse, UnconfirmedMemoryWriteError } from "../memory-write-response.js";
 import { recordAccess } from "../access-tracker.js";
 import { filterEphemeralTier } from "../memory-tier.js";
 import { findSiblings, renderVerbatimSections, verbatimOf, } from "../verbatim-source.js";
@@ -95,24 +95,32 @@ export async function handleMemosSave(arguments_) {
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
-    const result = await apiCallWithRetry("POST", `${MEMOS_URL}/memories`, cubeId, {
+    const result = await apiCallWithRetry("POST", apiUrl("/memories"), cubeId, {
         body: {
             user_id: MEMOS_USER,
             mem_cube_id: cubeId,
             memory_content: content,
+            memory_type: memoryType,
         },
     }, ensureCubeRegistered);
     if (result.success) {
-        markSaved(content, cubeId);
         const write = parseMemoryWriteResponse(result.data);
+        if (write.vectorSaved === false || (write.vectorSaved === true && write.memoryIds.length === 0)) {
+            throw new UnconfirmedMemoryWriteError(errorResponse("Vector storage was not confirmed; the save cannot be acknowledged.", "VECTOR_SAVE_UNCONFIRMED", ["Check API storage logs and search for the memory before retrying."]));
+        }
+        markSaved(content, cubeId);
         const idText = write.memoryIds.length > 0 ? ` · IDs: ${write.memoryIds.join(", ")}` : "";
         const warningText = write.warnings.length > 0
             ? ` · warnings: ${write.warnings.join("; ")}`
             : "";
+        const vectorText = write.vectorSaved === true ? " · vector saved" : "";
+        const enrichmentText = write.enrichmentStatus === "pending"
+            ? " · LLM parsing continues in background"
+            : write.enrichmentStatus === "failed" ? " · background parsing failed; saved memory is retained" : "";
         return [
             {
                 type: "text",
-                text: `Memory saved as [${memoryType}] in cube '${cubeId}'${idText}${warningText}`,
+                text: `Memory saved as [${memoryType}] in cube '${cubeId}'${idText}${vectorText}${enrichmentText}${warningText}`,
             },
         ];
     }
@@ -177,7 +185,7 @@ export async function handleMemosList(arguments_) {
     // (the API filters by internal type, not MCP type), but never the whole cube —
     // pulling everything blew a limit=5 request up to ~1.8M tokens on large cubes.
     params.limit = memoryType ? Math.max(limit * 20, 200) : limit;
-    const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, { params }, ensureCubeRegistered);
+    const result = await apiCallWithRetry("GET", apiUrl("/memories"), cubeId, { params }, ensureCubeRegistered);
     if (result.success && result.data) {
         const resultData = result.data.data ?? {};
         const allMemories = prepareListMemories(resultData, memoryType, limit);
@@ -233,7 +241,7 @@ export async function handleMemosList(arguments_) {
  */
 async function fetchSiblings(cubeId, target) {
     try {
-        const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId, limit: 200 } }, ensureCubeRegistered);
+        const result = await apiCallWithRetry("GET", apiUrl("/memories"), cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId, limit: 200 } }, ensureCubeRegistered);
         if (!result.success || !result.data)
             return [];
         const data = result.data.data;
@@ -286,7 +294,13 @@ export async function handleMemosGet(arguments_) {
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
-    const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories/${cubeId}/${memoryId}`, cubeId, {}, ensureCubeRegistered);
+    const result = await apiCallWithRetry("GET", apiUrl(`/memories/${cubeId}/${memoryId}`), cubeId, 
+    // user_id 必须显式传：后端 `get_memory` 的 user_id 是可选参数，缺失时回退到
+    // MOS 实例自己的 user_id（root）。而 ensureCubeRegistered 注册的是 MEMOS_USER
+    // （dev_user），于是 root 对该 cube 无授权，校验抛 ValueError → 400
+    // "User 'root' does not have access to cube '...'"。重注册重试也救不回来：
+    // 它仍然按 MEMOS_USER 注册，重试请求仍然不带 user_id，第二次照样落到 root。
+    { params: { user_id: MEMOS_USER } }, ensureCubeRegistered);
     if (result.success && result.data) {
         const resultData = result.data
             .data;
@@ -379,7 +393,7 @@ export async function handleMemosGetStats(arguments_) {
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
-    const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId } }, ensureCubeRegistered);
+    const result = await apiCallWithRetry("GET", apiUrl("/memories"), cubeId, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId } }, ensureCubeRegistered);
     if (result.success && result.data) {
         const [stats, total] = computeMemoryStats(result.data.data ?? {});
         if (total === 0) {

package/dist/handlers/search.js

@@ -3,9 +3,9 @@
  *
  * memos_search, memos_search, memos_suggest, memos_context_resume
  */
-import { MEMOS_URL, MEMOS_USER, NEO4J_HTTP_URL, NEO4J_USER, NEO4J_PASSWORD, MEMOS_MODE, MEMOS_CUBES_DIR, logger, } from "../config.js";
+import { MEMOS_USER, NEO4J_HTTP_URL, NEO4J_USER, NEO4J_PASSWORD, MEMOS_MODE, MEMOS_CUBES_DIR, logger, } from "../config.js";
 import { getMemoryProvider } from "../providers/provider-factory.js";
-import { apiCallWithRetry, fetchWithTimeout } from "../api-client.js";
+import { apiCallWithRetry, apiUrl, fetchWithTimeout } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { formatMemoriesForDisplay } from "../formatters.js";
 import { PREVIEW_COUNT, shouldCompact, compactedResultToText, toMinimal, } from "../models.js";
@@ -307,7 +307,7 @@ export async function handleMemosSearch(arguments_) {
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
-    const apiResult = await apiCallWithRetry("POST", `${MEMOS_URL}/search`, cubeId, {
+    const apiResult = await apiCallWithRetry("POST", apiUrl("/search"), cubeId, {
         body: {
             user_id: MEMOS_USER,
             query,
@@ -387,7 +387,7 @@ export async function handleMemosSearchContext(arguments_) {
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
     try {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/search`, {
+        const response = await fetchWithTimeout(apiUrl("/search"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -424,7 +424,7 @@ export async function handleMemosSearchContext(arguments_) {
             }
             else {
                 // Fallback to standard search
-                const fallbackResult = await apiCallWithRetry("POST", `${MEMOS_URL}/search`, cubeId, { body: { user_id: MEMOS_USER, query, install_cube_ids: [cubeId] } }, ensureCubeRegistered);
+                const fallbackResult = await apiCallWithRetry("POST", apiUrl("/search"), cubeId, { body: { user_id: MEMOS_USER, query, install_cube_ids: [cubeId] } }, ensureCubeRegistered);
                 if (fallbackResult.success && fallbackResult.data) {
                     let resultData = fallbackResult.data
                         .data ?? {};
@@ -564,7 +564,7 @@ export async function handleMemosContextResume(arguments_) {
     let recentMemories = await getTemporalMemories(cubeId, RESUME_LIMIT, 24);
     // Fallback to API list
     if (recentMemories.length === 0) {
-        const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, {
+        const result = await apiCallWithRetry("GET", apiUrl("/memories"), cubeId, {
             params: {
                 user_id: MEMOS_USER,
                 mem_cube_id: cubeId,

package/dist/handlers/think.js

@@ -14,8 +14,8 @@
  * of CONFLICT edges: those edges are only created by the reorganizer pipeline,
  * which is disabled by default, so in practice they rarely exist.
  */
-import { MEMOS_URL, MEMOS_USER } from "../config.js";
-import { apiCallWithRetry } from "../api-client.js";
+import { MEMOS_USER } from "../config.js";
+import { apiCallWithRetry, apiUrl } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { extractKeywords, extractMcpType } from "../query-processing.js";
 import { levenshteinDistance } from "../keyword-enhancer.js";
@@ -127,7 +127,7 @@ export async function handleMemosThink(arguments_) {
         return cubeRegistrationError(cubeId, regError);
     // Two recall paths in parallel: semantic search + recent temporal slice.
     const [apiResult, temporal] = await Promise.all([
-        apiCallWithRetry("POST", `${MEMOS_URL}/search`, cubeId, { body: { user_id: MEMOS_USER, query, install_cube_ids: [cubeId], top_k: topK } }, ensureCubeRegistered),
+        apiCallWithRetry("POST", apiUrl("/search"), cubeId, { body: { user_id: MEMOS_USER, query, install_cube_ids: [cubeId], top_k: topK } }, ensureCubeRegistered),
         getTemporalMemories(cubeId, 5, 72).catch(() => []),
     ]);
     if (!apiResult.success) {

package/dist/handlers/utils.js

@@ -5,6 +5,7 @@
  */
 import { detectCubeFromPath } from "../keyword-enhancer.js";
 import { getDefaultCubeId } from "../cube-manager.js";
+import { apiHealthUrl, apiUrlForDisplay } from "../api-client.js";
 // ============================================================================
 // Error Codes
 // ============================================================================
@@ -43,7 +44,7 @@ export function successResponse(message) {
 }
 export function cubeRegistrationError(cubeId, detail) {
     return errorResponse(`Cube '${cubeId}' registration failed: ${detail ?? "unknown error"}`, ERR_CUBE_REGISTRATION, [
-        `Check if MemOS API is running: \`curl http://localhost:18000/health\``,
+        `Check if MemOS API is running: \`curl ${apiUrlForDisplay(apiHealthUrl())}\``,
         `Verify cube exists: \`memos_admin(action="list_cubes", include_status=True)\``,
         `Try manual registration: \`memos_admin(action="register_cube", cube_id="...")\``,
     ]);
@@ -53,13 +54,22 @@ export function apiErrorResponse(operation, statusOrMsg) {
     // Turn known API errors into actionable next steps on the hot paths
     // (save/search/list hit these far more often than register_cube does).
     const suggestions = [];
-    if (msg.includes("user") && (msg.includes("not exist") || msg.includes("not found"))) {
+    // 「does not have access to cube」要在 user-missing 分支之前判：它同时含 "user"
+    // 和 cube 字样，但成因完全不同 —— 用户和 cube 都存在，只是该用户没被授权。
+    // 实测最常见的触发方式是调用方漏传 user_id，后端回退到 root 去校验（root 往往
+    // 没有项目 cube 的授权），所以提示要先指向 user_id，而不是让人去建用户。
+    if (msg.includes("does not have access")) {
+        suggestions.push('Cube exists but this user is not authorized — most often the caller omitted `user_id` and the API fell back to its own default user. Verify `MEMOS_USER` matches the cube owner, then re-register: `memos_admin(action="register_cube", cube_id="...")`');
+    }
+    else if (msg.includes("user") &&
+        (msg.includes("not exist") || msg.includes("not found"))) {
         suggestions.push('User missing — run `memos_admin(action="create_user", user_id="dev_user")`, then retry');
     }
-    else if (msg.includes("not loaded") || (msg.includes("cube") && msg.includes("not found"))) {
+    else if (msg.includes("not loaded") ||
+        (msg.includes("cube") && msg.includes("not found"))) {
         suggestions.push('Cube not registered — run `memos_admin(action="register_cube", cube_id="...")` (find ids via `memos_admin(action="list_cubes")`), then retry');
     }
-    suggestions.push("Check API health: `curl http://localhost:18000/health/detail`", "Check API logs for details");
+    suggestions.push(`Check API health: \`curl ${apiUrlForDisplay(apiHealthUrl(undefined, true))}\``, "Check API logs for details");
     return errorResponse(`${operation} failed: ${statusOrMsg}`, ERR_API_ERROR, suggestions);
 }
 // ============================================================================

package/dist/handlers/wiki-export.js

@@ -15,8 +15,8 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { MEMOS_URL, logger } from "../config.js";
-import { fetchWithTimeout } from "../api-client.js";
+import { logger } from "../config.js";
+import { apiUrl, fetchWithTimeout } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { extractMcpType } from "../query-processing.js";
 import { EDGE_LABELS } from "../wiki-relations.js";
@@ -33,7 +33,7 @@ async function fetchAllGraphData(cubeId) {
     let totalNodes = 0;
     let totalEdges = 0;
     for (let page = 1; page <= MAX_PAGES; page++) {
-        const response = await fetchWithTimeout(`${MEMOS_URL}/product/graph/data`, {
+        const response = await fetchWithTimeout(apiUrl("/product/graph/data"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             // user_id doubles as the Neo4j user_name filter server-side, and cube

package/dist/handlers/wiki-import-relations.js

@@ -1,5 +1,5 @@
-import { MEMOS_URL, MEMOS_USER } from "../config.js";
-import { apiCallWithRetry } from "../api-client.js";
+import { MEMOS_USER } from "../config.js";
+import { apiCallWithRetry, apiUrl } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { relationEdges } from "../wiki-relations.js";
 async function writeRelationsForPage(cubeId, effectiveId, page, fileBaseIndex) {
@@ -7,7 +7,7 @@ async function writeRelationsForPage(cubeId, effectiveId, page, fileBaseIndex) {
     const written = [];
     const failed = [];
     for (const edge of result.resolved) {
-        const relResult = await apiCallWithRetry("POST", `${MEMOS_URL}/product/graph/relation`, cubeId, {
+        const relResult = await apiCallWithRetry("POST", apiUrl("/product/graph/relation"), cubeId, {
             body: {
                 user_id: MEMOS_USER,
                 mem_cube_id: cubeId,

package/dist/handlers/wiki-import.js

@@ -17,12 +17,12 @@
 import * as crypto from "crypto";
 import * as fs from "fs";
 import * as path from "path";
-import { MEMOS_URL, MEMOS_USER, logger } from "../config.js";
-import { apiCallWithRetry } from "../api-client.js";
+import { MEMOS_USER, logger } from "../config.js";
+import { apiCallWithRetry, apiUrl } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { parseMemoryWriteResponse } from "../memory-write-response.js";
-import { inspectWikiPages, normalizeLedger } from "../wiki-import-safety.js";
-import { buildFileBaseIndex } from "../wiki-relations.js";
+import { inspectWikiPages, normalizeLedger, } from "../wiki-import-safety.js";
+import { buildFileBaseIndex, } from "../wiki-relations.js";
 import { writeRelationsForPage } from "./wiki-import-relations.js";
 import { buildMemoryContent, parseWikiPage, stripTypePrefix, } from "../wiki-import-format.js";
 import { ERR_OPERATION_FAILED, ERR_PARAM_MISSING, cubeRegistrationError, errorResponse, getCubeIdFromArgs, } from "./utils.js";
@@ -55,7 +55,10 @@ function collectMarkdownFiles(pagesDir) {
     return files;
 }
 function contentHash(page) {
-    return crypto.createHash("sha256").update(`${page.type}\n${page.content}`).digest("hex");
+    return crypto
+        .createHash("sha256")
+        .update(`${page.type}\n${page.content}`)
+        .digest("hex");
 }
 function loadLedger(wikiDir) {
     const ledgerPath = path.join(wikiDir, LEDGER_FILE);
@@ -89,7 +92,9 @@ function saveLedger(wikiDir, ledger) {
         try {
             fs.unlinkSync(temp);
         }
-        catch { /* best effort */ }
+        catch {
+            /* best effort */
+        }
         return false;
     }
 }
@@ -109,7 +114,10 @@ function acquireImportLock(wikiDir) {
             }
         }
         const fd = fs.openSync(lockPath, "wx");
-        fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, started_at: new Date(now).toISOString() }));
+        fs.writeFileSync(fd, JSON.stringify({
+            pid: process.pid,
+            started_at: new Date(now).toISOString(),
+        }));
         fs.closeSync(fd);
         return null;
     }
@@ -121,13 +129,20 @@ function releaseImportLock(wikiDir) {
     try {
         fs.unlinkSync(path.join(wikiDir, LOCK_FILE));
     }
-    catch { /* another process may own it */ }
+    catch {
+        /* another process may own it */
+    }
 }
 /** Returns the stored node, null when the memory does not exist, or an error string. */
 async function getStoredMemory(cubeId, memoryId) {
-    const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories/${cubeId}/${memoryId}`, cubeId, {}, ensureCubeRegistered);
+    const result = await apiCallWithRetry("GET", apiUrl(`/memories/${cubeId}/${memoryId}`), cubeId, 
+    // 同 handlers/memory.ts 的 handleMemosGet：缺 user_id 会让后端回退到 root，
+    // 对 MEMOS_USER 名下的 cube 报「does not have access」。这里更隐蔽 —— 该错误
+    // 既不含 "not found" 也不是 404，会被当成真实故障返回，把整页 import 判成失败。
+    { params: { user_id: MEMOS_USER } }, ensureCubeRegistered);
     if (result.success) {
-        return result.data?.data ?? null;
+        return (result.data
+            ?.data ?? null);
     }
     const msg = String(result.data?.message ?? "");
     if (msg.toLowerCase().includes("not found") || result.status === 404)
@@ -149,16 +164,23 @@ async function savePageAsMemory(cubeId, page) {
         body.created_at = page.created;
     if (page.updated)
         body.updated_at = page.updated;
-    const result = await apiCallWithRetry("POST", `${MEMOS_URL}/memories`, cubeId, { body }, ensureCubeRegistered);
+    const result = await apiCallWithRetry("POST", apiUrl("/memories"), cubeId, { body }, ensureCubeRegistered);
     if (!result.success) {
         return {
-            error: String(result.data?.message ?? `HTTP ${result.status}`),
+            error: String(result.data?.message ??
+                `HTTP ${result.status}`),
             memoryIds: [],
             warnings: [],
             uncertain: false,
         };
     }
     const parsed = parseMemoryWriteResponse(result.data);
+    if (parsed.vectorSaved === false || (parsed.vectorSaved === true && parsed.memoryIds.length === 0)) {
+        return {
+            error: "Vector storage was not confirmed", memoryIds: [],
+            warnings: parsed.warnings, uncertain: true,
+        };
+    }
     return {
         error: null,
         memoryIds: parsed.memoryIds,
@@ -174,12 +196,12 @@ export async function handleMemosImportWiki(arguments_) {
     const projectPath = arguments_.project_path;
     const dryRun = arguments_.dry_run === true;
     const onEdit = arguments_.on_edit === "version" ? "version" : "skip";
-    const wikiDir = arguments_.wiki_dir
-        ?? (projectPath ? path.join(projectPath, "docs", "memory-wiki") : undefined);
+    const wikiDir = arguments_.wiki_dir ??
+        (projectPath ? path.join(projectPath, "docs", "memory-wiki") : undefined);
     if (!wikiDir) {
         return errorResponse("Need project_path (default wiki: <project_path>/docs/memory-wiki) or an explicit wiki_dir", ERR_PARAM_MISSING, [
             '`memos_import_wiki(project_path="/mnt/g/my/project")`',
-            'Run `memos_export_wiki` first, edit pages, then import',
+            "Run `memos_export_wiki` first, edit pages, then import",
         ]);
     }
     const resolvedDir = path.resolve(wikiDir);
@@ -189,7 +211,9 @@ export async function handleMemosImportWiki(arguments_) {
         return errorResponse(lockError, ERR_OPERATION_FAILED);
     try {
         if (!fs.existsSync(pagesDir)) {
-            return errorResponse(`No pages directory under '${resolvedDir}' — export a wiki first`, ERR_OPERATION_FAILED, [`memos_export_wiki(project_path="...") writes <project_path>/docs/memory-wiki/pages/`]);
+            return errorResponse(`No pages directory under '${resolvedDir}' — export a wiki first`, ERR_OPERATION_FAILED, [
+                `memos_export_wiki(project_path="...") writes <project_path>/docs/memory-wiki/pages/`,
+            ]);
         }
         const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
         if (!regSuccess)
@@ -209,7 +233,10 @@ export async function handleMemosImportWiki(arguments_) {
             }
             const result = parseWikiPage(raw);
             if (result.ok)
-                parsed.push({ page: result.page, relPath: path.relative(resolvedDir, file) });
+                parsed.push({
+                    page: result.page,
+                    relPath: path.relative(resolvedDir, file),
+                });
             else if (result.foreign)
                 foreign += 1;
             else
@@ -252,7 +279,9 @@ export async function handleMemosImportWiki(arguments_) {
                 archived += 1;
                 continue;
             }
-            if (ledgerEntry && typeof ledgerEntry !== "string" && ledgerEntry.new_memory_ids.length > 0) {
+            if (ledgerEntry &&
+                typeof ledgerEntry !== "string" &&
+                ledgerEntry.new_memory_ids.length > 0) {
                 // The old page has already produced a new version; compare the edited
                 // content hash before doing another API lookup/version.
                 const mappedHash = ledgerEntry.content_hash;
@@ -306,7 +335,9 @@ export async function handleMemosImportWiki(arguments_) {
                 unchanged += 1;
                 continue;
             }
-            const ledgerHash = typeof ledgerEntry === "string" ? ledgerEntry : ledgerEntry?.content_hash;
+            const ledgerHash = typeof ledgerEntry === "string"
+                ? ledgerEntry
+                : ledgerEntry?.content_hash;
             if (ledgerHash === contentHash(page)) {
                 alreadyVersioned += 1;
                 continue;
@@ -370,7 +401,9 @@ export async function handleMemosImportWiki(arguments_) {
             lines.push("", `❌ 失败明细（前 ${REPORT_LIST_LIMIT} 条）：`, ...failures.slice(0, REPORT_LIST_LIMIT).map((s) => `- ${s}`));
         }
         if (apiWarnings.length > 0) {
-            lines.push("", "⚠️ API warnings:", ...apiWarnings.slice(0, REPORT_LIST_LIMIT).map((warning) => `- ${warning}`));
+            lines.push("", "⚠️ API warnings:", ...apiWarnings
+                .slice(0, REPORT_LIST_LIMIT)
+                .map((warning) => `- ${warning}`));
         }
         lines.push("", "ℹ️ 导入恢复 type/tags/confidence/status/时间字段；关联 wikilinks 写入 Neo4j 关系边；写入内容经过服务端凭据脱敏。");
         return [{ type: "text", text: lines.join("\n") }];

package/dist/memory-write-response.d.ts

@@ -1,7 +1,14 @@
-import type { ApiResponse } from "./types.js";
+import type { ApiResponse, TextContent } from "./types.js";
+/** A rejected storage acknowledgement must be an MCP tool error, not success text. */
+export declare class UnconfirmedMemoryWriteError extends Error {
+    readonly content: TextContent[];
+    constructor(content: TextContent[]);
+}
 export interface MemoryWriteResult {
     memoryIds: string[];
     warnings: string[];
+    vectorSaved?: boolean;
+    enrichmentStatus?: string;
 }
 /** Normalize the additive POST /memories response while accepting legacy APIs. */
 export declare function parseMemoryWriteResponse(response: ApiResponse<unknown>): MemoryWriteResult;

package/dist/memory-write-response.js

@@ -1,3 +1,12 @@
+/** A rejected storage acknowledgement must be an MCP tool error, not success text. */
+export class UnconfirmedMemoryWriteError extends Error {
+    content;
+    constructor(content) {
+        super(content.map((item) => item.text).join("\n"));
+        this.content = content;
+        this.name = "UnconfirmedMemoryWriteError";
+    }
+}
 /** Normalize the additive POST /memories response while accepting legacy APIs. */
 export function parseMemoryWriteResponse(response) {
     const data = response.data;
@@ -10,6 +19,10 @@ export function parseMemoryWriteResponse(response) {
     const warnings = Array.isArray(payload.warnings)
         ? payload.warnings.filter((warning) => typeof warning === "string" && warning.length > 0)
         : [];
-    return { memoryIds, warnings };
+    return {
+        memoryIds, warnings,
+        ...(typeof payload.vector_saved === "boolean" ? { vectorSaved: payload.vector_saved } : {}),
+        ...(typeof payload.enrichment_status === "string" ? { enrichmentStatus: payload.enrichment_status } : {}),
+    };
 }
 //# sourceMappingURL=memory-write-response.js.map

package/dist/models.js

@@ -76,6 +76,9 @@ export function toFull(memory, cubeId = "", userId = "") {
     const cleanContent = content.replace(/^\[[A-Z_]+\]\s*/, "");
     return {
         ...brief,
+        createdAt: memory.created_at ??
+            meta.created_at ??
+            brief.createdAt,
         content: cleanContent,
         background: memory.background ?? meta.background,
         cubeId,

package/dist/server.js

@@ -7,10 +7,11 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { MEMOS_DEFAULT_CUBE, MEMOS_ENABLE_DELETE, MEMOS_PROVIDER, logger } from "./config.js";
-import { waitForApiReady } from "./api-client.js";
+import { apiHealthUrl, apiUrlForDisplay, isApiTimeoutError, isApiUnreachableError, waitForApiReady, } from "./api-client.js";
 import { ensureCubeRegistered } from "./cube-manager.js";
 import { toolSchemas, toolAnnotations } from "./tools-registry.js";
-import { dispatchTool, handleApiUnreachable } from "./handlers/index.js";
+import { dispatchTool, handleApiTimeout, handleApiUnreachable } from "./handlers/index.js";
+import { UnconfirmedMemoryWriteError } from "./memory-write-response.js";
 import { createOnceFireAndForget } from "./server-lifecycle.js";
 import { NormalizingStdioTransport } from "./stdio-compat-transport.js";
 // ============================================================================
@@ -41,8 +42,14 @@ function registerTools(server) {
                 };
             }
             catch (err) {
+                if (err instanceof UnconfirmedMemoryWriteError) {
+                    return { content: err.content, isError: true };
+                }
                 const errStr = String(err);
-                if (errStr.includes("ECONNREFUSED") || errStr.includes("fetch failed")) {
+                if (isApiTimeoutError(err)) {
+                    return { content: await handleApiTimeout(), isError: true };
+                }
+                if (isApiUnreachableError(err)) {
                     const unreachable = await handleApiUnreachable();
                     return {
                         content: unreachable.map((r) => ({ type: "text", text: r.text })),
@@ -58,7 +65,7 @@ function registerTools(server) {
                                 "",
                                 "💡 Suggestions:",
                                 "- Check MCP server logs for details",
-                                "- Verify MemOS API is healthy: `curl http://localhost:18000/health/detail`",
+                                `- Verify MemOS API is healthy: \`curl ${apiUrlForDisplay(apiHealthUrl(undefined, true))}\``,
                             ].join("\n"),
                         },
                     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-memos-mcp",
-  "version": "3.1.7",
+  "version": "3.1.9",
   "description": "MCP Server for oh-memos — Intelligent Memory Management (Node.js, no Python required)",
   "type": "module",
   "main": "dist/index.js",