@yottameta/yotta-memory 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 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.zh-CN.md

@@ -22,6 +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.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.19.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.19.0）**：`context` 支持可选的本地扩展提供方（capability `memory.hook`）参与「哪些记忆进上下文」：提供方只能驱逐本次候选集内的条目；身份画像、BOUND / COMMIT、预算 / 去重 / 宽限仍由引擎掌控。未配置 / 未授权 / 超时 / 非法输出一律走普通记忆，输出不带扩展行；`context --json` 输出 `schema` / `hook` / `text`。配置与协议见 `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,248 @@
+'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',
+  ];
+  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.19.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', '<关键词>', '按当前任务聚焦', '这次任务很明确、想优先拉相关记忆时', ''),
@@ -7561,6 +7562,109 @@ 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 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;
+}
+
+/**
+ * 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 = readableEntries
+    .filter(function (entry) { return entry.type !== 'BOUND' && entry.type !== 'COMMIT'; })
+    .sort(compareContextRecent);
+  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 contextCore(opts) {
   opts = opts || {};
   const roots = memoryRoots();
@@ -7672,9 +7776,26 @@ function contextCore(opts) {
     }
   }
 
+  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;
+  }
+  if (hookState.status !== 'not_installed') {
+    const anchor = lines.indexOf('## 1. 身份');
+    lines.splice(anchor === -1 ? 2 : anchor, 0, '- 扩展装载（memory.hook）: ' + hookStatusText(hookState), '');
+    trace.push('[hook] status: ' + hookState.status
+      + ' provider: ' + (hookState.provider_id || '-')
+      + ' evicted: ' + hookState.evicted.length
+      + ' dropped: ' + hookState.dropped.length);
+  }
+
   lines.push('## 2.5 长期理解摘要');
   lines.push('');
-  const summaries = readableEntries.filter(isConsolidatedSummary).sort(compareContextRecent);
+  const summaries = readableEntries.filter(isConsolidatedSummary).filter(hookAllows).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)) {
@@ -7697,7 +7818,7 @@ function contextCore(opts) {
     });
     const focusedEntries = focused.entries || [];
     if (!focusedEntries.length) lines.push('（无匹配记忆）');
-    for (const e of focusedEntries) {
+    for (const e of focusedEntries.filter(hookAllows)) {
       appendContextEntry(e, 'focus_match score: ' + round3(e.score));
     }
     lines.push('');
@@ -7708,6 +7829,7 @@ function contextCore(opts) {
   const corridor = readableEntries
     .filter(function (e) { return !isConsolidatedSummary(e) && e.type !== 'BOUND' && e.type !== 'COMMIT'; })
     .sort(compareContextRecent)
+    .filter(hookAllows)
     .filter(function (e) { return !shownFiles.has(e.file); })
     .slice(0, limit);
   if (!corridor.length) lines.push('（暂无近期记忆）');
@@ -7717,7 +7839,7 @@ 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) && hookAllows(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; })
     .slice(0, limit);
@@ -7777,12 +7899,16 @@ 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 };
+  return { error: false, exitCode: 0, text: lines.join('\n'), trace: trace, hook: hookState };
 }
 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, 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 +11204,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.19.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,100 @@
+# 扩展提供方协议 v1（元忆 · capability `memory.hook`）
+
+元忆可以可选地调用一个由用户显式配置的**本地扩展提供方（provider）**，由它参与「哪些记忆进上下文」。
+未配置提供方时，`context` 的行为与输出与之前完全一致；任何失败都回落到普通记忆，不阻断命令。
+
+## 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"],
+      "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 与身份画像不可驱逐；预算、去重、宽限、章节顺序由引擎决定。
+
+需要授权或不可用时：
+
+```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. 审计与边界
+
+- 每次实际调用写一行 `<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.19.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",