autosnippet
Version:
Extract code patterns into a knowledge base for AI coding assistants
181 lines (180 loc) • 6.92 kB
TypeScript
/**
* MemoryCoordinator — 记忆系统统一协调器
*
* 设计原则 (CoALA / MemGPT / Generative Agents / Mem0):
* - Single Coordinator: 所有记忆操作通过此模块路由
* - Budget-Aware Injection: 记忆注入受统一 token 预算管控
* - Extract-Update Write Path: 写入经去重/合并/冲突解决
* - Graceful Degradation: 任意子系统故障不影响核心执行
*
* 生命周期:
* - Bootstrap 模式: 会话级 (orchestrator 创建, 贯穿所有维度)
* - User Chat 模式: 实例级 (AgentRuntime 创建)
*
* @module MemoryCoordinator
*/
import { ActiveContext } from './ActiveContext.js';
import type { DimensionReportInput, SessionStore } from './SessionStore.js';
/** PersistentMemory 接口 (声明式) */
interface PersistentMemoryLike {
toPromptSection(opts: {
source?: string;
}): Promise<string> | string;
append(entry: {
type: string;
content: string;
source: string;
importance: number;
}): void;
}
/** ConversationStore 接口 (声明式) */
interface ConversationStoreLike {
load(conversationId: string, opts?: {
tokenBudget?: number;
}): unknown[];
summarize(conversationId: string, opts?: {
aiProvider?: unknown;
}): Promise<unknown>;
}
/** AiProvider 接口 (声明式) */
interface AiProviderLike {
[key: string]: unknown;
}
/** MemoryCoordinator 构造选项 */
export interface MemoryCoordinatorConfig {
persistentMemory?: PersistentMemoryLike | null;
sessionStore?: SessionStore | null;
conversationLog?: ConversationStoreLike | null;
mode?: 'user' | 'bootstrap';
totalMemoryBudget?: number;
}
/** 静态记忆 Prompt 选项 */
export interface StaticMemoryOptions {
mode?: 'user' | 'analyst' | 'producer';
taskContext?: string;
currentDimId?: string;
focusKeywords?: string[];
scopeId?: string;
}
/** 维度 scope 配置 */
export interface DimensionScopeConfig {
lightweight?: boolean;
maxRecentRounds?: number;
}
export declare class MemoryCoordinator {
#private;
_lastSurplus: number;
/**
* @param [config.persistentMemory] PersistentMemory 实例
* @param [config.sessionStore] SessionStore 实例 (bootstrap 模式)
* @param [config.conversationLog] ConversationStore 实例
* @param [config.totalMemoryBudget=4000] 记忆 section 的 token 总预算
*/
constructor(config?: MemoryCoordinatorConfig);
/**
* 配置总预算 (由 AgentRuntime.execute 入口调用)
* @param options.totalContextBudget 模型总上下文 token 数
*/
configure({ totalContextBudget, model }?: {
totalContextBudget?: number;
model?: string;
}): void;
/**
* 按模式分配预算
* @param [totalTokens] 覆盖总预算
*/
allocateBudget(mode: 'user' | 'analyst' | 'producer', totalTokens?: number): void;
getTotalBudget(): number;
getBudgetAllocation(): {
activeContext: number;
sessionStore: number;
persistentMemory: number;
conversationLog: number;
};
/**
* 获取消息缓冲区可用预算 (F2)
* @param totalContextBudget 模型总上下文 token
*/
getMessageBudget(totalContextBudget: number, systemPromptEstimate?: number, toolSchemaEstimate?: number, safetyMargin?: number): number;
/**
* 构建静态记忆 prompt (execute 入口调用一次)
* 包含: PersistentMemory + ConversationLog + SessionStore 上下文
*
* @param [options.mode] 'user' | 'analyst' | 'producer'
* @param [options.taskContext] 当前任务描述 (用于 relevance 打分)
* @param [options.currentDimId] 当前维度 (用于 SessionStore 过滤)
* @param [options.focusKeywords] 聚焦关键词
*/
buildStaticMemoryPrompt(options?: StaticMemoryOptions): Promise<string>;
/**
* 构建动态记忆 prompt (每轮调用)
* 包含: ActiveContext / WorkingMemory 上下文
*/
buildDynamicMemoryPrompt(options?: StaticMemoryOptions): string;
/** 合并构建完整记忆 prompt (便捷方法) */
buildMemoryPrompt(options?: StaticMemoryOptions): Promise<string>;
/**
* 记录工具调用观察 (合并 WM.observe + TRC.set)
* @param round 当前迭代轮次
* @param [cacheHit=false] 本次是否缓存命中
*/
recordObservation(toolName: string, args: Record<string, unknown>, result: unknown, round: number, cacheHit?: boolean): void;
/**
* 记录关键发现 (从 note_finding handler 调用)
* @param importance 1-10
* @param [scopeId] 显式指定 scope (并行安全)
* @returns 响应消息
*/
noteFinding(finding: string, evidence: string, importance: number, round: number, scopeId?: string): string;
/**
* 从对话中提取记忆
*
* 写入路由 (WriteRouter):
* - 规则 1: 只在 user 源触发规则匹配 (B4 fix)
* - 规则 2: [MEMORY] 标签提取 (所有源)
*
* @param prompt 用户输入
* @param reply AI 回复
*/
extractFromConversation(prompt: string, reply: string, source: 'user' | 'system'): void;
/** 获取缓存的工具结果 */
getCachedResult(toolName: string, args: Record<string, unknown>): unknown | null;
/** 缓存工具结果 */
cacheToolResult(toolName: string, args: Record<string, unknown>, result: unknown): void;
/**
* 创建维度作用域 (D2/D3: 多 scope 支持)
*
* @param scopeId 如 'api-patterns:analyst', 'api-patterns:producer'
* @param [config.lightweight=false] 轻量模式 (User Chat)
* @returns WorkingMemory (Phase 2) / ActiveContext (Phase 3)
*/
createDimensionScope(scopeId: string, config?: DimensionScopeConfig): ActiveContext;
/**
* 完成维度: 蒸馏 + 存储到 SessionStore
* @param [report] 附加报告数据
*/
completeDimension(scopeId: string, report?: DimensionReportInput): void;
/**
* 完成会话: 触发 Consolidator
* @returns |null>}
*/
completeSession(): Promise<{
consolidated: number;
} | null>;
/** 获取当前或指定 scope 的 ActiveContext / WorkingMemory */
getActiveContext(scopeId?: string): ActiveContext | null;
/** 获取 SessionStore */
getSessionStore(): SessionStore | null;
/** 获取 PersistentMemory */
getPersistentMemory(): PersistentMemoryLike | null;
/** 获取 ConversationLog / ConversationStore */
getConversationLog(): ConversationStoreLike | null;
/** 对话更新后触发自动摘要 */
onConversationUpdated(conversationId: string, aiProvider: AiProviderLike | null): Promise<void>;
/** 保存 checkpoint */
checkpoint(projectRoot: string): Promise<void>;
/** 恢复 checkpoint */
restore(projectRoot: string): Promise<boolean>;
dispose(): void;
}
export default MemoryCoordinator;