oh-memos-mcp 3.1.0 → 3.1.2

package/README.md

@@ -6,7 +6,7 @@
 
 MCP Server for **oh-memos** — Intelligent Persistent Memory for AI Assistants.
 
-Pure Node.js. No Python required. Works with `npx` out of the box.
+Pure Node.js. No Python required.
 
 > **3.0:** requires Node.js 20+, serves legacy 2025-era and MCP `2026-07-28`
 > clients from the same stdio package, and requires no data migration. Still on
@@ -19,8 +19,8 @@ Pure Node.js. No Python required. Works with `npx` out of the box.
 - **Node.js 20 or newer**
 
 ```bash
-npx -y oh-memos-mcp        # 3.x, npm latest — needs Node.js 20+
-npx -y oh-memos-mcp@2      # 2.x maintenance line — still runs on Node.js 18
+npm i -g oh-memos-mcp       # 3.x, npm latest — needs Node.js 20+
+npm i -g oh-memos-mcp@2     # 2.x maintenance line — still runs on Node.js 18
 ```
 
 oh-memos backend API must be running before connecting this MCP server:
@@ -35,50 +35,96 @@ oh-memos backend API must be running before connecting this MCP server:
 
 ## Quick Start
 
-Add to your Claude Code `~/.claude/settings.json`:
+Install once, then point the client at the installed entry point:
+
+```bash
+npm install -g oh-memos-mcp
+npm root -g          # prints the directory used in "args" below
+```
 
 ```json
 {
   "mcpServers": {
     "oh-memos": {
-      "command": "npx",
-      "args": ["-y", "oh-memos-mcp"],
+      "command": "node",
+      "args": ["<npm root -g>/oh-memos-mcp/dist/index.js"],
       "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"
+        "MEMOS_CUBES_DIR": "/path/to/oh-memos/data/oh-memos_cubes",
+        "MEMOS_ENV_FILE": "/path/to/oh-memos/.env"
       }
     }
   }
 }
 ```
 
-Or use a `.env` file in your working directory (the server auto-discovers it):
+To upgrade, reinstall globally — the config needs no edit:
+
+```bash
+npm install -g oh-memos-mcp@latest
+```
+
+Then restart the client. A running MCP server is never swapped mid-session: the
+stdio pipe is bound when the client starts, so an upgrade takes effect only after
+the client restarts.
+
+### Why not `npx`
+
+`npx -y oh-memos-mcp@<version>` also works and is fine for a one-off trial, but it
+costs two extra processes per client — `cmd`/`sh` → `npx-cli` (node) → `cmd`/`sh` →
+server (node), versus a direct launch's two. With several MCP clients open at once
+that overhead is measurable: on one Windows machine running seven clients, the npx
+wrappers alone held ~360 MB. `npx` also pins the version inside every client
+config, so upgrading means editing each one.
+
+| | `npx -y oh-memos-mcp@x.y.z` | `node <npm root -g>/oh-memos-mcp/dist/index.js` |
+|---|---|---|
+| Processes per client | 4 | 2 |
+| Upgrade | edit every config | `npm i -g oh-memos-mcp@latest` |
+| Version source | the config | the global install |
+
+A third option is to point `args` at a checkout's `dist/index.js`. That is the
+lowest-overhead choice for working *on* oh-memos — `npm run build` takes effect on
+the next client restart, with no publish — but the client then breaks if the
+checkout moves or its build output is stale.
+
+Or use a `.env` file in your working directory (the server auto-discovers it when
+the working directory is the project root):
 
 ```bash
 cp node_modules/oh-memos-mcp/.env.example .env
 # Edit .env with your paths
-npx -y oh-memos-mcp
+node "$(npm root -g)/oh-memos-mcp/dist/index.js"
 ```
 
 ---
 
 ## Configuration Examples
 
+The `args` path below assumes npm's **default** global prefix for each platform.
+A custom prefix (nvm, fnm, Volta, a hand-set `prefix`) puts the package
+elsewhere, so confirm with `npm root -g` and use what it prints:
+
+```bash
+node -e "console.log(require('path').join(process.argv[1],'oh-memos-mcp/dist/index.js'))" "$(npm root -g)"
+```
+
 ### Linux / macOS
 
 ```json
 {
   "mcpServers": {
     "oh-memos": {
-      "command": "npx",
-      "args": ["-y", "oh-memos-mcp"],
+      "command": "node",
+      "args": ["/usr/local/lib/node_modules/oh-memos-mcp/dist/index.js"],
       "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"
+        "MEMOS_CUBES_DIR": "/home/user/oh-memos/data/oh-memos_cubes",
+        "MEMOS_ENV_FILE": "/home/user/oh-memos/.env"
       }
     }
   }
@@ -91,13 +137,14 @@ npx -y oh-memos-mcp
 {
   "mcpServers": {
     "oh-memos": {
-      "command": "npx",
-      "args": ["-y", "oh-memos-mcp"],
+      "command": "node",
+      "args": ["C:/Users/you/AppData/Roaming/npm/node_modules/oh-memos-mcp/dist/index.js"],
       "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"
+        "MEMOS_CUBES_DIR": "G:/test/oh-memos/data/oh-memos_cubes",
+        "MEMOS_ENV_FILE": "G:/test/oh-memos/.env"
       }
     }
   }
@@ -110,13 +157,14 @@ npx -y oh-memos-mcp
 {
   "mcpServers": {
     "oh-memos": {
-      "command": "npx",
-      "args": ["-y", "oh-memos-mcp"],
+      "command": "node",
+      "args": ["/usr/lib/node_modules/oh-memos-mcp/dist/index.js"],
       "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"
+        "MEMOS_CUBES_DIR": "/mnt/g/test/oh-memos/data/oh-memos_cubes",
+        "MEMOS_ENV_FILE": "/mnt/g/test/oh-memos/.env"
       }
     }
   }
@@ -137,13 +185,14 @@ be deleted without a prompt; add it only if you have decided you want that.
   "mcpServers": {
     "oh-memos": {
       "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "oh-memos-mcp"],
+      "command": "node",
+      "args": ["<npm root -g>/oh-memos-mcp/dist/index.js"],
       "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_CUBES_DIR": "/path/to/oh-memos/data/oh-memos_cubes",
+        "MEMOS_ENV_FILE": "/path/to/oh-memos/.env"
       },
       "alwaysAllow": [
         "memos_context_resume",
@@ -183,16 +232,80 @@ be deleted without a prompt; add it only if you have decided you want that.
 | `NEO4J_PASSWORD` | No | — | Neo4j password |
 | `MEMOS_ENV_FILE` | No | — | Explicit path to a `.env` file. Highest priority — see below |
 
+### Mode and provider
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MEMOS_MODE` | No | `full` | `lite` runs the local JSONL provider with no API, Python, Neo4j, or Qdrant. `full` uses the HTTP backend |
+| `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)
+
+These change what search returns. All are off or conservative by default, so
+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_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
+> still returns memories and logs nothing unusual — you simply get no ` via `
+> annotations. If you enabled the switch and see no annotations, check that the
+> Neo4j variables actually reach the server (under `npx`, that means
+> `MEMOS_ENV_FILE`), not that the feature is missing.
+
+Ranking that needs no configuration: per-type exponential decay (a `PROGRESS`
+note ages out in weeks, a `DECISION` stays relevant for years), access
+reinforcement, and near-duplicate folding with per-type thresholds. Folded
+duplicates are reported as ` · folded N: <ids>` rather than dropped.
+
+### Lite embeddings
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MEMOS_LITE_EMBED` | No | `auto` | `off` forces lexical search. `auto` uses Ollama embeddings when reachable and falls back to lexical |
+| `MEMOS_LITE_EMBED_URL` | No | `http://localhost:11434` | Ollama endpoint |
+| `MEMOS_LITE_EMBED_MODEL` | No | `nomic-embed-text` | Embedding model |
+
+### Read from `.env`, not from the client config
+
+The server reads these when building a cube, and they are conventionally kept in
+`.env` rather than repeated in every client config. `MOS_CHAT_MODEL` is
+**required** — cube registration dies on it first, surfacing as a cube that
+"registers" and immediately reports itself unregistered.
+
+| Variable | Description |
+|----------|-------------|
+| `MOS_CHAT_MODEL` | Chat model for memory extraction. Required |
+| `MOS_EMBEDDER_BACKEND` / `_PROVIDER` / `_MODEL` / `_API_BASE` | Embedder wiring |
+| `MOS_ENABLE_REORGANIZE` | Background memory reorganization |
+| `NEO4J_BACKEND` / `NEO4J_URI` / `NEO4J_DB_NAME` | Graph DB connection for cube construction |
+| `NEO4J_AUTO_CREATE` / `NEO4J_USE_MULTI_DB` | Cube creation policy |
+
 > **On locating `.env`**: without `MEMOS_ENV_FILE`, the file is found by guessing
 > from position (working directory, two levels above the package, then dotenv's
-> upward search). That works from a checkout and **never works under `npx`**,
-> where the package root sits in the npm cache and every candidate misses — so no
-> variable loads at all. Set `MEMOS_ENV_FILE` (or pass `--memos-env-file`) when the
-> client's working directory and the install location are both outside the project.
-> A path that does not exist warns on stderr rather than failing silently.
+> upward search). That works from a checkout but **not from a global install or
+> `npx`**, where the package sits outside the project and every candidate misses —
+> so no variable loads at all. Set `MEMOS_ENV_FILE` (or pass `--memos-env-file`)
+> when the client's working directory and the install location are both outside the
+> project. A path that does not exist warns on stderr rather than failing silently.
 >
 > Copy `.env.example` to get started.
 
+> **`MEMOS_ENV_FILE` wins over the client config.** It is loaded with
+> `override: true`, so a value in that file beats the same key in the MCP client's
+> `env` block. The positional fallbacks are the opposite — they only fill gaps and
+> never override the launcher. This is deliberate: an explicitly named env file is
+> meant to be authoritative, while a `.env` that merely happens to sit nearby is
+> not. The practical consequence is that switches like
+> `MEMOS_SHOW_WORKING_MEMORY` cannot be flipped from the client config once
+> `.env` sets them — edit the env file instead.
+
 ---
 
 ## Tools (17)

package/dist/handlers/memory.js

@@ -11,6 +11,7 @@ import { ensureCubeRegistered } from "../cube-manager.js";
 import { parseMemoryWriteResponse } 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";
 // formatMemoriesForDisplay intentionally not imported here — list output is built
 // from the truncated allMemories in handleMemosList (avoids printing the full cube).
 import { PREVIEW_COUNT, shouldCompact, compactedResultToText, toMinimal, toFull, } from "../models.js";
@@ -223,6 +224,26 @@ export async function handleMemosList(arguments_) {
 // ============================================================================
 // memos_get
 // ============================================================================
+/**
+ * 取同源碎片。只在当前记忆确实带原文时才发这次请求 —— fast-path 写入不会付这个代价。
+ *
+ * 失败即返回空数组：同源列表是附加信息，取不到时 `memos_get` 仍应给出原文。
+ * 拉取量上限 200，避免大 cube 上把整库拉回来（碎片来自同一次写入，时间相邻，
+ * 后端按 updated_at 倒序返回，200 条足以覆盖）。
+ */
+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);
+        if (!result.success || !result.data)
+            return [];
+        const data = result.data.data;
+        return findSiblings(target, extractMemoriesFromData(data ?? {}));
+    }
+    catch (err) {
+        logger.debug(`sibling lookup failed: ${String(err)}`);
+        return [];
+    }
+}
 export async function handleMemosGet(arguments_) {
     const cubeId = getCubeIdFromArgs(arguments_);
     const memoryId = String(arguments_.memory_id ?? "");
@@ -251,10 +272,11 @@ export async function handleMemosGet(arguments_) {
                     `**Cube**: ${full.cubeId} (local)`,
                     full.tags.length ? `**Tags**: ${full.tags.join(", ")}` : "",
                     full.createdAt ? `**Created**: ${full.createdAt}` : "",
-                    "",
-                    "### Content",
-                    "",
-                    full.content,
+                    // Lite 的 JSONL 不写 sources，verbatimOf 返回 null → 保持原有输出。
+                    // 保留这个分支是为了后端哪天开始写该字段时自动生效。
+                    ...(verbatimOf(node) === null
+                        ? ["", "### Content", "", full.content]
+                        : renderVerbatimSections(verbatimOf(node), [], full.content)),
                 ]
                     .filter(Boolean)
                     .join("\n"),
@@ -272,6 +294,7 @@ export async function handleMemosGet(arguments_) {
             // Full 模式同样记在本机侧车 —— 使用度是本机数据，不需要后端端点。
             recordAccess(MEMOS_CUBES_DIR, cubeId, [memoryId]);
             const fullMem = toFull(resultData, cubeId, MEMOS_USER);
+            const verbatim = verbatimOf(resultData);
             const lines = [
                 "## 📝 Memory Details",
                 "",
@@ -285,7 +308,14 @@ export async function handleMemosGet(arguments_) {
                 lines.push(`**Tags**: ${fullMem.tags.join(", ")}`);
             if (fullMem.createdAt)
                 lines.push(`**Created**: ${fullMem.createdAt}`);
-            lines.push("", "### Content", "", fullMem.content);
+            // 有原文时原文即正文，`memory` 字段（LLM 概括）降级到下方的「抽取概括」区块。
+            // 无原文（fast-path 写入）时保持原有行为。
+            if (verbatim === null) {
+                lines.push("", "### Content", "", fullMem.content);
+            }
+            else {
+                lines.push(...renderVerbatimSections(verbatim, await fetchSiblings(cubeId, resultData), fullMem.content));
+            }
             if (fullMem.background) {
                 lines.push("", "### Background", "", fullMem.background);
             }

package/dist/handlers/search.d.ts

@@ -4,9 +4,52 @@
  * memos_search, memos_search, memos_suggest, memos_context_resume
  */
 import type { TextContent, MemoryNode } from "../types.js";
+/**
+ * Cypher for the recency query behind `memos_context_resume` and the
+ * `temporal` search intent.
+ *
+ * ## 为什么必须在 Cypher 里排除 WorkingMemory，而不是在 handler 层
+ *
+ * 这个查询原先不 RETURN `memory_type`，构造出的 metadata 只有
+ * `relativity`/`temporal_rank`/`source`。于是 `isEphemeralTier()` 永远读到
+ * undefined 并判为可见 —— **下游任何分层过滤对 temporal 记忆都是空转**。
+ *
+ * 受害面是四个调用点，不只是 context_resume：
+ *   - `memos_context_resume`（成对显示，用户实测发现）
+ *   - `memos_search` 的 temporal intent 两处（经 applyMemoryQualityPolicy，
+ *     过滤存在但读不到字段）
+ *   - `memos_think`（同上）
+ *
+ * 在 Cypher 里滤还顺带避开超额取数：`LIMIT` 在过滤之后，要 10 条就得 10 条真
+ * 记忆。若放到 handler 层，limit 会被随即隐藏的副本吃掉（这正是 §9.6 在 list
+ * 路径踩过的顺序缺陷）。
+ *
+ * 同时 RETURN `memory_type`，让下游过滤从空转变成真的有落点 —— 双保险，
+ * 且 `mergeTemporalResults` 之后的 quality policy 也能正确判层。
+ *
+ * 逃生开关 `MEMOS_SHOW_WORKING_MEMORY=true` 时不加这个条件，与
+ * `filterEphemeralTier` 的语义保持一致。
+ */
+export declare function buildTemporalCypher(timeWindowHours?: number, env?: NodeJS.ProcessEnv): string;
 export declare function getTemporalMemories(cubeId: string, topK?: number, timeWindowHours?: number): Promise<MemoryNode[]>;
 export declare function handleMemosSearch(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleMemosSearchContext(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleMemosSuggest(arguments_: Record<string, unknown>): Promise<TextContent[]>;
+/**
+ * 分层过滤 + 截断，供 `memos_context_resume` 两条路径共用。
+ *
+ * ## 顺序要紧：滤层级必须在 slice 之前
+ *
+ * 放到之后，`limit` 会被随即隐藏的 WorkingMemory 副本吃掉 —— 要 10 条只拿到
+ * 5 条（用户实测就是 10 条里 5 对）。与 `prepareListMemories` 同形，
+ * 那处已经因为同样的原因栽过一次。
+ *
+ * ## 为什么必须是导出的函数
+ *
+ * 原先这段逻辑内联在 handler 里，单测触达不到 —— §9.6 与 P1.5 已两次证明：
+ * 切断 handler 内联逻辑时全部单测仍然通过。在测试里自行组合只能证明测试文件，
+ * 证明不了 handler。所以 handler 与测试必须调用**同一个**函数。
+ */
+export declare function prepareResumeMemories(memories: readonly MemoryNode[], limit: number, env?: NodeJS.ProcessEnv): MemoryNode[];
 export declare function handleMemosContextResume(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 //# sourceMappingURL=search.d.ts.map

package/dist/handlers/search.js

@@ -15,6 +15,7 @@ import { summarizeActiveCanvases } from "./canvas.js";
 import { applyMemoryQualityPolicy } from "../memory-quality.js";
 import { readAccessStats } from "../access-tracker.js";
 import { buildSpreadCypher, mergeSpread, pickSeeds, rankNeighbours, rowToNeighbour, spreadEnabled, spreadRelativity, toSpreadNode, } from "../spreading-activation.js";
+import { filterEphemeralTier, showsEphemeralTier } from "../memory-tier.js";
 import { apiErrorResponse, cubeRegistrationError, getCubeIdFromArgs, } from "./utils.js";
 /**
  * 检索排序策略的选项。
@@ -35,26 +36,59 @@ function qualityOptions(cubeId, query) {
 // ============================================================================
 // Temporal Graph Query (Neo4j)
 // ============================================================================
+/**
+ * Cypher for the recency query behind `memos_context_resume` and the
+ * `temporal` search intent.
+ *
+ * ## 为什么必须在 Cypher 里排除 WorkingMemory，而不是在 handler 层
+ *
+ * 这个查询原先不 RETURN `memory_type`，构造出的 metadata 只有
+ * `relativity`/`temporal_rank`/`source`。于是 `isEphemeralTier()` 永远读到
+ * undefined 并判为可见 —— **下游任何分层过滤对 temporal 记忆都是空转**。
+ *
+ * 受害面是四个调用点，不只是 context_resume：
+ *   - `memos_context_resume`（成对显示，用户实测发现）
+ *   - `memos_search` 的 temporal intent 两处（经 applyMemoryQualityPolicy，
+ *     过滤存在但读不到字段）
+ *   - `memos_think`（同上）
+ *
+ * 在 Cypher 里滤还顺带避开超额取数：`LIMIT` 在过滤之后，要 10 条就得 10 条真
+ * 记忆。若放到 handler 层，limit 会被随即隐藏的副本吃掉（这正是 §9.6 在 list
+ * 路径踩过的顺序缺陷）。
+ *
+ * 同时 RETURN `memory_type`，让下游过滤从空转变成真的有落点 —— 双保险，
+ * 且 `mergeTemporalResults` 之后的 quality policy 也能正确判层。
+ *
+ * 逃生开关 `MEMOS_SHOW_WORKING_MEMORY=true` 时不加这个条件，与
+ * `filterEphemeralTier` 的语义保持一致。
+ */
+export function buildTemporalCypher(timeWindowHours, env = process.env) {
+    const timeFilter = timeWindowHours
+        ? `AND n.updated_at >= datetime() - duration({hours: ${timeWindowHours}})`
+        : "";
+    const tierFilter = showsEphemeralTier(env)
+        ? ""
+        : "AND coalesce(n.memory_type, '') <> 'WorkingMemory'";
+    return `
+    MATCH (n:Memory)
+    WHERE n.user_name = $user_name
+    AND n.status = 'activated'
+    ${timeFilter}
+    ${tierFilter}
+    RETURN n.id AS id, n.memory AS memory, n.key AS key,
+           n.updated_at AS updated_at, n.background AS background,
+           n.tags AS tags, n.memory_type AS memory_type
+    ORDER BY n.updated_at DESC
+    LIMIT $top_k
+  `;
+}
 export async function getTemporalMemories(cubeId, topK = 10, timeWindowHours) {
     if (!NEO4J_HTTP_URL || !NEO4J_USER || !NEO4J_PASSWORD) {
         logger.debug("Neo4j config missing, skipping temporal query");
         return [];
     }
     const auth = Buffer.from(`${NEO4J_USER}:${NEO4J_PASSWORD}`).toString("base64");
-    const timeFilter = timeWindowHours
-        ? `AND n.updated_at >= datetime() - duration({hours: ${timeWindowHours}})`
-        : "";
-    const cypher = `
-    MATCH (n:Memory)
-    WHERE n.user_name = $user_name
-    AND n.status = 'activated'
-    ${timeFilter}
-    RETURN n.id AS id, n.memory AS memory, n.key AS key,
-           n.updated_at AS updated_at, n.background AS background,
-           n.tags AS tags
-    ORDER BY n.updated_at DESC
-    LIMIT $top_k
-  `;
+    const cypher = buildTemporalCypher(timeWindowHours);
     try {
         const response = await fetchWithTimeout(NEO4J_HTTP_URL, {
             method: "POST",
@@ -96,6 +130,13 @@ export async function getTemporalMemories(cubeId, topK = 10, timeWindowHours) {
                             relativity: 0.8 - i * 0.05,
                             temporal_rank: i + 1,
                             source: "temporal_query",
+                            // 带上层级，否则下游 filterEphemeralTier 读到 undefined 而空转。
+                            // Cypher 已排除 WorkingMemory，这里是双保险 + 让 quality policy
+                            // 能正确判层。r[6] 可能缺失（旧节点没写该属性），留 undefined 即
+                            // 按可见处理，与 isEphemeralTier 的缺失语义一致。
+                            ...(r.length > 6 && r[6] != null
+                                ? { memory_type: String(r[6]) }
+                                : {}),
                         },
                     });
                 }
@@ -467,7 +508,7 @@ function renderContextResume(cubeId, recentMemories) {
         lines.push(...canvasLines);
     if (recentMemories.length > 0) {
         lines.push(`**Recent memories** (${recentMemories.length} items, last 24h):`, "");
-        for (let i = 0; i < Math.min(recentMemories.length, 10); i++)
+        for (let i = 0; i < Math.min(recentMemories.length, RESUME_LIMIT); i++)
             lines.push(`${i + 1}. ${(recentMemories[i].memory ?? "").slice(0, 120).split("\n")[0]}`);
     }
     else
@@ -475,25 +516,68 @@ function renderContextResume(cubeId, recentMemories) {
     lines.push("", "---", "**REMINDER**: Use MCP memos tools for ALL memory operations.", "NEVER use `mkdir` or `Write` to create memory files.");
     return [{ type: "text", text: lines.join("\n") }];
 }
+/**
+ * 分层过滤 + 截断，供 `memos_context_resume` 两条路径共用。
+ *
+ * ## 顺序要紧：滤层级必须在 slice 之前
+ *
+ * 放到之后，`limit` 会被随即隐藏的 WorkingMemory 副本吃掉 —— 要 10 条只拿到
+ * 5 条（用户实测就是 10 条里 5 对）。与 `prepareListMemories` 同形，
+ * 那处已经因为同样的原因栽过一次。
+ *
+ * ## 为什么必须是导出的函数
+ *
+ * 原先这段逻辑内联在 handler 里，单测触达不到 —— §9.6 与 P1.5 已两次证明：
+ * 切断 handler 内联逻辑时全部单测仍然通过。在测试里自行组合只能证明测试文件，
+ * 证明不了 handler。所以 handler 与测试必须调用**同一个**函数。
+ */
+export function prepareResumeMemories(memories, limit, env = process.env) {
+    const visible = filterEphemeralTier(memories, (m) => m.metadata, env);
+    return [...visible].slice(0, limit);
+}
+/** `memos_context_resume` 显示的条数上限。 */
+const RESUME_LIMIT = 10;
+/**
+ * 取数时的超额系数。
+ *
+ * API 回退路径的 limit 由服务端施加，过滤只能在取回之后做，所以必须多取 ——
+ * 每条记忆恰好有一个 WorkingMemory 副本，2 倍即可覆盖，取 3 倍留余量
+ * （旧节点可能没有副本，多取的部分会被 slice 丢掉，无副作用）。
+ *
+ * temporal 路径不需要这个：Cypher 的 LIMIT 在过滤之后。
+ */
+const RESUME_OVERFETCH = 3;
 export async function handleMemosContextResume(arguments_) {
     const cubeId = getCubeIdFromArgs(arguments_);
     const localProvider = getMemoryProvider(MEMOS_CUBES_DIR);
     if (localProvider) {
-        const recentMemories = await localProvider.recent(cubeId, 24, 10);
-        return renderContextResume(cubeId, recentMemories);
+        // Lite 的 JSONL 不写 memory_type，filterEphemeralTier 按缺失即可见处理，
+        // 所以这里过滤是空操作 —— 保留它是为了后端哪天开始写该字段时自动生效。
+        const recentMemories = await localProvider.recent(cubeId, 24, RESUME_LIMIT);
+        return renderContextResume(cubeId, prepareResumeMemories(recentMemories, RESUME_LIMIT));
     }
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
-    // Try temporal query first
-    let recentMemories = await getTemporalMemories(cubeId, 10, 24);
+    // Try temporal query first. Cypher 已排除 WorkingMemory 且 LIMIT 在过滤之后，
+    // 所以按原样取 RESUME_LIMIT 条就是 RESUME_LIMIT 条真记忆。
+    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, { params: { user_id: MEMOS_USER, mem_cube_id: cubeId, limit: 10 } }, ensureCubeRegistered);
+        const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, {
+            params: {
+                user_id: MEMOS_USER,
+                mem_cube_id: cubeId,
+                // 超额取：服务端施加 limit，过滤只能在取回后做，不多取则 limit 被
+                // 随即隐藏的副本吃掉。
+                limit: RESUME_LIMIT * RESUME_OVERFETCH,
+            },
+        }, ensureCubeRegistered);
         if (result.success && result.data) {
             recentMemories = extractSearchMemories(result.data.data ?? {});
         }
     }
+    recentMemories = prepareResumeMemories(recentMemories, RESUME_LIMIT);
     const lines = ["## Context Resumed", ""];
     // Unfinished task canvases come first: after a compaction, "where was I" is
     // more urgent than "what do we know". Headlines only — the model opens what it
@@ -503,7 +587,7 @@ export async function handleMemosContextResume(arguments_) {
         lines.push(...canvasLines);
     if (recentMemories.length > 0) {
         lines.push(`**Recent memories** (${recentMemories.length} items, last 24h):`, "");
-        for (let i = 0; i < Math.min(recentMemories.length, 10); i++) {
+        for (let i = 0; i < Math.min(recentMemories.length, RESUME_LIMIT); i++) {
             const mem = recentMemories[i];
             const content = mem.memory ?? "";
             const summary = content.slice(0, 120).split("\n")[0];

package/dist/spreading-activation.js

@@ -32,20 +32,20 @@ export const SPREAD_FROM_KEY = "spread_from";
  */
 export function buildSpreadCypher() {
     const types = SPREAD_EDGE_TYPES.map((t) => `'${t}'`).join(", ");
-    return `
-    MATCH (n:Memory)-[r]-(m:Memory)
-    WHERE n.id IN $seeds
-      AND type(r) IN [${types}]
-      AND NOT m.id IN $seeds
-      AND m.user_name = $user_name
-      AND coalesce(m.status, 'activated') = 'activated'
-      AND coalesce(m.memory_type, '') <> 'WorkingMemory'
-      AND coalesce(m.type, '') <> 'reasoning'
-    WITH m, n, type(r) AS via, size([(m)--() | 1]) AS degree
-    WITH m, collect({via: via, from: n.id})[0] AS edge, degree
-    RETURN m.id AS id, m.memory AS memory, m.key AS key, m.tags AS tags,
-           m.updated_at AS updated_at, edge.via AS via, edge.from AS from,
-           degree
+    return `
+    MATCH (n:Memory)-[r]-(m:Memory)
+    WHERE n.id IN $seeds
+      AND type(r) IN [${types}]
+      AND NOT m.id IN $seeds
+      AND m.user_name = $user_name
+      AND coalesce(m.status, 'activated') = 'activated'
+      AND coalesce(m.memory_type, '') <> 'WorkingMemory'
+      AND coalesce(m.type, '') <> 'reasoning'
+    WITH m, n, type(r) AS via, size([(m)--() | 1]) AS degree
+    WITH m, collect({via: via, from: n.id})[0] AS edge, degree
+    RETURN m.id AS id, m.memory AS memory, m.key AS key, m.tags AS tags,
+           m.updated_at AS updated_at, edge.via AS via, edge.from AS from,
+           degree
   `;
 }
 /**

package/dist/verbatim-source.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 原文取回（verbatim source）。
+ *
+ * ## 为什么需要它
+ *
+ * `MOS_TYPED_SAVE_FAST=false` 时后端走 LLM 抽取：一次写入被切成多条记忆，每条的
+ * `memory` 字段是 LLM 概括（约 200-250 字），而**逐字原文保存在
+ * `metadata.sources[].content` 里**（实测：一条 877 字原文被切成 5 条，5 条的
+ * sources 内容 sha 完全相同）。
+ *
+ * 于是同一份数据有两层，用途不同：
+ *
+ * | 层 | 内容 | 服务于 |
+ * |---|---|---|
+ * | `memory` | LLM 概括，细粒度 | 向量化与建边 —— 图谱节点质量、扩散联想 |
+ * | `metadata.sources[].content` | 逐字原文 | `memos_get` —— 完整上下文 |
+ *
+ * 两者不冲突：抽取让图谱拿到细粒度节点（`memos_search` 的 ` via CAUSE from` 联想
+ * 依赖它），而 `memos_get` 读 sources 就不丢原文。维护者的决定是「保证图谱节点
+ * 编写分析，同时让 memos_get 拉原文」。
+ *
+ * ## 同源判定用内容指纹，不用 session_id
+ *
+ * 实测 5 条碎片的 `session_id` 相同 —— 但那是**整个 MCP 会话**的 id，一个会话里
+ * 的多次无关写入会共享它，用它分组会把无关记忆归到一起。`created_at` 也不行：
+ * 5 条各不相同（微秒级递增）。
+ *
+ * 只有 sources 内容本身是精确的分组键。
+ *
+ * ## fast-path 下本模块是无操作
+ *
+ * `MOS_TYPED_SAVE_FAST=true`（默认）时原样存储，`memory` 就是原文、`sources` 为空
+ * → `verbatimOf()` 返回 null，渲染层保持原有行为。所以这套改动对两种模式都安全。
+ *
+ * 设计讨论见 docs/design/memory-retrieval-optimization.md。
+ */
+import type { MemoryNode } from "./types.js";
+/**
+ * 取出逐字原文。
+ *
+ * 没有 sources、sources 为空、或第一条没有非空 content 时返回 null —— 调用方据此
+ * 判断「这条是 fast-path 存的，无需原文层」。
+ *
+ * 多条 sources 时用第一条：LLM 抽取路径下一次写入只产生一个 source（实测
+ * `src_n=1`）。多条的情况来自 messages 数组写入，此时第一条仍是用户输入。
+ */
+export declare function verbatimOf(node: MemoryNode | undefined | null): string | null;
+/**
+ * 同源指纹。同一次写入切出的碎片共享它。
+ *
+ * 直接用原文本身，不做哈希：这是进程内的分组键，不持久化也不跨机器比较，
+ * 字符串相等就是精确判定。
+ *
+ * 初版加了 `${text.length}:` 前缀，理由是「让不同原文在第一个字符就分开」——
+ * 变异验证时发现构造不出它能防住的碰撞（去掉前缀后 `abc` 与 `abcdef` 指纹依然
+ * 不同），且 V8 的字符串相等本就先比长度。没有测试能支撑的防御代码比没有更糟，
+ * 所以删掉。
+ *
+ * 无原文返回 null —— null 不参与分组，避免把所有 fast-path 记忆归成一组。
+ */
+export declare function sourceFingerprint(node: MemoryNode | undefined | null): string | null;
+/** 同源碎片的展示条目。 */
+export interface SiblingRef {
+    id: string;
+    key: string;
+}
+/** 渲染原文区块与同源碎片列表，供 `memos_get` 两条路径共用。 */
+export declare function renderVerbatimSections(verbatim: string | null, siblings: readonly SiblingRef[], summary: string): string[];
+/**
+ * 在候选集里找与 target 同源的其他碎片。
+ *
+ * 排除 target 自身，也排除没有原文的节点。顺序按候选集原顺序，由调用方决定
+ * 候选集怎么排（后端返回顺序通常已按 created_at）。
+ */
+export declare function findSiblings(target: MemoryNode | undefined | null, candidates: readonly (MemoryNode | undefined | null)[], limit?: number): SiblingRef[];
+//# sourceMappingURL=verbatim-source.d.ts.map

package/dist/verbatim-source.js

@@ -0,0 +1,118 @@
+/**
+ * 原文取回（verbatim source）。
+ *
+ * ## 为什么需要它
+ *
+ * `MOS_TYPED_SAVE_FAST=false` 时后端走 LLM 抽取：一次写入被切成多条记忆，每条的
+ * `memory` 字段是 LLM 概括（约 200-250 字），而**逐字原文保存在
+ * `metadata.sources[].content` 里**（实测：一条 877 字原文被切成 5 条，5 条的
+ * sources 内容 sha 完全相同）。
+ *
+ * 于是同一份数据有两层，用途不同：
+ *
+ * | 层 | 内容 | 服务于 |
+ * |---|---|---|
+ * | `memory` | LLM 概括，细粒度 | 向量化与建边 —— 图谱节点质量、扩散联想 |
+ * | `metadata.sources[].content` | 逐字原文 | `memos_get` —— 完整上下文 |
+ *
+ * 两者不冲突：抽取让图谱拿到细粒度节点（`memos_search` 的 ` via CAUSE from` 联想
+ * 依赖它），而 `memos_get` 读 sources 就不丢原文。维护者的决定是「保证图谱节点
+ * 编写分析，同时让 memos_get 拉原文」。
+ *
+ * ## 同源判定用内容指纹，不用 session_id
+ *
+ * 实测 5 条碎片的 `session_id` 相同 —— 但那是**整个 MCP 会话**的 id，一个会话里
+ * 的多次无关写入会共享它，用它分组会把无关记忆归到一起。`created_at` 也不行：
+ * 5 条各不相同（微秒级递增）。
+ *
+ * 只有 sources 内容本身是精确的分组键。
+ *
+ * ## fast-path 下本模块是无操作
+ *
+ * `MOS_TYPED_SAVE_FAST=true`（默认）时原样存储，`memory` 就是原文、`sources` 为空
+ * → `verbatimOf()` 返回 null，渲染层保持原有行为。所以这套改动对两种模式都安全。
+ *
+ * 设计讨论见 docs/design/memory-retrieval-optimization.md。
+ */
+/**
+ * 取出逐字原文。
+ *
+ * 没有 sources、sources 为空、或第一条没有非空 content 时返回 null —— 调用方据此
+ * 判断「这条是 fast-path 存的，无需原文层」。
+ *
+ * 多条 sources 时用第一条：LLM 抽取路径下一次写入只产生一个 source（实测
+ * `src_n=1`）。多条的情况来自 messages 数组写入，此时第一条仍是用户输入。
+ */
+export function verbatimOf(node) {
+    const sources = node?.metadata
+        ?.sources;
+    if (!Array.isArray(sources) || sources.length === 0)
+        return null;
+    const first = sources[0];
+    const content = first?.content;
+    if (typeof content !== "string" || content.trim() === "")
+        return null;
+    return content;
+}
+/**
+ * 同源指纹。同一次写入切出的碎片共享它。
+ *
+ * 直接用原文本身，不做哈希：这是进程内的分组键，不持久化也不跨机器比较，
+ * 字符串相等就是精确判定。
+ *
+ * 初版加了 `${text.length}:` 前缀，理由是「让不同原文在第一个字符就分开」——
+ * 变异验证时发现构造不出它能防住的碰撞（去掉前缀后 `abc` 与 `abcdef` 指纹依然
+ * 不同），且 V8 的字符串相等本就先比长度。没有测试能支撑的防御代码比没有更糟，
+ * 所以删掉。
+ *
+ * 无原文返回 null —— null 不参与分组，避免把所有 fast-path 记忆归成一组。
+ */
+export function sourceFingerprint(node) {
+    return verbatimOf(node);
+}
+/** 渲染原文区块与同源碎片列表，供 `memos_get` 两条路径共用。 */
+export function renderVerbatimSections(verbatim, siblings, summary) {
+    if (verbatim === null)
+        return [];
+    const lines = ["", "### 原文 | Verbatim source", "", verbatim];
+    // 概括也一并给出：它是向量化与建边的实际输入，看得见才能判断图谱节点切得对不对。
+    if (summary.trim() !== "" && summary.trim() !== verbatim.trim()) {
+        lines.push("", "### 本节点的抽取概括 | Extracted summary (this node)", "", summary);
+    }
+    if (siblings.length > 0) {
+        lines.push("", `### 同源节点 | Sibling nodes (${siblings.length})`, "", "同一份原文被 LLM 抽取切成的其他节点。原文在每条上都完整，无需逐条取回；", "这里列出是为了看清图谱节点的切分方式。", "Other nodes the same source was split into. Each carries the full source;", "listed so the graph-node segmentation is visible.", "");
+        for (const s of siblings) {
+            lines.push(`- \`${s.id}\`${s.key ? ` — ${s.key}` : ""}`);
+        }
+    }
+    return lines;
+}
+/**
+ * 在候选集里找与 target 同源的其他碎片。
+ *
+ * 排除 target 自身，也排除没有原文的节点。顺序按候选集原顺序，由调用方决定
+ * 候选集怎么排（后端返回顺序通常已按 created_at）。
+ */
+export function findSiblings(target, candidates, limit = 12) {
+    const fp = sourceFingerprint(target);
+    if (fp === null)
+        return [];
+    const targetId = String(target?.id ?? "");
+    const out = [];
+    const seen = new Set();
+    for (const node of candidates) {
+        if (out.length >= limit)
+            break;
+        const id = String(node?.id ?? "");
+        if (!id || id === targetId || seen.has(id))
+            continue;
+        if (sourceFingerprint(node) !== fp)
+            continue;
+        seen.add(id);
+        const meta = (node?.metadata ?? {});
+        const key = String(meta.key ?? "").trim();
+        out.push({ id, key });
+    }
+    return out;
+}
+//# sourceMappingURL=verbatim-source.js.map

package/package.json

@@ -1,67 +1,68 @@
-{
-  "name": "oh-memos-mcp",
-  "version": "3.1.0",
-  "description": "MCP Server for oh-memos — Intelligent Memory Management (Node.js, no Python required)",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "oh-memos-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "README.md",
-    "CHANGELOG.md",
-    ".env.example"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run",
-    "test:protocol": "npm run build && node scripts/protocol-smoke.mjs && node scripts/protocol-v2-smoke.mjs",
-    "test:protocol:v2": "npm run build && node scripts/protocol-v2-smoke.mjs",
-    "test:lite-smoke": "npm run build && node scripts/lite-smoke-test.mjs",
-    "test:spread-smoke": "npm run build && node scripts/spread-smoke-test.mjs",
-    "schema:semantic": "npm run build && node scripts/schema-semantic-snapshot.mjs --check",
-    "schema:semantic:freeze": "npm run build && node scripts/schema-semantic-snapshot.mjs --write",
-    "test:pack": "node scripts/pack-contract.mjs",
-    "test:watch": "vitest",
-    "schema:budget": "npm run build && node scripts/schema-budget.mjs --check",
-    "schema:budget:freeze": "npm run build && node scripts/schema-budget.mjs --write",
-    "prepublishOnly": "npm run build"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "keywords": [
-    "mcp",
-    "memory",
-    "memos",
-    "claude",
-    "ai",
-    "knowledge-graph"
-  ],
-  "author": "xigou",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/lsg1103275794/oh-memos.git",
-    "directory": "mcp-server-node"
-  },
-  "bugs": {
-    "url": "https://github.com/lsg1103275794/oh-memos/issues"
-  },
-  "homepage": "https://github.com/lsg1103275794/oh-memos/tree/main/mcp-server-node",
-  "dependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
-    "dotenv": "^16.0.0",
-    "zod": "^4.2.0"
-  },
-  "devDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
-    "@types/node": "^22.0.0",
-    "tsx": "^4.23.12",
-    "typescript": "^5.5.0",
-    "vitest": "3.2.7"
-  }
-}
+{
+  "name": "oh-memos-mcp",
+  "version": "3.1.2",
+  "description": "MCP Server for oh-memos — Intelligent Memory Management (Node.js, no Python required)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "oh-memos-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:protocol": "npm run build && node scripts/protocol-smoke.mjs && node scripts/protocol-v2-smoke.mjs",
+    "test:protocol:v2": "npm run build && node scripts/protocol-v2-smoke.mjs",
+    "test:lite-smoke": "npm run build && node scripts/lite-smoke-test.mjs",
+    "test:spread-smoke": "npm run build && node scripts/spread-smoke-test.mjs",
+    "test:host-env-smoke": "npm run build && node scripts/host-env-smoke.mjs",
+    "schema:semantic": "npm run build && node scripts/schema-semantic-snapshot.mjs --check",
+    "schema:semantic:freeze": "npm run build && node scripts/schema-semantic-snapshot.mjs --write",
+    "test:pack": "node scripts/pack-contract.mjs",
+    "test:watch": "vitest",
+    "schema:budget": "npm run build && node scripts/schema-budget.mjs --check",
+    "schema:budget:freeze": "npm run build && node scripts/schema-budget.mjs --write",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "memos",
+    "claude",
+    "ai",
+    "knowledge-graph"
+  ],
+  "author": "xigou",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lsg1103275794/oh-memos.git",
+    "directory": "mcp-server-node"
+  },
+  "bugs": {
+    "url": "https://github.com/lsg1103275794/oh-memos/issues"
+  },
+  "homepage": "https://github.com/lsg1103275794/oh-memos/tree/main/mcp-server-node",
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "dotenv": "^16.0.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.23.12",
+    "typescript": "^5.5.0",
+    "vitest": "3.2.7"
+  }
+}