@ppagent/memory 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,594 @@
+type MessageType = "text" | "image" | "file";
+type FactLevel = "user" | "chat";
+type SearchMode = "fast" | "auto" | "all";
+type SearchScope = "session" | "chat" | "user" | "all";
+/**
+ * 多模态消息的单个内容块，与 OpenAI content part 对齐
+ */
+interface ContentPart {
+    type: "text" | "image_url" | "file_url";
+    /** type 为 "text" 时的文本内容 */
+    text?: string;
+    /** type 为 "image_url" 时的图片信息 */
+    image_url?: {
+        url: string;
+    };
+    /** type 为 "file_url" 时的文件信息 */
+    file_url?: {
+        url: string;
+        name?: string;
+    };
+}
+interface RawMessage {
+    messageId?: string;
+    talkerId?: string;
+    chatId?: string;
+    userId?: string;
+    sessionId?: string;
+    type?: MessageType;
+    /**
+     * 纯文本内容，用于 embedding 和全文检索（必填）。
+     * 图片/文件消息填写 alt text，如 "[图片]"。
+     */
+    content: string;
+    /**
+     * 多模态结构化内容（可选）。纯文本消息无需传。
+     * 序列化后存入 LanceDB 的 parts 字段。
+     */
+    parts?: ContentPart[];
+    usage?: number;
+    metadata?: Record<string, unknown>;
+    createdAt?: number;
+}
+interface StoredMessage {
+    messageId: string;
+    talkerId: string;
+    chatId: string;
+    userId: string;
+    sessionId: string;
+    type: MessageType;
+    /** 纯文本，用于搜索和 embedding */
+    content: string;
+    /** JSON.stringify(ContentPart[])，纯文本消息为 "[]" */
+    parts: string;
+    usage: number;
+    metadata: string;
+    vector: number[];
+    createdAt: number;
+}
+interface Topic {
+    summaryId: string;
+    sessionId: string;
+    userId: string;
+    chatId: string;
+    /** 压缩时自动生成的主题标题（一句话），存量数据可能为空串 */
+    title: string;
+    detail: string;
+    summary: string;
+    concise: string;
+    startTime: number;
+    endTime: number;
+    createdAt: number;
+    updatedAt: number;
+    recallCount: number;
+    vector: number[];
+}
+interface Fact {
+    factId: string;
+    level: FactLevel;
+    chatId: string;
+    sessionId: string;
+    userId: string;
+    content: string;
+    createdAt: number;
+}
+interface EntityMeta {
+    messageId?: string;
+    sessionId: string;
+    userId: string;
+    chatId: string;
+    messageTime?: number;
+    [key: string]: unknown;
+}
+interface Entity {
+    name: string;
+    type: string;
+    meta: EntityMeta;
+}
+interface Relation {
+    from: string;
+    to: string;
+    type: string;
+    happenedAt?: number;
+    meta: EntityMeta;
+}
+interface SearchOptions {
+    query: string;
+    scope?: SearchScope;
+    scopeId?: string;
+    mode?: SearchMode;
+    limit?: number;
+}
+interface SearchResult {
+    type: "message" | "topic" | "entity" | "relation";
+    content: string;
+    score: number;
+    meta: Record<string, unknown>;
+}
+interface Session {
+    sessionId: string;
+    chatId: string;
+    userId: string;
+    title: string;
+    metadata: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionView {
+    sessionId: string;
+    chatId: string;
+    userId: string;
+    title: string;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+interface UpdateSessionOptions {
+    title?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SessionSearchOptions {
+    title?: string;
+    userId?: string;
+    chatId?: string;
+    limit?: number;
+}
+interface UpdateChatOptions {
+    userId?: string;
+    chatId?: string;
+    sessionId?: string;
+    sessionTitle?: string;
+    sessionMetadata?: Record<string, unknown>;
+}
+interface UpdateEntityOptions {
+    sessionId?: string;
+    chatId?: string;
+    userId?: string;
+}
+interface CompressOutput {
+    /** 自动生成的主题标题（一句话） */
+    title: string;
+    detail: string;
+    summary: string;
+    concise: string;
+    entities: Array<{
+        name: string;
+        type: string;
+        meta: Record<string, unknown>;
+    }>;
+    relations: Array<{
+        from: string;
+        to: string;
+        type: string;
+        happenedAt?: number;
+        meta: Record<string, unknown>;
+    }>;
+}
+interface SessionEntry {
+    messages: StoredMessage[];
+    totalTokens: number;
+    ids: {
+        chatId: string;
+        userId: string;
+    };
+}
+/** 是否为文档构建知识图谱：true/false 显式控制，"auto" 由内置 LLM 判定 */
+type BuildGraphMode = boolean | "auto";
+/** 文档的领域标记（与会话记忆一致，仅作元信息存储，检索时才决定过滤范围）*/
+interface DomainIds {
+    userId: string;
+    chatId: string;
+    sessionId: string;
+}
+/** 文档（一行一个上传文件）*/
+interface Document {
+    docId: string;
+    userId: string;
+    chatId: string;
+    sessionId: string;
+    title: string;
+    sourceName: string;
+    /** 完整 markdown 原文 */
+    fullContent: string;
+    /** 内容哈希，用于去重 */
+    contentHash: string;
+    /** LLM 生成的文档级摘要 */
+    summary: string;
+    /** summary 的 embedding，供文档级粗召回（schema 中列名为 vector）*/
+    summaryVector: number[];
+    chunkCount: number;
+    hasGraph: boolean;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+/** 知识片段（一行一个切块，带向量）*/
+interface Chunk {
+    chunkId: string;
+    docId: string;
+    userId: string;
+    chatId: string;
+    sessionId: string;
+    content: string;
+    /** content（含 headingPath 前缀）的 embedding */
+    vector: number[];
+    /** markdown 标题层级路径，如 "安装 / 环境要求 / Node 版本" */
+    headingPath: string;
+    /** 片段在文档中的顺序号 */
+    ordinal: number;
+    tokens: number;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+}
+/** 切块器输出（未带向量/id）*/
+interface ChunkPiece {
+    content: string;
+    headingPath: string;
+    ordinal: number;
+    tokens: number;
+}
+interface AddDocumentOptions {
+    /** markdown 原文（必填）*/
+    content: string;
+    userId?: string;
+    chatId?: string;
+    sessionId?: string;
+    /** 不传则从首个 H1 / sourceName 推断 */
+    title?: string;
+    sourceName?: string;
+    metadata?: Record<string, unknown>;
+    /** 默认取 config.buildGraphDefault（默认 "auto"）*/
+    buildGraph?: BuildGraphMode;
+    /** 默认 false：document 落库即返回；true 则等切块落库，文档可检索 */
+    wait?: boolean;
+    /** 默认 false：true 时在 wait 的基础上额外等待知识图谱构建完成 */
+    waitGraph?: boolean;
+}
+interface KnowledgeSearchOptions {
+    query: string;
+    scope?: SearchScope;
+    scopeId?: string;
+    mode?: SearchMode;
+    /** 片段返回上限，默认 config.knowledgeTopK */
+    limit?: number;
+}
+/** 命中的知识片段 */
+interface ChunkHit {
+    chunkId: string;
+    docId: string;
+    content: string;
+    headingPath: string;
+    score: number;
+}
+interface KnowledgeSearchResult {
+    /** 命中的知识片段（按相关度倒序）*/
+    chunks: ChunkHit[];
+    /** 本次涉及的文档及其命中片段数 */
+    documents: Array<{
+        docId: string;
+        title: string;
+        matchedChunkCount: number;
+    }>;
+    /** 图谱命中：mode=auto 命中高置信后扩展 / mode=all 时并发返回 */
+    graphHits: SearchResult[];
+}
+
+interface MemoryConfig {
+    lancedbPath: string;
+    grafeoPath: string;
+    embeddingBaseUrl: string;
+    embeddingApiKey: string;
+    embeddingModel: string;
+    embeddingDimension: number;
+    llmBaseUrl: string;
+    llmApiKey: string;
+    llmModel: string;
+    /** LLM / embedding HTTP 请求超时（毫秒，默认 30000）。超时即中止并按重试策略处理。*/
+    httpTimeoutMs?: number;
+    /** LLM / embedding 请求失败（网络错误/超时/5xx/429）时的最大重试次数（默认 2，即最多请求 3 次）。*/
+    httpMaxRetries?: number;
+    /** embedding 单次请求最多包含的文本条数，超出自动分批（默认 20）。*/
+    embeddingBatchSize?: number;
+    /** embedding 批次并发数（默认 2）。*/
+    embeddingConcurrency?: number;
+    sessionTokenLimit?: number;
+    historyWindowTokenLimit?: number;
+    topicRatio?: [number, number, number];
+    detailMaxTokens?: number;
+    summaryMaxTokens?: number;
+    conciseMaxTokens?: number;
+    maxConcurrentCompressions?: number;
+    entitySimilarityThreshold?: number;
+    defaultSearchLimit?: number;
+    /** 每次召回相当于多少毫秒的时间权重加成（默认 3_600_000 即 1 小时）*/
+    recallBoostMs?: number;
+    /** 切块策略，目前仅 "markdown-heading"（默认）*/
+    chunkStrategy?: "markdown-heading";
+    /** 单块 token 上限；标题块过长时按此二次切分（默认 800）*/
+    chunkMaxTokens?: number;
+    /** 块间重叠 token；标题切块默认不重叠（默认 0）*/
+    chunkOverlap?: number;
+    /** searchKnowledge 默认片段返回数（默认 8）*/
+    knowledgeTopK?: number;
+    /** 文档级粗召回候选文档数；设为 0 关闭粗召回直接全片段搜索（默认 5）*/
+    docCoarseTopK?: number;
+    /** addDocument 未传 buildGraph 时的默认值（默认 "auto"）*/
+    buildGraphDefault?: BuildGraphMode;
+    /**
+     * chunks 是否冗余存 userId/chatId/sessionId 三个 id：
+     * - true（默认）：chunks 行内冗余三 id，按域过滤一步到位
+     * - false：chunks 不冗余（存空串），过滤时先按域查 documents 取 docId 再过滤 chunks
+     */
+    chunkRedundantIds?: boolean;
+    /**
+     * auto 模式下，片段命中达到该相似度才触发知识图谱多跳扩展（默认 0.78）。
+     * 取值范围 0~1，cosine 相似度。
+     */
+    knowledgeGraphTriggerScore?: number;
+    /** 知识图谱实体向量检索返回的实体数（多跳扩展的候选锚点池，默认 10）*/
+    knowledgeGraphEntityTopK?: number;
+    /** 从候选实体中取前 K 个作为多跳扩展锚点（默认 3）*/
+    knowledgeGraphAnchorTopK?: number;
+    /** 每个锚点实体一跳扩展的最大关系数（默认 10）*/
+    knowledgeGraphHopLimit?: number;
+    /** 文档图谱构建时并发抽取片段数（默认 2）*/
+    graphExtractConcurrency?: number;
+    /** waitGraph=true 时等待图谱构建的整体超时（毫秒，默认 120000）*/
+    graphBuildTimeoutMs?: number;
+}
+interface ResolvedConfig extends Required<MemoryConfig> {
+}
+
+declare class MemoryManager {
+    private readonly config;
+    private readonly lance;
+    private readonly grafeo;
+    private readonly embed;
+    private readonly llm;
+    private readonly sessionCache;
+    private readonly factCache;
+    private readonly compressManager;
+    private readonly knowledgeManager;
+    private readonly sessionMap;
+    constructor(config: MemoryConfig);
+    init(): Promise<void>;
+    private restoreFromStorage;
+    updateChat(messages: RawMessage[], opts?: UpdateChatOptions): Promise<void>;
+    flushChat(sessionId?: string, opts?: {
+        wait?: boolean;
+        waitGraph?: boolean;
+    }): Promise<void>;
+    updateFacts(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
+    updateEntity(entities: Entity[], relations: Relation[], context?: UpdateEntityOptions): Promise<void>;
+    search(opts: SearchOptions): Promise<SearchResult[]>;
+    ask(opts: SearchOptions & {
+        maxChars?: number;
+        includeKnowledge?: boolean;
+    }): Promise<string>;
+    getFacts(level: FactLevel, id: string): Promise<string>;
+    /**
+     * 按层级语义取「上下文相关」的 facts 拼接字符串。
+     *
+     * scope 是层级包含的：user ⊃ chat ⊃ session。因此在某个 chat/session 上下文中，
+     * 既要看到该 chat 级的 facts，也要看到所属 user 级的 facts。
+     * 返回 user 级(userId) ∪ chat 级(chatId)，按时间正序拼接。
+     */
+    getFactsForContext(userId: string, chatId: string): Promise<string>;
+    getHistoryWindow(sessionId: string): string;
+    private buildLanceFilter;
+    private deserializeSession;
+    private serializeSession;
+    getRecentMessages(sessionId: string, limit: number): Promise<StoredMessage[]>;
+    getSession(sessionId: string): SessionView | null;
+    getSessionsByUserId(userId: string, opts?: {
+        limit?: number;
+    }): SessionView[];
+    getSessionsByChatId(chatId: string, opts?: {
+        limit?: number;
+    }): SessionView[];
+    searchSessions(opts: SessionSearchOptions): SessionView[];
+    updateSession(sessionId: string, opts: UpdateSessionOptions): Promise<SessionView | null>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    /** 概览统计：各类记忆数据的总量 */
+    stats(): Promise<{
+        sessions: number;
+        messages: number;
+        topics: number;
+        facts: number;
+        entities: number;
+        relations: number;
+        documents: number;
+        chunks: number;
+    }>;
+    /** 按天聚合最近 days 天的活跃趋势（概览图表用，含零值天）。days 默认 30，范围 1~365。 */
+    trend(days?: number): Promise<{
+        date: string;
+        sessions: number;
+        messages: number;
+        facts: number;
+    }[]>;
+    /** 列出会话，可选按 userId / chatId 过滤，按更新时间倒序 */
+    listSessions(filter?: {
+        userId?: string;
+        chatId?: string;
+    }): SessionView[];
+    /** 列出会话内的消息（按时间正序）*/
+    listMessages(sessionId: string, limit?: number): Promise<StoredMessage[]>;
+    /** 列出主题/摘要，可选按 sessionId / userId / chatId 过滤 */
+    listTopics(filter?: {
+        sessionId?: string;
+        userId?: string;
+        chatId?: string;
+    }): Promise<Topic[]>;
+    /**
+     * 列出事实，按创建时间倒序。过滤遵循 scope 层级包含语义：
+     * - 按 chatId 过滤时，除该 chat 级 facts 外，还包含该 chat 所属 user 的 user 级 facts
+     *   （user 级对其下所有 chat/session 生效）。
+     * - 按 userId 过滤时，返回该 user 名下全部 facts（两级都带 userId）。
+     * - level 过滤在层级过滤之后再叠加。
+     */
+    listFacts(filter?: {
+        level?: FactLevel;
+        userId?: string;
+        chatId?: string;
+    }): Fact[];
+    /** 由 chatId 反查所属 userId：优先用会话表映射，兜底用 chat 级 fact 自身。 */
+    private resolveChatOwner;
+    /** 手动新增一条事实 */
+    addFact(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
+    /** 删除单条事实，返回是否命中 */
+    deleteFact(factId: string): Promise<boolean>;
+    /** 列出全部实体（知识图谱节点）*/
+    listEntities(): Promise<Entity[]>;
+    /** 列出全部关系（知识图谱边）*/
+    listRelations(): Promise<Relation[]>;
+    /** 摄入一个文档（markdown）。document 落库即返回，切块/embedding/图谱后台执行（wait=true 可等待）。*/
+    addDocument(opts: AddDocumentOptions): Promise<{
+        docId: string;
+    }>;
+    /** 检索知识库片段，返回命中片段、涉及文档与图谱命中。*/
+    searchKnowledge(opts: KnowledgeSearchOptions): Promise<KnowledgeSearchResult>;
+    /** 获取文档（含原文）。*/
+    getDocument(docId: string): Promise<Document | null>;
+    /** 删除文档（级联删除其片段与知识图谱痕迹），返回是否命中。*/
+    deleteDocument(docId: string): Promise<boolean>;
+    /** 列出文档，可选按 userId / chatId / sessionId 过滤，按更新时间倒序。*/
+    listDocuments(filter?: {
+        userId?: string;
+        chatId?: string;
+        sessionId?: string;
+    }): Promise<Document[]>;
+    destroy(): void;
+}
+
+declare class LanceService {
+    private readonly config;
+    private conn;
+    private messagesTable;
+    private topicsTable;
+    private factsTable;
+    private sessionsTable;
+    private documentsTable;
+    private chunksTable;
+    private isNewMessagesTable;
+    private isNewSessionsTable;
+    private isNewDocumentsTable;
+    private isNewChunksTable;
+    constructor(config: ResolvedConfig);
+    init(): Promise<void>;
+    private ensureFtsIndexes;
+    /**
+     * 为存量 messages 表添加 parts 列（如果缺失）。
+     * LanceDB 0.14+ 支持 addColumns；旧版本会 throw，此时 rowToMessage 的 ?? "[]" 兜底。
+     */
+    private _ensurePartsColumn;
+    /**
+     * 为存量 topics 表添加 title 列（如果缺失）。
+     * 旧版本不支持 addColumns 时忽略，读取时 rowToTopic 的 ?? "" 兜底。
+     */
+    private _ensureTopicTitleColumn;
+    private ensureScalarIndex;
+    addMessages(messages: StoredMessage[]): Promise<void>;
+    addTopic(topic: Topic): Promise<void>;
+    updateTopicRecallCount(summaryId: string, count: number): Promise<void>;
+    getRecentTopics(chatId: string, userId: string, n1: number, n2: number, n3: number): Promise<{
+        detail: Topic[];
+        summary: Topic[];
+        concise: Topic[];
+    }>;
+    getMessagesSince(sessionId: string, since: number, limit?: number): Promise<StoredMessage[]>;
+    getLatestMessages(sessionId: string, limit: number): Promise<StoredMessage[]>;
+    searchMessages(vector: number[], filter?: string, limit?: number): Promise<Array<StoredMessage & {
+        _distance: number;
+    }>>;
+    hybridSearchMessages(query: string, vector: number[], filter?: string, limit?: number): Promise<StoredMessage[]>;
+    hybridSearchTopics(query: string, vector: number[], filter?: string, limit?: number): Promise<Topic[]>;
+    saveFact(fact: Fact): Promise<void>;
+    getAllFacts(): Promise<Fact[]>;
+    getAllSessionIds(): Promise<string[]>;
+    insertSession(session: Session): Promise<void>;
+    upsertSession(session: Session): Promise<void>;
+    getAllSessions(): Promise<Session[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    /** 全量读取 topics（管理面板列表用，不做 recall 加权排序，按 endTime 倒序）*/
+    getAllTopics(): Promise<Topic[]>;
+    /** 删除单条 fact */
+    deleteFact(factId: string): Promise<void>;
+    /** 删除某会话下的全部消息（级联删除会话时使用）*/
+    deleteMessagesBySession(sessionId: string): Promise<void>;
+    /** 删除某会话下的全部 topics（级联删除会话时使用）*/
+    deleteTopicsBySession(sessionId: string): Promise<void>;
+    /** 各表行数统计（概览卡片用）*/
+    countAll(): Promise<{
+        sessions: number;
+        messages: number;
+        topics: number;
+        facts: number;
+    }>;
+    /**
+     * 按天聚合最近 days 天的活跃趋势（概览图表用）。
+     * 返回连续日期序列（含无数据的零值天），按本地日期分桶。
+     */
+    trendDaily(days: number): Promise<{
+        date: string;
+        sessions: number;
+        messages: number;
+        facts: number;
+    }[]>;
+    addDocument(doc: Document): Promise<void>;
+    addChunks(chunks: Chunk[]): Promise<void>;
+    updateDocumentGraphFlag(docId: string, hasGraph: boolean): Promise<void>;
+    getDocument(docId: string): Promise<Document | null>;
+    /** 查找同域同 hash 的文档（去重用）*/
+    findDocumentByHash(contentHash: string, filter?: string): Promise<Document | null>;
+    /** 按域过滤返回 docId 列表（chunkRedundantIds=false 时用于 chunk 过滤）*/
+    getDocIdsByDomain(filter?: string): Promise<string[]>;
+    /** 文档级粗召回：对摘要向量做向量搜索，定位候选文档 */
+    searchDocuments(vector: number[], filter?: string, limit?: number): Promise<Array<Document & {
+        _distance: number;
+    }>>;
+    /** 知识片段混合检索（BM25 + 向量），失败回退纯向量 */
+    searchChunks(query: string, vector: number[], filter?: string, limit?: number): Promise<Chunk[]>;
+    deleteDocument(docId: string): Promise<void>;
+    deleteChunksByDoc(docId: string): Promise<void>;
+    /** 全量读取文档（管理面板用），按更新时间倒序 */
+    getAllDocuments(): Promise<Document[]>;
+    /** 知识库行数统计 */
+    countKnowledge(): Promise<{
+        documents: number;
+        chunks: number;
+    }>;
+    /**
+     * 根据 metadata 字段内容构建 SQL LIKE 过滤条件。
+     *
+     * metadata 以 JSON 字符串存储，此方法将键值对转换为 SQL LIKE 表达式，
+     * 可直接传给 searchMessages / hybridSearchTopics 的 filter 参数。
+     *
+     * 示例：buildMetadataFilter({ env: "prod", version: 2 })
+     *   → `metadata LIKE '%"env":"prod"%' AND metadata LIKE '%"version":2%'`
+     *
+     * 注意：仅适合简单标量值（字符串、数字、布尔）的精确匹配。
+     * 复杂嵌套对象或含空格的 JSON 值可能无法可靠匹配。
+     */
+    static buildMetadataFilter(conditions: Record<string, string | number | boolean>): string;
+}
+
+declare const DEFAULT_NODE_TYPES: readonly ["Person", "Group", "Organization", "Project", "Task", "Decision", "Plan", "Event", "Product", "Technology", "Data", "Document", "Topic", "Concept", "Preference", "Habit", "Goal", "Skill", "Attribute", "Value", "Status", "Time", "Location", "Resource", "Relationship"];
+declare const DEFAULT_RELATION_TYPES: readonly ["is_a", "part_of", "belongs_to", "contains", "has_member", "mentioned_in", "refers_to", "same_as", "alias_of", "related_to", "associated_with", "uses", "creates", "updates", "buys", "owns", "consumes", "works_on", "prefers", "likes", "dislikes", "interested_in", "favorite", "plans", "decides", "habit_of", "tends_to", "avoids", "skilled_in", "learning", "knows", "friends_with", "married_to", "parent_of", "child_of", "lives_with", "depends_on", "built_with", "integrates_with", "deployed_on", "inputs", "outputs", "trained_on", "predicts", "happens_at", "started_at", "ended_at", "affects", "causes", "leads_to", "improves", "reduces", "assigned_to", "executed_by", "blocks", "completes", "describes", "explains", "references"];
+type NodeType = (typeof DEFAULT_NODE_TYPES)[number];
+type RelationType = (typeof DEFAULT_RELATION_TYPES)[number];
+/** 图谱节点/边的来源标记：会话记忆 vs 知识库，用于隔离两类图谱 */
+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, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, LanceService, type MemoryConfig, MemoryManager, type MessageType, type NodeType, type RawMessage, type Relation, type RelationType, type SearchMode, type SearchOptions, type SearchResult, type SearchScope, type Session, type SessionEntry, type SessionSearchOptions, type SessionView, type StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions };