| name | memory-organ-trainer |
| description | Memory Organ Module 全自动训练技能。Use when: 需要训练记忆器官模块、生成记忆训练数据、运行记忆模块评估、运行记忆增强推理演示、初始化 transformer+ 项目环境、执行睯眠整合、调试遗忘规则、管理用户记忆动力学。Triggers: 记忆器官训练、memory organ、记忆模块训练、memory training、一键训练、全流程训练、睯眠整合、遗忘规则、session状态、LambdaNet、Qwen2.5-3B、14个文件最新1: 查看分析projectmd/plan-2.0.3.md和analyzeProject |
Memory Organ Module — 自动训练技能
路由决策表
| 用户意图 | 执行命令 | 前置条件 |
|---|
| "初始化项目" / "setup" / "检查环境" | python scripts/check_env.py → python scripts/setup_project.py | 无 |
| "生成训练数据" / "generate data" | python scripts/generate_data.py [--num-profiles N] [--sessions-per-user M] | 项目已初始化 |
| "开始训练" / "train" / "全阶段训练" | python scripts/run_training.py --phase all | 数据已生成 |
| "只训练融合" / "phase a" | python scripts/run_training.py --phase a | 数据已生成 |
| "只训练写入门控" / "phase b" | python scripts/run_training.py --phase b | Phase A checkpoint 存在 |
| "端到端微调" / "phase c" | python scripts/run_training.py --phase c | Phase B checkpoint 存在 |
| "评估" / "evaluate" | python scripts/run_eval.py | checkpoint 存在 |
| "evaluate autoregressive" / "check AR metrics" / "AR 评估" | python scripts/run_eval.py --metric ar | checkpoint 存在 |
| "演示" / "demo" / "对话测试" | python scripts/run_demo.py | checkpoint 存在 |
| "执行睡眠整合" / "sleep consolidation" | 调用 SleepConsolidation.run() | MemoryStore 已初始化 |
| "执行遗忘规则" / "forget gate" | 调用 MemoryStore.apply_forget_rules() | MemoryStore 已初始化 |
| "检查数据完整性" / "verify data" | 读取 data/stats.json，检查 write_target_coverage >= 0.99 | 数据已生成 |
| "全流程" / "一键完成" | 按序执行以下所有步骤 | 无 |
全流程执行步骤（一键模式）
按顺序执行，每步完成后调用 #tool:vscode_askQuestions 确认继续：
Step 1: 环境检查
python scripts/check_env.py
若出现阻断性错误（缺包、磁盘不足），先修复再继续。
Step 2: 项目初始化
python scripts/setup_project.py
Step 3: 生成训练数据
python scripts/generate_data.py --num-profiles 100 --sessions-per-user 5 --output-dir data/
完成后读取 data/stats.json 并报告统计摘要。
- 检查
write_target_coverage >= 0.99（若 < 0.95 应警告并重新生成）
- 确认
write_turns / total_turns 比例在 10%-20% 合理范围内
Step 4: 执行训练
python scripts/run_training.py --config config/default_config.yaml --phase all
监控输出：若 loss 出现 NaN，停止并报告；若训练正常，报告最终 loss 摘要。
Step 5: 评估（诚实评估门 — TF + AR 双指标）
python scripts/run_eval.py --checkpoint latest --metric all
python scripts/run_eval.py --checkpoint latest --metric ar
读取 outputs/eval_report.json，报告各指标。
诚实评估规范：
- 同时展示 TF (Teacher-Forcing) 和 AR (Autoregressive) 指标，清楚标注
[TF] / [AR]
- AR 指标是唯一真实指标，TF 指标仅作训练过程参考
- 若 AR 指标与 TF 指标偏差 > 50%，标红警告："⚠️ 评估可能不可靠 — TF/AR 偏差过大"
- PASS/FAIL 门控阈值：记忆召回 > 70%，已知数据：AR ReadGate 激活阈值待降低优化
- 回归检测：与上次最优指标比较，>10% 回归则报警（历史存储于
outputs/metric_history.json）
已知 AR-ReadGate 失效问题：
v2.0.3 实测中 ReadGate 在 AR 模式激活率为 0（阈值小面积为 0.3，实际输出约 0.05~0.25）。Memory Influence KL=3.66 确认记忆确实影响 prefill 分布。BLEU/ROUGE/Token Diversity 偏低是 AR ReadGate 激活阈值面题，非模型失败。评估时请注明此背景。
Step 6: 推理演示
python scripts/run_demo.py --non-interactive
报告演示通过率。
新增组件使用规范
P2 — 遗忘机制
ForgetGate 启发式规则（MemoryStore 内置，无训练成本）：
stats = store.apply_forget_rules(
strength_threshold=0.05,
cosine_merge_threshold=0.95,
max_age_days=30.0,
)
LambdaNet 可学习衰减（src/memory/lambda_net.py）：
- 将
LambdaNet 实例加入 optimizer，传入 MemoryStore.search(lambda_net=...) 即可启用 MLP λ
- 不传入时退化为固定
decay_lambda=1e-6（向后兼容）
P3 — 睡眠整合周期
from src.memory.sleep_consolidation import SleepConsolidation
sleep = SleepConsolidation(store, session_interval=50)
stats = sleep.tick()
stats = sleep.run()
SleepStats 包含：clusters_merged、low_utility_deleted、forget_rule_* 三项计数。
P4 — SessionState 内部记忆
- 由
MemoryAugmentedModel 内部自动管理，训练时无需额外操作
forward() 不需要 user_id_strings 参数（已移除多用户隔离）- session 结束时手动调用
model.session_state.reset() 清零状态
- 如需禁用（回退到纯外部记忆）：
MemoryAugmentedModel(enable_session_state=False)
- SessionState 已纳入 checkpoint 保存/加载，跨训练阶段状态不丢失
Phase A/C 全局 memory bank
- Phase A（记忆融合）和 Phase C（端到端微调）使用跨 profile 全局 memory bank
- 每个 epoch 开始时随机 shuffle 并采样
global_memory_bank_size（默认200）条向量
- 提升检索任务难度，避免 per-batch 小 bank 导致的过拟合
- 在训练日志中查找
[GlobalBank] N vectors from M profiles 确认生效
- Phase B（写入门控）继续使用 per-batch 小 bank，确保精确 GT 对齐
- 配置项：
training.global_memory_bank_size（见 config/default_config.yaml）
错误处理
| 错误现象 | 可能原因 | 解决方案 |
|---|
ValueError: encoder_model=None 时默认不允许... | 构建 MemoryDataset 未传入 encoder_model | 传入 encoder_model=model.base_model 或 debug_mode=True（仅调试） |
write_target_coverage < 0.95 | conversation_generator 生成数据有问题 | 重新生成数据，检查 should_write=True 的 turn 是否有 write_target_memory_index |
PPL 评估中 encoder_model=None ValueError | evaluate.py 未传入 encoder | 已在 evaluate.py 中修复，传入 model.base_model |
| TF 指标优秀但 AR 指标极差（偏差 > 50%） | 训练-推理分布漂移 | 检查 Scheduled Sampling 是否启用；验证 prefill-once 融合；运行 --metric ar 确认 |
| AR Token Diversity < 0.1 | 退化为重复 token | 检查 temperature/top_p 参数；确认 repetition_penalty > 1.0 |
| CUDA out of memory | Qwen2.5-3B bf16 显存占用约 6 GB，评估区段各需独立进程 | 评估使用 --metric 单项分批运行；BATCH_SIZE=2；添加 torch.no_grad() |
NativeCommandError（Windows Tee-Object） | PowerShell 管道 stderr 冲突 | 使用 Start-Process -WindowStyle Hidden -RedirectStandardOutput log -RedirectStandardError err |
MemoryFusion 双路融合
MemoryFusion.forward() 新增 session_state 可选参数：
- 传入时同时融合外部记忆（cross-attention）和 session 状态（门控注入）
- 不传入时（
None）退化为纯外部记忆模式，向后兼容 Phase A/B 训练
错误处理规范
- ModuleNotFoundError: 运行
pip install -r requirements.txt 重试
- CUDA out of memory: 自动降低 batch_size（16→8→4）重试
- FileNotFoundError（数据文件）: 提示用户先执行 Step 3 生成数据
- FileNotFoundError（checkpoint）: 提示用户先执行 Step 4 训练
- loss = NaN: 检查
config.py 中 LR 是否过大，建议降至 1e-5
- WriteGate F1 < 30%: 检查
losses.py 中 pos_weight 是否为 6.0（已默认修复）
- OMP Error #137（Windows）: 在命令前设置
$env:OMP_NUM_THREADS="1" 限制线程数
用户确认规范
每个步骤完成后，必须调用 #tool:vscode_askQuestions 询问用户是否继续。
在执行任何新步骤前，先从 projectmd/newFramework.md 读取对应该步骤的最新架构说明。
