@yottameta/yotta-memory 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## v0.20.0 (2026-09-30)
+
+上下文分页 P2.5：先修 `memory.hook` 的 PREF 驱逐空转，再新增 `context.paging` 预算调用点。
+
+- 修复 `memory.hook` 对画像段落驱逐空转：hook / paging 决策实际生效时，画像段落按实时可读条目渲染并套用同一套过滤；自我接入档案不进候选、不可驱逐；无 provider 时仍读 `profile.md`，基线输出逐字节不变。
+- 修复 `profile` 只读单层目录：`private/<owner>/{prefs,bounds,commits}/YYYY/MM/` 里的分层条目现在也会进入静态画像；`context` 的实时画像路径不受影响。
+- 新增 `context.paging`：仅在用户显式传 `--budget` 时调用；`memory.hook` 先过滤，`context.paging` 再排序 / 分页。`drop` 始终安全应用；`order` 仅在 `complete:true` 且候选未超过 500 时应用；候选集外文件只记 note、不进入输出。
+- `context --json` 新增 `paging` 块（`status` / `provider_id` / `applied` / `dropped` / `ordered` / `truncated` / `budget` / `used` / `note`）；文本仅在 `context.paging` 实际被声明或触发时增加状态行；审计沿用 `provider-audit.jsonl`，不含记忆正文。
+- provider 子进程透传 `YOTTA_LICENSE_HOME` / `YOTTA_LICENSE_KEYS_DIR` / `YOTTA_LICENSE_BASE_URL` / `YOTTA_LICENSE_SERVER_ID`，与路线 B 授权隔离环境一致。
+- 协议文档升级 v1.1，新增 `context.paging` 请求 / 响应 / 回落说明。
+
 ## v0.19.0 (2026-09-28)
 - 新增扩展提供方（provider）装载点：`context` 可选调用本地 provider（capability `memory.hook`），在权限过滤后的候选集内驱逐条目；BOUND / COMMIT 与身份画像不可驱逐，预算 / 去重 / 宽限仍由引擎掌控。
 - 未配置 / 未授权 / 超时 / 非法输出一律 fail-open 回普通记忆；`provider.json` 非法只记状态、不阻断。

package/README.md

@@ -107,7 +107,7 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 ### Profile & start-of-work context (v0.6.0 + v0.9.0 + v0.14.0)
 
 - **profile**: aggregates `private/<owner>/` PREF / BOUND / COMMIT verbatim, grouped by type + subject + tags, written to `profile.md`; the engine infers nothing — profile conclusions are formed internally by the AI per the "memory discipline", never pasted as labels.
-- **context**: one-shot start-of-work package — multi-agent integration rules + identity + long-term summaries first (`consolidate` output) + user profile digest + optional task-focused memory (`--focus`) + time-ordered recent corridor + deduplicated high-value backfill + boundary reminders + commitments/anchors + session loop contract; supports `--budget` for dynamic memory and `--explain` selection trace.
+- **context**: one-shot start-of-work package — multi-agent integration rules + identity + long-term summaries first (`consolidate` output) + user profile digest + optional task-focused memory (`--focus`) + time-ordered recent corridor + deduplicated high-value backfill + boundary reminders + commitments/anchors + session loop contract; supports `--budget` for dynamic memory and `--explain` selection trace. Optional local providers can add `memory.hook` filtering and, when `--budget` is explicit, `context.paging` ordering/paging; `context --json` returns `hook` and `paging` blocks.
 - **Memory discipline**: SKILL.md embeds a rule layer (type red lines / proactive trigger capture / know-the-user three stages / psychological grounding & alignment / bottom lines / host isolation / anti-patterns).
 
 ### Retrieval: semantic search (v0.8.0 + v0.9.0 embedding)

package/README.zh-CN.md

@@ -22,7 +22,7 @@
 </p>
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
-> 🆕 **v0.19.0（扩展提供方装载点 + context JSON）**：`context` 可选调用用户显式配置的本地扩展提供方（capability `memory.hook`）参与「哪些记忆进上下文」——提供方只能驱逐本次候选集内条目，BOUND / COMMIT 与身份画像不可驱逐，预算 / 去重 / 宽限仍由引擎掌控；未配置 / 未授权 / 超时 / 非法输出一律回普通记忆。`context --json` 输出结构化 JSON（`schema` / `hook` / `text`）。配置与协议见 `references/provider-protocol.md`。
+> 🆕 **v0.20.0（上下文分页 + 画像驱逐修复）**：`memory.hook` 的 PREF 驱逐空转已修复——hook / paging 决策生效时，画像段落按实时可读条目渲染并套用同一套过滤；自我接入档案不进候选、不可驱逐。新增 `context.paging`：仅在显式 `--budget` 时调用，hook 先过滤、paging 再排序与分页；`drop` 始终安全应用，`order` 仅在 `complete:true` 且未截断时应用。`context --json` 新增 `paging` 块，`--explain` 增加 `[paging]` 轨迹。配置与协议见 `references/provider-protocol.md`。
 > 🆕 **v0.18.1（蒸馏溯源 + 日期绝对化 + 巩固标记 + 规则晋升建议 + 写入纪律）**：`distill` 新增分类型提取清单（事件 / 教训 / 待办 / 成长 / 规则边界 / 其他）+ 逐条 `[溯源: 文件#L<a>-L<b>]` + 实测质量指标 + 跳过与边界，`--json` 输出结构化报告；`consolidate` 摘要按条目 `created` 把「昨天 / 上周 / 本月 / 今年」写成绝对日期，归档副本写入巩固标记（`--undo` 剥离还原）；`maintain --rules` 只读给出「重复踩坑 → 建议升级为规则」（默认阈值 3，不自动写 BOUND）；记忆守则新增冲突权威顺序 6 层与写入纪律 3 条。
 
 > 🆕 **v0.18.0（命中打点 + 容量水位 + consolidate 提案闸门 + 上下文压缩审计）**：`recall` / `explain` / `feedback --useful` / `context` 记录本地命中元数据（`hit_days` 默认保留 90 天；`hit_queries` 只存查询 8 位指纹、最多 12 槽，不存原文；随文件加密 / 备份 / 导出），`config set usage_enabled false` 或命令级 `--no-usage` 可关；只读命令与跨 owner 私密条目不写。`maintain --capacity` 只读报告容量水位、30 / 90 天活跃度、LRU / LFU 淘汰候选（冷却期 30 天 + immutable / BOUND / evergreen / pinned 豁免）与晋升建议（≥3 次命中且 ≥3 个不同查询，只出建议命令）；`archive` 默认豁免冷却期与标签常青，`--force` 可显式覆盖。`consolidate` 默认等价 `--propose`（结构化报告 + `--json`），`--apply` 交互式需确认串、非交互必须 `--yes`；首次启用显示一次数据生命周期说明。`doctor` 规模体检新增 `scale_info_*` 与逐项 `ok / info / warning` 分级（`doctor.ok` 仍只看 critical）。新增 `context --audit [--from <文件|->] [--json] [--gate N]`：核对被压缩掉的内容是否已落盘，输出未落盘清单与 `remember` 建议命令，只读、不自动补写。`archive --dry-run` 只预览不改库（不动文件 / 不建事务快照 / 不写审计），无候选时不建整库快照，`archive --json` 输出结构化报告；MCP 侧只补只读 / 预演能力（`archive.dryRun`、`maintain.capacity`、`context.audit` + 内联 `auditText`、`consolidate` 只出 propose 报告），`archive --force` 与 `consolidate --apply / --undo` 仍只在命令行。上一版 v0.17.4：`rename` 消除平铺 / 分层同序号冲突（跨布局 fail-closed + 破坏性闸门 + 审计）。

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-memory
 description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、长期理解摘要、近期走廊、会话闭环、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删、doctor、事务快照、基线探针、恢复演练、记忆库安全扫描、scan、命中打点、容量水位、--capacity、--propose、上下文压缩审计、context --audit
-version: 0.19.0
+version: 0.20.0
 license: MIT
 ---
 
@@ -36,7 +36,7 @@ license: MIT
 - **可靠性基线（v0.12.0）**：`init` 对非空记忆库默认拒绝覆盖（`--attach` 接入现有库）；`forget` 先移入 `.trash/` 并写审计；新增 `backup volumes / setup / status / ensure-daily / schedule / drill`（用户确认真实独立卷后默认每日自动备份）与 `backup create / list / doctor / restore`。
 - **可靠性收口（v0.12.2）**：新增 `yotta-memory doctor` 开工检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份）；`maintain --apply`、`consolidate --apply`、`merge`、`archive`、`--purge` 在写入前自动创建事务快照，快照失败或严重检查异常时拒绝写入。
 - **运行时 hook 声明（v0.13.0）**：manifest 声明 `after_milestone` / `remember_commit`；里程碑记忆必须有真实文件路径证据才标 verified，缺证据时输出 `explicit-unverified` + 一次纠偏。
-- **扩展提供方装载点（v0.19.0）**：`context` 支持可选的本地扩展提供方（capability `memory.hook`）参与「哪些记忆进上下文」：提供方只能驱逐本次候选集内的条目；身份画像、BOUND / COMMIT、预算 / 去重 / 宽限仍由引擎掌控。未配置 / 未授权 / 超时 / 非法输出一律走普通记忆，输出不带扩展行；`context --json` 输出 `schema` / `hook` / `text`。配置与协议见 `references/provider-protocol.md`。
+- **扩展提供方装载点（v0.20.0）**：`context` 支持可选的本地扩展提供方参与「哪些记忆进上下文」：`memory.hook` 先按候选集驱逐 / 白名单过滤，`context.paging` 在显式 `--budget` 时再排序与分页。身份段落、自我接入档案、BOUND / COMMIT、预算 / 去重 / 宽限仍由引擎掌控；未配置 / 未授权 / 超时 / 非法输出一律走普通记忆。`context --json` 输出 `schema` / `hook` / `paging` / `text`，`--explain` 增加 `[paging]` 轨迹。配置与协议见 `references/provider-protocol.md`。
 
 - **蒸馏溯源与分类型提取（v0.18.1）**：`distill` 输出新增「分类型提取清单（事件 / 教训 / 待办 / 成长 / 规则边界 / 其他）+ 质量指标 + 跳过与边界」；每条提取项带 `[溯源: 文件#L<a>-L<b>]`，报告只给实测压缩比 / 条目覆盖 / 溯源覆盖 / 要素提取率，不承诺压缩倍数或语义保真。`distill --json` 输出结构化报告；帮助补 `--owner` / `--out`。
 - **日期绝对化与巩固标记（v0.18.1）**：`consolidate` 生成摘要正文时，按条目 `created`（缺则 `updated`）把「昨天 / 上周 / 本月 / 今年」等写成绝对日期（如 `昨天（2026-01-09）`）；「最近 / 前几天 / 刚才」等模糊词不归一。归档副本末尾追加一行 `<!-- yotta-memory: consolidated to … -->` 巩固标记；`--undo` 剥离标记并还原原始内容；标记失败不影响批次，只在报告与审计里计数。

package/bin/provider.js

@@ -94,6 +94,7 @@ function minimalEnv() {
   const keep = [
     'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'windir', 'COMSPEC', 'ComSpec',
     'TEMP', 'TMP', 'HOME', 'USERPROFILE', 'LANG', 'LC_ALL',
+    'YOTTA_LICENSE_HOME', 'YOTTA_LICENSE_KEYS_DIR', 'YOTTA_LICENSE_BASE_URL', 'YOTTA_LICENSE_SERVER_ID',
   ];
   const env = {};
   for (const key of keep) {

package/bin/yotta-memory.js

@@ -25,7 +25,7 @@ const net = require('net');
 const child_process = require('child_process');
 const { AsyncLocalStorage } = require('async_hooks');
 
-const VERSION = '0.19.0';
+const VERSION = '0.20.0';
 const CLI_VALUE_OPTS = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--agent-id', '--agent-key', '--agent-key-file', '--plugin-data', '--threshold', '--scope', '--host', '--port', '--dir', '--name', '--user', '--relationship', '--source', '--weight', '--budget', '--password', '--new-password', '--recovery-key', '--recovery-key-out', '--reason', '--merge', '--model', '--subject', '--embedding', '--focus', '--embedding-timeout', '--min-age', '--min-idle', '--max-utility', '--min-group', '--period', '--to', '--id', '--time', '--tools', '--mcp-config', '--skill-dir', '--year', '--evalset', '--k', '--seed', '--bootstrap', '--gate', '--against', '--template', '--path', '--from']);
 const CLI_FLAG_OPTS = new Set(['--project', '--all', '--unsafe', '--no-auth', '--stdio', '--onstart', '--from-current', '--restart', '--force', '--attach', '--allow-same-volume', '--verify', '--no-hint', '--encrypt', '--no-encrypt', '--password-stdin', '--json', '--manual', '--skip-schedule', '--useful', '--useless', '--undo', '--dry-run', '--apply', '--purge', '--dedup', '--batches', '--propose', '--audit', '--capacity', '--rules', '--explain', '--semantic', '--runtime', '--ablate', '--timing', '--baseline', '--probe', '--quarantine', '--restore', '--no-usage', '--yes', '--keep-memories', '--keep-identity']);
 
@@ -7460,30 +7460,55 @@ function cmdWhoami(opts) {
 
 // ---- 用户画像聚合（v0.6.0，零推断：只归组呈现原文，结论由承载 AI 依据「记忆守则」内部形成）----
 function profileGroups(root, owner) {
-  const groups = [];
-  const map = {};
+  const entries = [];
   for (const t of PRIVATE_LEAF) {
     const dir = path.join(root, PRIVATE_DIR, owner, t);
     if (!fs.existsSync(dir)) continue;
-    for (const f of fs.readdirSync(dir)) {
-      if (!/\.md(\.enc)?$/.test(f)) continue;
-      const fp = path.join(dir, f);
-      if (!fs.statSync(fp).isFile()) continue;
+    const files = [];
+    walkEntryFiles(dir, files);
+    for (const fp of files) {
       let e;
       try { e = readEntry(fp, root); } catch (err) { continue; }
-      const key = e.type + '\u0000' + (e.subject || '') + '\u0000' + e.tags.join(',');
-      if (!map[key]) {
-        map[key] = { type: e.type, subject: e.subject || '', tags: e.tags || [], items: [] };
-        groups.push(map[key]);
-      }
-      map[key].items.push({
-        file: e.file, statement: e.statement, confidence: e.confidence,
-        last_accessed: e.last_accessed, updated: e.updated,
-      });
+      entries.push(e);
     }
   }
+  return profileGroupsFromEntries(entries);
+}
+function profileGroupsFromEntries(entries) {
+  const groups = [];
+  const map = {};
+  for (const e of (entries || [])) {
+    const key = e.type + '\u0000' + (e.subject || '') + '\u0000' + (e.tags || []).join(',');
+    if (!map[key]) {
+      map[key] = { type: e.type, subject: e.subject || '', tags: e.tags || [], items: [] };
+      groups.push(map[key]);
+    }
+    map[key].items.push({
+      file: e.file, statement: e.statement, confidence: e.confidence,
+      last_accessed: e.last_accessed, updated: e.updated,
+    });
+  }
   return groups;
 }
+function renderProfileText(owner, groups) {
+  const lines = [];
+  lines.push('# 用户画像（' + owner + '）');
+  lines.push('');
+  lines.push('> 生成: yotta-memory profile | 引擎零推断：以下为私密记忆原文的结构化归组，画像结论由承载 AI 依据「记忆守则」在内部形成，不当面贴标签。');
+  lines.push('> 刷新: ' + today());
+  lines.push('');
+  for (const g of (groups || [])) {
+    lines.push('## ' + g.type + ' · ' + (g.subject || '（无主题）') + (g.tags.length ? '  [tags: ' + g.tags.join(', ') + ']' : ''));
+    lines.push('');
+    for (const it of g.items) {
+      const acc = it.last_accessed ? '最近访问 ' + it.last_accessed : '未访问';
+      lines.push('- ' + it.statement + '（confidence ' + it.confidence + ' · ' + acc + '）');
+      lines.push('  - ' + it.file);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
 function profileCore(opts) {
   opts = opts || {};
   const root = userRoot();
@@ -7511,23 +7536,7 @@ function profileCore(opts) {
   }
   const groups = profileGroups(root, owner);
   if (!groups.length) return { error: false, text: '该智能体（' + owner + '）暂无画像：private/' + owner + '/ 下无 PREF / BOUND / COMMIT 条目。' };
-  const lines = [];
-  lines.push('# 用户画像（' + owner + '）');
-  lines.push('');
-  lines.push('> 生成: yotta-memory profile | 引擎零推断：以下为私密记忆原文的结构化归组，画像结论由承载 AI 依据「记忆守则」在内部形成，不当面贴标签。');
-  lines.push('> 刷新: ' + today());
-  lines.push('');
-  for (const g of groups) {
-    lines.push('## ' + g.type + ' · ' + (g.subject || '（无主题）') + (g.tags.length ? '  [tags: ' + g.tags.join(', ') + ']' : ''));
-    lines.push('');
-    for (const it of g.items) {
-      const acc = it.last_accessed ? '最近访问 ' + it.last_accessed : '未访问';
-      lines.push('- ' + it.statement + '（confidence ' + it.confidence + ' · ' + acc + '）');
-      lines.push('  - ' + it.file);
-    }
-    lines.push('');
-  }
-  const text = lines.join('\n');
+  const text = renderProfileText(owner, groups);
   const outFile = writeProfileText(root, owner, text + '\n');
   return { error: false, text: text + '\n\n[已写入] ' + outFile };
 }
@@ -7566,6 +7575,25 @@ function compareContextRecent(a, b) {
 const MEMORY_HOOK_MAX_CANDIDATES = 500;
 const MEMORY_HOOK_STATEMENT_LIMIT = 2000;
 
+function contextEntryLine(entry) {
+  return '- [' + entry.type + '] ' + entry.subject + ': ' + entry.statement;
+}
+
+function isSelfProfileEntry(entry, owner) {
+  if (!entry || entry.type !== 'PREF' || entry.subject !== SELF_PROFILE_SUBJECT) return false;
+  if (owner && entry.owner && entry.owner !== owner) return false;
+  const file = String(entry.file || '').replace(/\\/g, '/');
+  return owner ? file.indexOf('private/' + owner + '/prefs/') === 0 : false;
+}
+
+function contextPageableEntries(readableEntries, owner) {
+  return (readableEntries || [])
+    .filter(function (entry) {
+      return entry.type !== 'BOUND' && entry.type !== 'COMMIT' && !isSelfProfileEntry(entry, owner);
+    })
+    .sort(compareContextRecent);
+}
+
 function hookBlock(status, providerId, note) {
   return {
     status: status || 'not_installed',
@@ -7590,6 +7618,130 @@ function hookStatusText(hook) {
   return hook.status;
 }
 
+function pagingBlock(status, providerId, note) {
+  return {
+    status: status || 'not_installed',
+    provider_id: providerId || '',
+    applied: false,
+    dropped: [],
+    ordered: [],
+    truncated: false,
+    budget: 0,
+    used: 0,
+    note: note || '',
+  };
+}
+
+function pagingStatusText(paging) {
+  if (!paging) return '';
+  if (paging.status === 'active') {
+    const who = paging.provider_id ? '提供方 ' + paging.provider_id : '提供方';
+    return '已应用（' + who + '；丢弃 ' + paging.dropped.length + ' / 排序 ' + paging.ordered.length + '）';
+  }
+  if (paging.status === 'license_required') return '需授权（该能力需要授权后使用；普通记忆不受影响）';
+  if (paging.status === 'timeout') return '未生效（提供方超时，已回落普通记忆）';
+  if (paging.status === 'invalid_output') return '未生效（提供方输出无效，已回落普通记忆）';
+  if (paging.status === 'error') return '未生效（提供方异常，已回落普通记忆）';
+  return '';
+}
+
+function pagingCandidatePayload(entry, baselineSection) {
+  return {
+    file: entry.file,
+    type: entry.type,
+    subject: entry.subject,
+    statement: String(entry.statement || '').slice(0, MEMORY_HOOK_STATEMENT_LIMIT),
+    created: entry.created || '',
+    updated: entry.updated || '',
+    chars: contextEntryLine(entry).length,
+    baseline_section: baselineSection || 'high_value',
+  };
+}
+
+function applyContextPaging(pageable, opts, meta) {
+  opts = opts || {};
+  meta = meta || {};
+  const budget = parseInt(opts.budget || 0, 10) || 0;
+  if (budget <= 0) {
+    return {
+      block: pagingBlock('not_requested', '', '未传 --budget，未调用 context.paging'),
+      drop: new Set(),
+      order: null,
+      applied: false,
+    };
+  }
+  const block = pagingBlock('not_installed', '', '');
+  block.budget = budget;
+  const truncated = pageable.length > MEMORY_HOOK_MAX_CANDIDATES;
+  block.truncated = truncated;
+  const candidates = pageable.slice(0, MEMORY_HOOK_MAX_CANDIDATES);
+  const payload = {
+    agent: opts.owner || '',
+    budget: budget,
+    focus: opts.focus || '',
+    truncated: truncated,
+    protected: Array.isArray(meta.protected) ? meta.protected.slice() : [],
+    sections: meta.sections || {},
+    candidates: candidates.map(function (entry) {
+      return pagingCandidatePayload(entry, (meta.baselineSections || {})[entry.file]);
+    }),
+  };
+  let run;
+  try {
+    run = require('./provider').runCapability('context.paging', payload);
+  } catch (e) {
+    block.status = 'error';
+    block.note = '预算分页失败：' + e.message;
+    return { block: block, drop: new Set(), order: null, applied: false };
+  }
+  block.status = run.status;
+  block.provider_id = run.provider_id || '';
+  block.note = run.note || run.message || '';
+  if (run.status !== 'active' || !run.data || typeof run.data !== 'object') {
+    return { block: block, drop: new Set(), order: null, applied: false };
+  }
+  const sent = new Set(payload.candidates.map(function (item) { return item.file; }));
+  const rejected = [];
+  const dropped = [];
+  for (const item of (Array.isArray(run.data.drop) ? run.data.drop : [])) {
+    const file = String(item || '');
+    if (!file) continue;
+    if (!sent.has(file)) {
+      if (rejected.indexOf(file) === -1) rejected.push(file);
+      continue;
+    }
+    if (dropped.indexOf(file) === -1) dropped.push(file);
+  }
+  let order = null;
+  if (Array.isArray(run.data.order)) {
+    if (run.data.complete === true && !truncated) {
+      const picked = [];
+      for (const item of run.data.order) {
+        const file = String(item || '');
+        if (!file) continue;
+        if (!sent.has(file)) {
+          if (rejected.indexOf(file) === -1) rejected.push(file);
+          continue;
+        }
+        if (picked.indexOf(file) === -1) picked.push(file);
+      }
+      order = picked;
+    } else if (truncated) {
+      block.note = block.note || '候选超过 ' + MEMORY_HOOK_MAX_CANDIDATES + '，order 未应用（保护）';
+    } else {
+      block.note = block.note || 'provider 未声明 complete=true，order 未应用（保护）';
+    }
+  }
+  if (rejected.length) {
+    const text = '候选集外文件已忽略：' + rejected.join(', ');
+    block.note = block.note ? block.note + '；' + text : text;
+  }
+  block.dropped = dropped;
+  block.ordered = order || [];
+  block.applied = dropped.length > 0 || (order !== null && order.length > 0);
+  return { block: block, drop: new Set(dropped), order: order, applied: block.applied };
+}
+
 /**
  * memory.hook 装载点：只把「可驱逐」条目（非 BOUND / COMMIT）交给 provider。
  * provider 只能返回本次候选集内的 evict（驱逐清单）；complete=true 时可选 selected（白名单）。
@@ -7598,9 +7750,7 @@ function hookStatusText(hook) {
  */
 function applyMemoryHook(readableEntries, opts) {
   const block = hookBlock('not_installed', '', '');
-  const pageable = readableEntries
-    .filter(function (entry) { return entry.type !== 'BOUND' && entry.type !== 'COMMIT'; })
-    .sort(compareContextRecent);
+  const pageable = contextPageableEntries(readableEntries, opts.owner || '');
   const truncated = pageable.length > MEMORY_HOOK_MAX_CANDIDATES;
   const payload = {
     agent: opts.owner || '',
@@ -7665,6 +7815,25 @@ function applyMemoryHook(readableEntries, opts) {
   return { block: block, evict: new Set(evicted), selected: selected };
 }
 
+function replaceContextProfileSection(lines, profileText, fence) {
+  const start = lines.indexOf('## 2. 用户画像摘要');
+  if (start === -1) return false;
+  const marker = lines.indexOf('## 2.5 长期理解摘要');
+  const end = marker === -1 ? lines.length : marker;
+  if (end < start) return false;
+  const block = ['## 2. 用户画像摘要', ''];
+  if (profileText) {
+    block.push(fence + 'markdown');
+    block.push(String(profileText).trim());
+    block.push(fence);
+  } else {
+    block.push('（该身份暂无画像；可运行 yotta-memory profile 生成）');
+  }
+  block.push('');
+  lines.splice.apply(lines, [start, end - start].concat(block));
+  return true;
+}
+
 function contextCore(opts) {
   opts = opts || {};
   const roots = memoryRoots();
@@ -7698,6 +7867,7 @@ function contextCore(opts) {
   const lines = [];
   const shownFiles = new Set();
   const usedFiles = new Set();
+  let usedDynamicChars = 0;
   const FENCE = String.fromCharCode(96, 96, 96);
   function usedChars() { return lines.reduce(function (s, x) { return s + String(x).length + 1; }, 0); }
   function appendContextEntry(entry, reason, options) {
@@ -7707,7 +7877,7 @@ function contextCore(opts) {
       trace.push('[dropped] ' + entry.file + ' reason: duplicate');
       return false;
     }
-    const line = '- [' + entry.type + '] ' + entry.subject + ': ' + entry.statement;
+    const line = contextEntryLine(entry);
     if (options.budget !== false && budget > 0 && usedChars() + line.length > budget) {
       trace.push('[dropped] ' + entry.file + ' reason: budget_exceeded');
       return false;
@@ -7715,6 +7885,7 @@ function contextCore(opts) {
     lines.push(line);
     shownFiles.add(entry.file);
     usedFiles.add(entry.file);
+    usedDynamicChars += line.length;
     trace.push('[included] ' + entry.file + ' reason: ' + reason);
     return true;
   }
@@ -7784,19 +7955,124 @@ function contextCore(opts) {
     if (memHook.evict.has(entry.file)) return false;
     return true;
   }
+  let focusedEntries = [];
+  if (focus) {
+    const focused = recallCore(focus, {
+      limit: limit,
+      owner: owner,
+      unsafe: unsafe,
+      selfAgent: selfAgent,
+      years: years,
+      embedding: embeddingCommand,
+      embeddingTimeout: embeddingTimeout,
+      noUsage: true
+    });
+    focusedEntries = focused.entries || [];
+  }
+  const pageable = contextPageableEntries(readableEntries, owner).filter(hookAllows);
+  const summaryLimit = Math.min(3, Math.max(0, limit));
+  const summaryCandidates = pageable.filter(isConsolidatedSummary).slice(0, summaryLimit);
+  const summaryFiles = new Set(summaryCandidates.map(function (entry) { return entry.file; }));
+  const pageableFiles = new Set(pageable.map(function (entry) { return entry.file; }));
+  const focusCandidates = focusedEntries.filter(function (entry) {
+    return hookAllows(entry) && pageableFiles.has(entry.file);
+  });
+  const focusFiles = new Set(focusCandidates.map(function (entry) { return entry.file; }));
+  const corridorCandidates = pageable
+    .filter(function (entry) {
+      return !isConsolidatedSummary(entry) && !summaryFiles.has(entry.file) && !focusFiles.has(entry.file);
+    })
+    .slice(0, limit);
+  const corridorFiles = new Set(corridorCandidates.map(function (entry) { return entry.file; }));
+  const highValueCandidates = pageable
+    .filter(function (entry) {
+      return !isConsolidatedSummary(entry) && !summaryFiles.has(entry.file) && !focusFiles.has(entry.file) && !corridorFiles.has(entry.file);
+    })
+    .map(function (entry) { return { e: entry, s: 0.5 * importanceScore(entry) + 0.5 * utilityScore(entry) }; })
+    .sort(function (a, b) { return b.s - a.s; })
+    .slice(0, limit)
+    .map(function (item) { return item.e; });
+  const baselineSections = {};
+  function markBaseline(entries, section) {
+    for (const entry of entries) baselineSections[entry.file] = section;
+  }
+  markBaseline(summaryCandidates, 'summary');
+  markBaseline(focusCandidates, 'focus');
+  markBaseline(corridorCandidates, 'corridor');
+  markBaseline(highValueCandidates, 'high_value');
+  const paging = applyContextPaging(pageable, {
+    owner: owner,
+    budget: budget,
+    focus: focus,
+    limit: limit,
+  }, {
+    protected: readableEntries
+      .filter(function (entry) { return isSelfProfileEntry(entry, owner); })
+      .map(function (entry) { return entry.file; }),
+    sections: {
+      summary: summaryCandidates.map(function (entry) { return entry.file; }),
+      focus: focusCandidates.map(function (entry) { return entry.file; }),
+      corridor: corridorCandidates.map(function (entry) { return entry.file; }),
+      high_value: highValueCandidates.map(function (entry) { return entry.file; }),
+    },
+    baselineSections: baselineSections,
+  });
+  const pagingState = paging.block;
+  const pagingOrder = new Map();
+  for (let i = 0; i < pagingState.ordered.length; i++) pagingOrder.set(pagingState.ordered[i], i);
+  function pagingAllows(entry) {
+    return !entry || !paging.drop.has(entry.file);
+  }
+  function decisionAllows(entry) {
+    return hookAllows(entry) && pagingAllows(entry);
+  }
+  function pagingOrderIndex(entry) {
+    if (!entry || !pagingOrder.has(entry.file)) return Number.MAX_SAFE_INTEGER;
+    return pagingOrder.get(entry.file);
+  }
+  function compareWithPaging(a, b, fallback) {
+    const byOrder = pagingOrderIndex(a) - pagingOrderIndex(b);
+    if (byOrder !== 0) return byOrder;
+    return fallback(a, b);
+  }
+  if ((hookState.applied || pagingState.applied) && owner) {
+    const liveGroups = profileGroupsFromEntries(
+      readableEntries
+        .filter(function (entry) { return entry.type === 'PREF' || entry.type === 'BOUND' || entry.type === 'COMMIT'; })
+        .filter(decisionAllows)
+    );
+    replaceContextProfileSection(lines, renderProfileText(owner, liveGroups), FENCE);
+    trace.push('[profile] source: live reason: ' + (hookState.applied ? 'memory.hook' : 'context.paging'));
+  }
+  const statusLines = [];
   if (hookState.status !== 'not_installed') {
-    const anchor = lines.indexOf('## 1. 身份');
-    lines.splice(anchor === -1 ? 2 : anchor, 0, '- 扩展装载（memory.hook）: ' + hookStatusText(hookState), '');
+    statusLines.push('- 扩展装载（memory.hook）: ' + hookStatusText(hookState));
     trace.push('[hook] status: ' + hookState.status
       + ' provider: ' + (hookState.provider_id || '-')
       + ' evicted: ' + hookState.evicted.length
       + ' dropped: ' + hookState.dropped.length);
   }
+  const pagingText = pagingStatusText(pagingState);
+  if (pagingText) {
+    statusLines.push('- 预算分页（context.paging）: ' + pagingText);
+    trace.push('[paging] status: ' + pagingState.status
+      + ' provider: ' + (pagingState.provider_id || '-')
+      + ' dropped: ' + pagingState.dropped.length
+      + ' ordered: ' + pagingState.ordered.length
+      + ' truncated: ' + (pagingState.truncated ? 'true' : 'false'));
+  }
+  if (statusLines.length) {
+    const anchor = lines.indexOf('## 1. 身份');
+    statusLines.push('');
+    lines.splice.apply(lines, [anchor === -1 ? 2 : anchor, 0].concat(statusLines));
+  }
 
   lines.push('## 2.5 长期理解摘要');
   lines.push('');
-  const summaries = readableEntries.filter(isConsolidatedSummary).filter(hookAllows).sort(compareContextRecent);
-  const summaryLimit = Math.min(3, Math.max(0, limit));
+  const summaries = readableEntries
+    .filter(isConsolidatedSummary)
+    .filter(decisionAllows)
+    .sort(function (a, b) { return compareWithPaging(a, b, compareContextRecent); });
   if (!summaries.length) lines.push('（暂无周期摘要；可用 yotta-memory consolidate --apply 生成）');
   for (const e of summaries.slice(0, summaryLimit)) {
     appendContextEntry(e, 'summary_priority', { budget: false });
@@ -7806,19 +8082,11 @@ function contextCore(opts) {
   if (focus) {
     lines.push('## 2.6 任务相关记忆（--focus）');
     lines.push('');
-    const focused = recallCore(focus, {
-      limit: limit,
-      owner: owner,
-      unsafe: unsafe,
-      selfAgent: selfAgent,
-      years: years,
-      embedding: embeddingCommand,
-      embeddingTimeout: embeddingTimeout,
-      noUsage: true
-    });
-    const focusedEntries = focused.entries || [];
     if (!focusedEntries.length) lines.push('（无匹配记忆）');
-    for (const e of focusedEntries.filter(hookAllows)) {
+    const focusedVisible = focusedEntries
+      .filter(decisionAllows)
+      .sort(function (a, b) { return compareWithPaging(a, b, function () { return 0; }); });
+    for (const e of focusedVisible) {
       appendContextEntry(e, 'focus_match score: ' + round3(e.score));
     }
     lines.push('');
@@ -7828,8 +8096,8 @@ function contextCore(opts) {
   lines.push('');
   const corridor = readableEntries
     .filter(function (e) { return !isConsolidatedSummary(e) && e.type !== 'BOUND' && e.type !== 'COMMIT'; })
-    .sort(compareContextRecent)
-    .filter(hookAllows)
+    .filter(decisionAllows)
+    .sort(function (a, b) { return compareWithPaging(a, b, compareContextRecent); })
     .filter(function (e) { return !shownFiles.has(e.file); })
     .slice(0, limit);
   if (!corridor.length) lines.push('（暂无近期记忆）');
@@ -7839,9 +8107,9 @@ function contextCore(opts) {
   lines.push('## 4. 近期高价值记忆（补位）');
   lines.push('');
   const highValue = readableEntries
-    .filter(function (e) { return !isConsolidatedSummary(e) && e.type !== 'BOUND' && e.type !== 'COMMIT' && !shownFiles.has(e.file) && hookAllows(e); })
+    .filter(function (e) { return !isConsolidatedSummary(e) && e.type !== 'BOUND' && e.type !== 'COMMIT' && !shownFiles.has(e.file) && decisionAllows(e); })
     .map(function (e) { return { e: e, s: 0.5 * importanceScore(e) + 0.5 * utilityScore(e) }; })
-    .sort(function (a, b) { return b.s - a.s; })
+    .sort(function (a, b) { return compareWithPaging(a.e, b.e, function (x, y) { return y.s - x.s; }); })
     .slice(0, limit);
   if (!highValue.length) lines.push('（暂无补位条目）');
   for (const h of highValue) appendContextEntry(h.e, 'high_value_backfill');
@@ -7899,13 +8167,14 @@ function contextCore(opts) {
     for (const message of reliability.warnings) lines.push('- [警告] ' + message);
     if (!reliability.ok) lines.push('- 破坏性写入已锁定：先运行 yotta-memory doctor 修复严重问题。');
   }
-  return { error: false, exitCode: 0, text: lines.join('\n'), trace: trace, hook: hookState };
+  pagingState.used = usedDynamicChars;
+  return { error: false, exitCode: 0, text: lines.join('\n'), trace: trace, hook: hookState, paging: pagingState };
 }
 function cmdContext(opts) {
   const r = contextCore(opts);
   if (opts.json) {
     if (r.report) console.log(JSON.stringify(r.report, null, 2));
-    else console.log(JSON.stringify({ schema: 1, hook: r.hook || null, text: r.text }, null, 2));
+    else console.log(JSON.stringify({ schema: 1, hook: r.hook || null, paging: r.paging || null, text: r.text }, null, 2));
   } else {
     console.log(r.text);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Yuanyi (元忆) — boundary-aware, file-based memory for AI agents. File-based, zero-dependency, diff/rollback-able; FACT/PREF/BOUND/COMMIT types (public shared / private isolated), user-level + project-level storage; v0.12 reliability baseline (init guard, trash-based deletion, independent-volume backup/list/doctor/restore, start-of-work doctor, transactional snapshots before destructive writes), v0.10 consolidation (periodic summaries with provenance, near-duplicate auto-merge, per-type decay, batch audit + rollback), v0.9 recall quality + context focus + optional local embedding plugin, plus v0.8 semantic search, feedback loop, self-organization and distillation.",
   "license": "MIT",
   "keywords": [

package/references/provider-protocol.md

@@ -1,8 +1,13 @@
-# 扩展提供方协议 v1（元忆 · capability `memory.hook`）
+# 扩展提供方协议 v1.1（元忆 · capability `memory.hook` / `context.paging`）
 
 元忆可以可选地调用一个由用户显式配置的**本地扩展提供方（provider）**，由它参与「哪些记忆进上下文」。
 未配置提供方时，`context` 的行为与输出与之前完全一致；任何失败都回落到普通记忆，不阻断命令。
 
+本版协议包含两个 capability：
+
+- `memory.hook`：在装配前过滤候选集（`evict` / `selected`）。
+- `context.paging`：在用户显式传 `--budget` 时，对已通过 `memory.hook` 的候选集做排序与分页（`drop` / `order`）。
+
 ## 1. 配置
 
 配置文件：`<YOTTA_PROVIDER_HOME>/provider.json`，默认 `~/.yottameta/provider.json`。
@@ -15,7 +20,7 @@
     {
       "id": "local-provider",
       "version": "0.1.0",
-      "capabilities": ["memory.hook"],
+      "capabilities": ["memory.hook", "context.paging"],
       "command": ["node", "C:/path/to/provider.js"],
       "timeout_ms": 600
     }
@@ -69,7 +74,7 @@
 
 - **`evict`（推荐）**：要从上下文里驱逐的条目清单。每个 `file` 必须出现在本次 `candidates` 中；候选集外的 file 会被丢弃并记入 `dropped`。未见过的条目默认保留 —— 候选很多时也安全。
 - **`selected`（可选白名单）**：仅在 `complete: true` 且本次未 `truncated` 时接受。每个 `file` 必须 ∈ `candidates`；未列入的候选会被驱逐。
-- 元忆侧仍强制执行：BOUND / COMMIT 与身份画像不可驱逐；预算、去重、宽限、章节顺序由引擎决定。
+- 元忆侧仍强制执行：BOUND / COMMIT 与自我接入档案不可驱逐；`## 1. 身份` 段落不受影响，画像中的其它条目随条目一并参与驱逐；预算、去重、宽限、章节顺序由引擎决定。
 
 需要授权或不可用时：
 
@@ -91,7 +96,73 @@
 `context --json` 的 `hook` 块给出 `status` / `provider_id` / `applied` / `evicted` / `dropped` / `note`；
 `context --explain` 的 trace 里追加一行 `[hook] ...`。
 
-## 5. 审计与边界
+## 5. `context.paging`（v1.1 新增）
+
+### 5.1 调用时机
+
+- 仅在用户显式执行 `context` 且传了 `--budget`（大于 0）时调用；不传预算不调用，状态为 `not_requested`。
+- 调用顺序：`memory.hook` 先过滤，`context.paging` 再排序 / 分页。
+- 候选集与 `memory.hook` 同源：权限过滤后、去掉 BOUND / COMMIT / 自我接入档案；最多 500 条。
+- `context.paging` 不能覆盖引擎硬约束：身份段落、自我接入档案、BOUND / COMMIT 不参与；最终字符预算仍由元忆引擎强制。
+
+### 5.2 请求
+
+```json
+{
+  "schema": 1,
+  "capability": "context.paging",
+  "request_id": "<uuid>",
+  "payload": {
+    "agent": "codex",
+    "budget": 4000,
+    "focus": "",
+    "truncated": false,
+    "protected": ["private/codex/prefs/2026-08-25-0001.md"],
+    "sections": {
+      "summary": ["<file>"],
+      "focus": ["<file>"],
+      "corridor": ["<file>"],
+      "high_value": ["<file>"]
+    },
+    "candidates": [
+      {
+        "file": "facts/2026/09/2026-09-29-0001.md",
+        "type": "FACT",
+        "subject": "示例主题",
+        "statement": "示例内容（最多 2000 字）",
+        "created": "2026-09-29",
+        "updated": "2026-09-29",
+        "chars": 128,
+        "baseline_section": "corridor"
+      }
+    ]
+  }
+}
+```
+
+- `sections` 是引擎基线的分段落位，供 provider 参考，不构成约束。
+- `protected` 列出引擎硬保护、不可驱逐的文件（如自我接入档案）。
+
+### 5.3 响应
+
+```json
+{ "ok": true, "capability": "context.paging", "data": {
+  "drop": ["<file>"],
+  "order": ["<file>", "<file>"],
+  "complete": true
+} }
+```
+
+- `drop`：明确分页出去的条目，任意子集，**始终应用**；候选集外文件只记 note，不进入输出。
+- `order`：期望的进入顺序，**仅在 `complete: true` 且本次未 `truncated` 时应用**；未列入的候选按引擎基线顺序补尾，不丢内容。
+- 候选超过 500（`truncated=true`）时只接受 `drop`，`order` 不应用并写入 note。
+
+### 5.4 状态与回落
+
+`context --json` 的 `paging` 块给出 `status` / `provider_id` / `applied` / `dropped` / `ordered` / `truncated` / `budget` / `used` / `note`；
+`context --explain` 的 trace 里追加一行 `[paging] ...`。未配置 / 未声明该 capability 时为 `not_installed`；未传 `--budget` 时为 `not_requested`；授权失败 / 超时 / 非法输出 / 异常均回落普通上下文，不影响既有记忆。
+
+## 6. 审计与边界
 
 - 每次实际调用写一行 `<YOTTA_PROVIDER_HOME>/provider-audit.jsonl`：`ts` / `capability` / `provider_id` / `status` / `duration_ms` / `bytes_out`。
 - 审计**不记录**记忆正文、查询原文或任何 payload 内容。

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-memory",
   "name": "元忆",
   "package": "@yottameta/yotta-memory",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "trust": "yottameta",
   "install": {
     "idempotent": true