@ppagent/memory 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -27,7 +27,7 @@ interface Paginated<T> {
  * 多模态消息的单个内容块，与 OpenAI content part 对齐
  */
 interface ContentPart {
-    type: "text" | "image_url" | "file_url";
+    type: string;
     /** type 为 "text" 时的文本内容 */
     text?: string;
     /** type 为 "image_url" 时的图片信息 */
@@ -39,6 +39,8 @@ interface ContentPart {
         url: string;
         name?: string;
     };
+    /** 保留宿主框架自定义 content part，写入和回读时不丢字段。 */
+    [key: string]: unknown;
 }
 interface RawMessage {
     messageId?: string;
@@ -57,6 +59,8 @@ interface RawMessage {
      * 序列化后存入 LanceDB 的 parts 字段。
      */
     parts?: ContentPart[];
+    /** 宿主框架的原始消息载荷；记忆框架仅透明保存和回读。 */
+    payload?: unknown;
     usage?: number;
     metadata?: Record<string, unknown>;
     createdAt?: number;
@@ -72,6 +76,8 @@ interface StoredMessage {
     content: string;
     /** JSON.stringify(ContentPart[])，纯文本消息为 "[]" */
     parts: string;
+    /** JSON.stringify(payload)，未提供时为 undefined。 */
+    payload?: string;
     usage: number;
     metadata: string;
     vector: number[];
@@ -84,9 +90,17 @@ interface Topic {
     chatId: string;
     /** 压缩时自动生成的主题标题（一句话），存量数据可能为空串 */
     title: string;
-    detail: string;
+    /** 唯一的压缩正文。长度由内容重要性动态决定。 */
     summary: string;
-    concise: string;
+    /** 压缩结果的 token 数；旧数据缺失时由本地 tokenizer 回填。 */
+    tokens: number;
+    /** 本 Topic 覆盖的首尾原始消息 id，便于同毫秒边界精确恢复。 */
+    startMessageId?: string;
+    endMessageId?: string;
+    /** @deprecated 仅用于读取尚未迁移的 0.3.x 数据。 */
+    detail?: string;
+    /** @deprecated 仅用于读取尚未迁移的 0.3.x 数据。 */
+    concise?: string;
     startTime: number;
     endTime: number;
     createdAt: number;
@@ -100,8 +114,12 @@ interface Fact {
     chatId: string;
     sessionId: string;
     userId: string;
+    /** 同一 level/owner 内用于 upsert 的稳定键；旧数据可能为空。 */
+    key?: string;
     content: string;
     createdAt: number;
+    /** 最近一次同 key 更新时刻；旧数据回落 createdAt。 */
+    updatedAt?: number;
 }
 interface EntityMeta {
     messageId?: string;
@@ -179,9 +197,9 @@ interface UpdateEntityOptions {
 interface CompressOutput {
     /** 自动生成的主题标题（一句话） */
     title: string;
-    detail: string;
     summary: string;
-    concise: string;
+    /** 模型报告的摘要输出 token；缺失时由本地 tokenizer 计算。 */
+    tokens?: number;
     entities: Array<{
         name: string;
         type: string;
@@ -198,10 +216,54 @@ interface CompressOutput {
 interface SessionEntry {
     messages: StoredMessage[];
     totalTokens: number;
+    topics: Topic[];
+    topicTokens: number;
     ids: {
         chatId: string;
         userId: string;
     };
+    lastModelContextTokens?: number;
+    lastAccessAt: number;
+}
+/** getHistoryWindow 返回的原始消息；字段形态与 updateChat 输入保持一致。 */
+interface MemoryRawMessage {
+    messageId: string;
+    talkerId: string;
+    chatId: string;
+    userId: string;
+    sessionId: string;
+    type: MessageType;
+    content: string;
+    parts?: ContentPart[];
+    payload?: unknown;
+    usage: number;
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+}
+interface MemoryContextWindowUsage {
+    modelContextTokens: number;
+    usableContextTokens: number;
+    compressedTokenLimit: number;
+    compressedTokens: number;
+    rawTokenLimit: number;
+    rawTokens: number;
+}
+type MemoryBlockingCompressionReason = "pending" | "raw" | "topics";
+interface MemoryBlockingCompressionEvent {
+    sessionId: string;
+    phase: "start" | "end";
+    reason: MemoryBlockingCompressionReason;
+}
+interface GetHistoryWindowOptions {
+    /** 仅当前读取确实被压缩阻塞时调用；回调异常不会影响记忆读取。 */
+    onBlockingCompression?: (event: MemoryBlockingCompressionEvent) => void;
+}
+/** 固定预算的压缩记忆 + 近期未压缩原始消息。 */
+interface MemoryContextWindow {
+    sessionId: string;
+    compressedContext: string;
+    recentMessages: MemoryRawMessage[];
+    usage: MemoryContextWindowUsage;
 }
 /** 是否为文档构建知识图谱：true/false 显式控制，"auto" 由内置 LLM 判定 */
 type BuildGraphMode = boolean | "auto";
@@ -264,6 +326,8 @@ interface AddDocumentOptions {
     userId?: string;
     chatId?: string;
     sessionId?: string;
+    /** 内容哈希去重范围；默认 session（兼容旧行为）。 */
+    scope?: SearchScope;
     /** 不传则从首个 H1 / sourceName 推断 */
     title?: string;
     sourceName?: string;
@@ -333,16 +397,46 @@ interface MemoryConfig {
     embeddingBatchSize?: number;
     /** embedding 批次并发数（默认 2）。*/
     embeddingConcurrency?: number;
+    /** 压缩 Topic 的全局存储上限，默认 16K。 */
+    compressedContextTokenLimit?: number;
+    /** Topic 最多占本次可用模型上下文的比例，默认 0.10。 */
+    compressedContextRatio?: number;
+    /** Topic 超过本次有效预算多少倍后必须同步归并，默认 1.25。 */
+    topicCompactionSyncRatio?: number;
+    /** 模型上下文中允许历史记忆使用的比例，默认 0.75。 */
+    contextUsageRatio?: number;
+    /** 原始消息达到其可用预算的此比例时后台预压缩，默认 0.75。 */
+    precompressionRatio?: number;
+    /** 单次压缩目标占原始消息预算的比例，默认 0.5。 */
+    compressionBatchRatio?: number;
+    /** 单次压缩硬上限；0 表示只受 compressionBatchRatio 控制。 */
+    compressionBatchTokenLimit?: number;
+    /** 单条 Topic 摘要硬上限，实际长度由重要性决定，默认 2048。 */
+    topicSummaryMaxTokens?: number;
+    /** 未传 getHistoryWindow 模型窗口时使用，默认 256K。 */
+    defaultModelContextTokens?: number;
+    /** 冷启动最多恢复多久以前的压缩 Topic；0 表示永久。 */
+    maxHistoryAgeMs?: number;
+    /** 会话缓存空闲释放时间，默认 30 分钟；<=0 关闭。 */
+    sessionIdleTtlMs?: number;
+    /** 空闲会话扫描周期，默认 1 分钟。 */
+    sessionSweepIntervalMs?: number;
+    /** @deprecated 0.3.x 原始消息固定阈值；仅为配置兼容保留。 */
     sessionTokenLimit?: number;
+    /** @deprecated 使用 compressedContextTokenLimit。 */
     historyWindowTokenLimit?: number;
+    /** @deprecated 三级 Topic 窗口已移除。 */
     topicRatio?: [number, number, number];
+    /** @deprecated 使用 topicSummaryMaxTokens。 */
     detailMaxTokens?: number;
+    /** 文档摘要仍使用此限制；对话 Topic 使用 topicSummaryMaxTokens。 */
     summaryMaxTokens?: number;
+    /** @deprecated 三级 Topic 窗口已移除。 */
     conciseMaxTokens?: number;
     maxConcurrentCompressions?: number;
     entitySimilarityThreshold?: number;
     defaultSearchLimit?: number;
-    /** 每次召回相当于多少毫秒的时间权重加成（默认 3_600_000 即 1 小时）*/
+    /** @deprecated 连续历史窗口不再按召回热度重排。 */
     recallBoostMs?: number;
     /** 切块策略，目前仅 "markdown-heading"（默认）*/
     chunkStrategy?: "markdown-heading";
@@ -573,7 +667,14 @@ declare class MemoryManager {
     private readonly knowledgeManager;
     private readonly sessionMap;
     private optimizeTimer?;
+    private sessionSweepTimer?;
     private optimizeRunning;
+    private optimizeTask?;
+    private destroyTask?;
+    private readonly hydration;
+    private readonly pendingWrites;
+    private readonly topicCompactions;
+    private warnedDefaultModelContext;
     constructor(config: MemoryConfig);
     init(): Promise<void>;
     /** 后台压实的统一入口：防重入（上一轮未结束则跳过），失败仅告警不影响服务。*/
@@ -583,13 +684,17 @@ declare class MemoryManager {
      * @param retentionMs 保留多久内的历史版本，默认取配置 optimizeVersionRetentionMs
      */
     optimizeStorage(retentionMs?: number): Promise<StorageOptimizeResult[]>;
-    private restoreFromStorage;
+    private ensureSessionHydrated;
+    private isSessionBusy;
+    private waitForPendingWrites;
+    private queueSessionWrite;
     updateChat(messages: RawMessage[], opts?: UpdateChatOptions): Promise<void>;
+    private doUpdateChat;
     flushChat(sessionId?: string, opts?: {
         wait?: boolean;
         waitGraph?: boolean;
     }): Promise<void>;
-    updateFacts(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
+    updateFacts(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string, key?: string): Promise<void>;
     updateEntity(entities: Entity[], relations: Relation[], context?: UpdateEntityOptions): Promise<void>;
     search(opts: SearchOptions): Promise<SearchResult[]>;
     ask(opts: SearchOptions & {
@@ -605,7 +710,10 @@ declare class MemoryManager {
      * 返回 user 级(userId) ∪ chat 级(chatId)，按时间正序拼接。
      */
     getFactsForContext(userId: string, chatId: string): Promise<string>;
-    getHistoryWindow(sessionId: string): string;
+    getHistoryWindow(sessionId: string, modelContextTokens?: number, options?: GetHistoryWindowOptions): Promise<MemoryContextWindow>;
+    private compactTopicsForBudget;
+    private notifyBlockingCompression;
+    private calculateWindowUsage;
     private buildScopeFilter;
     private deserializeSession;
     private serializeSession;
@@ -691,7 +799,7 @@ declare class MemoryManager {
     /** 由 chatId 反查所属 userId：优先用会话表映射，兜底用 chat 级 fact 自身。 */
     private resolveChatOwner;
     /** 手动新增一条事实 */
-    addFact(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
+    addFact(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string, key?: string): Promise<void>;
     /** 删除单条事实，返回是否命中 */
     deleteFact(factId: string): Promise<boolean>;
     /**
@@ -742,9 +850,32 @@ declare class MemoryManager {
         chatId?: string;
         sessionId?: string;
     } | undefined, page: PageParams): Promise<Paginated<Document>>;
-    destroy(): void;
+    destroy(): Promise<void>;
 }
 
+interface MemoryContextBudget {
+    modelContextTokens: number;
+    usableContextTokens: number;
+    compressedTokenLimit: number;
+    rawTokenLimit: number;
+}
+/**
+ * 统一计算一次 history window 的 Topic / raw 预算。
+ *
+ * Topic 同时受全局质量上限和当前模型比例约束；最后保留至少 1 token raw 空间，
+ * 避免小窗口模型被固定 Topic 上限完全挤空。
+ */
+declare function calculateContextBudget(config: Pick<ResolvedConfig, "contextUsageRatio" | "compressedContextRatio" | "compressedContextTokenLimit">, modelContextTokens: number): MemoryContextBudget;
+
+interface MemoryMigrationReport {
+    provider: string;
+    topicsScanned: number;
+    topicsUpdated: number;
+    messagesScanned: number;
+    messagesUpdated: number;
+    factsScanned: number;
+    factsUpdated: number;
+}
 /**
  * 记忆系统的存储域层：保持原 LanceService 的公开方法面，内部组合
  * VectorStoreProvider 的通用原语实现。业务逻辑（混合检索融合、话题回退、
@@ -766,7 +897,12 @@ declare class MemoryStore {
      */
     optimizeStorage(retentionMs?: number): Promise<StorageOptimizeResult[]>;
     addMessages(messages: StoredMessage[]): Promise<void>;
+    /** 0.3.x → 0.4.x 数据回填；幂等，不调用 LLM、不删除原始消息。 */
+    migrateLegacyData(): Promise<MemoryMigrationReport>;
+    /** message_id 稳定时更新原行，否则新增；用于流式 assistant 消息最终态覆盖。 */
+    upsertMessages(messages: StoredMessage[]): Promise<void>;
     getMessagesSince(sessionId: string, since: number, limit?: number): Promise<StoredMessage[]>;
+    getMessagesAfterBoundary(sessionId: string, endTime: number, endMessageId?: string): Promise<StoredMessage[]>;
     getLatestMessages(sessionId: string, limit: number): Promise<StoredMessage[]>;
     /** 取某会话的全部消息（按 createdAt 升序），供管理面板分页切片使用 */
     getAllMessagesBySession(sessionId: string): Promise<StoredMessage[]>;
@@ -782,7 +918,10 @@ declare class MemoryStore {
     private hybridSearch;
     private keyColumnOf;
     addTopic(topic: Topic): Promise<void>;
+    updateTopic(topic: Topic): Promise<void>;
     updateTopicRecallCount(summaryId: string, count: number): Promise<void>;
+    incrementTopicRecallCounts(topics: Topic[]): Promise<void>;
+    getTopicsBySession(sessionId: string, since?: number): Promise<Topic[]>;
     getRecentTopics(chatId: string, userId: string, n1: number, n2: number, n3: number): Promise<{
         detail: Topic[];
         summary: Topic[];
@@ -791,7 +930,9 @@ declare class MemoryStore {
     /** 全量读取 topics（管理面板列表用，不做 recall 加权排序，按 endTime 倒序）*/
     getAllTopics(): Promise<Topic[]>;
     deleteTopicsBySession(sessionId: string): Promise<void>;
+    deleteTopicsByIds(summaryIds: string[]): Promise<void>;
     saveFact(fact: Fact): Promise<void>;
+    updateFact(fact: Fact): Promise<void>;
     getAllFacts(): Promise<Fact[]>;
     /** 删除单条 fact */
     deleteFact(factId: string): Promise<void>;
@@ -864,4 +1005,4 @@ type RelationType = (typeof DEFAULT_RELATION_TYPES)[number];
 declare const KIND_CONVERSATION = "conversation";
 declare const KIND_KNOWLEDGE = "knowledge";
 
-export { type AddDocumentOptions, type BuildGraphMode, type Chunk, type ChunkHit, type ChunkPiece, type CompressOutput, type ContentPart, DEFAULT_NODE_TYPES, DEFAULT_RELATION_TYPES, type Document, type DomainIds, type Entity, type EntityMeta, type Fact, type FactLevel, type Filter, type FilterCondition, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, type MemoryConfig, MemoryManager, MemoryStore, type MessageType, type NodeType, type PageParams, type Paginated, type ProviderCapabilities, type ProviderKind, type RawMessage, type Relation, type RelationType, type SearchMode, type SearchOptions, type SearchResult, type SearchScope, type Session, type SessionEntry, type SessionSearchOptions, type SessionView, type StorageOptimizeResult, type StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions, type VectorStoreProvider };
+export { type AddDocumentOptions, type BuildGraphMode, type Chunk, type ChunkHit, type ChunkPiece, type CompressOutput, type ContentPart, DEFAULT_NODE_TYPES, DEFAULT_RELATION_TYPES, type Document, type DomainIds, type Entity, type EntityMeta, type Fact, type FactLevel, type Filter, type FilterCondition, type GetHistoryWindowOptions, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, type MemoryBlockingCompressionEvent, type MemoryBlockingCompressionReason, type MemoryConfig, type MemoryContextBudget, type MemoryContextWindow, type MemoryContextWindowUsage, MemoryManager, type MemoryMigrationReport, type MemoryRawMessage, MemoryStore, type MessageType, type NodeType, type PageParams, type Paginated, type ProviderCapabilities, type ProviderKind, type RawMessage, type Relation, type RelationType, type SearchMode, type SearchOptions, type SearchResult, type SearchScope, type Session, type SessionEntry, type SessionSearchOptions, type SessionView, type StorageOptimizeResult, type StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions, type VectorStoreProvider, calculateContextBudget };