@yottameta/yotta-memory 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 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` 非法只记状态、不阻断。
+- `context --json` 输出结构化 JSON（`schema` / `hook` / `text`）；此前该参数回落为文本。
+- 扩展调用只写本地审计元数据（`provider-audit.jsonl`：capability / 状态 / 耗时 / 字节数），不含 payload 正文。
+
 ## v0.18.1 (2026-09-27)
 
 第二波 P2：蒸馏溯源链 + 分类型提取 / 相对日期绝对化 + 巩固标记 / 重复踩坑 → 规则晋升建议 / 权威顺序与写入纪律（文档）。

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,6 +22,7 @@
 </p>
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.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.18.1
+version: 0.20.0
 license: MIT
 ---
 
@@ -36,6 +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.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

@@ -0,0 +1,249 @@
+'use strict';
+
+// 扩展提供方（provider）装载器 v1：外部子进程 + stdin/stdout JSON。
+// 设计：docs/路线B-P1-接口预留设计-2026-09-28.md（根仓库）；对外协议：references/provider-protocol.md。
+// 零依赖；未配置 / 任何失败都 fail-open 回开源基线，不阻断调用方。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const SCHEMA = 1;
+const DEFAULT_TIMEOUT_MS = 600;
+const MAX_TIMEOUT_MS = 5000;
+const MIN_TIMEOUT_MS = 50;
+const MAX_STDOUT_BYTES = 256 * 1024;
+const KNOWN_CAPABILITIES = ['o1.route', 'm1.adjudicate', 'memory.hook', 'context.paging'];
+
+function providerHome() {
+  const fromEnv = process.env.YOTTA_PROVIDER_HOME;
+  if (fromEnv && String(fromEnv).trim()) return path.resolve(String(fromEnv).trim());
+  return path.join(os.homedir(), '.yottameta');
+}
+
+function configPath() {
+  return path.join(providerHome(), 'provider.json');
+}
+
+function validateProvider(item) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return 'provider 条目必须是对象';
+  if (!item.id || typeof item.id !== 'string') return 'provider 缺 id';
+  if (!Array.isArray(item.capabilities) || !item.capabilities.length) return 'provider ' + item.id + ' 缺 capabilities';
+  for (const capability of item.capabilities) {
+    if (KNOWN_CAPABILITIES.indexOf(capability) === -1) return 'provider ' + item.id + ' 含未知 capability：' + capability;
+  }
+  if (!Array.isArray(item.command) || !item.command.length) return 'provider ' + item.id + ' 的 command 必须是数组';
+  for (const part of item.command) {
+    if (typeof part !== 'string' || !part) return 'provider ' + item.id + ' 的 command 含非法参数';
+    if (part.indexOf('\0') !== -1) return 'provider ' + item.id + ' 的 command 含非法字符';
+  }
+  if (item.timeout_ms !== undefined && (!Number.isFinite(item.timeout_ms) || item.timeout_ms <= 0)) {
+    return 'provider ' + item.id + ' 的 timeout_ms 非法';
+  }
+  return '';
+}
+
+function normalizeProvider(item) {
+  return {
+    id: item.id,
+    version: typeof item.version === 'string' ? item.version : '',
+    capabilities: item.capabilities.slice(),
+    command: item.command.slice(),
+    timeout_ms: Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.round(item.timeout_ms || DEFAULT_TIMEOUT_MS))),
+  };
+}
+
+function readConfig() {
+  const file = configPath();
+  if (!fs.existsSync(file)) return { status: 'not_installed', providers: [], error: '' };
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { status: 'error', providers: [], error: 'provider.json 解析失败：' + e.message };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { status: 'error', providers: [], error: 'provider.json 必须是对象' };
+  }
+  if (raw.schema !== SCHEMA) {
+    return { status: 'error', providers: [], error: 'provider.json schema 不支持：' + String(raw.schema) };
+  }
+  if (!Array.isArray(raw.providers)) {
+    return { status: 'error', providers: [], error: 'provider.json providers 必须是数组' };
+  }
+  const providers = [];
+  for (const item of raw.providers) {
+    const invalid = validateProvider(item);
+    if (invalid) return { status: 'error', providers: [], error: invalid };
+    providers.push(normalizeProvider(item));
+  }
+  return { status: 'ok', providers, error: '' };
+}
+
+function pickProvider(config, capability) {
+  if (!config || config.status !== 'ok') return null;
+  for (const item of config.providers) {
+    if (item.capabilities.indexOf(capability) !== -1) return item;
+  }
+  return null;
+}
+
+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) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  env.YOTTA_PROVIDER_HOME = providerHome();
+  return env;
+}
+
+function requestId() {
+  try {
+    if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  } catch (e) {
+    // 回退到随机 hex
+  }
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function invokeProvider(provider, capability, payload) {
+  const started = Date.now();
+  const request = {
+    schema: SCHEMA,
+    capability,
+    request_id: requestId(),
+    payload: payload || {},
+  };
+  let proc;
+  try {
+    proc = spawnSync(provider.command[0], provider.command.slice(1), {
+      input: JSON.stringify(request),
+      encoding: 'utf8',
+      timeout: provider.timeout_ms,
+      maxBuffer: MAX_STDOUT_BYTES,
+      shell: false,
+      cwd: providerHome(),
+      env: minimalEnv(),
+      windowsHide: true,
+    });
+  } catch (e) {
+    return {
+      status: 'error',
+      provider_id: provider.id,
+      duration_ms: Date.now() - started,
+      note: 'provider 启动失败：' + e.message,
+    };
+  }
+  const duration = Date.now() - started;
+  if (proc.error) {
+    const code = proc.error.code || '';
+    const timedOut = code === 'ETIMEDOUT';
+    const oversize = code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
+    return {
+      status: timedOut ? 'timeout' : 'error',
+      provider_id: provider.id,
+      duration_ms: duration,
+      note: timedOut
+        ? 'provider 超时'
+        : (oversize
+          ? 'provider 输出超过 ' + MAX_STDOUT_BYTES + ' 字节'
+          : 'provider 执行失败：' + (code || proc.error.message || 'unknown')),
+    };
+  }
+  if (proc.status !== 0) {
+    return {
+      status: 'error',
+      provider_id: provider.id,
+      duration_ms: duration,
+      note: 'provider 退出码非 0：' + proc.status,
+    };
+  }
+  let response;
+  try {
+    response = JSON.parse(String(proc.stdout || '').trim() || '{}');
+  } catch (e) {
+    return { status: 'invalid_output', provider_id: provider.id, duration_ms: duration, note: 'provider 输出不是 JSON' };
+  }
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    return { status: 'invalid_output', provider_id: provider.id, duration_ms: duration, note: 'provider 输出不是对象' };
+  }
+  if (response.ok === false) {
+    const code = typeof response.code === 'string' && response.code ? response.code : 'provider_error';
+    return {
+      status: code === 'license_required' ? 'license_required' : 'error',
+      provider_id: provider.id,
+      code,
+      message: typeof response.message === 'string' ? response.message : '',
+      duration_ms: duration,
+      note: typeof response.message === 'string' ? response.message : code,
+    };
+  }
+  if (response.ok !== true) {
+    return { status: 'invalid_output', provider_id: provider.id, duration_ms: duration, note: 'provider 响应缺 ok 字段' };
+  }
+  return {
+    status: 'active',
+    provider_id: provider.id,
+    data: response.data,
+    duration_ms: duration,
+    bytes_out: Buffer.byteLength(String(proc.stdout || ''), 'utf8'),
+    note: '',
+  };
+}
+
+function appendAudit(entry) {
+  try {
+    const home = providerHome();
+    fs.mkdirSync(home, { recursive: true });
+    fs.appendFileSync(
+      path.join(home, 'provider-audit.jsonl'),
+      JSON.stringify(Object.assign({ schema: SCHEMA, ts: new Date().toISOString() }, entry)) + '\n',
+      'utf8',
+    );
+  } catch (e) {
+    // 审计失败不影响调用
+  }
+}
+
+function runCapability(capability, payload) {
+  const config = readConfig();
+  if (config.status === 'not_installed') {
+    return { status: 'not_installed', provider_id: '', note: '未配置扩展提供方' };
+  }
+  if (config.status === 'error') {
+    return { status: 'error', provider_id: '', note: config.error };
+  }
+  const provider = pickProvider(config, capability);
+  if (!provider) {
+    return { status: 'not_installed', provider_id: '', note: '未配置声明 ' + capability + ' 的提供方' };
+  }
+  const result = invokeProvider(provider, capability, payload);
+  appendAudit({
+    capability,
+    provider_id: result.provider_id,
+    status: result.status,
+    duration_ms: result.duration_ms,
+    bytes_out: result.bytes_out || 0,
+  });
+  return result;
+}
+
+module.exports = {
+  SCHEMA,
+  DEFAULT_TIMEOUT_MS,
+  MAX_TIMEOUT_MS,
+  MAX_STDOUT_BYTES,
+  KNOWN_CAPABILITIES,
+  providerHome,
+  configPath,
+  readConfig,
+  pickProvider,
+  runCapability,
+};

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.18.1';
+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']);
 
@@ -210,6 +210,7 @@ const HELP_MODEL = [
       helpOption('--audit', '', '审计被压缩掉的内容是否已经落盘', '宿主压缩上下文后，想确认有没有决策只存在于对话里时', '只读：只打印 remember 建议，不会自动补写'),
       helpOption('--from', '<文件|->', '指定待审计内容（- 表示标准输入）', '把宿主压缩摘要或丢弃段落喂给审计时', '不传时审计当前上下文包的丢弃清单'),
       helpOption('--limit', '<条数>', '限制近期记忆条数', '上下文太长、想缩短时', ''),
+      helpOption('--json', '', '输出结构化 JSON（hook 块 + text）', '脚本读取上下文包或扩展装载状态时', '未配置扩展提供方时也返回 JSON'),
       helpOption('--owner', '<id>', '指定 owner 范围', '需要看某个 owner 的上下文时', '仍然受私密区权限约束'),
       helpOption('--budget', '<字符数>', '设置动态记忆字符预算', '需要控制上下文包大小时', '0 表示不限制'),
       helpOption('--focus', '<关键词>', '按当前任务聚焦', '这次任务很明确、想优先拉相关记忆时', ''),
@@ -7459,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();
@@ -7510,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 };
 }
@@ -7561,6 +7571,269 @@ function compareContextRecent(a, b) {
   if (byTime !== 0) return byTime;
   return (b.access_count || 0) - (a.access_count || 0);
 }
+
+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',
+    provider_id: providerId || '',
+    applied: false,
+    evicted: [],
+    dropped: [],
+    note: note || '',
+  };
+}
+
+function hookStatusText(hook) {
+  if (!hook) return '';
+  if (hook.status === 'active') {
+    const who = hook.provider_id ? '提供方 ' + hook.provider_id : '提供方';
+    return '已应用（' + who + '；驱逐 ' + hook.evicted.length + ' / 丢弃 ' + hook.dropped.length + '）';
+  }
+  if (hook.status === 'license_required') return '需授权（该能力需要授权后使用；普通记忆不受影响）';
+  if (hook.status === 'timeout') return '未生效（提供方超时，已回落普通记忆）';
+  if (hook.status === 'invalid_output') return '未生效（提供方输出无效，已回落普通记忆）';
+  if (hook.status === 'error') return '未生效（提供方异常，已回落普通记忆）';
+  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（白名单）。
+ * 身份画像、BOUND / COMMIT、预算 / 去重 / 宽限始终由引擎掌控；任何失败都走普通记忆。
+ * 协议见 references/provider-protocol.md。
+ */
+function applyMemoryHook(readableEntries, opts) {
+  const block = hookBlock('not_installed', '', '');
+  const pageable = contextPageableEntries(readableEntries, opts.owner || '');
+  const truncated = pageable.length > MEMORY_HOOK_MAX_CANDIDATES;
+  const payload = {
+    agent: opts.owner || '',
+    budget: opts.budget || 0,
+    focus: opts.focus || '',
+    truncated: truncated,
+    candidates: pageable.slice(0, MEMORY_HOOK_MAX_CANDIDATES).map(function (entry) {
+      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 || '',
+      };
+    }),
+  };
+  let run;
+  try {
+    run = require('./provider').runCapability('memory.hook', payload);
+  } catch (e) {
+    block.status = 'error';
+    block.note = '扩展装载失败：' + e.message;
+    return { block: block, evict: new Set(), selected: null };
+  }
+  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, evict: new Set(), selected: null };
+  }
+  const sent = new Set(payload.candidates.map(function (item) { return item.file; }));
+  const evicted = [];
+  for (const item of (Array.isArray(run.data.evict) ? run.data.evict : [])) {
+    const file = String(item || '');
+    if (!file) continue;
+    if (!sent.has(file)) {
+      block.dropped.push(file);
+      continue;
+    }
+    if (evicted.indexOf(file) === -1) evicted.push(file);
+  }
+  let selected = null;
+  if (Array.isArray(run.data.selected) && run.data.complete === true && !truncated) {
+    const picked = [];
+    for (const item of run.data.selected) {
+      const file = String(item || '');
+      if (!file) continue;
+      if (!sent.has(file)) {
+        block.dropped.push(file);
+        continue;
+      }
+      if (picked.indexOf(file) === -1) picked.push(file);
+    }
+    selected = new Set(picked);
+  }
+  block.evicted = evicted;
+  block.applied = evicted.length > 0 || selected !== null;
+  if (truncated && Array.isArray(run.data.selected)) {
+    block.note = block.note || '候选超过 ' + MEMORY_HOOK_MAX_CANDIDATES + '，白名单模式未应用（保护）';
+  }
+  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();
@@ -7594,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) {
@@ -7603,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;
@@ -7611,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;
   }
@@ -7672,19 +7947,16 @@ function contextCore(opts) {
     }
   }
 
-  lines.push('## 2.5 长期理解摘要');
-  lines.push('');
-  const summaries = readableEntries.filter(isConsolidatedSummary).sort(compareContextRecent);
-  const summaryLimit = Math.min(3, Math.max(0, limit));
-  if (!summaries.length) lines.push('（暂无周期摘要；可用 yotta-memory consolidate --apply 生成）');
-  for (const e of summaries.slice(0, summaryLimit)) {
-    appendContextEntry(e, 'summary_priority', { budget: false });
+  const memHook = applyMemoryHook(readableEntries, { owner: owner, budget: budget, focus: focus, limit: limit });
+  const hookState = memHook.block;
+  function hookAllows(entry) {
+    if (!entry) return false;
+    if (memHook.selected && !memHook.selected.has(entry.file)) return false;
+    if (memHook.evict.has(entry.file)) return false;
+    return true;
   }
-  lines.push('');
-
+  let focusedEntries = [];
   if (focus) {
-    lines.push('## 2.6 任务相关记忆（--focus）');
-    lines.push('');
     const focused = recallCore(focus, {
       limit: limit,
       owner: owner,
@@ -7695,9 +7967,126 @@ function contextCore(opts) {
       embeddingTimeout: embeddingTimeout,
       noUsage: true
     });
-    const focusedEntries = focused.entries || [];
+    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') {
+    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(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 });
+  }
+  lines.push('');
+
+  if (focus) {
+    lines.push('## 2.6 任务相关记忆（--focus）');
+    lines.push('');
     if (!focusedEntries.length) lines.push('（无匹配记忆）');
-    for (const e of focusedEntries) {
+    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('');
@@ -7707,7 +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(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('（暂无近期记忆）');
@@ -7717,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); })
+    .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');
@@ -7777,12 +8167,17 @@ 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 };
+  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 && r.report) console.log(JSON.stringify(r.report, null, 2));
-  else console.log(r.text);
+  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, paging: r.paging || null, text: r.text }, null, 2));
+  } else {
+    console.log(r.text);
+  }
   if (r.error) {
     const reminder = migrationReminderText(userRoot());
     if (reminder) console.log('\n' + reminder);
@@ -11078,6 +11473,7 @@ module.exports = {
   profileCore: profileCore,
   contextCore: contextCore,
   contextAuditCore: contextAuditCore,
+  applyMemoryHook: applyMemoryHook,
   importanceScore: importanceScore,
   usageSettings: usageSettings,
   usageTotals: usageTotals,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.18.1",
+  "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

@@ -0,0 +1,171 @@
+# 扩展提供方协议 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`。
+环境变量 `YOTTA_PROVIDER_HOME` 可覆盖根目录（测试与隔离环境用）。
+
+```json
+{
+  "schema": 1,
+  "providers": [
+    {
+      "id": "local-provider",
+      "version": "0.1.0",
+      "capabilities": ["memory.hook", "context.paging"],
+      "command": ["node", "C:/path/to/provider.js"],
+      "timeout_ms": 600
+    }
+  ]
+}
+```
+
+- `command` 必须是**数组**（argv 语义），以 `shell: false` 执行；不接受字符串命令。
+- `timeout_ms` 默认 600，最小 50，最大 5000；超时即回落。
+- 配置文件缺失、解析失败、`command` 非数组、capability 未知：**只记录状态，不阻断命令**；缺失等同「未安装」。
+
+## 2. 调用
+
+- 只在用户显式执行 `context`（或 `context --json` / `--explain`）时触发；`init` / `install` / `doctor` / `scan` 等路径不触发。
+- 元忆把**一个 JSON 请求**写入 provider 的 stdin（随后关闭），从 stdout 读**一个 JSON 响应**；stderr 只作诊断。
+- stdout 上限 256 KB；超过按错误处理并回落。
+- 请求与环境：
+
+```json
+{
+  "schema": 1,
+  "capability": "memory.hook",
+  "request_id": "<uuid>",
+  "payload": {
+    "agent": "codex",
+    "budget": 0,
+    "focus": "",
+    "truncated": false,
+    "candidates": [
+      {
+        "file": "facts/2026/09/2026-09-27-0001.md",
+        "type": "FACT",
+        "subject": "示例主题",
+        "statement": "示例内容（最多 2000 字）",
+        "created": "2026-09-27",
+        "updated": "2026-09-27"
+      }
+    ]
+  }
+}
+```
+
+- `candidates` 只包含**调用者有权读取**、且**可驱逐**的条目（已过滤私密越权项；BOUND / COMMIT 不在其中）。
+- 候选最多 500 条；超过时 `truncated = true`，此时白名单模式不生效（见 §3），驱逐模式仍安全。
+
+## 3. 响应
+
+```json
+{ "ok": true, "capability": "memory.hook", "data": { "evict": ["facts/2026/09/2026-09-27-0001.md"] } }
+```
+
+- **`evict`（推荐）**：要从上下文里驱逐的条目清单。每个 `file` 必须出现在本次 `candidates` 中；候选集外的 file 会被丢弃并记入 `dropped`。未见过的条目默认保留 —— 候选很多时也安全。
+- **`selected`（可选白名单）**：仅在 `complete: true` 且本次未 `truncated` 时接受。每个 `file` 必须 ∈ `candidates`；未列入的候选会被驱逐。
+- 元忆侧仍强制执行：BOUND / COMMIT 与自我接入档案不可驱逐；`## 1. 身份` 段落不受影响，画像中的其它条目随条目一并参与驱逐；预算、去重、宽限、章节顺序由引擎决定。
+
+需要授权或不可用时：
+
+```json
+{ "ok": false, "code": "license_required", "message": "该能力需要授权后使用" }
+```
+
+## 4. 状态与回落
+
+| 状态 | 触发 | 元忆行为 |
+| --- | --- | --- |
+| `not_installed` | 无配置 / 无匹配 capability | 普通记忆，输出与历史一致 |
+| `active` | 调用成功且响应合法 | 在约束内应用 `evict` / `selected` |
+| `license_required` | provider 明确返回该 code | 普通记忆 + 一行状态提示 |
+| `timeout` | 超过 `timeout_ms` | 普通记忆 + 一行状态提示 |
+| `invalid_output` | 非 JSON / 缺 `ok` | 普通记忆 + 一行状态提示 |
+| `error` | 启动失败 / 退出码非 0 / 输出超限 / 配置非法 | 普通记忆 + 一行状态提示 |
+
+`context --json` 的 `hook` 块给出 `status` / `provider_id` / `applied` / `evicted` / `dropped` / `note`；
+`context --explain` 的 trace 里追加一行 `[hook] ...`。
+
+## 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 内容。
+- 元忆不替 provider 联网；provider 自身行为由它自己的包声明。
+- 删除 `provider.json` 即回到普通记忆，无残留依赖。
+- provider 输出只当数据使用：候选集外的条目、非白名单内容一律丢弃，不作为指令执行。

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-memory",
   "name": "元忆",
   "package": "@yottameta/yotta-memory",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "trust": "yottameta",
   "install": {
     "idempotent": true
@@ -12,7 +12,7 @@
     "filesystem": "user-skills-dir",
     "network": "none",
     "process": "child-process",
-    "note": "只调用本包内 Node 引擎读写本地记忆库；默认不联网。"
+    "note": "只调用本包内 Node 引擎读写本地记忆库；默认不联网；仅在用户显式配置扩展提供方（provider.json）时按其配置调用本地子进程。"
   },
   "auto_apply": {
     "mode": "hook",