Context Engine：OpenClaw 的记忆架构

// src/memory/root-memory-files.ts
export const MEMORY_FILE_NAMES = ['MEMORY.md', 'memory.md'] // canonical + legacy

export function findMemoryFile(workspacePath: string): string | null {
  for (const name of MEMORY_FILE_NAMES) {
    const fullPath = path.join(workspacePath, name)
    if (fs.existsSync(fullPath)) return fullPath
  }
  return null
}

// Agent 在以下时机写入记忆：
// 1. 用户显式要求 "记住这个"
// 2. 用户纠正了 Agent 的行为（feedback 类型）
// 3. 发现了非显而易见的项目规则
// 4. 用户角色/偏好信息

// 记忆不应该存储的：
// - 代码结构（读文件就能得到）
// - Git 历史（git log 就能查到）
// - 临时任务状态（用 task list 跟踪）

// src/context-engine/index.ts
export interface ContextEngine {
  // 初始化：加载 MEMORY.md、系统指令等
  bootstrap(config: EngineConfig): Promise<void>

  // 摄入新内容（用户消息、工具结果）
  ingest(event: ContextEvent): Promise<void>

  // 核心方法：组装发送给 LLM 的完整 messages
  assemble(budget: TokenBudget): Promise<Message[]>

  // 压缩：当上下文接近预算上限时触发
  compact(): Promise<void>

  // 每轮结束后的维护（更新摘要、清理过期内容）
  maintain(): Promise<void>

  // 生命周期钩子
  afterTurn(turnResult: TurnResult): Promise<void>
}

async assemble(budget: TokenBudget): Promise<Message[]> {
  const messages: Message[] = []
  let tokensUsed = 0

  // 1. 系统指令（最高优先级，必须包含）
  const systemPrompt = this.buildSystemPrompt()
  messages.push({ role: 'system', content: systemPrompt })
  tokensUsed += countTokens(systemPrompt)

  // 2. MEMORY.md 索引（持久化记忆）
  const memoryContent = await this.loadMemoryIndex()
  if (memoryContent) {
    messages[0].content += `\n\n# Memory\n${memoryContent}`
    tokensUsed += countTokens(memoryContent)
  }

  // 3. 早期对话的压缩摘要（如果有）
  if (this.compressedSummary) {
    messages.push({ role: 'assistant', content: `[Earlier context]\n${this.compressedSummary}` })
    tokensUsed += countTokens(this.compressedSummary)
  }

  // 4. 近期对话（从最新往前填充，直到预算用完）
  const recentMessages = this.transcript.slice().reverse()
  const fittingMessages: Message[] = []

  for (const msg of recentMessages) {
    const msgTokens = countTokens(msg.content)
    if (tokensUsed + msgTokens > budget.maxTokens) break
    fittingMessages.unshift(msg)
    tokensUsed += msgTokens
  }

  messages.push(...fittingMessages)
  return messages
}

async compact(): Promise<void> {
  // 取出需要压缩的早期消息
  const cutoff = this.transcript.length - this.keepRecentCount
  const toCompress = this.transcript.slice(0, cutoff)

  // 用 LLM 生成摘要
  const summary = await this.llm.chat([
    { role: 'system', content: 'Summarize the key decisions, findings, and context from this conversation. Preserve actionable information.' },
    ...toCompress
  ])

  // 替换为摘要
  this.compressedSummary = summary.content
  this.transcript = this.transcript.slice(cutoff)
}

// src/context-engine/registry.ts
// 进程全局单例注册表，支持切换不同的 Context Engine 实现
class ContextEngineRegistry {
  private engines: Map<string, ContextEngineFactory> = new Map()
  private activeEngine: string = 'default'

  register(name: string, factory: ContextEngineFactory): void {
    this.engines.set(name, factory)
  }

  getActive(): ContextEngine {
    return this.engines.get(this.activeEngine)!.create()
  }
}

// 配置文件中选择策略
// config.plugins.slots.contextEngine = "legacy" | "semantic" | "custom"

// 默认 cron 配置：每天凌晨 3 点运行
dreaming:
  schedule: "0 3 * * *"
  phases: [light, deep, rem]
  maxDuration: 1800  // 最多运行 30 分钟

// 压缩时的标识符保留策略
compaction:
  identifierPreservation: "strict"  // 默认严格模式
  // strict: 文件路径、函数名、变量名、行号必须原样保留
  // relaxed: 只保留文件路径和函数名
  // none: 不做特殊保留（不推荐）

// src/sessions/index.ts
export interface Session {
  id: string                    // 唯一标识
  createdAt: Date
  lastActiveAt: Date
  transcript: TranscriptEvent[] // 完整事件记录
  config: SessionConfig         // 模型、级别等覆盖配置
}

// 传统方式：spawn sub-agent 做异步任务
// 问题：进程崩溃丢失状态、无法重试、无法观测

// GBrain 方式：Postgres 持久化 Job Queue
await minions.enqueue({
  type: 'consolidate_memory',
  payload: { pageId: 'tech-preferences', newEvidence: '...' },
  retries: 3,
  timeout: 60_000
})