oh-memos-mcp 3.0.0 → 3.1.0

package/dist/handlers/graph.js

@@ -3,11 +3,11 @@
  *
  * 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 { MEMOS_URL, MEMOS_USER, NEO4J_HTTP_URL, NEO4J_USER, NEO4J_PASSWORD, logger, registeredCubes, } from "../config.js";
 import { fetchWithTimeout } from "../api-client.js";
 import { ensureCubeRegistered } from "../cube-manager.js";
 import { formatProvenance } from "../graph-provenance.js";
-import { buildGraphImportPlan, renderGraphImportPlan } from "../graphify-import.js";
+import { buildGraphImportPlan, renderGraphImportPlan, } from "../graphify-import.js";
 import { detectQueryIntent, extractMemoriesFromResponse, getGraphsForIntent, getIntentDescription, } from "../query-processing.js";
 import { ERR_NEO4J_CONFIG, ERR_PARAM_MISSING, apiErrorResponse, cubeRegistrationError, errorResponse, getCubeIdFromArgs, } from "./utils.js";
 // ============================================================================
@@ -22,8 +22,13 @@ import { ERR_NEO4J_CONFIG, ERR_PARAM_MISSING, apiErrorResponse, cubeRegistration
  */
 export function handleMemosGraphifyImport(arguments_) {
     const raw = arguments_.graph_json;
-    if (raw === undefined || raw === null || (typeof raw === "string" && !raw.trim())) {
-        return errorResponse("graph_json is required for Graphify import dry-run", ERR_PARAM_MISSING, ["Pass the contents of Graphify graph.json as graph_json", "No database write occurs in this mode"]);
+    if (raw === undefined ||
+        raw === null ||
+        (typeof raw === "string" && !raw.trim())) {
+        return errorResponse("graph_json is required for Graphify import dry-run", ERR_PARAM_MISSING, [
+            "Pass the contents of Graphify graph.json as graph_json",
+            "No database write occurs in this mode",
+        ]);
     }
     let parsed = raw;
     if (typeof raw === "string") {
@@ -39,7 +44,9 @@ export function handleMemosGraphifyImport(arguments_) {
     }
     try {
         const plan = buildGraphImportPlan(parsed, {
-            projectKey: typeof arguments_.project_key === "string" ? arguments_.project_key : undefined,
+            projectKey: typeof arguments_.project_key === "string"
+                ? arguments_.project_key
+                : undefined,
         });
         return [{ type: "text", text: renderGraphImportPlan(plan) }];
     }
@@ -66,7 +73,7 @@ async function neo4jQuery(cypher, parameters) {
             }),
             timeoutMs: 15,
         });
-        const data = await response.json();
+        const data = (await response.json());
         return { ok: response.ok, data, status: response.status };
     }
     catch (err) {
@@ -105,7 +112,7 @@ export async function handleMemosTracePath(arguments_) {
             }),
         });
         if (response.ok) {
-            const data = await response.json();
+            const data = (await response.json());
             if (data.code === 200) {
                 const traceData = data.data ?? {};
                 const found = traceData.path_found ?? traceData.found ?? false;
@@ -136,7 +143,10 @@ export async function handleMemosTracePath(arguments_) {
                         const nodes = path.nodes ?? [];
                         const edges = path.edges ?? [];
                         // If API returns empty nodes, fall back to Neo4j
-                        if (nodes.length === 0 && NEO4J_HTTP_URL && NEO4J_USER && NEO4J_PASSWORD) {
+                        if (nodes.length === 0 &&
+                            NEO4J_HTTP_URL &&
+                            NEO4J_USER &&
+                            NEO4J_PASSWORD) {
                             throw new Error("API returned empty path nodes, falling back to Neo4j");
                         }
                         results.push(`### Path ${i + 1} (Length: ${length})`, "", "```");
@@ -175,12 +185,15 @@ export async function handleMemosTracePath(arguments_) {
         const cypher = `
       MATCH (source:Memory), (target:Memory)
       WHERE source.id = $source_id AND target.id = $target_id
-      MATCH path = shortestPath((source)-[*1..${maxDepth}]-(target))
-      RETURN [n IN nodes(path) | {id: n.id, memory: n.memory}] AS nodes,
-             [r IN relationships(path) | {type: type(r), provenance: properties(r)}] AS rels
+      MATCH path = shortestPath((source)-[*1..${maxDepth}]-(target))
+      RETURN [n IN nodes(path) | {id: n.id, memory: n.memory}] AS nodes,
+             [r IN relationships(path) | {type: type(r), provenance: properties(r)}] AS rels
       LIMIT 1
     `;
-        const { ok, data, status } = await neo4jQuery(cypher, { source_id: sourceId, target_id: targetId });
+        const { ok, data, status } = await neo4jQuery(cypher, {
+            source_id: sourceId,
+            target_id: targetId,
+        });
         const results = ["## 🔗 Path Trace (Direct Query)", ""];
         if (ok && data) {
             const rows = data.results?.[0]?.data ?? [];
@@ -240,7 +253,7 @@ export async function handleMemosGetGraph(arguments_) {
             }),
         });
         if (searchResponse.ok) {
-            const data = await searchResponse.json();
+            const data = (await searchResponse.json());
             if (data.code === 200) {
                 memories = extractMemoriesFromResponse(data.data ?? {});
             }
@@ -252,10 +265,14 @@ export async function handleMemosGetGraph(arguments_) {
                     const retrySearch = await fetchWithTimeout(`${MEMOS_URL}/search`, {
                         method: "POST",
                         headers: { "Content-Type": "application/json" },
-                        body: JSON.stringify({ user_id: MEMOS_USER, query, install_cube_ids: [cubeId] }),
+                        body: JSON.stringify({
+                            user_id: MEMOS_USER,
+                            query,
+                            install_cube_ids: [cubeId],
+                        }),
                     });
                     if (retrySearch.ok) {
-                        const retryData = await retrySearch.json();
+                        const retryData = (await retrySearch.json());
                         if (retryData.code === 200) {
                             memories = extractMemoriesFromResponse(retryData.data ?? {});
                         }
@@ -280,10 +297,10 @@ export async function handleMemosGetGraph(arguments_) {
         cypher = `
       MATCH (a)-[r:${edgeTypesCypher}]->(b)
       WHERE a.id IN [${idList}] OR b.id IN [${idList}]
-      RETURN a.id as source_id, a.memory as source_memory,
-             type(r) as relation_type,
-             b.id as target_id, b.memory as target_memory,
-             properties(r) as relation_provenance
+      RETURN a.id as source_id, a.memory as source_memory,
+             type(r) as relation_type,
+             b.id as target_id, b.memory as target_memory,
+             properties(r) as relation_provenance
       LIMIT 20
     `;
         params = {};
@@ -293,10 +310,10 @@ export async function handleMemosGetGraph(arguments_) {
         cypher = `
       MATCH (a)-[r:${edgeTypesCypher}]->(b)
       WHERE a.memory CONTAINS $keyword OR b.memory CONTAINS $keyword
-      RETURN a.id as source_id, a.memory as source_memory,
-             type(r) as relation_type,
-             b.id as target_id, b.memory as target_memory,
-             properties(r) as relation_provenance
+      RETURN a.id as source_id, a.memory as source_memory,
+             type(r) as relation_type,
+             b.id as target_id, b.memory as target_memory,
+             properties(r) as relation_provenance
       LIMIT 20
     `;
         params = { keyword: firstWord };
@@ -358,6 +375,123 @@ export async function handleMemosGetGraph(arguments_) {
 // ============================================================================
 // memos_graph(mode="schema")
 // ============================================================================
+/**
+ * 把 /graph/schema 的响应渲染成报告。
+ *
+ * ## 为什么是导出的纯函数
+ *
+ * 这段逻辑原本内联在 handler 里，单测触达不到 —— 于是**五个字段名读错了
+ * 却长期无人发现**。抽出来才能钉住字段契约。同一类漏洞本轮已出现过两次
+ * （list 路径的层级过滤、access-tracker 的接线）。
+ *
+ * ## 修掉的字段名不匹配
+ *
+ * API（SchemaData）返回的键与此前读取的键对不上，读不到就 `?? 0` 静默兜成零：
+ *
+ * | 此前读                      | API 实际返回        |
+ * |----------------------------|--------------------|
+ * | `avg_connections_per_node` | `avg_connections`  |
+ * | `orphan_node_count`        | `orphan_nodes`     |
+ * | `edge_type_distribution`   | `edge_types`       |
+ * | `memory_type_distribution` | `memory_types`     |
+ * | `tag_frequency`            | `top_tags`         |
+ *
+ * `max_connections` / `total_nodes` / `total_edges` / `time_range` 恰好同名，
+ * 所以只有上面五项失效 —— 部分正确正是它难被发现的原因。
+ *
+ * 后果不只是少显示：健康评估读的也是错字段，于是 orphan 比例恒为 0（永远
+ * 报「连接良好」），avg 恒为 0（永远报「平均连接过低」）。两句结论同时出现、
+ * 自相矛盾，而它们**都是基于零值**得出的。
+ *
+ * 兼容两种键名：后端字段若将来改回长名，读取仍然成立。
+ */
+export function formatSchemaReport(schema) {
+    /** 依次尝试多个键名，取第一个存在的。 */
+    const pick = (...keys) => {
+        for (const key of keys) {
+            if (schema[key] !== undefined && schema[key] !== null)
+                return schema[key];
+        }
+        return undefined;
+    };
+    const num = (...keys) => {
+        const raw = Number(pick(...keys));
+        return Number.isFinite(raw) ? raw : 0;
+    };
+    const dict = (...keys) => {
+        const raw = pick(...keys);
+        return raw && typeof raw === "object"
+            ? raw
+            : {};
+    };
+    const totalNodes = num("total_nodes");
+    const avgConn = num("avg_connections", "avg_connections_per_node");
+    const orphanCount = num("orphan_nodes", "orphan_node_count");
+    const results = ["## 📊 Knowledge Graph Schema", ""];
+    results.push("### Overview");
+    results.push(`- **Total Nodes**: ${totalNodes}`);
+    results.push(`- **Total Edges**: ${num("total_edges")}`);
+    results.push(`- **Avg Connections/Node**: ${avgConn.toFixed(2)}`);
+    results.push(`- **Max Connections**: ${num("max_connections")}`);
+    results.push(`- **Orphan Nodes**: ${orphanCount}`);
+    results.push("");
+    const timeRange = dict("time_range");
+    if (timeRange.earliest || timeRange.latest) {
+        results.push("### Time Range");
+        if (timeRange.earliest)
+            results.push(`- Earliest: ${timeRange.earliest}`);
+        if (timeRange.latest)
+            results.push(`- Latest: ${timeRange.latest}`);
+        results.push("");
+    }
+    const edgeDist = dict("edge_types", "edge_type_distribution");
+    if (Object.keys(edgeDist).length > 0) {
+        results.push("### Relationship Types");
+        for (const [t, c] of Object.entries(edgeDist).sort((a, b) => b[1] - a[1])) {
+            results.push(`- **${t}**: ${c}`);
+        }
+        results.push("");
+    }
+    const memDist = dict("memory_types", "memory_type_distribution");
+    if (Object.keys(memDist).length > 0) {
+        results.push("### Memory Types");
+        for (const [t, c] of Object.entries(memDist).sort((a, b) => b[1] - a[1])) {
+            results.push(`- ${t}: ${c}`);
+        }
+        results.push("");
+    }
+    // top_tags 在 SchemaData 里是 list；旧读法当成 {tag: count} 字典。两种都收。
+    const rawTags = pick("top_tags", "tag_frequency");
+    const tagItems = Array.isArray(rawTags)
+        ? rawTags
+            .slice(0, 10)
+            .map((entry) => Array.isArray(entry)
+            ? [String(entry[0]), entry[1]]
+            : [String(entry), ""])
+        : Object.entries(dict("top_tags", "tag_frequency")).slice(0, 10);
+    if (tagItems.length > 0) {
+        results.push("### Top Tags");
+        for (const [tag, count] of tagItems) {
+            results.push(count === "" ? `- \`${tag}\`` : `- \`${tag}\`: ${count}`);
+        }
+        results.push("");
+    }
+    results.push("### Health Assessment");
+    if (totalNodes > 0) {
+        const orphanRatio = orphanCount / totalNodes;
+        if (orphanRatio > 0.5)
+            results.push("⚠️ High orphan ratio - many memories are not connected");
+        else if (orphanRatio > 0.2)
+            results.push("📋 Moderate orphan ratio");
+        else
+            results.push("✅ Good connectivity - memories are well connected");
+    }
+    if (avgConn < 1)
+        results.push("⚠️ Low average connections - consider enriching relationships");
+    else if (avgConn > 5)
+        results.push("✅ Rich relationships - good knowledge graph density");
+    return results.join("\n");
+}
 export async function handleMemosExportSchema(arguments_) {
     const cubeId = getCubeIdFromArgs(arguments_);
     const sampleSize = Math.min(Math.max(Number(arguments_.sample_size ?? 100), 10), 1000);
@@ -375,70 +509,10 @@ export async function handleMemosExportSchema(arguments_) {
             }),
         });
         if (response.ok) {
-            const data = await response.json();
+            const data = (await response.json());
             if (data.code === 200) {
                 const schema = data.data ?? {};
-                const results = [];
-                results.push("## 📊 Knowledge Graph Schema", "");
-                results.push("### Overview");
-                results.push(`- **Total Nodes**: ${schema.total_nodes ?? 0}`);
-                results.push(`- **Total Edges**: ${schema.total_edges ?? 0}`);
-                results.push(`- **Avg Connections/Node**: ${Number(schema.avg_connections_per_node ?? 0).toFixed(2)}`);
-                results.push(`- **Max Connections**: ${schema.max_connections ?? 0}`);
-                results.push(`- **Orphan Nodes**: ${schema.orphan_node_count ?? 0}`);
-                results.push("");
-                const timeRange = schema.time_range ?? {};
-                if (timeRange.earliest || timeRange.latest) {
-                    results.push("### Time Range");
-                    if (timeRange.earliest)
-                        results.push(`- Earliest: ${timeRange.earliest}`);
-                    if (timeRange.latest)
-                        results.push(`- Latest: ${timeRange.latest}`);
-                    results.push("");
-                }
-                const edgeDist = schema.edge_type_distribution ?? {};
-                if (Object.keys(edgeDist).length > 0) {
-                    results.push("### Relationship Types");
-                    for (const [t, c] of Object.entries(edgeDist).sort((a, b) => b[1] - a[1])) {
-                        results.push(`- **${t}**: ${c}`);
-                    }
-                    results.push("");
-                }
-                const memDist = schema.memory_type_distribution ?? {};
-                if (Object.keys(memDist).length > 0) {
-                    results.push("### Memory Types");
-                    for (const [t, c] of Object.entries(memDist).sort((a, b) => b[1] - a[1])) {
-                        results.push(`- ${t}: ${c}`);
-                    }
-                    results.push("");
-                }
-                const tagFreq = schema.tag_frequency ?? {};
-                const tagItems = Object.entries(tagFreq).slice(0, 10);
-                if (tagItems.length > 0) {
-                    results.push("### Top Tags");
-                    for (const [tag, count] of tagItems) {
-                        results.push(`- \`${tag}\`: ${count}`);
-                    }
-                    results.push("");
-                }
-                results.push("### Health Assessment");
-                const totalNodes = Number(schema.total_nodes ?? 0);
-                const orphanCount = Number(schema.orphan_node_count ?? 0);
-                if (totalNodes > 0) {
-                    const orphanRatio = orphanCount / totalNodes;
-                    if (orphanRatio > 0.5)
-                        results.push("⚠️ High orphan ratio - many memories are not connected");
-                    else if (orphanRatio > 0.2)
-                        results.push("📋 Moderate orphan ratio");
-                    else
-                        results.push("✅ Good connectivity - memories are well connected");
-                }
-                const avgConn = Number(schema.avg_connections_per_node ?? 0);
-                if (avgConn < 1)
-                    results.push("⚠️ Low average connections - consider enriching relationships");
-                else if (avgConn > 5)
-                    results.push("✅ Rich relationships - good knowledge graph density");
-                return [{ type: "text", text: results.join("\n") }];
+                return [{ type: "text", text: formatSchemaReport(schema) }];
             }
             else {
                 return apiErrorResponse("Schema export", String(data.message ?? "Unknown error"));
@@ -475,13 +549,15 @@ export async function handleMemosImpact(arguments_) {
     MATCH (source:Memory {id: $source_id})-[:CAUSE|FOLLOWS*1..${maxDepth}]->(node:Memory)
     WITH DISTINCT source, node
     MATCH path = shortestPath((source)-[:CAUSE|FOLLOWS*1..${maxDepth}]->(node))
-    RETURN node.id AS id, node.key AS key, node.memory AS memory,
-           length(path) AS depth, properties(node) AS node_provenance
+    RETURN node.id AS id, node.key AS key, node.memory AS memory,
+           length(path) AS depth, properties(node) AS node_provenance
     ORDER BY depth ASC
     LIMIT 30
   `;
     try {
-        const { ok, data, status } = await neo4jQuery(cypher, { source_id: memoryId });
+        const { ok, data, status } = await neo4jQuery(cypher, {
+            source_id: memoryId,
+        });
         if (!ok) {
             return apiErrorResponse("Impact analysis", `Neo4j HTTP ${status}`);
         }
@@ -495,7 +571,12 @@ export async function handleMemosImpact(arguments_) {
         }
         const rows = data.results?.[0]?.data ?? [];
         if (rows.length === 0) {
-            return [{ type: "text", text: "No forward impact found — this memory has no CAUSE or FOLLOWS successors." }];
+            return [
+                {
+                    type: "text",
+                    text: "No forward impact found — this memory has no CAUSE or FOLLOWS successors.",
+                },
+            ];
         }
         // Group by depth
         const depthGroups = {};
@@ -525,7 +606,9 @@ export async function handleMemosImpact(arguments_) {
             1: "Direct Impact",
             2: "Indirect Impact",
         };
-        for (const depth of Object.keys(depthGroups).map(Number).sort((a, b) => a - b)) {
+        for (const depth of Object.keys(depthGroups)
+            .map(Number)
+            .sort((a, b) => a - b)) {
             const items = depthGroups[depth];
             const label = depthLabels[depth] ?? `Downstream (hop ${depth})`;
             results.push(`### ${label} (${items.length} node${items.length !== 1 ? "s" : ""})`, "");

package/dist/handlers/memory.d.ts

@@ -9,4 +9,20 @@ export declare function handleMemosList(arguments_: Record<string, unknown>): Pr
 export declare function handleMemosGet(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleMemosGetStats(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function extractMemoriesFromData(data: SearchData): MemoryNode[];
+/**
+ * memos_list_v2（Full 路径）的取数序列：提取 → 滤层级 → 滤业务类型 → 截断。
+ *
+ * 抽成导出的纯函数**只为让顺序可测**。这三步的次序不是随意的：
+ *
+ *   - 滤层级必须在 slice **之前**。放到之后，`limit` 会被随即隐藏的
+ *     WorkingMemory 副本吃掉 —— 要 20 条只拿到 10 条。
+ *   - slice 必须最后。它是对外承诺的输出上界。
+ *
+ * 之前这段逻辑内联在 handler 里，单测触达不到：实测切断层级过滤后
+ * 全部 319 项 vitest 依然通过。这与 P1.5 的 W3/W4 是同一类漏洞
+ * （见 docs/design/memory-retrieval-optimization.md 第 11 节）。
+ * 在测试里自行组合这几步只能证明测试文件本身，证明不了 handler，
+ * 所以必须让 handler 和测试调用同一个函数。
+ */
+export declare function prepareListMemories(data: SearchData, memoryType: string | undefined, limit: number): MemoryNode[];
 //# sourceMappingURL=memory.d.ts.map

package/dist/handlers/memory.js

@@ -9,6 +9,8 @@ import { getMemoryProvider } from "../providers/provider-factory.js";
 import { apiCallWithRetry } from "../api-client.js";
 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";
 // 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";
@@ -66,13 +68,28 @@ export async function handleMemosSave(arguments_) {
         content = `[${memoryType}] ${content}`;
     }
     if (isDuplicateSave(content, cubeId)) {
-        return [{ type: "text", text: `⏭️ Skipped: Same content was saved within ${DEDUP_TTL_SECONDS}s (dedup protection)` }];
+        return [
+            {
+                type: "text",
+                text: `⏭️ Skipped: Same content was saved within ${DEDUP_TTL_SECONDS}s (dedup protection)`,
+            },
+        ];
     }
     const provider = getMemoryProvider(MEMOS_CUBES_DIR);
     if (provider) {
-        const saved = await provider.save({ cubeId, content, memoryType, tags: [memoryType] });
+        const saved = await provider.save({
+            cubeId,
+            content,
+            memoryType,
+            tags: [memoryType],
+        });
         markSaved(content, cubeId);
-        return [{ type: "text", text: `Memory saved as [${memoryType}] in local cube '${cubeId}' · ID: ${saved.id}` }];
+        return [
+            {
+                type: "text",
+                text: `Memory saved as [${memoryType}] in local cube '${cubeId}' · ID: ${saved.id}`,
+            },
+        ];
     }
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
@@ -88,8 +105,15 @@ export async function handleMemosSave(arguments_) {
         markSaved(content, cubeId);
         const write = parseMemoryWriteResponse(result.data);
         const idText = write.memoryIds.length > 0 ? ` · IDs: ${write.memoryIds.join(", ")}` : "";
-        const warningText = write.warnings.length > 0 ? ` · warnings: ${write.warnings.join("; ")}` : "";
-        return [{ type: "text", text: `Memory saved as [${memoryType}] in cube '${cubeId}'${idText}${warningText}` }];
+        const warningText = write.warnings.length > 0
+            ? ` · warnings: ${write.warnings.join("; ")}`
+            : "";
+        return [
+            {
+                type: "text",
+                text: `Memory saved as [${memoryType}] in cube '${cubeId}'${idText}${warningText}`,
+            },
+        ];
     }
     else if (result.data) {
         return apiErrorResponse("Save", String(result.data.message ?? "Unknown error"));
@@ -112,11 +136,34 @@ export async function handleMemosList(arguments_) {
         allMemories = allMemories.slice(0, limit);
         const totalCount = allMemories.length;
         if (compact && shouldCompact(totalCount)) {
-            return [{ type: "text", text: compactedResultToText({ preview: allMemories.slice(0, PREVIEW_COUNT).map(toMinimal), totalCount, omittedCount: totalCount - Math.min(PREVIEW_COUNT, totalCount), message: 'Use memos_get(memory_id="<id>") for full details', query: "local list", cubeId }) }];
+            return [
+                {
+                    type: "text",
+                    text: compactedResultToText({
+                        preview: allMemories.slice(0, PREVIEW_COUNT).map(toMinimal),
+                        totalCount,
+                        omittedCount: totalCount - Math.min(PREVIEW_COUNT, totalCount),
+                        message: 'Use memos_get(memory_id="<id>") for full details',
+                        query: "local list",
+                        cubeId,
+                    }),
+                },
+            ];
         }
         if (!allMemories.length)
-            return [{ type: "text", text: `## Cube: ${cubeId}\n\nNo memories found.` }];
-        return [{ type: "text", text: [`## Cube: ${cubeId} (${allMemories.length})`, "", ...allMemories.map((m, i) => `${i + 1}. [${extractMcpType(m)}] ${m.memory}\n   ID: \`${m.id}\``)].join("\n\n") }];
+            return [
+                { type: "text", text: `## Cube: ${cubeId}\n\nNo memories found.` },
+            ];
+        return [
+            {
+                type: "text",
+                text: [
+                    `## Cube: ${cubeId} (${allMemories.length})`,
+                    "",
+                    ...allMemories.map((m, i) => `${i + 1}. [${extractMcpType(m)}] ${m.memory}\n   ID: \`${m.id}\``),
+                ].join("\n\n"),
+            },
+        ];
     }
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
@@ -132,11 +179,7 @@ export async function handleMemosList(arguments_) {
     const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories`, cubeId, { params }, ensureCubeRegistered);
     if (result.success && result.data) {
         const resultData = result.data.data ?? {};
-        let allMemories = extractMemoriesFromData(resultData);
-        if (memoryType) {
-            allMemories = allMemories.filter((m) => extractMcpType(m) === memoryType);
-        }
-        allMemories = allMemories.slice(0, limit); // always bound output to the requested limit
+        const allMemories = prepareListMemories(resultData, memoryType, limit);
         const totalCount = allMemories.length;
         if (compact && shouldCompact(totalCount)) {
             const preview = allMemories.slice(0, PREVIEW_COUNT).map(toMinimal);
@@ -154,7 +197,12 @@ export async function handleMemosList(arguments_) {
         // (Previously this fell back to formatMemoriesForDisplay(resultData) = the full
         // untrimmed pull, which is how a limit=5 request printed the entire cube.)
         if (totalCount === 0) {
-            return [{ type: "text", text: `## Cube: ${cubeId}\n\nNo memories${memoryType ? ` of type ${memoryType}` : ""} found.` }];
+            return [
+                {
+                    type: "text",
+                    text: `## Cube: ${cubeId}\n\nNo memories${memoryType ? ` of type ${memoryType}` : ""} found.`,
+                },
+            ];
         }
         const header = memoryType
             ? `## Cube: ${cubeId} — type=${memoryType} (${totalCount})`
@@ -189,16 +237,40 @@ export async function handleMemosGet(arguments_) {
         const node = await localProvider.get(cubeId, memoryId);
         if (!node)
             return [{ type: "text", text: notFoundText(memoryId) }];
+        // 只在确实取到记忆后记账 —— 未命中的 id 不构成使用度信号。
+        recordAccess(MEMOS_CUBES_DIR, cubeId, [memoryId]);
         const full = toFull(node, cubeId, MEMOS_USER);
-        return [{ type: "text", text: ["## 📝 Memory Details", "", `**ID**: \`${full.id}\``, `**Type**: ${full.memoryType}`, `**Cube**: ${full.cubeId} (local)`, full.tags.length ? `**Tags**: ${full.tags.join(", ")}` : "", full.createdAt ? `**Created**: ${full.createdAt}` : "", "", "### Content", "", full.content].filter(Boolean).join("\n") }];
+        return [
+            {
+                type: "text",
+                text: [
+                    "## 📝 Memory Details",
+                    "",
+                    `**ID**: \`${full.id}\``,
+                    `**Type**: ${full.memoryType}`,
+                    `**Cube**: ${full.cubeId} (local)`,
+                    full.tags.length ? `**Tags**: ${full.tags.join(", ")}` : "",
+                    full.createdAt ? `**Created**: ${full.createdAt}` : "",
+                    "",
+                    "### Content",
+                    "",
+                    full.content,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+            },
+        ];
     }
     const [regSuccess, regError] = await ensureCubeRegistered(cubeId);
     if (!regSuccess)
         return cubeRegistrationError(cubeId, regError);
     const result = await apiCallWithRetry("GET", `${MEMOS_URL}/memories/${cubeId}/${memoryId}`, cubeId, {}, ensureCubeRegistered);
     if (result.success && result.data) {
-        const resultData = result.data.data;
+        const resultData = result.data
+            .data;
         if (resultData) {
+            // Full 模式同样记在本机侧车 —— 使用度是本机数据，不需要后端端点。
+            recordAccess(MEMOS_CUBES_DIR, cubeId, [memoryId]);
             const fullMem = toFull(resultData, cubeId, MEMOS_USER);
             const lines = [
                 "## 📝 Memory Details",
@@ -265,14 +337,25 @@ export async function handleMemosGetStats(arguments_) {
             return [{ type: "text", text: `No memories found in cube '${cubeId}'.` }];
         }
         const typeIcons = {
-            BUGFIX: "🐛", ERROR_PATTERN: "🔴", DECISION: "📋",
-            GOTCHA: "⚠️", CODE_PATTERN: "📝", CONFIG: "⚙️",
-            FEATURE: "✨", MILESTONE: "🎯", PROGRESS: "📊", INFERRED: "🔗",
+            BUGFIX: "🐛",
+            ERROR_PATTERN: "🔴",
+            DECISION: "📋",
+            GOTCHA: "⚠️",
+            CODE_PATTERN: "📝",
+            CONFIG: "⚙️",
+            FEATURE: "✨",
+            MILESTONE: "🎯",
+            PROGRESS: "📊",
+            INFERRED: "🔗",
             SYNTHESIS: "🧠",
         };
-        const result_lines = [`## 📊 Memory Stats: ${cubeId}`, `Total Memories: **${total}**`, ""];
+        const result_lines = [
+            `## 📊 Memory Stats: ${cubeId}`,
+            `Total Memories: **${total}**`,
+            "",
+        ];
         for (const [mtype, count] of Object.entries(stats).sort((a, b) => b[1] - a[1])) {
-            const percentage = (count / total * 100).toFixed(1);
+            const percentage = ((count / total) * 100).toFixed(1);
             const icon = typeIcons[mtype] ?? "📌";
             result_lines.push(`- ${icon} **${mtype}**: ${count} (${percentage}%)`);
         }
@@ -287,7 +370,7 @@ export async function handleMemosGetStats(arguments_) {
             result_lines.push("   `BUGFIX` · `DECISION` · `MILESTONE` · `FEATURE` · `GOTCHA` · `CONFIG`");
         }
         if (userTyped > 0) {
-            result_lines.push("", `✅ **用户标注记忆**: ${userTyped} 条 (${(userTyped / total * 100).toFixed(0)}%)`);
+            result_lines.push("", `✅ **用户标注记忆**: ${userTyped} 条 (${((userTyped / total) * 100).toFixed(0)}%)`);
         }
         return [{ type: "text", text: result_lines.join("\n") }];
     }
@@ -315,4 +398,27 @@ export function extractMemoriesFromData(data) {
     }
     return memories;
 }
+/**
+ * memos_list_v2（Full 路径）的取数序列：提取 → 滤层级 → 滤业务类型 → 截断。
+ *
+ * 抽成导出的纯函数**只为让顺序可测**。这三步的次序不是随意的：
+ *
+ *   - 滤层级必须在 slice **之前**。放到之后，`limit` 会被随即隐藏的
+ *     WorkingMemory 副本吃掉 —— 要 20 条只拿到 10 条。
+ *   - slice 必须最后。它是对外承诺的输出上界。
+ *
+ * 之前这段逻辑内联在 handler 里，单测触达不到：实测切断层级过滤后
+ * 全部 319 项 vitest 依然通过。这与 P1.5 的 W3/W4 是同一类漏洞
+ * （见 docs/design/memory-retrieval-optimization.md 第 11 节）。
+ * 在测试里自行组合这几步只能证明测试文件本身，证明不了 handler，
+ * 所以必须让 handler 和测试调用同一个函数。
+ */
+export function prepareListMemories(data, memoryType, limit) {
+    const extracted = extractMemoriesFromData(data);
+    const visible = [...filterEphemeralTier(extracted, (m) => m.metadata)];
+    const typed = memoryType
+        ? visible.filter((m) => extractMcpType(m) === memoryType)
+        : visible;
+    return typed.slice(0, limit);
+}
 //# sourceMappingURL=memory.js.map