#Memory User-Guide：5 分钟上手

本文聚焦"概念入门 + UI 导航"。深入设计原理见 025-the-memory-system.md；理论支撑见 026-memory-whitepaper.md；API 集成见 memory-integration.md。

#1. 一图认识 Memory 模块

#2. 6 类记忆类型

衰减率/权重定义见 apps/negentropy/src/negentropy/engine/governance/memory.py _MEMORY_TYPE_DECAY_RATES。

#2.5 高级特性（默认开箱即用）

5 个高级特性现已默认全部启用（开箱即用），并各自带运行时安全闸，必要时可一键关闭。详细工程契约见 025-the-memory-system.md §10 与 026-memory-whitepaper.md §4。

可观测性（默认开）：memory.observability.health_enabled / metrics_enabled → /memory/health（暴露当前生效的 hipporag/reflection/consolidation_steps/pii_engine）与 /memory/metrics（需 admin）。

#首次部署：安装 PII NER 模型

F4 Presidio 默认引擎依赖 spaCy NER 模型（独立下载产物，非 pip 依赖）。一键安装：

cd apps/negentropy && uv run negentropy bootstrap-pii-models   # 下载 en_core_web_lg + zh_core_web_sm

未安装时不阻断启动：PII 引擎按 allow_engine_fallback=true 自动降级回 regex（4 类正则），实际生效引擎可在 /memory/health 的 features.pii_engine 查看。

#逐特性验证清单（开箱即用走查）

#一键关闭 / 回退

在 config.default.yaml（或用户配置 / 环境变量）将对应 enabled 置 false：

memory:
  hipporag: { enabled: false }       # 即时回退纯 Hybrid
  reflection: { enabled: false }     # 已有反思记忆保留，不再生成新的
  relevance: { enabled: false }      # 读侧不再应用 relevance_weight
  consolidation: { legacy: true }    # 回到 Phase 4 硬编码两步（fact_extract + auto_link）
  pii: { engine: regex }             # 已有 pii_spans 保留；gatekeeper 仍按角色遮蔽

环境变量等价（优先级最高）：NE_MEMORY_HIPPORAG__ENABLED=false、NE_MEMORY_REFLECTION__ENABLED=false 等。

5 个特性的故障排除见 memory-troubleshooting.md §11~§14。

#3. UI 导航（5 个页面 + Scheduler）

所有页面源自 apps/negentropy-ui/app/memory/。 Activity（平台 Toast 通知历史）已迁移至 Home / Dashboard 底部，作为 localStorage 日志面板与后端 Execution Timeline 正交并列；详见 /dashboard。

#Retention 红绿灯

• 🟢 ≥ 50%：健康
• 🟠 ≥ 10%：将衰减
• 🔴 < 10%：候选清理（自动化任务会处理）

#Timeline 卡片视觉指南

每张记忆卡片展示以下信息层次：

1. 记忆类型标识（顶部左侧）：彩色 pill badge 区分 6 种记忆类型，颜色与 §2 衰减率表格对应——Core (violet)、Semantic (blue)、Episodic (amber)、Procedural (green)、Preference (pink)、Fact (cyan)
2. 双评分条（顶部右侧）：
   • Retention（Ret）：时间衰减指标，颜色逻辑同红绿灯（绿/琥珀/红）
   • Importance（Imp）：权重指标，blue ≥70% / cyan 40-70% / slate <40%
3. 内容区（中部）：默认展示前 150 字符，超长内容可点击"展开全文"查看完整内容
4. 元数据底栏（底部）：访问次数、上次访问相对时间、创建日期

时间线按日期分组（Today / Yesterday / 具体日期），便于定位特定时段的记忆。

参考文献：Park et al. (2023) importance/recency/relevance 三维评分；Zep (2025) 时间分组与双时间戳；Hu et al. (2026) factual/experiential/working 记忆分类法。

#PII 锁标

• 🔒 表示 metadata.pii_flags / pii_spans 命中（默认 Presidio 引擎）
• 命中类型：email / phone / id_card / credit_card / person / location 等（Presidio NER 识别人名、地名等 regex 无法覆盖的类别；中文手机号 / 身份证由 CN 自定义识别器补强）
• 检索侧：gatekeeper_enabled=true（需手动开启）时，低于 acl_role_threshold（默认 editor）的角色看到 content 经 retrieval_policy（默认 anonymize）遮蔽的副本

#4. 常见操作清单

#5. 下一步

• 工程师 → memory-integration.md
• 运维 → memory-automation.md
• 故障排除 → memory-troubleshooting.md
• 架构师 → 025-the-memory-system.md + 026-memory-whitepaper.md