dsh-prime-memory 0.21.0 → 0.22.2

package/dist/stats.js

@@ -19,6 +19,7 @@ import { effectiveCfg } from './pipeline/runner.js';
 import { emptyRecallStats } from './hooks/recall.js';
 import { buildRouteChain, decideSendableEffort, LAYER_DEFAULT_BUDGETS, layerChainOrNull, resolveModelContextWindow, resolveModelEfforts, resolveModelRoute } from './llm.js';
 import { mergeRoom, renameRoom } from './room-review.js';
+import { scanSources } from './memport/scan.js';
 import { projectDistillChain, validateDistillChain } from './settings.js';
 import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from './store/receipts.js';
 import { getTraceStore } from './store/trace.js';
@@ -33,6 +34,7 @@ import { isWingCorner } from './store/session-modes.js';
 import { startWingBackfill } from './wing-backfill.js';
 import { errDetail } from './util/filelog.js';
 import { snapshotTokenCost } from './token-cost.js';
+import { computeMaturity } from './util/maturity.js';
 const require = createRequire(import.meta.url);
 export const PLUGIN_VERSION = require('../package.json').version;
 /**
@@ -93,6 +95,13 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/cleanup-retired',
     'dsh-memory/snapshots-list',
     'dsh-memory/snapshot-restore',
+    'dsh-memory/memory-sources-list',
+    'dsh-memory/memory-sources-add',
+    'dsh-memory/memory-sources-retire',
+    'dsh-memory/memport-scan',
+    'dsh-memory/skills-list',
+    'dsh-memory/session-recalled',
+    'dsh-memory/skills-action',
 ];
 /** HTTP 路由前缀(客户端 fetch `/dsh-memory/rpc/<短方法名>`)。 */
 const RPC_ROUTE_PREFIX = '/dsh-memory/rpc';
@@ -173,6 +182,8 @@ export function buildEndpointDeps(base, sources, controller) {
         sessionInfo: sources.sessionInfo,
         ruminate: controller,
         roomRegistry: sources.roomRegistry,
+        memorySources: sources.memorySources,
+        skillStore: sources.skillStore,
     };
     return { ...base, ...injected };
 }
@@ -180,7 +191,11 @@ export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes,
 /** 反刍控制器(存储降级时为 undefined):经 buildEndpointDeps 落入 deps.ruminate。 */
 ruminate, 
 /** Room 分类管理依赖(注册表;缺省 = rooms-get 不带 registry、rooms-export 恒 404 语义)。 */
-roomRegistry) {
+roomRegistry, 
+/** 外部来源注册表（轨3 Connect；经 buildEndpointDeps 落入 deps.memorySources）。 */
+memorySources, 
+/** 技能存储（轨2；经 buildEndpointDeps 落入 deps.skillStore）。 */
+skillStore) {
     /** 当前是否持有一段有效注册(dispose 完成后清空,允许服务重上线时重注册)。 */
     let holding = false;
     /** 当前 handle 绑定的 connection 实例(internal/service 第二参;用于识别实例替换)。 */
@@ -201,7 +216,7 @@ roomRegistry) {
                     const value = await handleEndpoint(endpoint, payload, buildEndpointDeps({ ctx, cfg, stores, logger }, 
                     // roomRegistry 必须随 sources 下发——漏带 = 面板侧 room-* 恒"未装配"
                     // (工具面直传不受影响;2026-10-02 beta.9 实测回归)
-                    { status, live, modes, dataDir, rebuild, embedManager, sessionInfo, roomRegistry }, ruminate));
+                    { status, live, modes, dataDir, rebuild, embedManager, sessionInfo, roomRegistry, memorySources, skillStore }, ruminate));
                     return { ok: true, value };
                 }
                 catch (err) {
@@ -349,7 +364,7 @@ function sanitizeSettings(s) {
 }
 /** 端点分发表(导出供测试直调:可精确注入 rebuild/ruminate 等可选控制器,验证 deps 接线)。 */
 export async function handleEndpoint(endpoint, payload, deps) {
-    const { cfg, stores, status, live, modes, dataDir, rebuild, ruminate, embedManager, sessionInfo, roomRegistry } = deps;
+    const { cfg, stores, status, live, modes, dataDir, rebuild, ruminate, embedManager, sessionInfo, roomRegistry, memorySources, skillStore } = deps;
     switch (endpoint) {
         case 'dsh-memory/stats':
             return buildStats(cfg, stores, status);
@@ -386,6 +401,21 @@ export async function handleEndpoint(endpoint, payload, deps) {
             };
             return v;
         }
+        case 'dsh-memory/session-recalled': {
+            // G-live：返回本会话（按 ownerId）已注入、尚未被压缩覆盖的召回记忆。
+            const p = (payload ?? {});
+            const sessionId = expectSessionId(p.sessionId);
+            const ids = stores.recalled?.list(sessionId) ?? [];
+            if (ids.length === 0)
+                return { sessionId, records: [] };
+            const halfLife = effectiveCfg(cfg, live).recall?.decayHalfLifeDays ?? 0;
+            const byId = new Map(stores.l1.getByIds(ids).map((r) => [r.id, r]));
+            const records = ids
+                .map((id) => byId.get(id))
+                .filter((r) => r !== undefined)
+                .map((r) => hitToUiRecord(r, { agingWeight: agingWeightOf(r.updatedAt, halfLife), usage: stores.usage?.get(r.id) ?? null }));
+            return { sessionId, records };
+        }
         case 'dsh-memory/session-mode-set': {
             if (!modes)
                 throw new Error('档位存储未初始化');
@@ -499,6 +529,150 @@ export async function handleEndpoint(endpoint, payload, deps) {
             };
             return v;
         }
+        // ── 轨3 外部记忆来源（Connect）：登记/列表/退役/只读扫描。整面默认关（cfg.memport.enabled）。
+        case 'dsh-memory/memory-sources-list': {
+            const enabled = cfg.memport?.enabled === true;
+            const v = {
+                sources: enabled && memorySources
+                    ? memorySources.list().map((e) => ({
+                        id: e.id,
+                        kind: e.kind,
+                        path: e.path,
+                        label: e.label,
+                        lastScanAt: e.lastScanAt,
+                        lastImportAt: e.lastImportAt,
+                        disabled: e.disabled,
+                        status: e.status,
+                    }))
+                    : [],
+                memoryMutate: live?.get().memoryMutate === true,
+            };
+            return v;
+        }
+        case 'dsh-memory/memory-sources-add': {
+            if (cfg.memport?.enabled !== true)
+                throw new Error('外部记忆来源未启用（config memport.enabled）。');
+            if (!memorySources)
+                throw new Error('外部来源注册表未装配（需要插件重载以初始化）。');
+            if (!live?.get().memoryMutate)
+                throw new Error('记忆写删未开放：请在记忆库面板开启「高权限模式」后才能登记外部来源。');
+            const p = (payload ?? {});
+            const r = await memorySources.register({
+                id: String(p.id ?? '').trim(),
+                kind: String(p.kind ?? 'file') ?? 'file',
+                path: String(p.path ?? '').trim(),
+                label: typeof p.label === 'string' ? p.label : undefined,
+            });
+            const v = {
+                id: r.entry.id,
+                created: r.created,
+                notice: r.created ? '已登记来源。' : '来源已存在（已按新 path/label 原地更新）。',
+            };
+            return v;
+        }
+        case 'dsh-memory/memory-sources-retire': {
+            if (cfg.memport?.enabled !== true)
+                throw new Error('外部记忆来源未启用（config memport.enabled）。');
+            if (!memorySources)
+                throw new Error('外部来源注册表未装配（需要插件重载以初始化）。');
+            if (!live?.get().memoryMutate)
+                throw new Error('记忆写删未开放：请在记忆库面板开启「高权限模式」后才能管理外部来源。');
+            const p = (payload ?? {});
+            const changed = await memorySources.setStatus(String(p.id ?? '').trim(), p.active === true ? 'active' : 'retired');
+            const v = {
+                changed,
+                notice: !changed
+                    ? '未找到该来源。'
+                    : p.active === true
+                        ? '已恢复来源。'
+                        : '已退役来源（不删已导入数据；来源路径与 ext_key 仍在，可重放）。',
+            };
+            return v;
+        }
+        case 'dsh-memory/memport-scan': {
+            if (cfg.memport?.enabled !== true) {
+                const v = { enabled: false, sources: [], notice: '外部记忆扫描未启用（config memport.enabled）。' };
+                return v;
+            }
+            if (!memorySources) {
+                const v = { enabled: true, sources: [], notice: '外部来源注册表未装配。' };
+                return v;
+            }
+            const p = (payload ?? {});
+            const all = memorySources.listEnabled();
+            const targets = p.sourceId ? all.filter((e) => e.id === p.sourceId) : all;
+            const maxRecords = cfg.memport?.scanMaxRecords ?? 5000;
+            // 只读扫描：不写库（写走 memory_import）。逐个标扫描时间（失败不影响预览）。
+            const sources = await scanSources({ sources: targets, l1: stores.l1, maxRecords });
+            const nowIso = new Date().toISOString();
+            for (const s of targets)
+                await memorySources.markScanned(s.id, nowIso);
+            const v = { enabled: true, sources };
+            return v;
+        }
+        // ── 轨2 技能（SkillsTab）：列表 + 人工审阅动作（晋升/归档/pin/改档）。整面默认关（cfg.skills.enabled）。
+        case 'dsh-memory/skills-list': {
+            const enabled = cfg.skills?.enabled === true || live?.get().skillsEnabled === true;
+            const v = {
+                enabled,
+                allowPromote: cfg.skills?.allowPromote === true,
+                memoryMutate: live?.get().memoryMutate === true,
+                skills: enabled && skillStore
+                    ? skillStore.list().map((s) => ({
+                        id: s.id,
+                        title: s.title,
+                        status: s.status,
+                        tier: s.injectionTier,
+                        pinned: s.pinned,
+                        sessionCount: skillStore.sessionCount(s.id),
+                        updatedAt: s.updatedAt,
+                    }))
+                    : [],
+            };
+            return v;
+        }
+        case 'dsh-memory/skills-action': {
+            if (!(cfg.skills?.enabled === true || live?.get().skillsEnabled === true))
+                throw new Error('技能功能未启用（在概览页开启「技能」开关，或 config skills.enabled）。');
+            if (!skillStore)
+                throw new Error('技能存储未装配。');
+            if (!live?.get().memoryMutate)
+                throw new Error('记忆写删未开放：请在记忆库面板开启「高权限模式」后才能管理技能。');
+            const p = (payload ?? {});
+            const id = String(p.id ?? '').trim();
+            if (!id)
+                throw new Error('id 不能为空');
+            const minSessions = cfg.skills.minSessions;
+            const v = { changed: false, notice: '' };
+            if (p.action === 'promote') {
+                // 人工审阅晋升：不受自动闸 allowPromote 约束，但仍需证据达阈（不凭空的晋升）。
+                if (skillStore.sessionCount(id) < minSessions)
+                    return { changed: false, notice: `证据会话数不足（<${minSessions}），暂不能晋升。` };
+                const ok = await skillStore.tryPromote(id, minSessions, { allowPromote: true });
+                return { changed: ok, notice: ok ? '已晋升为 active。' : '未找到候选或状态已变。' };
+            }
+            if (p.action === 'archive') {
+                const ok = await skillStore.archive(id, String(p.reason ?? 'manual').slice(0, 120) || 'manual');
+                return { changed: ok, notice: ok ? '已归档（不再注入，可恢复）。' : '未找到或已归档。' };
+            }
+            if (p.action === 'pin') {
+                const ok = await skillStore.update(id, { pinned: true });
+                return { changed: ok, notice: ok ? '已固定。' : '未找到技能。' };
+            }
+            if (p.action === 'unpin') {
+                const ok = await skillStore.update(id, { pinned: false });
+                return { changed: ok, notice: ok ? '已取消固定。' : '未找到技能。' };
+            }
+            if (p.action === 'set-tier') {
+                const tier = p.tier === 'full' || p.tier === 'excerpt' || p.tier === 'hint' ? p.tier : null;
+                if (!tier)
+                    throw new Error('tier 非法（仅 full/excerpt/hint）');
+                const ok = await skillStore.update(id, { injectionTier: tier });
+                return { changed: ok, notice: ok ? `已设为 ${tier} 档。` : '未找到技能。' };
+            }
+            void v;
+            throw new Error(`未知 action: ${String(p.action)}`);
+        }
         case 'dsh-memory/room-register': {
             if (!roomRegistry)
                 throw new Error('Room 注册表未装配(需要插件重载以初始化)。');
@@ -812,6 +986,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     embedRemoteBaseURL: '', embedRemoteApiKey: '', embedRemoteModel: '', embedRemoteDimensions: 0,
                     memoryMutate: false,
                     conflictFreeze: live?.get()?.conflictFreeze === true,
+                    skillsEnabled: live?.get()?.skillsEnabled === true,
                 }),
                 // 静态部署上限(cordis.patch.yml):运行时开关与它取 AND
                 ceilings: { capture: cfg.capture.enabled, distill: cfg.extract.enabled, recall: cfg.recall.enabled },
@@ -850,7 +1025,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const patch = (payload ?? {});
             const clean = {};
             // 布尔开关组:memoryMutate(高权限写删门)与主开关同列;conflictFreeze(§C 人工冲突裁决)
-            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate', 'conflictFreeze', 'toolRoom', 'toolGraph', 'toolRuminate', 'toolConflict', 'toolMutate']) {
+            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate', 'conflictFreeze', 'skillsEnabled', 'toolRoom', 'toolGraph', 'toolRuminate', 'toolConflict', 'toolMutate']) {
                 if (typeof patch[key] === 'boolean')
                     clean[key] = patch[key];
             }
@@ -1107,7 +1282,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
             // (live.conflictFreeze 覆盖静态 cfg.conflictFreeze.enabled)。此前这里直接读
             // cfg.conflictFreeze.enabled —— 面板开关写的是 live,而部署静态值恒 false,
             // 于是开关已开、settings.yaml 已落 true,本页仍报"矛盾冻结未开启"。
-            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: effectiveCfg(cfg, live).conflictFreeze?.enabled === true }, { limit: Number(p.limit) || undefined });
+            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: effectiveCfg(cfg, live).conflictFreeze?.enabled === true, usage: stores.usage, decayHalfLifeDays: effectiveCfg(cfg, live).recall?.decayHalfLifeDays }, { limit: Number(p.limit) || undefined });
         }
         // ── §C 矛盾冻结裁决(task_25):与 memory_resolve_conflict 工具共用同一形状 ──
         // 端点层同样不给"提示文案"出口的例外只有一条:**队列未开启**不是调用错误而是
@@ -1714,6 +1889,10 @@ export function hitToUiRecord(r, extra) {
         retiredReason: retired ? (mark?.reason ?? 'unknown') : null,
         agingWeight: extra?.agingWeight ?? null,
         usage: extra?.usage ?? null,
+        // G3 成熟度：读时派生（priority + used + 老化），无额外端点/存储。
+        maturity: computeMaturity({ priority: r.priority ?? 60, usage: extra?.usage ?? null, agingWeight: extra?.agingWeight ?? null }),
+        // G1 使用场景：从命名空间保留键读出（功能关/无键 → undefined）。
+        usageScenario: Array.isArray(r.metadata?.dsh_usage_scenario) ? r.metadata?.dsh_usage_scenario : undefined,
     };
 }
 /**

package/dist/store/file-versions.d.ts

@@ -21,6 +21,8 @@ export declare const SESSION_MODES_FILE_VERSION = 1;
 export declare const OCCUPANCY_FILE_VERSION = 1;
 /** `recall-dedupe.json`。 */
 export declare const RECALL_DEDUPE_FILE_VERSION = 1;
+/** `session-recalled.json`（G-live 活召回集，持久化以令旧会话重开可读）。 */
+export declare const SESSION_RECALLED_FILE_VERSION = 1;
 /** `pending.json`。 */
 export declare const PENDING_FILE_VERSION = 1;
 /** `reconcile-state.json`。 */

package/dist/store/file-versions.js

@@ -21,6 +21,8 @@ export const SESSION_MODES_FILE_VERSION = 1;
 export const OCCUPANCY_FILE_VERSION = 1;
 /** `recall-dedupe.json`。 */
 export const RECALL_DEDUPE_FILE_VERSION = 1;
+/** `session-recalled.json`（G-live 活召回集，持久化以令旧会话重开可读）。 */
+export const SESSION_RECALLED_FILE_VERSION = 1;
 /** `pending.json`。 */
 export const PENDING_FILE_VERSION = 1;
 /** `reconcile-state.json`。 */

package/dist/store/l1.d.ts

@@ -142,6 +142,8 @@ export declare class L1Store {
     };
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
+    /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
+    findIdByExtKey(extKey: string): string | undefined;
     /**
      * §B 决策凭证落盘(L1Store 的薄缝)。
      * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增

package/dist/store/l1.js

@@ -229,6 +229,10 @@ export class L1Store {
     getByIds(ids) {
         return this.db.getL1ByIds(ids);
     }
+    /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
+    findIdByExtKey(extKey) {
+        return this.db.findRecordIdByExtKey(extKey);
+    }
     /**
      * §B 决策凭证落盘(L1Store 的薄缝)。
      * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增

package/dist/store/memory-sources.d.ts

@@ -0,0 +1,59 @@
+import type { MemoryLogger } from '../types.js';
+/** sidecar 版本常量（file-versions 同款集中纪律）。 */
+export declare const MEMORY_SOURCES_FILE_VERSION: 1;
+/** 已知外部 agent 来源类别（与 memport foreign-agent.md 对齐）；'file' = 任意路径。 */
+export declare const SOURCE_KINDS: readonly ["trae", "qoder", "codex", "claude", "workbuddy", "golutra", "cursor", "file"];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+export interface MemorySourceEntry {
+    /** 稳定 id（小写字母数字连字符）；扫描/导入按此归类、支持按来源撤销。 */
+    id: string;
+    kind: SourceKind;
+    /** 路径指针（绝对路径/目录），正文永不复制进来。 */
+    path: string;
+    label?: string;
+    /** 最近一次扫描时间（ISO）；未扫为空。 */
+    lastScanAt: string;
+    /** 最近一次导入时间（ISO）；未导入为空。 */
+    lastImportAt: string;
+    /** 用户临时停用（保留条目但不参与自动扫描；≠ 删除）。 */
+    disabled: boolean;
+    status: 'active' | 'retired';
+    createdAt: string;
+    updatedAt: string;
+}
+export type MemorySourceInput = Pick<MemorySourceEntry, 'id' | 'kind' | 'path'> & Partial<Pick<MemorySourceEntry, 'label'>>;
+export declare class MemorySourceStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private rev;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入（启动 await 一次）。缺失 = 合法空表；损坏 = 只读降级（回退"无来源"）。 */
+    init(): Promise<void>;
+    private ensureLoaded;
+    /** 全量条目（含 retired；副本返回，活引用纪律）。 */
+    list(): MemorySourceEntry[];
+    /** active 且未停用的来源（扫描/导入遍历用）。 */
+    listEnabled(): MemorySourceEntry[];
+    byId(id: string): MemorySourceEntry | undefined;
+    /** 登记来源（幂等：同 id 已存在则原地补全 kind/path/label，不新建）。上限防刷。 */
+    register(input: MemorySourceInput): Promise<{
+        entry: MemorySourceEntry;
+        created: boolean;
+    }>;
+    /** 记一次扫描时间。 */
+    markScanned(id: string, at: string): Promise<boolean>;
+    /** 记一次导入时间。 */
+    markImported(id: string, at: string): Promise<boolean>;
+    /** 启用/停用（停用保留条目、只是不参与自动扫描）。 */
+    setDisabled(id: string, disabled: boolean): Promise<boolean>;
+    /** 退役/恢复（status 迁移）。 */
+    setStatus(id: string, status: 'active' | 'retired'): Promise<boolean>;
+    private patch;
+    /** 写穿持久化（串行链；失败降级内存态并告警一次，绝不抛出阻塞调用方）。 */
+    private persist;
+}

package/dist/store/memory-sources.js

@@ -0,0 +1,214 @@
+/**
+ * 外部记忆来源注册表（轨3 Connect 路径的一等实体）。
+ *
+ * 动机：此前"其他 agent → 记忆库"的取内容路径只装配到 `memory_import` 这最后一寸，
+ * 前面十一寸（发现来源、记录来源、按来源管理）全外包给 skill 文本 + 用户手填路径。
+ * 本注册表把"来源"升为可持久、可枚举、可按来源撤销的一等实体。
+ *
+ * **路径指针不复制**（Connect 语义，援引 `slots.refs` 先例）：每条只存 `path` + 摘要，
+ * 正文**永不落进插件目录**——既是"移动房子家具先消毒"的卫生边界，也让带 ext_key 的
+ * 外部记忆"来源仍在、可重放"（可重建性显式化）。
+ *
+ * 存储：rooms-registry 同款 sidecar（`memory-sources.json`），全量载入内存 + 写穿原子持久化，
+ * `rev` 乐观计数。文件缺失 = 合法空表；损坏/不可读 → 告警 + 只读降级（内存态照常、停止回写），
+ * **绝不阻塞扫描/导入/面板**（降级即回退"无注册来源"，非破坏性）。上限防刷。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+/** sidecar 版本常量（file-versions 同款集中纪律）。 */
+export const MEMORY_SOURCES_FILE_VERSION = 1;
+/** 已知外部 agent 来源类别（与 memport foreign-agent.md 对齐）；'file' = 任意路径。 */
+export const SOURCE_KINDS = ['trae', 'qoder', 'codex', 'claude', 'workbuddy', 'golutra', 'cursor', 'file'];
+/** 来源上限（防刷；一个工作区通常 <20 个外部工具记忆落点）。 */
+const SOURCES_CAP = 100;
+const PATH_MAX = 500;
+const LABEL_MAX = 80;
+function isSourceId(s) {
+    return /^[a-z0-9][a-z0-9-]{0,63}$/.test(s);
+}
+function normKind(k) {
+    return SOURCE_KINDS.includes(String(k)) ? k : 'file';
+}
+export class MemorySourceStore {
+    logger;
+    file;
+    entries = [];
+    rev = 0;
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'memory-sources.json');
+    }
+    /** 载入（启动 await 一次）。缺失 = 合法空表；损坏 = 只读降级（回退"无来源"）。 */
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 外部来源注册表只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        if (read.value.version !== MEMORY_SOURCES_FILE_VERSION) {
+            this.logger?.warn(`[memory] 外部来源注册表版本 ${String(read.value.version)} 未知，按当前形状读取`);
+        }
+        const sources = Array.isArray(read.value.sources) ? read.value.sources : [];
+        for (const s of sources) {
+            if (!s || typeof s.id !== 'string' || !isSourceId(s.id))
+                continue; // 非法 id 丢弃
+            if (typeof s.path !== 'string' || !s.path)
+                continue; // 无路径指针的来源无意义，丢弃
+            this.entries.push({
+                id: s.id,
+                kind: normKind(s.kind),
+                path: s.path.slice(0, PATH_MAX),
+                label: typeof s.label === 'string' ? s.label : undefined,
+                lastScanAt: typeof s.lastScanAt === 'string' ? s.lastScanAt : '',
+                lastImportAt: typeof s.lastImportAt === 'string' ? s.lastImportAt : '',
+                disabled: s.disabled === true,
+                status: s.status === 'retired' ? 'retired' : 'active',
+                createdAt: typeof s.createdAt === 'string' ? s.createdAt : '',
+                updatedAt: typeof s.updatedAt === 'string' ? s.updatedAt : '',
+            });
+        }
+        this.rev = typeof read.value.rev === 'number' ? read.value.rev : 0;
+        this.loaded = true;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('外部来源注册表未初始化（先 await init()）');
+    }
+    /** 全量条目（含 retired；副本返回，活引用纪律）。 */
+    list() {
+        this.ensureLoaded();
+        return this.entries.map((e) => ({ ...e }));
+    }
+    /** active 且未停用的来源（扫描/导入遍历用）。 */
+    listEnabled() {
+        return this.list().filter((e) => e.status === 'active' && !e.disabled);
+    }
+    byId(id) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.id === id);
+        return found ? { ...found } : undefined;
+    }
+    /** 登记来源（幂等：同 id 已存在则原地补全 kind/path/label，不新建）。上限防刷。 */
+    async register(input) {
+        this.ensureLoaded();
+        const id = String(input.id ?? '').trim().toLowerCase();
+        if (!isSourceId(id))
+            throw new Error(`非法来源 id: ${String(input.id)}（小写字母数字连字符，≤64）`);
+        const p = String(input.path ?? '').trim();
+        if (!p)
+            throw new Error('来源 path 不能为空（路径指针不复制，但必须指向真实落点）');
+        if (p.length > PATH_MAX)
+            throw new Error(`来源 path 过长（>${PATH_MAX}）`);
+        const found = this.entries.find((e) => e.id === id);
+        if (found) {
+            let changed = false;
+            const kind = normKind(input.kind);
+            if (found.kind !== kind) {
+                found.kind = kind;
+                changed = true;
+            }
+            if (found.path !== p) {
+                found.path = p;
+                changed = true;
+            }
+            if (typeof input.label === 'string' && input.label.trim() && found.label !== input.label.trim().slice(0, LABEL_MAX)) {
+                found.label = input.label.trim().slice(0, LABEL_MAX);
+                changed = true;
+            }
+            if (found.status === 'retired') {
+                found.status = 'active';
+                changed = true;
+            }
+            if (changed) {
+                found.updatedAt = new Date().toISOString();
+                this.rev++;
+                await this.persist();
+            }
+            return { entry: { ...found }, created: false };
+        }
+        if (this.entries.length >= SOURCES_CAP)
+            throw new Error(`外部来源已达上限（${SOURCES_CAP}），请先退役部分来源`);
+        const now = new Date().toISOString();
+        const entry = {
+            id,
+            kind: normKind(input.kind),
+            path: p.slice(0, PATH_MAX),
+            label: typeof input.label === 'string' && input.label.trim() ? input.label.trim().slice(0, LABEL_MAX) : undefined,
+            lastScanAt: '',
+            lastImportAt: '',
+            disabled: false,
+            status: 'active',
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.entries.push(entry);
+        this.rev++;
+        await this.persist();
+        return { entry: { ...entry }, created: true };
+    }
+    /** 记一次扫描时间。 */
+    async markScanned(id, at) {
+        return this.patch(id, (e) => {
+            e.lastScanAt = at;
+        });
+    }
+    /** 记一次导入时间。 */
+    async markImported(id, at) {
+        return this.patch(id, (e) => {
+            e.lastImportAt = at;
+        });
+    }
+    /** 启用/停用（停用保留条目、只是不参与自动扫描）。 */
+    async setDisabled(id, disabled) {
+        return this.patch(id, (e) => {
+            e.disabled = disabled;
+        });
+    }
+    /** 退役/恢复（status 迁移）。 */
+    async setStatus(id, status) {
+        return this.patch(id, (e) => {
+            e.status = status;
+        });
+    }
+    async patch(id, mut) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.id === id);
+        if (!found)
+            return false;
+        mut(found);
+        found.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 写穿持久化（串行链；失败降级内存态并告警一次，绝不抛出阻塞调用方）。 */
+    async persist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(async () => {
+            const data = { version: MEMORY_SOURCES_FILE_VERSION, rev: this.rev + 1, sources: this.entries };
+            try {
+                await ensureDir(path.dirname(this.file));
+                await atomicWriteText(this.file, JSON.stringify(data, null, 2));
+                this.rev = data.rev;
+            }
+            catch (err) {
+                this.degraded = err instanceof Error ? err.message : String(err);
+                if (!this.degradedLogged) {
+                    this.degradedLogged = true;
+                    this.logger?.warn(`[memory] 外部来源注册表写入失败，只读降级: ${this.degraded}`);
+                }
+            }
+        });
+        await this.writeChain;
+    }
+}

package/dist/store/session-recalled.d.ts

@@ -0,0 +1,25 @@
+import type { MemoryLogger } from '../types.js';
+export declare class SessionRecalledStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private degraded;
+    private degradedLogged;
+    private lastPersisted;
+    private writeChain;
+    /** 脏检序号：每次真实变更 +1，投影 apply 据此 O(1) 判断是否重建。 */
+    private rev;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    revision(): number;
+    private init;
+    /** 记入本 sessionKey 本轮实际注入的记录 id（写穿；插入序淘汰最旧）。 */
+    add(sessionKey: string, recordIds: readonly string[]): void;
+    list(sessionKey: string): string[];
+    /** 压缩/清空：注入内容已离开上下文，清该会话活召回集（写穿）。 */
+    reset(sessionKey: string): void;
+    size(): number;
+    /** 等待在途持久化写完成（测试/停机）。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}