oh-memos-mcp 3.0.1 → 3.1.1

package/dist/access-tracker.d.ts

@@ -0,0 +1,22 @@
+export interface AccessStat {
+    count: number;
+    lastAt: string;
+}
+/** id → 统计。查不到即表示从未被显式读取过。 */
+export type AccessStats = ReadonlyMap<string, AccessStat>;
+/**
+ * 读取某个 cube 的访问统计。任何失败都返回空 map —— 使用度是软数据，
+ * 读不到只意味着「没有强化信号」，绝不该让检索失败。
+ */
+export declare function readAccessStats(cubesDir: string, cubeId: string): AccessStats;
+/**
+ * 记一次显式读取。**永不抛异常** —— 追踪是尽力而为的旁路，
+ * 磁盘满、权限不足、目录不存在都不该影响 memos_get 的返回。
+ *
+ * 单次 append 的载荷远小于 4 KB，在 POSIX 与 Windows 上都是原子写入，
+ * 因此多进程并发追加不需要加锁。
+ */
+export declare function recordAccess(cubesDir: string, cubeId: string, ids: readonly string[]): void;
+/** 仅供测试：清掉进程内缓存，让下一次读取真的落盘。 */
+export declare function resetAccessCache(): void;
+//# sourceMappingURL=access-tracker.d.ts.map

package/dist/access-tracker.js

@@ -0,0 +1,187 @@
+/**
+ * 记忆访问追踪 —— 让 memoryQualityScore 的 reinforcement 项真正有数据。
+ *
+ * ## 为什么是本地 sidecar，而不是回写记忆存储
+ *
+ * 直接给记忆记录加 access_count 会让检索从只读变成读写：Full 模式需要一个
+ * 不存在的后端端点；Lite 模式要在每次检索后重写 memories.jsonl，与既有的
+ * withLock 抢锁（多 agent 并发检索同一 cube 就会 `store lock held`）。
+ *
+ * 这里改成本地 append-only 侧车日志：
+ *   - 不碰记忆存储 → Full / Lite 行为一致，无需后端改动
+ *   - 只追加、不读改写 → 不与 withLock 交互，并发安全
+ *   - fire-and-forget → 追踪失败绝不让业务调用失败
+ *
+ * 语义上这也更诚实：访问次数是**本机使用度**，不是全局真相。同一条记忆在
+ * 另一台机器上的使用情况与本机无关，也不该影响本机排序。
+ *
+ * ## 为什么只在 memos_get 记账，不在 search 记账
+ *
+ * 若「出现在检索结果里」就记账，会形成正反馈：高分记忆更常被返回 → 拿到更多
+ * 访问计数 → 分数更高 → 更常被返回。富者愈富，且新记忆永远追不上。
+ *
+ * `memos_get(memory_id=...)` 是**明确的选择性读取** —— agent 从候选里挑了这一条
+ * 看全文。它不参与排序输入，因此不构成回路。信号更稀疏但无偏。
+ *
+ * 设计文档：docs/design/memory-retrieval-optimization.md 第 6.4 节
+ */
+import * as fs from "fs";
+import * as path from "path";
+const LOG_FILE = "access-log.jsonl";
+/** 超过这个行数就压实成一条快照，把增长界定在「去重记忆数」而非「累计访问数」。 */
+const COMPACT_AFTER_LINES = 500;
+/** 缓存有效期。同一次会话里连续检索不必反复读盘。 */
+const CACHE_TTL_MS = 5_000;
+const EMPTY = new Map();
+const cache = new Map();
+function logPath(cubesDir, cubeId) {
+    return path.join(cubesDir, cubeId, LOG_FILE);
+}
+function merge(target, id, at, count = 1) {
+    const prev = target.get(id);
+    if (!prev) {
+        target.set(id, { count, lastAt: at });
+        return;
+    }
+    target.set(id, {
+        count: prev.count + count,
+        lastAt: prev.lastAt > at ? prev.lastAt : at,
+    });
+}
+/**
+ * 解析一行日志并累加进 target。
+ *
+ * 两种行格式：
+ *   {"t":"<iso>","ids":["a","b"]}                 —— 一次访问事件
+ *   {"t":"<iso>","snapshot":{"a":[3,"<iso>"]}}    —— 压实后的快照
+ *
+ * 无法解析的行**静默跳过**：并发追加理论上可能撕裂一行，跳过坏行让日志自愈，
+ * 而抛异常会让一个坏字节永久废掉整份使用度数据。
+ */
+function applyLine(target, line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return;
+    const record = parsed;
+    const snapshot = record.snapshot;
+    if (snapshot && typeof snapshot === "object") {
+        for (const [id, value] of Object.entries(snapshot)) {
+            if (!Array.isArray(value))
+                continue;
+            const count = Number(value[0]);
+            const at = String(value[1] ?? "");
+            if (!id || !Number.isFinite(count) || count <= 0 || !at)
+                continue;
+            merge(target, id, at, Math.floor(count));
+        }
+        return;
+    }
+    const at = String(record.t ?? "");
+    const ids = record.ids;
+    if (!at || !Array.isArray(ids))
+        return;
+    for (const raw of ids) {
+        const id = String(raw ?? "").trim();
+        if (id)
+            merge(target, id, at, 1);
+    }
+}
+function parseLog(raw) {
+    const stats = new Map();
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed)
+            applyLine(stats, trimmed);
+    }
+    return stats;
+}
+/**
+ * 读取某个 cube 的访问统计。任何失败都返回空 map —— 使用度是软数据，
+ * 读不到只意味着「没有强化信号」，绝不该让检索失败。
+ */
+export function readAccessStats(cubesDir, cubeId) {
+    const file = logPath(cubesDir, cubeId);
+    const key = file;
+    try {
+        const stat = fs.statSync(file);
+        const hit = cache.get(key);
+        // mtime + size 双条件：单看 mtime 在粗粒度时间戳的文件系统上会漏掉同秒内的追加。
+        if (hit &&
+            hit.mtimeMs === stat.mtimeMs &&
+            hit.size === stat.size &&
+            Date.now() - hit.readAt < CACHE_TTL_MS) {
+            return hit.stats;
+        }
+        const stats = parseLog(fs.readFileSync(file, "utf8"));
+        cache.set(key, {
+            stats,
+            readAt: Date.now(),
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+        });
+        return stats;
+    }
+    catch {
+        return EMPTY;
+    }
+}
+/**
+ * 把当前统计压实成单行快照。
+ *
+ * 写临时文件再 rename —— rename 在同一文件系统内是原子的（Windows 亦然，
+ * 用 fs.renameSync 覆盖目标）。两个进程同时压实时后者胜出，可能丢掉几条
+ * 刚追加的访问；对软数据可接受，换来的是日志大小有界。
+ */
+function compact(file, stats) {
+    const snapshot = {};
+    for (const [id, stat] of stats)
+        snapshot[id] = [stat.count, stat.lastAt];
+    const line = `${JSON.stringify({ t: new Date().toISOString(), snapshot })}\n`;
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, line, "utf8");
+    fs.renameSync(tmp, file);
+}
+function countLines(raw) {
+    let lines = 0;
+    for (const ch of raw)
+        if (ch === "\n")
+            lines += 1;
+    return lines;
+}
+/**
+ * 记一次显式读取。**永不抛异常** —— 追踪是尽力而为的旁路，
+ * 磁盘满、权限不足、目录不存在都不该影响 memos_get 的返回。
+ *
+ * 单次 append 的载荷远小于 4 KB，在 POSIX 与 Windows 上都是原子写入，
+ * 因此多进程并发追加不需要加锁。
+ */
+export function recordAccess(cubesDir, cubeId, ids) {
+    // trim 而非裸 filter(Boolean)：全空白的 id 无意义，且带首尾空白的 id
+    // 会与 readAccessStats 的查找键不一致，导致记了账却查不到。
+    const clean = ids.map((id) => String(id ?? "").trim()).filter(Boolean);
+    if (clean.length === 0)
+        return;
+    const file = logPath(cubesDir, cubeId);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({ t: new Date().toISOString(), ids: clean })}\n`, "utf8");
+        cache.delete(file);
+        const raw = fs.readFileSync(file, "utf8");
+        if (countLines(raw) > COMPACT_AFTER_LINES)
+            compact(file, parseLog(raw));
+    }
+    catch {
+        // 尽力而为：使用度数据的价值不足以让业务调用失败。
+    }
+}
+/** 仅供测试：清掉进程内缓存，让下一次读取真的落盘。 */
+export function resetAccessCache() {
+    cache.clear();
+}
+//# sourceMappingURL=access-tracker.js.map

package/dist/formatters.d.ts

@@ -4,6 +4,24 @@
  * Formats memory search results and knowledge graphs for display.
  */
 import type { SearchData, MemoryNode, GraphEdge } from "./types.js";
+/**
+ * 附在 ID 行后的检索期注解。
+ *
+ * 为什么需要这个：quality policy 会往 metadata 写 `access_count`、`freshness`、
+ * `duplicates_folded`，但显示层原本只输出 cube / type / 首行 / ID —— 这些字段
+ * **算出来就被丢掉了**。后果分两类：
+ *
+ *   1. `duplicates_folded` 拿不到 → 设计文档声称「折叠后信息不丢，可用 memos_get
+ *      展开」，实际上 agent 根本看不到被折叠的 id。这是我自己引入的缺陷。
+ *   2. `freshness` 的 stale / expired 判定是可行动信号（该复核这条记忆了），
+ *      不显示等于白算。
+ *
+ * 抽成纯函数是为了可单测 —— formatMemoriesForDisplay 的分支被 handler 层包着，
+ * 上一轮 P1.5 的教训是改这个文件的东西会整体逃出单测。
+ *
+ * 输出刻意吝啬：只在字段真有内容时才占字符，全新且未被读过的记忆无任何附加。
+ */
+export declare function memoryAnnotations(metadata: unknown): string;
 export declare function formatMemoriesForDisplay(data: SearchData): string;
 export interface GraphCubeData {
     cube_id?: string;

package/dist/formatters.js

@@ -6,6 +6,47 @@
 // ============================================================================
 // Memory Display Formatter
 // ============================================================================
+/**
+ * 附在 ID 行后的检索期注解。
+ *
+ * 为什么需要这个：quality policy 会往 metadata 写 `access_count`、`freshness`、
+ * `duplicates_folded`，但显示层原本只输出 cube / type / 首行 / ID —— 这些字段
+ * **算出来就被丢掉了**。后果分两类：
+ *
+ *   1. `duplicates_folded` 拿不到 → 设计文档声称「折叠后信息不丢，可用 memos_get
+ *      展开」，实际上 agent 根本看不到被折叠的 id。这是我自己引入的缺陷。
+ *   2. `freshness` 的 stale / expired 判定是可行动信号（该复核这条记忆了），
+ *      不显示等于白算。
+ *
+ * 抽成纯函数是为了可单测 —— formatMemoriesForDisplay 的分支被 handler 层包着，
+ * 上一轮 P1.5 的教训是改这个文件的东西会整体逃出单测。
+ *
+ * 输出刻意吝啬：只在字段真有内容时才占字符，全新且未被读过的记忆无任何附加。
+ */
+export function memoryAnnotations(metadata) {
+    const meta = (metadata ?? {});
+    const parts = [];
+    const used = Number(meta.access_count);
+    if (Number.isFinite(used) && used > 0)
+        parts.push(`access_count ${Math.floor(used)}`);
+    // fresh 是常态，不值得占字符；stale / expired 才是要 agent 注意的。
+    const freshness = String(meta.freshness ?? "");
+    if (freshness === "stale" || freshness === "expired")
+        parts.push(freshness);
+    const folded = meta.duplicates_folded;
+    if (Array.isArray(folded) && folded.length > 0) {
+        parts.push(`folded ${folded.length}: ${folded.map(String).join(", ")}`);
+    }
+    // 扩散来源。P4 的可解释性要求：agent 必须看得出哪条是直接命中、哪条是
+    // 沿边联想带回的，以及经由什么边类型。不显示等于白算 —— 与本文件开头
+    // 记的 duplicates_folded 是同一类缺陷（算出来没人读）。
+    const via = String(meta.spread_via ?? "");
+    if (via !== "") {
+        const from = String(meta.spread_from ?? "");
+        parts.push(from === "" ? `via ${via}` : `via ${via} from ${from.slice(0, 8)}`);
+    }
+    return parts.length > 0 ? ` · ${parts.join(" · ")}` : "";
+}
 export function formatMemoriesForDisplay(data) {
     const results = [];
     const textMems = data.text_mem ?? [];
@@ -50,10 +91,12 @@ export function formatMemoriesForDisplay(data) {
                 else {
                     results.push(`#### ${i + 1}. ${displayText}`);
                 }
-                results.push(`ID: \`${memId}\``);
+                results.push(`ID: \`${memId}\`${memoryAnnotations(mem.metadata)}`);
                 results.push("");
                 // Detect code blocks
-                const hasCodeIndicator = displayText.split("\n").some((line) => /^(import |def |class |export |const |let |var )/.test(line.trim()));
+                const hasCodeIndicator = displayText
+                    .split("\n")
+                    .some((line) => /^(import |def |class |export |const |let |var )/.test(line.trim()));
                 if (!displayText.includes("```") && hasCodeIndicator) {
                     results.push("```python");
                     results.push(displayText);
@@ -90,8 +133,13 @@ export function formatGraphForDisplay(data) {
             for (const node of nodes) {
                 const nodeId = node.id ?? "";
                 const nodeMemory = node.memory ?? "";
-                const cleanText = nodeMemory.replace(/\n/g, " ").replace(/"/g, "'").replace(/\[/g, "(").replace(/\]/g, ")");
-                nodeLookup[nodeId] = cleanText.length > 50 ? cleanText.slice(0, 50) + "..." : cleanText;
+                const cleanText = nodeMemory
+                    .replace(/\n/g, " ")
+                    .replace(/"/g, "'")
+                    .replace(/\[/g, "(")
+                    .replace(/\]/g, ")");
+                nodeLookup[nodeId] =
+                    cleanText.length > 50 ? cleanText.slice(0, 50) + "..." : cleanText;
             }
             // Display nodes
             if (nodes.length > 0) {

package/dist/handlers/graph.d.ts

@@ -14,6 +14,37 @@ import type { TextContent } from "../types.js";
 export declare function handleMemosGraphifyImport(arguments_: Record<string, unknown>): TextContent[];
 export declare function handleMemosTracePath(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleMemosGetGraph(arguments_: Record<string, unknown>): Promise<TextContent[]>;
+/**
+ * 把 /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 declare function formatSchemaReport(schema: Record<string, unknown>): string;
 export declare function handleMemosExportSchema(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleMemosImpact(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 //# sourceMappingURL=graph.d.ts.map