@ppagent/memory 0.1.4 → 0.4.0

package/dist/cli.js

@@ -0,0 +1,1187 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path2 from "node:path";
+
+// src/config.ts
+import * as path from "node:path";
+function resolveConfig(config) {
+  let embeddingBaseUrl = config.embeddingBaseUrl;
+  let embeddingApiKey = config.embeddingApiKey;
+  if (!embeddingBaseUrl) {
+    console.warn(
+      "[MemoryConfig] embeddingBaseUrl \u672A\u914D\u7F6E\uFF0C\u81EA\u52A8\u56DE\u9000\u4F7F\u7528 llmBaseUrl\uFF1A" + config.llmBaseUrl
+    );
+    embeddingBaseUrl = config.llmBaseUrl;
+  }
+  if (!embeddingApiKey) {
+    console.warn("[MemoryConfig] embeddingApiKey \u672A\u914D\u7F6E\uFF0C\u81EA\u52A8\u56DE\u9000\u4F7F\u7528 llmApiKey\u3002");
+    embeddingApiKey = config.llmApiKey;
+  }
+  const compressedContextTokenLimit = positiveInt(
+    config.compressedContextTokenLimit ?? config.historyWindowTokenLimit ?? 16 * 1024,
+    "compressedContextTokenLimit"
+  );
+  if (compressedContextTokenLimit > 32 * 1024) {
+    console.warn(
+      `[MemoryConfig] compressedContextTokenLimit=${compressedContextTokenLimit} \u8D85\u8FC7 32K\uFF0C\u4F1A\u5360\u7528\u8F83\u591A\u6A21\u578B\u4E0A\u4E0B\u6587\u5E76\u589E\u52A0\u5E38\u9A7B\u5185\u5B58\u3002`
+    );
+  }
+  return {
+    ...config,
+    embeddingBaseUrl,
+    embeddingApiKey,
+    provider: config.provider ?? "auto",
+    sqlitePath: config.sqlitePath ?? path.join(path.dirname(config.lancedbPath), "memory.sqlite3"),
+    sessionTokenLimit: config.sessionTokenLimit ?? 16386,
+    historyWindowTokenLimit: config.historyWindowTokenLimit ?? compressedContextTokenLimit,
+    topicRatio: config.topicRatio ?? [1, 5, 20],
+    detailMaxTokens: config.detailMaxTokens ?? 2048,
+    summaryMaxTokens: config.summaryMaxTokens ?? 512,
+    conciseMaxTokens: config.conciseMaxTokens ?? 128,
+    compressedContextTokenLimit,
+    contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
+    precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
+    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.5, "compressionBatchRatio"),
+    compressionBatchTokenLimit: Math.max(0, Math.floor(config.compressionBatchTokenLimit ?? 0)),
+    topicSummaryMaxTokens: positiveInt(
+      config.topicSummaryMaxTokens ?? config.detailMaxTokens ?? 2048,
+      "topicSummaryMaxTokens"
+    ),
+    defaultModelContextTokens: positiveInt(
+      config.defaultModelContextTokens ?? 256 * 1024,
+      "defaultModelContextTokens"
+    ),
+    maxHistoryAgeMs: Math.max(0, Math.floor(config.maxHistoryAgeMs ?? 0)),
+    sessionIdleTtlMs: Math.floor(config.sessionIdleTtlMs ?? 30 * 6e4),
+    sessionSweepIntervalMs: positiveInt(
+      config.sessionSweepIntervalMs ?? 6e4,
+      "sessionSweepIntervalMs"
+    ),
+    httpTimeoutMs: config.httpTimeoutMs ?? 6e4,
+    httpMaxRetries: config.httpMaxRetries ?? 2,
+    embeddingBatchSize: config.embeddingBatchSize ?? 20,
+    embeddingConcurrency: config.embeddingConcurrency ?? 2,
+    maxConcurrentCompressions: config.maxConcurrentCompressions ?? 3,
+    entitySimilarityThreshold: config.entitySimilarityThreshold ?? 0.92,
+    defaultSearchLimit: config.defaultSearchLimit ?? 10,
+    recallBoostMs: config.recallBoostMs ?? 36e5,
+    chunkStrategy: config.chunkStrategy ?? "markdown-heading",
+    chunkMaxTokens: config.chunkMaxTokens ?? 800,
+    chunkOverlap: config.chunkOverlap ?? 0,
+    knowledgeTopK: config.knowledgeTopK ?? 8,
+    docCoarseTopK: config.docCoarseTopK ?? 5,
+    buildGraphDefault: config.buildGraphDefault ?? "auto",
+    chunkRedundantIds: config.chunkRedundantIds ?? true,
+    knowledgeGraphTriggerScore: config.knowledgeGraphTriggerScore ?? 0.78,
+    knowledgeGraphEntityTopK: config.knowledgeGraphEntityTopK ?? 10,
+    knowledgeGraphAnchorTopK: config.knowledgeGraphAnchorTopK ?? 3,
+    knowledgeGraphHopLimit: config.knowledgeGraphHopLimit ?? 10,
+    graphExtractConcurrency: config.graphExtractConcurrency ?? 2,
+    graphBuildTimeoutMs: config.graphBuildTimeoutMs ?? 12e4,
+    autoOptimizeOnInit: config.autoOptimizeOnInit ?? true,
+    autoOptimizeIntervalMs: config.autoOptimizeIntervalMs ?? 6 * 36e5,
+    optimizeVersionRetentionMs: config.optimizeVersionRetentionMs ?? 0,
+    restoreConcurrency: config.restoreConcurrency ?? 8
+  };
+}
+function ratio(value, name) {
+  if (!Number.isFinite(value) || value <= 0 || value > 1) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u5728 (0, 1] \u8303\u56F4\u5185`);
+  }
+  return value;
+}
+function positiveInt(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u6B63\u6570`);
+  }
+  return Math.floor(value);
+}
+
+// src/db/store.types.ts
+function eq(field, value) {
+  return { op: "eq", field, value };
+}
+
+// src/page.util.ts
+function cmpStr(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// src/llm/embed.service.ts
+import { get_encoding } from "@dqbd/tiktoken";
+var encoder = null;
+function countTokens(text) {
+  if (!encoder) {
+    encoder = get_encoding("cl100k_base");
+  }
+  return encoder.encode(text).length;
+}
+
+// src/db/memory.store.ts
+var MESSAGES_TABLE = "messages";
+var TOPICS_TABLE = "topics";
+var FACTS_TABLE = "facts";
+var SESSIONS_TABLE = "sessions";
+var DOCUMENTS_TABLE = "documents";
+var CHUNKS_TABLE = "chunks";
+var RRF_K = 60;
+var HYBRID_OVERFETCH = 2;
+function tableDefs(dim) {
+  return [
+    {
+      name: MESSAGES_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "message_id", type: "text" },
+        { name: "talker_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "type", type: "text" },
+        { name: "content", type: "text" },
+        { name: "parts", type: "text", nullable: true },
+        // 兼容存量数据
+        { name: "payload", type: "text", nullable: true },
+        { name: "vector", type: "vector" },
+        { name: "usage", type: "int" },
+        { name: "metadata", type: "text" },
+        { name: "created_at", type: "long" }
+      ],
+      indexes: [
+        { column: "message_id", kind: "scalar" },
+        { column: "session_id", kind: "scalar" },
+        { column: "content", kind: "fts" },
+        { column: "metadata", kind: "fts" }
+      ]
+    },
+    {
+      name: TOPICS_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "summary_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "title", type: "text", nullable: true },
+        // 兼容存量数据
+        { name: "detail", type: "text", nullable: true },
+        { name: "summary", type: "text" },
+        { name: "concise", type: "text", nullable: true },
+        { name: "tokens", type: "int", nullable: true },
+        { name: "start_message_id", type: "text", nullable: true },
+        { name: "end_message_id", type: "text", nullable: true },
+        { name: "vector", type: "vector" },
+        { name: "start_time", type: "long" },
+        { name: "end_time", type: "long" },
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long" },
+        { name: "recall_count", type: "int" }
+      ],
+      indexes: [
+        { column: "chat_id", kind: "scalar" },
+        { column: "summary", kind: "fts" }
+      ]
+    },
+    {
+      name: FACTS_TABLE,
+      columns: [
+        { name: "fact_id", type: "text" },
+        { name: "level", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "fact_key", type: "text", nullable: true },
+        { name: "content", type: "text" },
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long", nullable: true }
+      ],
+      indexes: []
+    },
+    {
+      name: SESSIONS_TABLE,
+      columns: [
+        { name: "session_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "title", type: "text" },
+        { name: "metadata", type: "text" },
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long" }
+      ],
+      indexes: [{ column: "session_id", kind: "scalar" }]
+    },
+    {
+      name: DOCUMENTS_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "doc_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "title", type: "text" },
+        { name: "source_name", type: "text" },
+        { name: "full_content", type: "text" },
+        { name: "content_hash", type: "text" },
+        { name: "summary", type: "text" },
+        // vector 列存储文档摘要向量（summaryVector），用于文档级粗召回
+        { name: "vector", type: "vector" },
+        { name: "chunk_count", type: "int" },
+        { name: "has_graph", type: "int" },
+        // 0/1 充当布尔
+        { name: "metadata", type: "text" },
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long" }
+      ],
+      indexes: [{ column: "doc_id", kind: "scalar" }]
+    },
+    {
+      name: CHUNKS_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "chunk_id", type: "text" },
+        { name: "doc_id", type: "text" },
+        // user_id/chat_id/session_id：chunkRedundantIds=false 时存空串，仅经 documents join 过滤
+        { name: "user_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "content", type: "text" },
+        { name: "vector", type: "vector" },
+        { name: "heading_path", type: "text" },
+        { name: "ordinal", type: "int" },
+        { name: "tokens", type: "int" },
+        { name: "metadata", type: "text" },
+        { name: "created_at", type: "long" }
+      ],
+      indexes: [
+        { column: "doc_id", kind: "scalar" },
+        { column: "content", kind: "fts" }
+      ]
+    }
+  ];
+}
+function toVector(v) {
+  return Array.isArray(v) ? v : Array.from(v);
+}
+function messageToRow(m) {
+  return {
+    message_id: m.messageId,
+    talker_id: m.talkerId,
+    chat_id: m.chatId,
+    user_id: m.userId,
+    session_id: m.sessionId,
+    type: m.type,
+    content: m.content,
+    parts: m.parts ?? "[]",
+    payload: m.payload ?? null,
+    vector: m.vector,
+    usage: m.usage,
+    metadata: m.metadata,
+    created_at: m.createdAt
+  };
+}
+function rowToMessage(r) {
+  return {
+    messageId: r.message_id,
+    talkerId: r.talker_id,
+    chatId: r.chat_id,
+    userId: r.user_id,
+    sessionId: r.session_id,
+    type: r.type,
+    content: r.content,
+    parts: r.parts ?? "[]",
+    // 旧数据无此列时安全降级
+    payload: r.payload ?? void 0,
+    vector: toVector(r.vector),
+    usage: positiveNumber(r.usage),
+    metadata: r.metadata,
+    createdAt: Number(r.created_at)
+  };
+}
+function topicToRow(t) {
+  return {
+    summary_id: t.summaryId,
+    session_id: t.sessionId,
+    user_id: t.userId,
+    chat_id: t.chatId,
+    title: t.title ?? "",
+    // 旧库的 detail/concise 可能仍是 NOT NULL；兼容写入但业务只读取 summary。
+    detail: t.detail ?? t.summary,
+    summary: t.summary,
+    concise: t.concise ?? t.summary,
+    tokens: t.tokens,
+    start_message_id: t.startMessageId ?? null,
+    end_message_id: t.endMessageId ?? null,
+    vector: t.vector,
+    start_time: t.startTime,
+    end_time: t.endTime,
+    created_at: t.createdAt,
+    updated_at: t.updatedAt,
+    recall_count: t.recallCount
+  };
+}
+function rowToTopic(r) {
+  return {
+    summaryId: r.summary_id,
+    sessionId: r.session_id,
+    userId: r.user_id,
+    chatId: r.chat_id,
+    title: r.title ?? "",
+    summary: r.summary || r.detail || r.concise || "",
+    tokens: positiveNumber(r.tokens),
+    startMessageId: r.start_message_id ?? void 0,
+    endMessageId: r.end_message_id ?? void 0,
+    detail: r.detail ?? void 0,
+    concise: r.concise ?? void 0,
+    vector: toVector(r.vector),
+    startTime: Number(r.start_time),
+    endTime: Number(r.end_time),
+    createdAt: Number(r.created_at),
+    updatedAt: Number(r.updated_at),
+    recallCount: Number(r.recall_count)
+  };
+}
+function factToRow(f) {
+  return {
+    fact_id: f.factId,
+    level: f.level,
+    chat_id: f.chatId,
+    session_id: f.sessionId,
+    user_id: f.userId,
+    fact_key: f.key ?? null,
+    content: f.content,
+    created_at: f.createdAt,
+    updated_at: f.updatedAt ?? f.createdAt
+  };
+}
+function rowToFact(r) {
+  return {
+    factId: r.fact_id,
+    level: r.level,
+    chatId: r.chat_id,
+    sessionId: r.session_id,
+    userId: r.user_id,
+    key: r.fact_key ?? void 0,
+    content: r.content,
+    createdAt: Number(r.created_at),
+    updatedAt: Number(r.updated_at ?? r.created_at)
+  };
+}
+function sessionToRow(s) {
+  return {
+    session_id: s.sessionId,
+    chat_id: s.chatId,
+    user_id: s.userId,
+    title: s.title,
+    metadata: s.metadata,
+    created_at: s.createdAt,
+    updated_at: s.updatedAt
+  };
+}
+function rowToSession(r) {
+  return {
+    sessionId: r.session_id,
+    chatId: r.chat_id,
+    userId: r.user_id,
+    title: r.title,
+    metadata: r.metadata,
+    createdAt: Number(r.created_at),
+    updatedAt: Number(r.updated_at)
+  };
+}
+function documentToRow(d) {
+  return {
+    doc_id: d.docId,
+    user_id: d.userId,
+    chat_id: d.chatId,
+    session_id: d.sessionId,
+    title: d.title,
+    source_name: d.sourceName,
+    full_content: d.fullContent,
+    content_hash: d.contentHash,
+    summary: d.summary,
+    vector: d.summaryVector,
+    chunk_count: d.chunkCount,
+    has_graph: d.hasGraph ? 1 : 0,
+    metadata: JSON.stringify(d.metadata ?? {}),
+    created_at: d.createdAt,
+    updated_at: d.updatedAt
+  };
+}
+function rowToDocument(r) {
+  return {
+    docId: r.doc_id,
+    userId: r.user_id,
+    chatId: r.chat_id,
+    sessionId: r.session_id,
+    title: r.title,
+    sourceName: r.source_name,
+    fullContent: r.full_content,
+    contentHash: r.content_hash,
+    summary: r.summary,
+    summaryVector: toVector(r.vector),
+    chunkCount: Number(r.chunk_count),
+    hasGraph: Number(r.has_graph) === 1,
+    metadata: safeParseObject(r.metadata),
+    createdAt: Number(r.created_at),
+    updatedAt: Number(r.updated_at)
+  };
+}
+function chunkToRow(c) {
+  return {
+    chunk_id: c.chunkId,
+    doc_id: c.docId,
+    user_id: c.userId,
+    chat_id: c.chatId,
+    session_id: c.sessionId,
+    content: c.content,
+    vector: c.vector,
+    heading_path: c.headingPath,
+    ordinal: c.ordinal,
+    tokens: c.tokens,
+    metadata: JSON.stringify(c.metadata ?? {}),
+    created_at: c.createdAt
+  };
+}
+function rowToChunk(r) {
+  return {
+    chunkId: r.chunk_id,
+    docId: r.doc_id,
+    userId: r.user_id,
+    chatId: r.chat_id,
+    sessionId: r.session_id,
+    content: r.content,
+    vector: toVector(r.vector),
+    headingPath: r.heading_path,
+    ordinal: Number(r.ordinal),
+    tokens: Number(r.tokens),
+    metadata: safeParseObject(r.metadata),
+    createdAt: Number(r.created_at)
+  };
+}
+function safeParseObject(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return {};
+  }
+}
+function positiveNumber(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+function migrationValueEquals(current, next) {
+  if (current == null && next == null) return true;
+  if (typeof next === "number") return Number(current) === next;
+  return String(current) === String(next);
+}
+function rrfFuse(lists, keyOf) {
+  const acc = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    list.forEach((row, idx) => {
+      const id = keyOf(row);
+      const inc = 1 / (RRF_K + idx + 1);
+      const entry = acc.get(id);
+      if (entry) entry.score += inc;
+      else acc.set(id, { row, score: inc });
+    });
+  }
+  return [...acc.values()].sort((a, b) => b.score - a.score).map((e) => e.row);
+}
+var MemoryStore = class {
+  config;
+  provider;
+  providerOverride;
+  /** provider 省略时在 init() 阶段经 provider.resolver 自动探测创建（测试可显式注入） */
+  constructor(config, provider) {
+    this.config = config;
+    this.providerOverride = provider;
+  }
+  /** 当前后端 provider 标识（日志/诊断用） */
+  get providerKind() {
+    return this.provider?.kind ?? "uninitialized";
+  }
+  async init() {
+    if (this.providerOverride) {
+      this.provider = this.providerOverride;
+    } else {
+      const { createProvider } = await import("./provider.resolver-2KS2YYNV.js");
+      this.provider = await createProvider(this.config);
+      console.info(`[memory] \u5411\u91CF\u5B58\u50A8\u540E\u7AEF\uFF1A${this.provider.kind}`);
+    }
+    await this.provider.init(tableDefs(this.config.embeddingDimension));
+  }
+  async close() {
+    await this.provider.close();
+  }
+  /**
+   * 存储压实（碎片合并 + 历史版本清理）。
+   * LanceDB 后端长期运行必须定期执行；SQLite 后端为可选的空间回收。
+   */
+  async optimizeStorage(retentionMs = 0) {
+    return this.provider.optimize(retentionMs);
+  }
+  // ── messages ───────────────────────────────────────────────────────────────
+  async addMessages(messages) {
+    if (messages.length === 0) return;
+    await this.provider.add(MESSAGES_TABLE, messages.map(messageToRow));
+  }
+  /** 0.3.x → 0.4.x 数据回填；幂等，不调用 LLM、不删除原始消息。 */
+  async migrateLegacyData() {
+    const report = {
+      provider: this.providerKind,
+      topicsScanned: 0,
+      topicsUpdated: 0,
+      messagesScanned: 0,
+      messagesUpdated: 0,
+      factsScanned: 0,
+      factsUpdated: 0
+    };
+    const topicRows = await this.provider.query(TOPICS_TABLE);
+    report.topicsScanned = topicRows.length;
+    const messagesBySession = /* @__PURE__ */ new Map();
+    for (const row of topicRows) {
+      const sessionId = String(row.session_id);
+      let messages = messagesBySession.get(sessionId);
+      if (!messages) {
+        messages = await this.provider.query(MESSAGES_TABLE, {
+          filter: [eq("session_id", sessionId)],
+          orderBy: [
+            { column: "created_at", ascending: true },
+            { column: "message_id", ascending: true }
+          ]
+        });
+        messagesBySession.set(sessionId, messages);
+      }
+      const summary = String(row.summary || row.detail || row.concise || "");
+      const startTime = Number(row.start_time);
+      const endTime = Number(row.end_time);
+      const covered = messages.filter(
+        (message) => Number(message.created_at) >= startTime && Number(message.created_at) <= endTime
+      );
+      const values = {
+        summary,
+        tokens: positiveNumber(row.tokens) || Math.max(1, countTokens(summary)),
+        start_message_id: row.start_message_id ?? covered.at(0)?.message_id ?? null,
+        end_message_id: row.end_message_id ?? covered.at(-1)?.message_id ?? null,
+        updated_at: Number(row.updated_at || Date.now())
+      };
+      const changed = Object.entries(values).some(
+        ([key, value]) => !migrationValueEquals(row[key], value)
+      );
+      if (changed) {
+        await this.provider.update(TOPICS_TABLE, values, [eq("summary_id", String(row.summary_id))]);
+        report.topicsUpdated++;
+      }
+    }
+    const messageRows = await this.provider.query(MESSAGES_TABLE);
+    report.messagesScanned = messageRows.length;
+    for (const row of messageRows) {
+      const usage2 = countTokens(
+        [row.content, row.parts ?? "[]", row.metadata ?? "{}", row.payload ?? ""].map(String).join("\n")
+      );
+      if (Number(row.usage) === usage2) continue;
+      await this.provider.update(MESSAGES_TABLE, { usage: usage2 }, [
+        eq("message_id", String(row.message_id))
+      ]);
+      report.messagesUpdated++;
+    }
+    const factRows = await this.provider.query(FACTS_TABLE);
+    report.factsScanned = factRows.length;
+    for (const row of factRows) {
+      const updatedAt = Number(row.updated_at || row.created_at);
+      if (Number(row.updated_at) === updatedAt) continue;
+      await this.provider.update(FACTS_TABLE, { updated_at: updatedAt }, [
+        eq("fact_id", String(row.fact_id))
+      ]);
+      report.factsUpdated++;
+    }
+    return report;
+  }
+  /** message_id 稳定时更新原行，否则新增；用于流式 assistant 消息最终态覆盖。 */
+  async upsertMessages(messages) {
+    if (messages.length === 0) return;
+    const ids = messages.map((message) => message.messageId);
+    const existing = await this.provider.query(MESSAGES_TABLE, {
+      filter: [{ op: "in", field: "message_id", values: ids }],
+      select: ["message_id"]
+    });
+    const existingIds = new Set(existing.map((row) => String(row.message_id)));
+    await Promise.all(
+      messages.filter((message) => existingIds.has(message.messageId)).map(
+        (message) => this.provider.update(
+          MESSAGES_TABLE,
+          messageToRow(message),
+          [eq("message_id", message.messageId)]
+        )
+      )
+    );
+    await this.addMessages(messages.filter((message) => !existingIds.has(message.messageId)));
+  }
+  async getMessagesSince(sessionId, since, limit) {
+    try {
+      const rows = await this.provider.query(MESSAGES_TABLE, {
+        filter: [eq("session_id", sessionId), { op: "gt", field: "created_at", value: since }],
+        limit
+      });
+      return rows.sort((a, b) => Number(a.created_at) - Number(b.created_at)).map(rowToMessage);
+    } catch {
+      return [];
+    }
+  }
+  async getMessagesAfterBoundary(sessionId, endTime, endMessageId) {
+    const messages = await this.getAllMessagesBySession(sessionId);
+    return messages.filter(
+      (message) => message.createdAt > endTime || message.createdAt === endTime && endMessageId != null && message.messageId.localeCompare(endMessageId) > 0
+    );
+  }
+  async getLatestMessages(sessionId, limit) {
+    if (limit <= 0) return [];
+    try {
+      const rows = await this.provider.query(MESSAGES_TABLE, {
+        filter: [eq("session_id", sessionId)],
+        orderBy: [
+          { column: "created_at", ascending: false },
+          { column: "message_id", ascending: false }
+        ],
+        limit
+      });
+      return rows.reverse().map(rowToMessage);
+    } catch {
+      return [];
+    }
+  }
+  /** 取某会话的全部消息（按 createdAt 升序），供管理面板分页切片使用 */
+  async getAllMessagesBySession(sessionId) {
+    try {
+      const rows = await this.provider.query(MESSAGES_TABLE, {
+        filter: [eq("session_id", sessionId)]
+      });
+      return rows.sort(
+        (a, b) => Number(a.created_at) - Number(b.created_at) || cmpStr(a.message_id, b.message_id)
+      ).map(rowToMessage);
+    } catch {
+      return [];
+    }
+  }
+  async searchMessages(vector, filter, limit = 10) {
+    const rows = await this.provider.vectorSearch(MESSAGES_TABLE, vector, { filter, limit });
+    return rows.map((r) => ({ ...rowToMessage(r), _distance: r._distance }));
+  }
+  // 对 messages 表执行混合搜索（BM25 + 向量），用于 topics 搜索无结果时的回退
+  async hybridSearchMessages(query, vector, filter, limit = 10) {
+    const fused = await this.hybridSearch(
+      MESSAGES_TABLE,
+      ["content", "metadata"],
+      query,
+      vector,
+      filter,
+      limit
+    );
+    return fused.slice(0, limit).map(rowToMessage);
+  }
+  async hybridSearchTopics(query, vector, filter, limit = 10) {
+    try {
+      const fused = (await this.hybridSearch(TOPICS_TABLE, ["summary"], query, vector, filter, limit)).slice(0, limit);
+      if (fused.length > 0) {
+        const total = fused.length;
+        return fused.map((r, idx) => ({
+          row: r,
+          score: total - idx + Math.log1p(Number(r.recall_count))
+        })).sort((a, b) => b.score - a.score).map((x) => rowToTopic(x.row));
+      }
+      return [];
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * 通用混合检索：FTS（BM25）与向量两路各取 limit*HYBRID_OVERFETCH 候选，RRF 融合。
+   * FTS 不可用（后端不支持或查询失败）时降级为纯向量。返回融合后的完整候选序列（未截断）。
+   */
+  async hybridSearch(table, ftsColumns, query, vector, filter, limit) {
+    const fetchN = limit * HYBRID_OVERFETCH;
+    const supportsFts = this.provider.capabilities().fts;
+    const [ftsRows, vecRows] = await Promise.all([
+      supportsFts ? this.provider.ftsSearch(table, query, { columns: ftsColumns, filter, limit: fetchN }).catch(() => []) : Promise.resolve([]),
+      this.provider.vectorSearch(table, vector, { filter, limit: fetchN }).catch(() => [])
+    ]);
+    const keyColumn = this.keyColumnOf(table);
+    return rrfFuse([ftsRows, vecRows], (r) => String(r[keyColumn]));
+  }
+  keyColumnOf(table) {
+    switch (table) {
+      case MESSAGES_TABLE:
+        return "message_id";
+      case TOPICS_TABLE:
+        return "summary_id";
+      case DOCUMENTS_TABLE:
+        return "doc_id";
+      case CHUNKS_TABLE:
+        return "chunk_id";
+      case SESSIONS_TABLE:
+        return "session_id";
+      case FACTS_TABLE:
+        return "fact_id";
+      default:
+        throw new Error(`Unknown table: ${table}`);
+    }
+  }
+  // ── topics ─────────────────────────────────────────────────────────────────
+  async addTopic(topic) {
+    await this.provider.add(TOPICS_TABLE, [topicToRow(topic)]);
+  }
+  async updateTopic(topic) {
+    await this.provider.update(
+      TOPICS_TABLE,
+      topicToRow(topic),
+      [eq("summary_id", topic.summaryId)]
+    );
+  }
+  async updateTopicRecallCount(summaryId, count) {
+    await this.provider.update(
+      TOPICS_TABLE,
+      { recall_count: count, updated_at: Date.now() },
+      [eq("summary_id", summaryId)]
+    );
+  }
+  async incrementTopicRecallCounts(topics) {
+    await Promise.all(
+      topics.map((topic) => this.updateTopicRecallCount(topic.summaryId, topic.recallCount + 1))
+    );
+  }
+  async getTopicsBySession(sessionId, since = 0) {
+    try {
+      const filter = [eq("session_id", sessionId)];
+      if (since > 0) filter.push({ op: "gte", field: "end_time", value: since });
+      const rows = await this.provider.query(TOPICS_TABLE, { filter });
+      return rows.sort(
+        (a, b) => Number(a.end_time) - Number(b.end_time) || cmpStr(a.summary_id, b.summary_id)
+      ).map(rowToTopic);
+    } catch {
+      return [];
+    }
+  }
+  async getRecentTopics(chatId, userId, n1, n2, n3) {
+    const filter = [eq("chat_id", chatId), eq("user_id", userId)];
+    const recallBoostMs = this.config.recallBoostMs;
+    const fetchTopics = async (count) => {
+      if (count <= 0) return [];
+      try {
+        const rows = await this.provider.query(TOPICS_TABLE, {
+          filter,
+          limit: count * 5
+        });
+        return rows.sort((a, b) => {
+          const scoreA = Number(a.end_time) + Number(a.recall_count) * recallBoostMs;
+          const scoreB = Number(b.end_time) + Number(b.recall_count) * recallBoostMs;
+          return scoreB - scoreA;
+        }).slice(0, count).map(rowToTopic);
+      } catch {
+        return [];
+      }
+    };
+    const allTopics = await fetchTopics(n1 + n2 + n3);
+    return {
+      detail: allTopics.slice(0, n1),
+      summary: allTopics.slice(n1, n1 + n2),
+      concise: allTopics.slice(n1 + n2, n1 + n2 + n3)
+    };
+  }
+  /** 全量读取 topics（管理面板列表用，不做 recall 加权排序，按 endTime 倒序）*/
+  async getAllTopics() {
+    try {
+      const rows = await this.provider.query(TOPICS_TABLE);
+      return rows.sort(
+        (a, b) => Number(b.end_time) - Number(a.end_time) || cmpStr(a.summary_id, b.summary_id)
+      ).map(rowToTopic);
+    } catch {
+      return [];
+    }
+  }
+  async deleteTopicsBySession(sessionId) {
+    await this.provider.deleteWhere(TOPICS_TABLE, [eq("session_id", sessionId)]);
+  }
+  async deleteTopicsByIds(summaryIds) {
+    if (summaryIds.length === 0) return;
+    await this.provider.deleteWhere(TOPICS_TABLE, [
+      { op: "in", field: "summary_id", values: summaryIds }
+    ]);
+  }
+  // ── facts ──────────────────────────────────────────────────────────────────
+  async saveFact(fact) {
+    await this.provider.add(FACTS_TABLE, [factToRow(fact)]);
+  }
+  async updateFact(fact) {
+    await this.provider.update(FACTS_TABLE, factToRow(fact), [eq("fact_id", fact.factId)]);
+  }
+  async getAllFacts() {
+    try {
+      const rows = await this.provider.query(FACTS_TABLE);
+      return rows.map(rowToFact);
+    } catch {
+      return [];
+    }
+  }
+  /** 删除单条 fact */
+  async deleteFact(factId) {
+    await this.provider.deleteWhere(FACTS_TABLE, [eq("fact_id", factId)]);
+  }
+  // ── sessions ───────────────────────────────────────────────────────────────
+  async getAllSessionIds() {
+    try {
+      const rows = await this.provider.query(MESSAGES_TABLE, {
+        select: ["session_id"],
+        limit: 1e4
+      });
+      return [...new Set(rows.map((r) => r.session_id))];
+    } catch {
+      return [];
+    }
+  }
+  async insertSession(session) {
+    await this.provider.add(SESSIONS_TABLE, [sessionToRow(session)]);
+  }
+  async upsertSession(session) {
+    await this.provider.deleteWhere(SESSIONS_TABLE, [eq("session_id", session.sessionId)]);
+    await this.provider.add(SESSIONS_TABLE, [sessionToRow(session)]);
+  }
+  async getAllSessions() {
+    try {
+      const rows = await this.provider.query(SESSIONS_TABLE);
+      return rows.map(rowToSession);
+    } catch {
+      return [];
+    }
+  }
+  async deleteSession(sessionId) {
+    await this.provider.deleteWhere(SESSIONS_TABLE, [eq("session_id", sessionId)]);
+  }
+  /** 删除某会话下的全部消息（级联删除会话时使用）*/
+  async deleteMessagesBySession(sessionId) {
+    await this.provider.deleteWhere(MESSAGES_TABLE, [eq("session_id", sessionId)]);
+  }
+  // ── 统计 ───────────────────────────────────────────────────────────────────
+  /** 各表行数统计（概览卡片用）*/
+  async countAll() {
+    const safeCount = async (table) => {
+      try {
+        return await this.provider.count(table);
+      } catch {
+        return 0;
+      }
+    };
+    const [sessions, messages, topics, facts] = await Promise.all([
+      safeCount(SESSIONS_TABLE),
+      safeCount(MESSAGES_TABLE),
+      safeCount(TOPICS_TABLE),
+      safeCount(FACTS_TABLE)
+    ]);
+    return { sessions, messages, topics, facts };
+  }
+  /**
+   * 按天聚合最近 days 天的活跃趋势（概览图表用）。
+   * 返回连续日期序列（含无数据的零值天），按本地日期分桶。
+   */
+  async trendDaily(days) {
+    const dayMs = 864e5;
+    const now = /* @__PURE__ */ new Date();
+    const todayMidnight = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+    const startMs = todayMidnight - (days - 1) * dayMs;
+    const fmt = (ts) => {
+      const d = new Date(ts);
+      const mm = String(d.getMonth() + 1).padStart(2, "0");
+      const dd = String(d.getDate()).padStart(2, "0");
+      return `${d.getFullYear()}-${mm}-${dd}`;
+    };
+    const readCreatedAt = async (table) => {
+      try {
+        const rows = await this.provider.query(table, {
+          select: ["created_at"],
+          filter: [{ op: "gte", field: "created_at", value: startMs }],
+          limit: 1e6
+        });
+        return rows.map((r) => Number(r.created_at)).filter((n) => Number.isFinite(n));
+      } catch {
+        return [];
+      }
+    };
+    const [sessionTs, messageTs, factTs] = await Promise.all([
+      readCreatedAt(SESSIONS_TABLE),
+      readCreatedAt(MESSAGES_TABLE),
+      readCreatedAt(FACTS_TABLE)
+    ]);
+    const buckets = /* @__PURE__ */ new Map();
+    for (let i = 0; i < days; i++) {
+      const key = fmt(startMs + i * dayMs);
+      buckets.set(key, { date: key, sessions: 0, messages: 0, facts: 0 });
+    }
+    const tally = (list, field) => {
+      for (const ts of list) {
+        const b = buckets.get(fmt(ts));
+        if (b) b[field]++;
+      }
+    };
+    tally(sessionTs, "sessions");
+    tally(messageTs, "messages");
+    tally(factTs, "facts");
+    return [...buckets.values()];
+  }
+  // ── 知识库：documents / chunks ─────────────────────────────────────────────
+  async addDocument(doc) {
+    await this.provider.add(DOCUMENTS_TABLE, [documentToRow(doc)]);
+  }
+  async addChunks(chunks) {
+    if (chunks.length === 0) return;
+    await this.provider.add(CHUNKS_TABLE, chunks.map(chunkToRow));
+  }
+  async updateDocumentGraphFlag(docId, hasGraph) {
+    await this.provider.update(
+      DOCUMENTS_TABLE,
+      { has_graph: hasGraph ? 1 : 0, updated_at: Date.now() },
+      [eq("doc_id", docId)]
+    );
+  }
+  async getDocument(docId) {
+    try {
+      const rows = await this.provider.query(DOCUMENTS_TABLE, {
+        filter: [eq("doc_id", docId)],
+        limit: 1
+      });
+      if (rows.length === 0) return null;
+      return rowToDocument(rows[0]);
+    } catch {
+      return null;
+    }
+  }
+  /** 查找同域同 hash 的文档（去重用）*/
+  async findDocumentByHash(contentHash, filter) {
+    try {
+      const rows = await this.provider.query(DOCUMENTS_TABLE, {
+        filter: [eq("content_hash", contentHash), ...filter ?? []],
+        limit: 1
+      });
+      if (rows.length === 0) return null;
+      return rowToDocument(rows[0]);
+    } catch {
+      return null;
+    }
+  }
+  /** 按域过滤返回 docId 列表（chunkRedundantIds=false 时用于 chunk 过滤）*/
+  async getDocIdsByDomain(filter) {
+    try {
+      const rows = await this.provider.query(DOCUMENTS_TABLE, {
+        select: ["doc_id"],
+        filter,
+        limit: 1e5
+      });
+      return [...new Set(rows.map((r) => r.doc_id))];
+    } catch {
+      return [];
+    }
+  }
+  /** 文档级粗召回：对摘要向量做向量搜索，定位候选文档 */
+  async searchDocuments(vector, filter, limit = 5) {
+    try {
+      const rows = await this.provider.vectorSearch(DOCUMENTS_TABLE, vector, { filter, limit });
+      return rows.map((r) => ({ ...rowToDocument(r), _distance: r._distance }));
+    } catch {
+      return [];
+    }
+  }
+  /** 知识片段混合检索（BM25 + 向量），失败回退纯向量 */
+  async searchChunks(query, vector, filter, limit = 8) {
+    try {
+      const fused = await this.hybridSearch(CHUNKS_TABLE, ["content"], query, vector, filter, limit);
+      if (fused.length > 0) return fused.slice(0, limit).map(rowToChunk);
+    } catch {
+    }
+    try {
+      const rows = await this.provider.vectorSearch(CHUNKS_TABLE, vector, { filter, limit });
+      return rows.map(rowToChunk);
+    } catch {
+      return [];
+    }
+  }
+  async deleteDocument(docId) {
+    await this.provider.deleteWhere(DOCUMENTS_TABLE, [eq("doc_id", docId)]);
+  }
+  async deleteChunksByDoc(docId) {
+    await this.provider.deleteWhere(CHUNKS_TABLE, [eq("doc_id", docId)]);
+  }
+  /** 全量读取文档（管理面板用），按更新时间倒序 */
+  async getAllDocuments() {
+    try {
+      const rows = await this.provider.query(DOCUMENTS_TABLE);
+      return rows.sort(
+        (a, b) => Number(b.updated_at) - Number(a.updated_at) || cmpStr(a.doc_id, b.doc_id)
+      ).map(rowToDocument);
+    } catch {
+      return [];
+    }
+  }
+  /** 知识库行数统计 */
+  async countKnowledge() {
+    const safeCount = async (table) => {
+      try {
+        return await this.provider.count(table);
+      } catch {
+        return 0;
+      }
+    };
+    const [documents, chunks] = await Promise.all([
+      safeCount(DOCUMENTS_TABLE),
+      safeCount(CHUNKS_TABLE)
+    ]);
+    return { documents, chunks };
+  }
+  /**
+   * 根据 metadata 字段内容构建结构化过滤条件。
+   *
+   * metadata 以 JSON 字符串存储，此方法将键值对转换为 jsonContains 条件，
+   * 可直接传给 searchMessages / hybridSearchTopics 的 filter 参数。
+   *
+   * 注意：仅适合简单标量值（字符串、数字、布尔）的精确匹配。
+   * 复杂嵌套对象或含空格的 JSON 值可能无法可靠匹配。
+   */
+  static buildMetadataFilter(conditions) {
+    return Object.entries(conditions).map(([key, value]) => ({
+      op: "jsonContains",
+      field: "metadata",
+      key,
+      value
+    }));
+  }
+};
+
+// src/cli.ts
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (command !== "migrate") {
+    usage();
+    process.exitCode = command ? 1 : 0;
+    return;
+  }
+  const configArg = valueOf(args, "--config");
+  if (!configArg) throw new Error("migrate requires --config <config.json>");
+  const dryRun = args.includes("--dry-run");
+  const configPath = path2.resolve(configArg);
+  const configDir = path2.dirname(configPath);
+  const parsed = JSON.parse(await fs.readFile(configPath, "utf8"));
+  const source = findMemoryConfig(parsed);
+  const liveConfig = resolveConfig(absolutizeConfig(source, configDir));
+  let config = liveConfig;
+  console.info(
+    `[ppagent-memory] migration ${dryRun ? "dry-run" : "start"}; stop all processes using the memory database first.`
+  );
+  let tempDir;
+  if (dryRun) {
+    tempDir = await fs.mkdtemp(path2.join(os.tmpdir(), "ppagent-memory-migrate-"));
+    config = await cloneConfigStorage(liveConfig, tempDir);
+  } else {
+    const backupArg = valueOf(args, "--backup");
+    const backupDir = path2.resolve(
+      backupArg ?? path2.join(configDir, `memory-backup-${safeTimestamp()}`)
+    );
+    await backupStorage(liveConfig, backupDir);
+    console.info(`[ppagent-memory] backup created at ${backupDir}`);
+  }
+  const store = new MemoryStore(config);
+  try {
+    await store.init();
+    const report = await store.migrateLegacyData();
+    console.info(JSON.stringify({ dryRun, ...report }, null, 2));
+    console.info(
+      dryRun ? "[ppagent-memory] dry-run complete; original storage was not modified." : "[ppagent-memory] migration complete; original raw messages were retained."
+    );
+  } finally {
+    await store.close().catch(() => {
+    });
+    if (tempDir) await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+function findMemoryConfig(root) {
+  const candidates = [
+    root,
+    root.memory,
+    objectAt(root, ["app", "memory", "auto"]),
+    objectAt(root, ["service", "memory"])
+  ];
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === "object" && "lancedbPath" in candidate && "embeddingModel" in candidate && "llmModel" in candidate) {
+      const value = candidate;
+      const { advanced, ...base } = value;
+      return { ...advanced ?? {}, ...base };
+    }
+  }
+  throw new Error("No @ppagent/memory config found (checked root and app.memory.auto)");
+}
+function objectAt(root, keys) {
+  let value = root;
+  for (const key of keys) {
+    if (!value || typeof value !== "object") return void 0;
+    value = value[key];
+  }
+  return value;
+}
+function absolutizeConfig(config, base) {
+  const absolute = (value) => value == null || path2.isAbsolute(value) ? value : path2.resolve(base, value);
+  return {
+    ...config,
+    lancedbPath: absolute(config.lancedbPath),
+    sqlitePath: absolute(config.sqlitePath),
+    grafeoPath: absolute(config.grafeoPath)
+  };
+}
+async function cloneConfigStorage(config, tempDir) {
+  const lancedbPath = path2.join(tempDir, "lancedb");
+  const sqlitePath = path2.join(tempDir, "memory.sqlite3");
+  if (await exists(config.lancedbPath)) await fs.cp(config.lancedbPath, lancedbPath, { recursive: true });
+  if (await exists(config.sqlitePath)) await fs.copyFile(config.sqlitePath, sqlitePath);
+  if (await exists(`${config.sqlitePath}-wal`)) await fs.copyFile(`${config.sqlitePath}-wal`, `${sqlitePath}-wal`);
+  if (await exists(`${config.sqlitePath}-shm`)) await fs.copyFile(`${config.sqlitePath}-shm`, `${sqlitePath}-shm`);
+  const marker = path2.join(path2.dirname(config.lancedbPath), ".memory-provider");
+  const marked = await fs.readFile(marker, "utf8").then((value) => value.trim(), () => "");
+  const provider = config.provider === "auto" ? marked === "sqlite" || marked === "lancedb" ? marked : await exists(config.sqlitePath) ? "sqlite" : "lancedb" : config.provider;
+  return { ...config, provider, lancedbPath, sqlitePath, grafeoPath: path2.join(tempDir, "grafeo") };
+}
+async function backupStorage(config, backupDir) {
+  await fs.mkdir(backupDir, { recursive: true });
+  const entries = [
+    [config.lancedbPath, "lancedb"],
+    [config.sqlitePath, "memory.sqlite3"],
+    [config.sqlitePath ? `${config.sqlitePath}-wal` : void 0, "memory.sqlite3-wal"],
+    [config.sqlitePath ? `${config.sqlitePath}-shm` : void 0, "memory.sqlite3-shm"],
+    [config.grafeoPath, "grafeo"]
+  ];
+  for (const [source, name] of entries) {
+    if (!source || !await exists(source)) continue;
+    await fs.cp(source, path2.join(backupDir, name), { recursive: true });
+  }
+  await fs.writeFile(
+    path2.join(backupDir, "MIGRATION.txt"),
+    "Backup created before @ppagent/memory migration. Stop the service, then restore these files to roll back.\n"
+  );
+}
+async function exists(file) {
+  return fs.access(file).then(() => true, () => false);
+}
+function valueOf(args, flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : void 0;
+}
+function safeTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function usage() {
+  console.info(
+    "Usage: ppagent-memory migrate --config <config.json> [--dry-run] [--backup <directory>]"
+  );
+}
+main().catch((error) => {
+  console.error(`[ppagent-memory] ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});