memory-organ-trainer

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,  # 两条记忆 cosine > 此值 → 合并保留较强者
    max_age_days=30.0,            # 从未被访问且超过30天 → 软删除
)

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)
# 每次对话结束后 tick，满 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 读取对应该步骤的最新架构说明。