@x-otto/memory 0.0.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,1117 @@
+import { Message } from "@x-otto/ai";
+
+//#region src/types.d.ts
+/**
+ * 触发阈值的三种表达。
+ * - `['tokens', n]`   绝对 token 数。
+ * - `['fraction', f]` 占窗口比例(显式覆盖逃生口；不再是默认压缩触发)。
+ * - `['headroom', h]` 绝对留白:阈值 = max(安全下界, window − h)。默认压缩触发用此——
+ *   自适应窗口大小(小窗早压防溢出、大窗晚压省成本)。
+ */
+type ContextSize = ['tokens', number] | ['fraction', number] | ['headroom', number];
+type StorageType = 'file' | 'http' | 'memory';
+interface MemorySource {
+  path: string;
+  writable: boolean;
+}
+interface MemoryStore {
+  load(sources: MemorySource[]): Promise<Map<string, string>>;
+  /**
+   * 写入一份记忆文件。**远端同步的延迟语义按实现分化**（终局审查 2026-07-18 显式声明）：
+   * `HttpMemoryStore` 对 user-scope 路径是本地写完即 resolve（远端 fire-and-forget，
+   * 不阻塞、静默降级），对 workspace-scope 路径则 await 远端写入（D6 冲突检测的
+   * onConflict 回调需要与 write() resolve 同步可见）——调用方不应假设 resolve 时
+   * 远端一定已同步。纯本地实现（FileSystemMemoryStore）resolve 即落盘完成。
+   */
+  write(path: string, content: string): Promise<void>;
+  watch?(sources: MemorySource[], onChange: (path: string) => void): () => void;
+}
+interface PruneConfig {
+  trigger: ContextSize;
+  protect: ContextSize;
+  minimum: number;
+  /**
+   * 可再生工具允许列表(fail-closed)。**仅**裁此列表内工具的 tool_result;
+   * 列表外(未知/MCP/agent 产物/一次性快照如 capture_file_state)默认保留——其输出不可廉价重生,
+   * 裁掉=真实信息损失。空列表 = 不裁任何 tool_result。
+   */
+  regenerableTools: string[];
+  /** 二次保护:即便在 regenerableTools 内,列入此处的工具仍不裁(覆盖)。 */
+  protectedTools: string[];
+  truncateTools: string[];
+  truncateMaxLength: number;
+}
+interface PruneResult {
+  messages: Message[];
+  prunedCount: number;
+  tokensSaved: number;
+  changed: boolean;
+}
+interface CompactionConfig {
+  enabled: boolean;
+  trigger: ContextSize;
+  keepRecent: ContextSize;
+  /**
+   * RFC-321 M6：生效上下文窗口（token），供 `compact()` 做**压缩输入窗口预检**——
+   * 待摘要文本超 `窗口 × MEMORY_COMPACTION_INPUT_WINDOW_FRACTION` 时改走分批归约
+   * （map-reduce），避免单个超长 prompt 直接 413 导致摘要产不出（底线2 机制保证）。
+   * 由 `MemoryManager.compact()` 从 `effectiveContextWindow()` 注入；未提供时退回
+   * 单批行为（向后兼容）。
+   */
+  contextWindow?: number;
+  reserveTokens: number;
+  /**
+   * 压缩 total 口径硬顶占窗口比例（RFC-066 增量修复，事故 f9bab4c0）。不设则用
+   * MEMORY_COMPACTION_HARD_CEILING_FRACTION 默认（0.90，可经 env 覆盖）。config/api option
+   * 层显式覆盖点——宿主可按模型/场景定制硬顶余量。
+   */
+  hardCeilingFraction?: number;
+  /**
+   * RFC-324 D3：摘要覆盖率 warning 阈值。coverage 低于此值时，下次压缩调大批次上限
+   * （每批更小源内容 → 提高覆盖率）。缺省 `MEMORY_COVERAGE_WARN_THRESHOLD`（0.7）。
+   * 由宿主从 `.otto/config.json` 的 `residency.coverage_warn_threshold` 注入。
+   */
+  coverageWarnThreshold?: number;
+  /**
+   * RFC-324 D3：摘要覆盖率 error 阈值。coverage 低于此值时记 warn 日志并**双重**调大
+   * 批次上限（更激进的质量保护）。缺省 `MEMORY_COVERAGE_ERROR_THRESHOLD`（0.5）。
+   * 必须 ≤ warn 阈值，否则 error 分支永不可达（接线层已做钳制）。
+   */
+  coverageErrorThreshold?: number;
+  /**
+   * RFC-340 D1：摘要覆盖率**硬下限**。低于此值时 `MemoryManager.process()` 不建立
+   * 压缩边界（视同本轮压缩未发生），阻断"摘要未覆盖的历史被 `capStoredHistory`
+   * 当作死历史物理删除"这条不可逆损失路径。缺省 `MEMORY_COVERAGE_FLOOR_THRESHOLD`（0.3）。
+   *
+   * 不变式 `floor ≤ error ≤ warn`——floor 是叠加在既有 warn/error 递推之上的**新档位**，
+   * 不替换它们（RFC-340 规则 4）。接线层负责钳制，防配置写反导致档位失效。
+   */
+  coverageFloorThreshold?: number;
+  customInstructions?: string;
+}
+interface CutPoint {
+  firstKeptIndex: number;
+  turnStartIndex: number;
+  isSplitTurn: boolean;
+}
+interface CompactionPreparation {
+  messagesToSummarize: Message[];
+  turnPrefixMessages: Message[];
+  preservedMessages: Message[];
+  isSplitTurn: boolean;
+  tokensBefore: number;
+  previousSummary?: string;
+  fileOps: {
+    read: string[];
+    modified: string[];
+  };
+}
+interface CompactionResult {
+  summary: string;
+  firstKeptIndex: number;
+  tokensBefore: number;
+  archivePath?: string;
+  /**
+   * RFC-340 D1：摘要覆盖率 = 真实喂入摘要器的字符量 ÷ 源字符量。单批路径恒为 1
+   * （全量喂入）；map-reduce 路径为实算值（截断导致 <1）。
+   *
+   * **纯上报，compaction 层不据此决策**——判定归 `MemoryManager.compact()`（策略与
+   * 执行分离）：低于 floor 时给摘要正文前置低保真标注（`buildLowCoverageNotice`），
+   * 边界照常建立。标注本身进摘要正文（对模型可见），故不需要平行的布尔标志位——
+   * 终局复审（2026-08-10）删除了首版的 `coverageDegraded` 字段：零消费方的 write-only
+   * 状态位是形式化包装，可观测性已由 warn 日志 + 摘要文本承载。
+   */
+  coverage: number;
+}
+interface ArchiveStorage {
+  readonly type: StorageType;
+  archive(sessionId: string, messages: Message[], summary: string): Promise<string>;
+  read(archivePath: string): Promise<string>;
+  list(sessionId: string): Promise<ArchiveEntry[]>;
+  /**
+   * 会话销毁时驱逐其归档数据（可选——仅内存态实现如 InMemoryArchiveStorage 需要，
+   * 落盘/远程实现天然无需随进程内 session 生命周期清理）。MemoryManager.forgetSession
+   * 无条件调用（缺省时 no-op），防内存态实现在长跑进程中无界增长。
+   */
+  forgetSession?(sessionId: string): void;
+}
+interface ArchiveEntry {
+  path: string;
+  timestamp: number;
+  messageCount: number;
+  summary: string;
+}
+/**
+ * MemoryManager 读取会话条目的最小契约——避免 @x-otto/memory 依赖
+ * @x-otto/session。实现侧(RelationalSessionPersistence / SqliteSessionRepository)满足此形。
+ */
+interface MinimalEntry {
+  readonly type: 'message' | 'compaction' | 'clear';
+  /** 插入序(seq),用于排序;缺省时按负载时间戳回落。 */
+  readonly seq?: number;
+  readonly data: unknown;
+}
+/** 从会话条目中提取 Message(供 formatArchive 重建归档)。 */
+type MessageFromEntry = (entry: MinimalEntry) => Message | null;
+interface ContextTokenEstimate {
+  total: number;
+  fromUsage: number;
+  fromEstimate: number;
+  lastUsageIndex: number;
+  /**
+   * 稳定系统前缀的派生 token 数(system prompt + tool schemas + memory 注入)。
+   * 这些不在 `messages` 数组里(provider 层单独注入)，但被 provider 的 usage 计入——故
+   * = `fromUsage − (usage 覆盖区间内消息的纯估算)`。无 usage 时为 0。
+   */
+  derivedPrefix: number;
+  /**
+   * BodyAfterPrefix 触发口径 = `total − derivedPrefix`。压缩/prune 软触发以此为准，
+   * 使大的稳定缓存前缀不把上下文管理提前顶过阈值(减压缩频次 = provider 无关的缓存收益)。
+   */
+  bodyAfterPrefix: number;
+}
+interface MemoryManagerConfig {
+  sources?: MemorySource[];
+  memoryStore?: MemoryStore;
+  compaction?: Partial<CompactionConfig>;
+  prune?: Partial<PruneConfig>;
+  /** @deprecated archive = session 派生视图;此字段仅作 InMemory 回退(无 session entries 时)。 */
+  archiveStorage?: ArchiveStorage;
+  /**
+   * 从 session entries 按 sessionId 加载条目的委托。
+   * MemoryManager 用此按需重建 archive(compact 间 messages 还原),替代独立 archive persistence。
+   * 未注入时回退到 archiveStorage(InMemory)。实现侧在 App 接线,惰性绕开「session persistence 在 memory 之后构建」时序。
+   */
+  loadSessionEntries?: (sessionId: string) => Promise<MinimalEntry[]>;
+  /**
+   * 从 MinimalEntry.data 中提取 Message(供 formatArchive)。
+   * 实现侧简单:message entries 的 data = Message。注入以避免 @x-otto/memory 依赖 @x-otto/ai Message 类型。
+   */
+  messageFromEntry?: MessageFromEntry;
+  summarize: (prompt: string, options?: {
+    maxTokens?: number;
+    signal?: AbortSignal;
+  }) => Promise<string>;
+  estimateTokens?: (text: string) => number;
+  model?: {
+    contextWindow: number;
+    maxOutput: number;
+  };
+  /**
+   * **惰性**上下文窗口解析器,每次触发判定时调用,使 prune/compaction 阈值
+   * 始终跟随当前生效模型。解决"构造期 model 未知(惰性解析)→ contextWindow 落 200K 默认 +
+   * reconfigure 未接线 → DeepSeek 1M 被当 200K、compaction 在真实容量 ~17% 就过早触发"的 bug。
+   * 返回 undefined(模型仍未定)时回退构造期 contextWindow。优先级高于 reconfigure 写入值。
+   */
+  getContextWindow?: () => number | undefined;
+  /**
+   * 会话消息内容字节估算预算（RFC-178 触发器 B 软段，同 `@x-otto/session-contract` 的
+   * `SESSION_MAX_CONTENT_BYTES`，调用方注入——本包不直接依赖 session-contract，对齐
+   * `messageFromEntry`/`getContextWindow` 等既有"实现侧注入避免跨包依赖"模式）。
+   * 用于 `needsCompaction` 的字节触发因子：估算字节逼近预算（×0.9）时提前强制压缩，
+   * 确保字节维度的存储层收紧（`capStoredHistoryByBytes`）触发时压缩边界必然已存在。
+   * 未注入或 `getEstimatedBytes` 缺席时不启用该因子（向后兼容）。
+   */
+  maxContentBytes?: number;
+  /**
+   * RFC-321 M3：**生效**字节预算的惰性读数（覆盖 `maxContentBytes` 静态值）。
+   *
+   * 存在理由：`ResidencyGovernor`（RFC-178 触发器 C）在内存压力 warning/critical 时把
+   * 驻留层的字节 cap 除以 2/4，但 memory 侧的压缩触发阈值此前是**构造期注入的静态值**，
+   * 无 reconfigure 通路——实测 critical 档下驻留层 cap 已收紧、而 `needsCompaction` 仍
+   * 按全值判定，导致「cap 触发时压缩边界必然已存在」的不变式在压力档结构性失效
+   * （而压力档恰是最需要它成立的时刻）。
+   *
+   * 注入后两侧读同一个有效值，收紧同步生效。缺省时回退 `maxContentBytes`（向后兼容）。
+   * 模式对齐同文件的 `getContextWindow`/`getEstimatedBytes`（实现侧注入避免跨包依赖）。
+   */
+  getMaxContentBytes?: () => number | undefined;
+  /**
+   * RFC-324 D3：摘要覆盖率阈值的惰性读数。
+   *
+   * 必须是 getter 而非静态值——`compactionConfig` 在构造期/`reconfigure` 时快照，
+   * 而宿主 settings 在 App 构造**之后**才 load，静态传值会永远读到 undefined
+   * （这正是此前 `coverage_*` 配置零消费的成因之一）。模式对齐同文件的
+   * `getContextWindow`/`getMaxContentBytes`。
+   */
+  getCoverageThresholds?: () => {
+    warn?: number;
+    error?: number;
+    floor?: number;
+  } | undefined;
+  /**
+   * 当前会话消息字节估算读数（RFC-178：`InMemorySession.estimatedContentBytes` 的惰性
+   * 读取器，跟随活跃会话）。与 `maxContentBytes` 配对注入，缺一不启用字节因子。
+   */
+  getEstimatedBytes?: () => number | undefined;
+}
+interface MemoryDefaults {
+  compaction: CompactionConfig;
+  prune: PruneConfig;
+}
+//#endregion
+//#region src/memory-manager.d.ts
+declare class MemoryManager {
+  private readonly persistent;
+  /**
+   * archive = session 派生视图——loadSessionEntries 就位时走 session 条目的
+   * compaction 边界间重建;未就位(无持久化/V 形态)时回退到 archiveStorage(InMemory)。
+   */
+  private readonly archiveStorage;
+  private readonly loadSessionEntries?;
+  private readonly messageFromEntry?;
+  private readonly summarize;
+  private readonly estimateTokens;
+  /** 构造时保留原始配置副本，供 reconfigure 用新窗口重算阈值。 */
+  private readonly rawConfig;
+  private contextWindow;
+  /** 惰性窗口解析器(跟随生效模型),优先于 this.contextWindow。 */
+  private readonly getContextWindow?;
+  private compactionConfig;
+  private pruneConfig;
+  /** 会话消息字节估算预算（RFC-178 字节触发因子；RFC-321 M2 后是唯一的非 token 触发因子）。 */
+  private readonly maxContentBytes?;
+  /** RFC-321 M3：生效字节预算惰性读数（跟随 ResidencyGovernor 收紧档位）。 */
+  private readonly getMaxContentBytes?;
+  private readonly getEstimatedBytes?;
+  private readonly previousSummaries;
+  /** archive Path 单调发号——每会话内独立(archive:{sessionId}:{1..N})。 */
+  private readonly archiveIdCounter;
+  /**
+   * 终局架构 review 建议优化项：并发 process() 门闩（per-session）。
+   *
+   * 单进程事件循环下 JS 无 TOCTOU（check-then-act 之间不会被抢占），但若同一 sessionId
+   * 的两次 process() 调用在 await LLM 压缩（compact()）期间交错（如同一会话被两个不同
+   * 入口几乎同时触发 process，例如 work-loop 的常规压缩检查与用户手动 /compact 命令
+   * 撞车），后调用者会基于前调用者压缩前的旧快照重复生成摘要，产生冗余/冲突的
+   * previousSummaries 写入。此 flag 在 compact() 的 await 期间挡住同 session 的重入，
+   * 后来者直接跳过本轮压缩（下一次 needsCompaction 判定仍会触发，不丢失压缩机会，只是
+   * 延后一轮），finally 保证异常路径也会复位。
+   */
+  private readonly compactionInFlight;
+  constructor(config: MemoryManagerConfig);
+  /**
+   * `/clear`——驱逐本会话的滚动压缩摘要桶（L2 工作记忆）。L1 持久知识(persistent)
+   * 与 L3 归档(archiveStorage)不动。无 sessionId 走 __default__ 桶（单会话场景）。
+   */
+  clearSession(sessionId?: string): void;
+  /**
+   * 审计修复:会话销毁/驱逐时遗忘其全部 per-session 状态——防三个 Map 在长跑进程中无界增长。
+   * 与 clearSession 不同:此处清 archiveIdCounter(会话终态,无再压缩可能)。
+   */
+  forgetSession(sessionId: string): void;
+  /**
+   * 模型切换时更新上下文窗口 + 重算 compaction/prune 触发阈值。
+   * 调用后 needsCompaction/needsPrune 基于新窗口判定。
+   */
+  reconfigure(model: {
+    contextWindow: number;
+    maxOutput: number;
+  }): void;
+  /**
+   * 生效上下文窗口——优先惰性解析器(跟随当前模型),回退构造期/ reconfigure 值。
+   * prune/compaction 一切触发线均按此计算,避免构造期 model 未知导致的 200K 默认锁死。
+   */
+  private effectiveContextWindow;
+  /**
+   * 主动检查当前消息量是否超过压缩触发线（基于 reconfigure 后的新窗口）；
+   * 超过则 force-compact。用于模型切换时预防下一轮 413。
+   */
+  ensureFitsWindow(messages: readonly Message[], sessionId?: string, signal?: AbortSignal): Promise<{
+    messages: Message[];
+    compacted: boolean;
+    summary?: string;
+    replacement?: Message[];
+  }>;
+  loadMemory(): Promise<void>;
+  getMemoryPrompt(): string;
+  reloadMemory(): Promise<void>;
+  getMemories(): ReadonlyMap<string, string>;
+  needsPrune(messages: readonly Message[]): boolean;
+  /** 估算复用变体（终局审查 2026-07-18：process() 一次估算供判定+执行两处消费，
+   *  消除同批消息的重复全量遍历——WeakMap 缓存对 spread 新建的消息数组会穿透）。 */
+  private needsPruneWith;
+  prune(messages: readonly Message[], force?: boolean): PruneResult;
+  private pruneWith;
+  needsCompaction(messages: readonly Message[]): boolean;
+  /**
+   * 驻留（字节）维度是否已逼近预算——`needsCompaction` 的非 token 触发因子。
+   *
+   * 单独抽出的原因（RFC-321 R10，二轮实证）：字节因子与已删除的条数因子**同型死区**——
+   * 判定为真不代表切得动。`findCutPoint` 要求总 token ≥ keepRecent（窗口×0.1），大窗口下
+   * 「字节超预算但总 token 偏小」的形态（如少量大附件）会让 `prepareCompaction` 返回 null，
+   * 压缩静默不发生（实证：1M 窗口、200 条 × 1000 字符、字节因子触发 → compacted=false、
+   * LLM 调用 0）。故 `process()` 在**由驻留压力驱动**时同样启用 keepRecent 钳制，与
+   * 逃生阀 force 路径共用同一修法。
+   */
+  private residencyPressure;
+  isEligibleForManualCompact(messages: readonly Message[]): boolean;
+  /**
+   * @param options.force RFC-321 R10：强制压缩语义下 keepRecent 钳制到当前总量一半，
+   *   使"总 token < keepRecent"的超短会话也能切出边界（否则 force 仍被切点约束挡住、
+   *   压缩静默不发生）。详见 `compaction.ts` 的 prepareCompaction 内注释。
+   */
+  prepareCompaction(messages: readonly Message[], sessionId?: string, options?: {
+    force?: boolean;
+  }): CompactionPreparation | null;
+  compact(preparation: CompactionPreparation, sessionId?: string, signal?: AbortSignal): Promise<CompactionResult>;
+  /**
+   * 压缩归档单源（reused B1 缓存命中 / fresh LLM 压缩两路共用，memory-1 去重）：递增 per-session
+   * 归档序号 → 赋逻辑 `archive:<sessionId>:<idx>` → 仅当无 loadSessionEntries 重建器时落盘
+   * （有重建器则归档按需从会话条目还原，archivePath 只作逻辑引用）。
+   */
+  private recordCompactionArchive;
+  process(messages: readonly Message[], sessionId?: string, signal?: AbortSignal, options?: {
+    force?: boolean;
+    skipPrune?: boolean;
+  }): Promise<{
+    messages: Message[];
+    summary?: string;
+    archivePath?: string;
+    pruned: boolean;
+    compacted: boolean;
+    replacement?: Message[];
+    pruneMetrics?: {
+      prunedCount: number;
+      tokensSaved: number;
+      messagesBefore: number;
+      messagesAfter: number;
+    };
+  }>;
+  listArchives(sessionId: string): Promise<ArchiveEntry[]>;
+  /** 从 session entries 的 compaction 节点枚举 ArchiveEntry 列表。 */
+  private listArchivesFromEntries;
+  readArchive(archivePath: string): Promise<string>;
+  /** 从 session entries 的 compaction 边界间重建归档全文。 */
+  private readArchiveFromEntries;
+  dispose(): void;
+}
+declare function createMemoryManager(config: MemoryManagerConfig): MemoryManager;
+//#endregion
+//#region src/persistent-memory.d.ts
+declare const DEFAULT_MEMORY_SOURCES: MemorySource[];
+declare class PersistentMemory {
+  private readonly store;
+  private readonly sources;
+  private memories;
+  private unwatch?;
+  constructor(store: MemoryStore, sources?: MemorySource[]);
+  load(): Promise<void>;
+  reload(): Promise<void>;
+  getInjection(): string;
+  getMemories(): ReadonlyMap<string, string>;
+  /**
+   * 写入可写源（M13-03）：让 MemorySource.writable 标记成真。
+   * 仅 sources 中声明且 writable: true 的路径可写；写后同步内存缓存（无需全量 reload）。
+   */
+  write(sourcePath: string, content: string): Promise<void>;
+  watching(): void;
+  stop(): void;
+  dispose(): void;
+}
+declare class InMemoryMemoryStore implements MemoryStore {
+  private data;
+  set(path: string, content: string): void;
+  load(sources: MemorySource[]): Promise<Map<string, string>>;
+  write(path: string, content: string): Promise<void>;
+}
+declare class FileSystemMemoryStore implements MemoryStore {
+  private cwd;
+  /**
+   * `~/` 前缀路径展开的用户主目录 override（缺省调用真实 `os.homedir()`）。
+   *
+   * **测试隔离缺陷修复**（终局 memory 审计发现的持续污染源）：此前 `resolvePath()` 硬编码
+   * 调用 `homedir()`，完全忽略构造函数传入的 `cwd`——测试传 `localDir: TEST_DIR` 只对不带
+   * `~/` 前缀的相对路径生效，但 `DEFAULT_MEMORY_SOURCES`/测试用例大量使用 `~/.otto/AGENTS.md`
+   * 这类带 `~/` 前缀的路径，一律写穿到真实用户主目录（`http-memory-store.test.ts` 的
+   * "remote user"/"memory index content" 等 fixture 字符串因此持续覆盖真实 `~/.otto/AGENTS.md`）。
+   * 生产环境不传时行为完全不变（仍用真实 `homedir()`），仅测试可注入隔离目录。
+   */
+  private readonly homeDirOverride?;
+  constructor(cwd?: string, homeDirOverride?: string);
+  load(sources: MemorySource[]): Promise<Map<string, string>>;
+  write(path: string, content: string): Promise<void>;
+  private resolvePath;
+}
+//#endregion
+//#region src/http-memory-store.d.ts
+/**
+ * M71c + RFC-164 M164-2: 远端 user 级 / workspace 级 memory 的 HTTP MemoryStore。
+ *
+ * 对 user 源（~/.otto/AGENTS.md 等）走远端 HTTP 读/写，project 源走本地文件系统；
+ * R 形态 opt-in 后 workspace 源（./.otto/MEMORY.md 等）同样走远端（M164-2 新增）。
+ * - 读：HTTP GET → 缓存本地 → 返回；远端不可达时回退本地缓存（R5 降级）
+ * - 写：本地缓存先写，再 fire-and-forget 推远端（R5 降级：远端不可达不阻塞）
+ *
+ * 远端 key：
+ * - user-scope = `user:<userId>:<相对 ~/.otto/ 的文件路径>`（如 AGENTS.md/MEMORY.md/memory/foo.md）。
+ * - workspace-scope（M164-2）= `workspace:<userId>:<workspaceKey>:<相对 workspace 根的文件路径>`
+ *   （`userId` 仍是安全边界，`workspaceKey` 是同用户下的项目分区，见 `entity-route.ts` 设计记录）。
+ *
+ * **惰性 getter 而非构造期快照**（RFC-164 M164-2 摸底阶段发现的时序断层修正）：
+ * `workspaceKey`/`isWorkspaceSyncEnabled` 均为函数，每次 `load()`/`write()` 才实时求值——
+ * `HttpMemoryStore` 从始至终只构造一次（App 构造期），但是否真的走远端由每次 I/O 时的
+ * 当前状态决定，不在构造期"决定死"。`workspaceRef`（携带这两个字段的来源）要到 `start()`
+ * 才异步解析完成，构造期读不到；惰性 getter 与本仓 `getWorkspaceKey: () => this.workspaceRef?.key`
+ * （`app.ts:718`）同一模式。
+ */
+declare class HttpMemoryStore implements MemoryStore {
+  private readonly baseUrl;
+  /** user-scope 路径的用户身份——M164-2 改为可选：R 形态可能没有 userIdentity（未登录），
+   *  此时 user-scope 路径优雅降级为本地（不抛错），workspace-scope 路径不受影响。 */
+  private readonly userId?;
+  private readonly workspaceKeyGetter?;
+  private readonly isWorkspaceSyncEnabled;
+  private readonly getAuth;
+  private readonly fetchImpl;
+  private readonly timeoutMs;
+  private readonly local;
+  /** 冲突发生时的可选通知回调（RFC-164 M164-2 子agent评审F3）——app 层接线 TUI toast。 */
+  private readonly onConflict?;
+  /** 每个 path 的冲突环形缓冲计数器（进程内存,不持久化——仅用于槽位轮转,不影响正确性）。 */
+  private readonly conflictCounters;
+  /** 每个远端 path 的已知版本号（简单单调计数器,进程内存）——PUT 时携带,供服务端判定冲突。 */
+  private readonly knownVersions;
+  constructor(options: {
+    /** 远端服务器 base URL（不尾斜线）。 */baseUrl: string; /** 获取 Bearer token 的工厂。 */
+    getAuth: () => Promise<{
+      token: string;
+    }>; /** fetch 实现。 */
+    fetch: typeof globalThis.fetch; /** 请求超时 (ms)。 */
+    timeoutMs: number; /** 当前用户 identity id（可选——R 形态可能未登录）。 */
+    userId?: string;
+    /**
+     * workspace key 的惰性 getter（R 形态 opt-in 时使用）。缺省时 workspace-scope 路径
+     * 恒判定为不可用（降级本地），与 `isWorkspaceSyncEnabled` 缺省行为一致。
+     */
+    workspaceKey?: () => string | undefined;
+    /**
+     * workspace 记忆远端同步是否已 opt-in 的惰性 getter（RFC-164 D2）。每次 I/O 时才求值——
+     * 不在构造期决定,而是随 `workspaceRef.memorySyncEnabled` 的当前值实时判定。
+     * 缺省 = 恒 `false`（向后兼容,user-only 场景不受影响）。
+     */
+    isWorkspaceSyncEnabled?: () => boolean; /** 本地缓存根目录（传给 FileSystemMemoryStore 的 cwd）；缺省 process.cwd()。 */
+    localDir?: string;
+    /**
+     * `~/` 前缀路径展开的用户主目录 override（透传给内部 `FileSystemMemoryStore`，仅测试
+     * 使用——见 `FileSystemMemoryStore.homeDirOverride` 注释：修复持续写污染真实
+     * `~/.otto/` 的测试隔离缺陷）。生产环境不传，行为不变。
+     */
+    homeDirOverride?: string; /** 冲突检测到时的通知回调（可选）。 */
+    onConflict?: (path: string, conflictPath: string) => void;
+  });
+  load(sources: MemorySource[]): Promise<Map<string, string>>;
+  write(path: string, content: string): Promise<void>;
+  watch?(_sources: MemorySource[], _onChange: (path: string) => void): () => void;
+  /** workspace-scope 判定：路径形如 workspace 根下的 `.otto/` 文件（非 `~/.otto/`）且 opt-in 已启用。 */
+  private isWorkspaceSourceEnabled;
+  private remoteKey;
+  /**
+   * 新路由 `/memory/user/:resourceId` 的 resourceId——文件相对路径（如 `AGENTS.md`/
+   * `MEMORY.md`/`memory/foo.md`）本身。多个不同 path 各自映射独立 resourceId，
+   * 避免固定单一 key 导致的跨文件覆盖（RFC-108 D1 修正）。
+   */
+  private remoteResourceId;
+  /** workspace-scope resourceId——相对 workspace 根的路径（如 `.otto/MEMORY.md` → `MEMORY.md`）。 */
+  private workspaceResourceId;
+  /** 远端 GET(user-scope) → { content: string } | null (网络/404均返回 null) */
+  private loadRemoteUser;
+  /** 远端 PUT(user-scope)（best-effort, 失败静默——R5） */
+  private writeRemoteUser;
+  /** 远端 GET(workspace-scope) → { content: string } | null (网络/404均返回 null) */
+  private loadRemoteWorkspace;
+  /**
+   * 远端 PUT(workspace-scope)（best-effort, 失败静默——R5）。
+   * D6 冲突检测：携带客户端已知版本号；服务端返回 409（版本不匹配）时，不覆盖，
+   * 转存为环形缓冲冲突旁路文件。
+   */
+  private writeRemoteWorkspace;
+  /** 环形缓冲冲突旁路文件——`<path>.conflict-<slot>`，slot 循环覆盖（M164-2 D6 实现简化）。 */
+  private writeConflictSidecar;
+}
+//#endregion
+//#region src/overlay-memory-store.d.ts
+/**
+ * RFC-345 影子模式：MemoryStore 的 overlay 包装（读穿透 base、写只进内存）。
+ *
+ * 语义（对齐 Chromium OverlayUserPrefStore + MCP token store 的 overlay）：
+ * - write：只写内存 Map，绝不落盘/不触发远端同步；
+ * - load：内存 overlay 命中优先（保证"本会话内 record 后 memory_read 读得到"，
+ *   即写后读正确性），未命中回退 base（继承磁盘/远端既有记忆，可注入 prompt）。
+ *
+ * 为何是 overlay 而非"write no-op"：AutoMemory 的索引（this.index）确实是内存真源，
+ * 但 memory_read → readEntry → store.load(entryPath) 读的是**条目文件内容**。若 write
+ * 纯 no-op，条目文件从未进任何存储，同会话内 record 后 read 该条目会落空。overlay 让
+ * 写入的条目留在内存 Map 里，load 优先命中，写后读因此成立（RFC-345 §D3）。
+ *
+ * 由 §D1 白名单装配点（storage-wiring.buildMemoryStore）在影子态包装 base store。
+ * watch 不转发——影子会话不监听外部记忆变更（与 AuthStore overlay 关 watch 同理）。
+ */
+declare function createOverlayMemoryStore(base: MemoryStore): MemoryStore;
+//#endregion
+//#region src/agents-discovery.d.ts
+interface AgentsDiscoveryOptions {
+  /** 文件名，默认 'AGENTS.md'。 */
+  fileName?: string;
+  /** 项目根标记，遇到即停（含该层），默认 ['.git']。 */
+  rootMarkers?: string[];
+  /** 向上层数硬上限（防符号链接环 / 异常深路径），默认 25。 */
+  maxDepth?: number;
+  /** 收集文件数上限，超出保留最靠近 cwd 的（更相关），默认 10。 */
+  maxFiles?: number;
+  /** 单文件字节上限，超出跳过（防巨型文件撑爆上下文），默认 64KiB。 */
+  maxFileBytes?: number;
+}
+/**
+ * 从 startDir 向上发现 AGENTS.md，返回 root→cwd 顺序的只读 MemorySource（绝对路径）。
+ */
+declare function discoverAgentsSources(startDir: string, opts?: AgentsDiscoveryOptions): MemorySource[];
+//#endregion
+//#region src/auto-memory.d.ts
+/**
+ * AutoMemory（M13-03）：可写的跨会话记忆。
+ *
+ * 约定（progressive disclosure）：
+ * - `<baseDir>/MEMORY.md` —— 索引，一行一条目指针（`- [name](memory/<slug>.md) — hook`）。
+ *   每会话仅注入索引，控制 token 占用。
+ * - `<baseDir>/memory/<slug>.md` —— 单事实条目全文，按需经 `read(name)` 读取。
+ *
+ * 存储经 `MemoryStore` 抽象（FileSystemMemoryStore / HttpMemoryStore / InMemory 同构），
+ * 即本地与 remote 双后端天然同源（M13 目标）。
+ *
+ * 并发边界（已知设计）：索引为单文件 last-write-wins，单写者假设
+ * （app 级单实例持有）；多实例并发 record 同名索引可能丢行。
+ */
+interface AutoMemoryOptions {
+  store: MemoryStore;
+  /** 记忆根目录（store 语义下的路径前缀），缺省 `./.otto`。 */
+  baseDir?: string;
+  /**
+   * 机器特定记忆根目录（RFC-164 D3/M164-1），缺省 `${baseDir}/local`。
+   * `scope:'local'` 的条目落此目录——物理隔离于 `baseDir` 之外，天然不参与
+   * 未来 workspace 远端同步判定（M164-2 的 `HttpMemoryStore.isWorkspaceSource()`
+   * 只识别 `baseDir` 下路径，不识别 `localBaseDir`）。
+   */
+  localBaseDir?: string;
+}
+interface AutoMemoryEntry {
+  name: string;
+  description: string;
+  content: string;
+}
+/**
+ * 记忆归属域：`workspace`（RFC-164 D3）= 可移植项目知识（默认，向后兼容，结构化
+ * index+entry 存储）；`local`（RFC-164 D3）= 机器特定事实，永不跨设备同步；
+ * `project-shared`（RFC-228 D2）= 团队可见的项目级约定，直接写 `./.otto/AGENTS.md`
+ * （marker 块格式，不接入 remote workspace sync——见 `recordProjectShared` 注释）。
+ */
+type MemoryScope = 'workspace' | 'local' | 'project-shared';
+declare class AutoMemory {
+  private readonly store;
+  private readonly baseDir;
+  private readonly localBaseDir;
+  private index;
+  /** local scope 的独立索引（不与 workspace 索引合并，读取侧透明查找）。 */
+  private localIndex;
+  private loaded;
+  private localLoaded;
+  constructor(options: AutoMemoryOptions);
+  get indexPath(): string;
+  entryPathOf(slug: string): string;
+  get localIndexPath(): string;
+  localEntryPathOf(slug: string): string;
+  /** PersistentMemory sources 接入点：索引作为一个可写 L1 源注入。 */
+  asSource(): MemorySource;
+  /** local 索引同样作为一个可写 L1 源注入（RFC-164 grill 已确认：常驻注入，不做按需裁剪）。 */
+  asLocalSource(): MemorySource;
+  load(): Promise<void>;
+  loadLocal(): Promise<void>;
+  /**
+   * 注入文本 = 索引原文 + 读取导语（空索引 → 空串，不占 token）。
+   * 导语说明条目的真实存放位置（可能 ≠ workspace 相对路径，review F4）。
+   */
+  getInjection(): string;
+  /** local 索引的注入文本（同结构，指向 localBaseDir，供组合注入到独立来源段落）。 */
+  getLocalInjection(): string;
+  record(entry: AutoMemoryEntry, scope?: MemoryScope): Promise<void>;
+  private recordLocal;
+  /**
+   * RFC-228 D2：`project-shared` scope——直接写 `./.otto/AGENTS.md`（marker 块格式），
+   * 收编此前"模型直接 edit/write AGENTS.md"的旁路（见 `prompts.ts` 的 `<memory_guidelines>`
+   * 文案变更，D3）。**不接入 remote workspace sync**——`HttpMemoryStore.isWorkspaceSource()`
+   * 不识别 `./.otto/AGENTS.md`，AGENTS.md 继续走 git 单一权威协作模型，与 lessons.json/
+   * MEMORY.md 的"多机自动同步"模型不同（RFC-228 D2 决策）。
+   *
+   * **写前 load-latest**（不依赖内存缓存的旧快照）：每次调用都重新 `store.load()` 取当前磁盘
+   * 最新内容，避免同会话内先前的注入快照覆盖并发写入（人工编辑或另一进程）的内容。
+   *
+   * slug 复用 `resolveSlug`（同名复用、异名消歧），marker 块按 slug 精确定位替换，不依赖
+   * heading 文本本身（避免 `entry.content` 内嵌 `##`/换行破坏边界）。
+   */
+  private recordProjectShared;
+  /**
+   * 读取侧透明合并：先查 workspace 索引，未命中再查 local 索引（RFC-164 §4.2）。
+   * RFC-164 M164-2 D6：读到的条目若存在冲突旁路文件（`<path>.conflict-0..4`），
+   * 前缀 `[CONFLICT]` 标签——避免 agent 把冲突副本当作等同权威记忆使用（子agent评审 F3）。
+   */
+  read(name: string): Promise<string | null>;
+  /** 探测 `<path>.conflict-0..4` 旁路文件是否存在，存在则前缀 `[CONFLICT]` 标签。 */
+  private withConflictLabel;
+  private readEntry;
+  forget(name: string): Promise<void>;
+  /** record/forget 前确保索引已加载（review F1：防未 load 的 record 清空既有索引）。 */
+  private ensureLoaded;
+  private ensureLocalLoaded;
+  private indexLines;
+  private localIndexLines;
+  /** 索引中 name → slug 的既有映射（精确名匹配）。传入 lines 使 workspace/local 两套索引共用同一实现。 */
+  private slugByName;
+  /** slug 解析：同名复用既有 slug；异名撞 slug 追加序号消歧（review F2）。传入 lines 使 workspace/local 两套索引共用同一实现。 */
+  private resolveSlug;
+}
+//#endregion
+//#region src/token-estimator.d.ts
+/**
+ * 确保 tokenizer 已加载（异步）。多次调用安全。
+ * 可在应用启动时调用一次，避免首次估算时的加载延迟。
+ */
+declare function ensureTokenizer(): Promise<void>;
+/**
+ * 图片 block 的固定 token 估算值（非精确计算，刻意保守）。
+ *
+ * Anthropic 官方公式：tokens = (width px * height px) / 750，图片被 resize 到最大
+ * 2000x2000px 上限时对应约 5333 tokens。本估算刻意采用远低于该上限的保守值，
+ * 宁可估算偏大触发提前压缩，也不要估算偏小导致压缩滞后（沿用
+ * IMAGE_MAX_TOKEN_SIZE=2000 的保守设计）。
+ *
+ * 注意：该常量上调会通过 estimateMessageTokens → needsCompaction 双阈值判断
+ * 使含图会话的压缩触发时机提前，这是预期效果而非副作用。
+ */
+declare const IMAGE_BLOCK_TOKEN_ESTIMATE = 2000;
+declare function estimateTokensHeuristic(text: string): number;
+/**
+ * 估算文本的 token 数。
+ * 优先使用 js-tiktoken（cl100k_base），未加载时回落启发式。
+ * 病理输入（同字符长 run / 超长文本）直接走启发式，避免 O(n²) BPE 阻塞主线程。
+ */
+declare function estimateTokens(text: string): number;
+declare function messageToText(message: Message): string;
+declare function estimateMessageTokens(message: Message, estimator?: typeof estimateTokens): number;
+declare function estimateMessagesTokens(messages: readonly Message[], estimator?: typeof estimateTokens): number;
+//#endregion
+//#region src/prune.d.ts
+declare function prune(messages: readonly Message[], contextWindow: number, config?: Partial<PruneConfig>, estimator?: typeof estimateTokens, opts?: {
+  currentTokens?: number;
+  force?: boolean;
+}): PruneResult;
+//#endregion
+//#region src/archive.d.ts
+declare class InMemoryArchiveStorage implements ArchiveStorage {
+  readonly type: StorageType;
+  private archives;
+  private sessionIndex;
+  archive(sessionId: string, messages: Message[], summary: string): Promise<string>;
+  read(archivePath: string): Promise<string>;
+  list(sessionId: string): Promise<ArchiveEntry[]>;
+  /** 会话销毁时驱逐其全部归档条目——防长跑进程中 archives/sessionIndex 无界增长。 */
+  forgetSession(sessionId: string): void;
+}
+/**
+ * file/http archive persistence 整栈已删。
+ * archive = session 派生视图——仅 `InMemoryArchiveStorage` 为 V 形态/无持久化 session tree 回退。
+ * createArchiveStorage() 工厂亦退场。
+ */
+declare function formatArchive(messages: Message[], summary: string, timestamp: number): string;
+//#endregion
+//#region src/defaults.d.ts
+declare function computeMemoryDefaults(model: {
+  contextWindow: number;
+  maxOutput: number;
+}): MemoryDefaults;
+declare const DEFAULT_COMPACTION_CONFIG: CompactionConfig;
+declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+declare function resolveContextSize(size: ContextSize, contextWindow: number): number;
+//#endregion
+//#region src/prompts.d.ts
+declare const SUMMARIZATION_PROMPT = "You are a conversation summarizer for an AI coding assistant. Your task is to create a structured summary of the conversation that preserves all information needed to continue the work.\n\nCreate the summary in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 quote the user's own wording; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent it derives from \u2014 anchors the task, prevents drift.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations";
+declare const UPDATE_SUMMARIZATION_PROMPT = "You are updating an existing conversation summary with new information. The existing summary and new messages are provided below.\n\nProduce a single UPDATED summary that stays BOUNDED \u2014 a summary that grows without limit across rounds eventually gets hard-truncated by the output cap, silently losing whatever fell past the limit. Keep it tight by actively triaging, not by appending.\n\nKeep (never drop):\n- Every distinct user request/instruction (the \"All User Requests\" record is authoritative)\n- Unfinished, in-progress, or blocked work\n- Decisions not yet verified, and anything the user corrected you on\n- Exact file paths, function names, error messages, code snippets still in play\n\nDrop / compress (make room):\n- Work that is both completed AND verified \u2014 collapse to a one-line outcome\n- Superseded intermediate attempts and abandoned approaches\n- Redundant restatements already captured elsewhere in the summary\n\nRules:\n- Move completed \"In Progress\" items to \"Done\", then compress \"Done\" per the above\n- Merge new work items, decisions, and context; do not simply append\n- Keep the same structured format (including \"All User Requests\")\n- If any information conflicts, use the newer version";
+declare const TURN_PREFIX_SUMMARIZATION_PROMPT = "You are summarizing the FIRST PART of an assistant turn that was split during conversation compaction. The remaining part of this turn is still in the conversation.\n\nCreate a brief summary in this format:\n\n## Original Request\n[What did the user ask for in this turn?]\n\n## Early Progress\n- [Key actions completed in the prefix portion]\n\n## Context for Remaining Messages\n- [Information needed to understand the remaining suffix messages]\n\nKeep it concise \u2014 this will be prepended to the remaining messages of this turn.";
+declare const WITH_PRESERVED_TAIL_PROMPT = "You are a conversation summarizer for an AI coding assistant. You are summarizing the EARLIER portion of a conversation. The most recent messages are NOT shown to you here \u2014 they are kept verbatim and will follow your summary unchanged.\n\nYour summary and those preserved recent messages together become the assistant's full context going forward.\n\nCreate the summary in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 multi-round compaction must never let an earlier request silently drop. Quote the user's own wording for each; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent that it derives from \u2014 this anchors the task and prevents interpretation drift across compactions.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\n## Context the Preserved Tail Depends On\n- [Facts a reader MUST know to correctly understand the preserved recent messages that follow: decisions already made, file paths and their current state, conventions/constraints agreed earlier, mistakes already corrected, and any partially-done work the recent messages continue. This section is the whole point of this summary \u2014 be specific.]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations\n- Do NOT re-summarize the preserved recent messages themselves \u2014 they are kept verbatim after your summary. Summarize only the EARLIER conversation and surface what the tail depends on.";
+declare const SEGMENT_SUMMARIZATION_PROMPT = "You are summarizing ONE SEGMENT of a longer conversation for an AI coding assistant. This is a partial view \u2014 you are NOT seeing the whole conversation, and other segments are being summarized separately. Your segment summary will later be merged with the others.\n\nCreate a concise summary of THIS SEGMENT in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 multi-round compaction must never let an earlier request silently drop. Quote the user's own wording for each; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent that it derives from \u2014 this anchors the task and prevents interpretation drift across compactions.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations\n- Do NOT emit conclusions that require seeing the whole conversation (e.g. a single global \"next step\"). Report only what THIS segment establishes; the merge step will reconcile across segments.";
+declare const SEGMENT_MERGE_PROMPT = "You are merging several segment summaries of one conversation into a single coherent summary for an AI coding assistant. Each input below is a summary of a different (chronological) segment of the same conversation.\n\nReconcile them into one summary in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 multi-round compaction must never let an earlier request silently drop. Quote the user's own wording for each; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent that it derives from \u2014 this anchors the task and prevents interpretation drift across compactions.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations\n- Resolve conflicts in favour of the LATER segment.\n- Merge duplicate items; do not simply concatenate.";
+/**
+ * RFC-339 D3：摘要提示词变体标识。调用方据压缩形态选择（见 `compaction.ts`）。
+ * - `full`：无保留区的全量折叠（或有旧摘要走 UPDATE 路径，见 buildSummarizationPrompt）。
+ * - `preserved-tail`：主路径，切点之后有原样保留的近期消息。
+ * - `segment`：map-reduce 的单段摘要。
+ * - `merge`：map-reduce 的合并阶段（输入是段摘要，非原始对话）。
+ */
+type SummarizationVariant = 'full' | 'preserved-tail' | 'segment' | 'merge';
+/**
+ * RFC-339 D3：切点上下文——让提示词感知「保留区」的存在。
+ * `preservedCount` = 切点之后原样保留的消息条数（0 = 全量折叠）。
+ */
+interface SummarizationContext {
+  variant: SummarizationVariant;
+  preservedCount?: number;
+}
+/**
+ * 构造摘要提示词。RFC-339 D3：新增可选 `context` 参数使提示词感知切点/批次形态；
+ * **不传时行为与改造前逐字节等价**（向后兼容——现有测试与未接线调用点不受影响）。
+ *
+ * 变体优先级：
+ * - `context.variant === 'segment'` → SEGMENT_SUMMARIZATION_PROMPT（map 阶段，忽略 previousSummary）
+ * - 有 `previousSummary` → UPDATE_SUMMARIZATION_PROMPT（增量更新，最高优先，兼容旧行为）
+ * - `context.variant === 'preserved-tail'` → WITH_PRESERVED_TAIL_PROMPT（主路径）
+ * - 否则 → SUMMARIZATION_PROMPT（FULL，全量折叠）
+ *
+ * 注：UPDATE 优先于 preserved-tail 是刻意的——增量补摘（有旧摘要）时，模型的任务是
+ * 把新增消息并入旧摘要，UPDATE 模板的「保留旧摘要全部信息」语义比 preserved-tail 更贴切；
+ * 保留区提示由 `preservedCount` 仍通过尾注补充（见下）。
+ */
+declare function buildSummarizationPrompt(messages: string, previousSummary?: string, customInstructions?: string, context?: SummarizationContext): string;
+/**
+ * RFC-339 D3：map-reduce 合并阶段的提示词。输入是各段摘要（非原始对话），
+ * 包在 `<segment_summaries>` 标签内——修正改造前 reduce 阶段误用 `<conversation>`
+ * 标签（内容类型与标签语义不符）的问题。
+ */
+declare function buildSegmentMergePrompt(segmentSummaries: string, previousSummary?: string, customInstructions?: string): string;
+declare function buildTurnPrefixPrompt(turnPrefixMessages: string): string;
+/**
+ * `<agent_memory>` 段的默认总预算（tokens，粗估）。
+ *
+ * 本仓正常场景（AGENTS.md 三源 + AutoMemory 索引）实测 ~3.4k tokens；monorepo
+ * `discoverAgentsSources` 理论上限是 10 文件 × 64KB = 640KB，若真的堆到那个量级会把
+ * system prompt 撑爆。这里的预算不是替代 discoverAgentsSources 的单文件/文件数上限
+ * （那层继续管），而是在全部来源（含它管不到的 writable AGENTS.md / AutoMemory 索引）
+ * 汇总之后再把一道总闸——`buildMemoryInjection` 是唯一收口点，别处管不到的这里管。
+ *
+ * 取 3.4k 实测值的 ~2.3 倍留余量，同时把极端场景压掉 95%+。
+ */
+declare const DEFAULT_MEMORY_INJECTION_BUDGET_TOKENS = 8000;
+declare function buildMemoryInjection(memories: Map<string, string>, budgetTokens?: number): string;
+/**
+ * 跨会话经验抽取提示词。要求模型从一段会话切片里提炼可复用的「经验」
+ * （trigger=何时适用 / insight=怎么做 / tags=召回关键词），严格输出 JSON 数组。
+ * 内容边界（D7/R3）对齐 `buildMemoryInjection` 的 should/should-NOT remember——不存可从
+ * repo/git/AGENTS.md 推导的事实、不存 ephemeral 任务态、不存密钥。无可存则输出 []。
+ */
+declare const LESSON_EXTRACTION_PROMPT = "You are a learning extractor for an AI coding assistant. Read the conversation below and extract durable, cross-session \"lessons\" \u2014 operational knowledge that will help the assistant do better on FUTURE, unrelated sessions in this project.\n\nA lesson captures a reusable cause\u2192action:\n- \"trigger\": the situation/context that should recall this lesson (when it applies)\n- \"insight\": the actionable guidance learned (what to do)\n- \"tags\": 1-5 lowercase keywords for retrieval\n\nSAVE these (durable, reusable):\n- A user correction that reveals a lasting preference (\"user prefers X over Y\")\n- A non-obvious gotcha discovered the hard way (\"running Z without flag W silently fails\")\n- A project-specific workflow or command that isn't written down elsewhere\n- A constraint or convention the user insisted on\n\nDO NOT save these (they pollute recall):\n- Anything derivable from the repo, git history, or AGENTS.md/README \u2014 do not restate the obvious\n- Ephemeral task state (\"currently editing foo.ts\") \u2014 lessons must outlive this session\n- One-off Q&A, casual conversation, or a summary of what happened\n- Secrets, API keys, passwords, tokens, or any sensitive value\n\nOutput ONLY a JSON array, nothing else. Each element: {\"trigger\": string, \"insight\": string, \"tags\": string[]}.\nIf there is nothing durable worth saving, output exactly: []";
+declare function buildExtractionPrompt(conversationText: string): string;
+/**
+ * RFC-340 D2 方案 B（M2 兑现）：压缩摘要的上下文引用。
+ *
+ * 演进史（两步，勿回退）：
+ * - **原始文案**承诺 "can be accessed via the **read** tool"——断头路：通用 read 工具
+ *   不认识 `archive:` 前缀，`MemoryManager.readArchive()` 零工具暴露，模型照做只会
+ *   拿到"文件不存在"。
+ * - **M1** 据"不做无法兑现的承诺"删掉可读表述，只留溯源标识。
+ * - **M2（本版）** 把召回能力真正做出来（`memory_archive_read`），故把承诺加回——
+ *   但指向**具体工具名**而非泛泛的 "read tool"，这正是原文案出错的地方。
+ *
+ * 工具可能未注册（`archiveRecall` 能力未注入，如 V 形态/无持久化会话）。此时文案仍
+ * 提到该工具是可接受的：模型调用不存在的工具会得到明确的 unknown-tool 反馈，
+ * 比"以为取不回而不去尝试"损失更小；且未注册场景本身就是少数派配置。
+ */
+declare function buildArchiveReference(archivePath: string, summary: string): string;
+/**
+ * RFC-340 D1：低覆盖摘要的前置标注文本。
+ *
+ * 目的是**如实告知而非静默降级**：模型据此知道这段摘要并未覆盖全部历史，遇到摘要里
+ * 没有的细节应当向用户确认，而不是当作"历史里就没发生过"。
+ */
+declare function buildLowCoverageNotice(coverage: number): string;
+//#endregion
+//#region src/operational-learning.d.ts
+/**
+ * RFC-284 D2：经验的语义类别，与 `state` 生命周期正交。
+ *
+ * 判别基准是「换一个技术栈后是否还成立」：
+ * - `norm` 在任何项目都成立（如「禁用 git stash」）→ 常驻 Core Pack。
+ * - `fact` 只在碰到该技术栈时才需要（如「undici 默认 keep-alive 会让第二个请求挂起」）→ 按需检索。
+ * - `case` 是某次落地/排障的纪要 → 只供 explain/审计。
+ * - `ephemeral` 绑定某台机器/某次基线 → TTL 到期归档。
+ */
+type LessonClass = 'norm' | 'fact' | 'case' | 'ephemeral';
+/**
+ * RFC-284 D2：经验的生命周期状态。
+ *
+ * `live` 表示当前会话的 stable snapshot 仍引用它——内存压力也不得淘汰，
+ * 只能从下一个会话起生效（对齐 Flutter ImageCache 对 live image 的处理）。
+ */
+type LessonState = 'active' | 'live' | 'archived' | 'tombstone';
+interface Lesson {
+  id: string;
+  tags: string[];
+  trigger: string;
+  insight: string;
+  sourceSessionId: string;
+  createdAt: number;
+  /**
+   * @deprecated RFC-284 D8：改用 `relevantHitCount`。
+   *
+   * 该字段唯一自增点是 `search()`，而注入路径走 `list()` 且 `search()` 零生产调用方，
+   * 故它在历史数据中结构性恒为 0（详见 RFC-036 §8.9 勘误）。保留仅为向后兼容：
+   * 读取时与 `relevantHitCount` 双向同步，不再作为新的判据来源。
+   */
+  appliedCount: number;
+  /** 语义类别。缺省视为未归类，由 M4 审计填充。 */
+  class?: LessonClass;
+  /** 生命周期状态。缺省视为 `active`。 */
+  state?: LessonState;
+  /** 作用域。由所属 store 类型决定，不从 v1 正文推断。 */
+  scope?: 'workspace' | 'local';
+  /** 注入文本的内容哈希——只由 content 字段决定，统计字段变化不得影响它。 */
+  contentHash?: string;
+  /** 注入成本估算（CJK 加权）。用于预算核算，不参与 `contentHash`。 */
+  estimatedTokens?: number;
+  /** 被 Relevant Hints 检索命中的次数（承接旧 `appliedCount` 语义）。 */
+  relevantHitCount?: number;
+  /** 进入 stable Core Pack 的次数。 */
+  coreInjectedCount?: number;
+  /** 任意 selector 命中总数。 */
+  hitCountTotal?: number;
+  /** 最近一次被 selector 命中的时间。 */
+  lastAccessedAt?: number;
+  /** 用户或系统固定，不得自动归档。 */
+  pinned?: boolean;
+  /** 被哪条经验取代（同主题合并后指向合并条款）。 */
+  supersededBy?: string;
+  /** 合并来源——规范条款保留原始 lesson id，维持 AGENTS.md 引用可追溯性。 */
+  mergedFrom?: string[];
+}
+type LessonInput = Omit<Lesson, 'id' | 'createdAt' | 'appliedCount'>;
+interface LessonFilter {
+  tags?: string[];
+  query?: string;
+}
+interface SimilarLesson {
+  lesson: Lesson;
+  /** Jaccard 词集相似度 [0,1]。 */
+  similarity: number;
+}
+/** 默认去重阈值——trigger+insight 词集 Jaccard ≥ 此值即视作近似重复。 */
+declare const DEFAULT_SIMILARITY_THRESHOLD = 0.6;
+interface LearningStoreOptions {
+  /** 本地文件持久化路径（与 `store` 互斥；两者都缺省时纯内存,不持久化）。 */
+  path?: string;
+  /**
+   * RFC-164 M164-2 D5：可选 `MemoryStore` 抽象接入——提供时,读写改走
+   * `store.load()`/`store.write()`（序列化为 JSON 字符串），使 lessons.json 与
+   * auto-memory 走同一远端同步管道（不再是碎片化的"auto-memory 同步了但 lessons 没同步"）。
+   * 与 `path` 二选一：`store` 优先；两者都提供时 `store` 生效、`path` 被忽略（`store` 场景下
+   * 仍用 `path` 派生 `storeKey`，即 store 语义下的路径,通常与 `path` 同值)。
+   */
+  store?: MemoryStore;
+  /** `store` 模式下的存储路径（store 语义下的 key/path）。仅 `store` 提供时使用，缺省复用 `path`。 */
+  storePath?: string;
+  /**
+   * 可选 logger——提供时用于诊断加载/持久化错误（warn 级别）。
+   * 默认不打印，避免影响现有调用方。
+   */
+  logger?: {
+    warn: (...args: unknown[]) => void;
+  };
+  /**
+   * RFC-284 D11：本 store 承载的作用域。由装配方按 store 类型传入
+   * （workspace store 传 'workspace'，local store 传 'local'），
+   * 不从 lesson 正文推断——scope 是存储边界属性，不是内容属性。
+   */
+  scope?: 'workspace' | 'local';
+  /**
+   * RFC-345 §D3：影子模式——persist() 整体短路（唯一写盘出口）。
+   *
+   * 教训子系统是内存优先架构（this.lessons Map 为真源，list/get/search 全读 Map），
+   * persist() 只是把 Map 刷盘（§E2 已实证）。短路 persist 后写后读天然正确（写进 Map、
+   * 读从 Map），同会话内行为与普通模式一致，仅退出后不留痕。覆盖 store 与 persistence
+   * 两个写盘分支于单点。由 §D1 白名单点 agent-services-setup 从 isShadowModeEnabled 派生。
+   */
+  ephemeral?: boolean;
+}
+/** 估算注入 token（CJK≈1/字，ASCII≈4 字符/token）。与 RFC-284 探针脚本同口径。 */
+declare function estimateLessonTokens(lesson: Pick<Lesson, 'tags' | 'trigger' | 'insight'>): number;
+/**
+ * 内容哈希——**只覆盖进入注入文本的字段**（RFC-284 D6）。
+ *
+ * 统计字段（hitCount/lastAccessedAt/…）绝不参与，否则每次 selector 命中都会
+ * 改变 packId、逐轮击穿 prompt cache 的 stable 前缀。
+ */
+declare function computeLessonContentHash(lesson: Pick<Lesson, 'tags' | 'trigger' | 'insight'>): string;
+declare class OperationalLearningStore {
+  private lessons;
+  private nextId;
+  private loaded;
+  private readonly snapshotId;
+  private readonly persistence;
+  /** RFC-164 M164-2 D5：MemoryStore 接入（可选）——提供时优先于 `persistence` 路径。 */
+  private readonly store;
+  private readonly storePath;
+  private readonly logger;
+  /** RFC-284 D11：本 store 的作用域，装配期注入，写入时打到每条 lesson 上。 */
+  private readonly scope;
+  /** RFC-345 §D3：影子态——persist() 短路（内存优先架构，写后读经 this.lessons Map 保持）。 */
+  private readonly ephemeral;
+  constructor(options?: LearningStoreOptions);
+  save(input: LessonInput): Promise<Lesson>;
+  search(query: string, limit?: number): Promise<Lesson[]>;
+  /**
+   * RFC-036 M61(R4 去重前置）：在写入前查找与 `(trigger, insight)` 近似重复的既有经验。
+   * 返回相似度最高且 ≥ `threshold` 的一条,没有则 `undefined`。**只读,不自增 appliedCount**
+   * （区别于 `search`——`search` 是召回侧、计数被引用；`findSimilar` 是写前去重、不应计数）。
+   */
+  findSimilar(trigger: string, insight: string, threshold?: number): Promise<SimilarLesson | undefined>;
+  /**
+   * RFC-036 M62-03(R4):去重写入——写前 `findSimilar`,命中近似既有经验则**复用**(不新增),
+   * 否则 `save`。`learn` 工具与 `saveExtractedLessons` 共用此原语,保证所有写入口都过去重。
+   */
+  saveDeduped(input: LessonInput, threshold?: number): Promise<{
+    lesson: Lesson;
+    deduped: boolean;
+  }>;
+  list(filter?: LessonFilter): Promise<Lesson[]>;
+  get(id: string): Promise<Lesson | undefined>;
+  /** RFC-284 T3b：记录 Relevant Hints 命中；只更新统计字段，不改变 contentHash/estimatedTokens。 */
+  recordRelevantHits(ids: readonly string[], now?: number): Promise<void>;
+  delete(id: string): Promise<boolean>;
+  get size(): number;
+  private ensureLoaded;
+  /**
+   * RFC-164 M164-2 D4b：强制重新从 store 拉取一次（"最终同步"场景——R↔L 切换 disable 前
+   * 拉取远端最新内容覆盖本地缓存，避免用户看到 stale 数据）。仅 store 模式生效；
+   * 本地文件模式（无 store）为 no-op（无远端可拉取）。
+   */
+  refresh(): Promise<void>;
+  /** RFC-164 M164-2 D5：MemoryStore 路径的加载——store.load 返回原始 JSON 字符串,本地解析。 */
+  private loadFromStore;
+  private persist;
+}
+//#endregion
+//#region src/memory-extractor.d.ts
+/**
+ * 抽取器调用 LLM 的接缝——与 compaction 的 `summarize` 同形。memory 包保持纯净:运行时
+ * 再决定注入 forked-agent 还是复用主 summarize。
+ */
+type ExtractLLM = (prompt: string, options?: {
+  maxTokens?: number;
+  signal?: AbortSignal;
+}) => Promise<string>;
+interface ExtractionOptions {
+  /** 抽取调用的 token 上限。默认 DEFAULT_MAX_TOKENS=2048。 */
+  maxTokens?: number;
+  signal?: AbortSignal;
+  /** 单次抽取最多产出多少条 lesson(防爆 / 防召回污染)。默认 5。 */
+  maxLessons?: number;
+}
+/**
+ * 从会话切片抽取跨会话经验(Lesson)。
+ *
+ * **fail-closed**:LLM 失败/超时/解析失败一律返回 `[]`,绝不抛——抽取永不阻塞、
+ * 不污染主回合。本函数是纯库逻辑(经 `ExtractLLM` 注入模型调用),不依赖 agent/ForkRunner;
+ * 触发节流、不与主 agent 抢、去重写入由上层负责。
+ *
+ * @param messages          会话切片(通常是上次抽取后的新增消息)
+ * @param sourceSessionId   产出 lesson 的来源会话 id(写入 `LessonInput.sourceSessionId`)
+ * @param llm               模型调用接缝
+ * @returns 规整后的 `LessonInput[]`(可直接喂 `OperationalLearningStore.save`),失败为空数组
+ */
+declare function extractLessons(messages: readonly Message[], sourceSessionId: string, llm: ExtractLLM, options?: ExtractionOptions): Promise<LessonInput[]>;
+/** `saveExtractedLessons` 依赖的最小 store 接口——便于单测注入 in-memory store。 */
+interface LessonWriteStore {
+  saveDeduped(input: LessonInput, threshold?: number): Promise<{
+    lesson: Lesson;
+    deduped: boolean;
+  }>;
+}
+interface SaveExtractedResult {
+  /** 真正写入的新经验。 */
+  saved: Lesson[];
+  /** 因命中近似既有经验而跳过的数量(去重)。 */
+  skippedSimilar: number;
+}
+interface SaveExtractedOptions {
+  /** 去重阈值,透传 `findSimilar`。省略用 store 默认值。 */
+  similarityThreshold?: number;
+}
+/**
+ * 去重前置写入:把抽取出的候选 `LessonInput[]` 逐条写入 store——**写前必 `findSimilar`**,
+ * 命中近似既有经验则跳过,否则 `save`。严禁无去重批量追加(否则 lesson 爆炸→召回退化+持久化膨胀)。
+ *
+ * 批内去重天然成立:顺序写入 + `findSimilar` 查实时 store,故后续候选会命中刚写入的同批经验而跳过。
+ */
+declare function saveExtractedLessons(store: LessonWriteStore, candidates: readonly LessonInput[], options?: SaveExtractedOptions): Promise<SaveExtractedResult>;
+//#endregion
+//#region src/auto-extract.d.ts
+/** 编排器配置(camelCase 运行时形态;App 层从 snake_case settings 映射)。 */
+interface MemoryAutoExtractConfig {
+  /** 总开关。默认关——灰度验证信噪比后再放开(R6)。 */
+  enabled: boolean;
+  /** 节流:每 N 次 idle 才抽取一次(累积切片)。默认 1(每次 idle 都抽)。 */
+  everyNTurns?: number;
+  /** 单次抽取上限,透传 extractLessons。 */
+  maxLessons?: number;
+  /** 去重阈值,透传 saveExtractedLessons。 */
+  similarityThreshold?: number;
+  /** 抽取调用 token 上限,透传 extractLessons。 */
+  maxTokens?: number;
+}
+interface MemoryAutoExtractorDeps {
+  llm: ExtractLLM;
+  store: LessonWriteStore;
+  config: MemoryAutoExtractConfig;
+  /**
+   * R5 不与主 agent 抢:判定某工具调用是否算"记忆写入"——若本批切片里主 agent 已写过记忆,
+   * 跳过本次抽取。默认认 `learn` 工具与名字含 `memory` 的工具。
+   */
+  isMemoryWriteTool?: (toolName: string) => boolean;
+}
+type AutoExtractReason = 'disabled' | 'no-new-messages' | 'throttled' | 'main-agent-wrote' | 'error';
+interface AutoExtractOutcome {
+  ran: boolean;
+  reason?: AutoExtractReason;
+  saved: number;
+  skippedSimilar: number;
+}
+/**
+ * 会话经验自动抽取编排器(纯库 + 全注入)。
+ *
+ * 在每次会话 idle(由 runtime 订阅 `session.idle`/`turn.end` 触发)调 `onIdle`——按
+ * gate(R6 默认关)→ 节流(R7)→ 不抢(R5)→ 抽取(fail-closed)→ 去重写入(R4)流程跑。
+ * **永不抛**(R2):任何失败返回 `{ran:false, reason:'error'}`,绝不阻塞或污染主回合。
+ * runtime 层只需提供 `llm`(复用 summarize 接缝)、`store`、`config`,并在每次 idle 把会话
+ * 全量 messages 传进来——编排器自己按 `lastExtractedIndex` 切增量。
+ */
+declare function createMemoryAutoExtractor(deps: MemoryAutoExtractorDeps): {
+  onIdle: (sessionId: string, messages: readonly Message[], opts?: {
+    signal?: AbortSignal;
+  }) => Promise<AutoExtractOutcome>;
+  reset: (sessionId: string) => void;
+};
+//#endregion
+//#region src/file-state-snapshot.d.ts
+interface FileStateSnapshot {
+  timestamp: number;
+  directoryTree: string;
+  modifiedFiles: Array<{
+    path: string;
+    action: 'created' | 'modified' | 'deleted';
+    summary: string;
+  }>;
+  planStatus?: string;
+  findings: string[];
+}
+interface FileStateCapture {
+  workspaceDir: string;
+  recentFiles?: string[];
+  planStatus?: string;
+}
+declare class FileStateManager {
+  private lastSnapshot;
+  capture(input: FileStateCapture): Promise<FileStateSnapshot>;
+  getLastSnapshot(): FileStateSnapshot | null;
+  formatSnapshot(snapshot: FileStateSnapshot): string;
+  private buildDirectoryTree;
+  private checkRecentFiles;
+}
+//#endregion
+export { type AgentsDiscoveryOptions, type ArchiveEntry, type ArchiveStorage, type AutoExtractOutcome, type AutoExtractReason, AutoMemory, type AutoMemoryEntry, type AutoMemoryOptions, type CompactionConfig, type CompactionPreparation, type CompactionResult, type ContextSize, type ContextTokenEstimate, type CutPoint, DEFAULT_COMPACTION_CONFIG, DEFAULT_MEMORY_INJECTION_BUDGET_TOKENS, DEFAULT_MEMORY_SOURCES, DEFAULT_PRUNE_CONFIG, DEFAULT_SIMILARITY_THRESHOLD, type ExtractLLM, type ExtractionOptions, type FileStateCapture, FileStateManager, type FileStateSnapshot, FileSystemMemoryStore, HttpMemoryStore, IMAGE_BLOCK_TOKEN_ESTIMATE, InMemoryArchiveStorage, InMemoryMemoryStore, LESSON_EXTRACTION_PROMPT, type LearningStoreOptions, type Lesson, type LessonClass, type LessonFilter, type LessonInput, type LessonState, type LessonWriteStore, type MemoryAutoExtractConfig, type MemoryAutoExtractorDeps, type MemoryDefaults, MemoryManager, type MemoryManagerConfig, type MemorySource, type MemoryStore, type MessageFromEntry, type MinimalEntry, OperationalLearningStore, PersistentMemory, type PruneConfig, type PruneResult, SEGMENT_MERGE_PROMPT, SEGMENT_SUMMARIZATION_PROMPT, SUMMARIZATION_PROMPT, type SaveExtractedOptions, type SaveExtractedResult, type SimilarLesson, type StorageType, type SummarizationContext, type SummarizationVariant, TURN_PREFIX_SUMMARIZATION_PROMPT, UPDATE_SUMMARIZATION_PROMPT, WITH_PRESERVED_TAIL_PROMPT, buildArchiveReference, buildExtractionPrompt, buildLowCoverageNotice, buildMemoryInjection, buildSegmentMergePrompt, buildSummarizationPrompt, buildTurnPrefixPrompt, computeLessonContentHash, computeMemoryDefaults, createMemoryAutoExtractor, createMemoryManager, createOverlayMemoryStore, discoverAgentsSources, ensureTokenizer, estimateLessonTokens, estimateMessageTokens, estimateMessagesTokens, estimateTokens, estimateTokensHeuristic, extractLessons, formatArchive, messageToText, prune, resolveContextSize, saveExtractedLessons };
+//# sourceMappingURL=index.d.ts.map