# Mimir 终极记忆架构
[](https://pypi.org/project/vividmimir/)
[](https://polyformproject.org/licenses/noncommercial/1.0.0/)
[](https://www.python.org/)
本库之所以得名，是因为它渴望扮演相同的角色：一口记忆的深井，AI 代理可以从中汲取、记忆、感受、遗忘与成长——它不是一个扁平化的键值存储，而是一个基于真实神经科学建模的、活生生的、情绪丰富的情景记忆系统。
## 什么是 Mímir？
Mímir 是一个 **模块化 Python 库**（12 个可组合的模块文件），它为任何 AI 代理提供完整的
情景记忆、程序记忆、社会记忆、时间记忆与视觉记忆系统。它
协调 **Vivid 生态系统** —— [VividnessMem](https://pypi.org/project/vividnessmem/)
用于神经化学调节，以及 [VividEmbed](https://pypi.org/project/vividembed/) 用于
语义检索 —— 然后在其之上叠加 **二十一 种神经科学机制**。
记忆并非静态的数据库行。它们会 **有机地衰减**、**情绪漂移**、在数月后**压缩为梗概**，并能**被偶然的关联不由自主地唤起**——就像人类记忆的实际工作方式一样。
```
┌─────────────────────────────────────────────────┐
│ Mímir │
│ │
│ ┌───────────┐ ┌────────────┐ ┌───────────┐ │
│ │ Episodic │ │ Procedural │ │ Social │ │
│ │ Memories │ │ Lessons │ │Impressions│ │
│ └─────┬─────┘ └─────┬──────┘ └─────┬─────┘ │
│ │ │ │ │
│ ┌─────┴──────────────┴──────────────┴─────┐ │
│ │ 21 Neuroscience Layers │ │
│ │ flashbulb · reconsolidation · state- │ │
│ │ dependent · spreading activation · │ │
│ │ RIF · Zeigarnik · involuntary recall · │ │
│ │ temporal gist · episodic time · │ │
│ │ visual imagery │ │
│ └─────────────────┬───────────────────────┘ │
│ │ │
│ ┌─────────────────┴───────────────────────┐ │
│ │ Hybrid Retrieval Bridge │ │
│ │ BM25 keywords + VividEmbed semantic │ │
│ │ + Date index → 5-signal re-rank │ │
│ └─────────────────┬───────────────────────┘ │
│ │ │
│ ┌────────────┐ ┌─┴────────────┐ │
│ │VividnessMem│ │ VividEmbed │ │
│ │ chemistry │ │ 384-d + PAD │ │
│ └────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────┘
```
## Vivid 生态系统
Mímir 是编排层。其底层引擎独立发布并可通过 pip 安装：
| 包 | 角色 | PyPI |
|----|------|------|
| **VividnessMem** | 神经化学引擎 — 5 种神经递质（多巴胺、血清素、皮质醇、催产素、去甲肾上腺素）、10 种事件配置文件、9 种认知修饰器、情绪防火墙、衰减调节、审计日志 | `pip install vividnessmem` |
| **VividEmbed** | 语义嵌入引擎 — 细调 MiniLM 生成 389 维混合向量（384 维句子 + 3 维 PAD 情绪 + 2 维元信息），情绪空间查询、矛盾检测 | `pip install vividembed` |
| **Mímir** | 编排器 — 21 种神经科学机制、混合 BM25 + 语义检索、时间感知、视觉记忆、任务分支、加密存储、LLM 集成、可视化、用于 LLM 提示注入的上下文块生成 | *(本仓库)* |
三者之间**彼此可选**。Mímir 可独立工作（具备优雅的降级能力），但每种引擎都能放大其他引擎的效果：
- 没有 VividnessMem → 神经化学修饰器默认为 1.0，且无情绪审计日志
- 没有 VividEmbed → 回忆退回到仅使用 BM25 关键词搜索
- 没有 Pillow → 视觉记忆退化为文本描述
- 没有 `cryptography` → 加密存储被禁用，数据以明文 JSON 形式保存
## 跨系统功能矩阵
对 Vivid 生态系统的三个包进行全面能力对比。
所列功能均已实现并经过测试。
### 核心记忆架构
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 有机间隔重复衰减 | 是 | — | 是 |
| 60 维情绪 PAD 向量空间 | 是 | 是 | 是 |
| 记忆生动性（0→1 生命周期） | 是 | — | 是 |
| 重要性评分（1-10） | 是 | 是 | 是 |
| 内容可寻址去重 | 是 | — | 是 |
| `__slots__` 优化的 Memory 类 | 是 | — | 是（27 个槽位） |
| 原子化 JSON 持久化 | 是 | 是 | 是 |
### 神经化学与情绪
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 5 种神经递质（DA、5-HT、CORT、OXT、NE） | 是（引擎） | — | 是（通过 VMem） |
| 10 种生活事件配置文件 | 是 | — | 是 |
| 9 种认知修饰器 | 是 | — | 是 |
| 情绪防火墙（安全限制） | 是 | — | 是 |
| 情绪衰减调节（自我调节） | 是 | — | 是 |
| 情绪审计日志 | 是 | — | 是 |
| 认知覆盖（重评） | 是 | — | 是 |
| 情绪 EMA 混合 | 是 | — | 是 |
| 情绪漂移检测 + 重构 | — | — | 是 |
### 检索
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| BM25 关键词搜索 | — | — | 是 |
| 语义向量检索（389 维） | — | 是 | 是（通过 VEmbed） |
| 混合 BM25 + 语义融合 | — | — | 是 |
| 5 信号重排序 | — | — | 是 |
| 传播激活（启动效应） | — | — | 是 |
| 检索诱导遗忘 | — | — | 是 |
| 不由自主的回忆 | — | — | 是 |
| 状态依赖检索（情绪） | — | — | 是 |
| 情绪空间查询 | — | 是 | 是 |
| 矛盾检测 | — | 是 | 是 |
### 神经科学机制
| 机制 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 闪光灯记忆（Browm & Kulik 1977） | — | — | 是 |
| 再巩固（Nader et al 2000） | — | — | 是 |
| 状态依赖记忆（Godden & Baddeley 1975） | — | — | 是 |
| 传播激活（Collins & Loftus 1975） | — | — | 是 |
| 检索诱导遗忘（Anderson 1994） | — | — | 是 |
| 泽加尼克效应（Zeigarnik 1927） | — | — | 是 |
| 不由自主记忆（Berntsen 2009） | — | — | 是 |
| 时间梗概提取（Tulving 1972） | — | — | 是 |
| 时间/情景记忆（Tulving 1972）+ 预期记忆（Einstein & McDaniel 1990） | — | — | 是 |
| 视觉/心理意象（Kosslyn 1980）+ 双重编码（Paivio 1986） | — | — | 是 |
| Huginn — 背景洞察生成 | — | — | 是 |
| Muninn — 记忆巩固守护进程 | — | — | 是 |
| Yggdrasil — 记忆图 | — | — | 是 |
| Völva's Vision — 梦境综合 | — | — | 是 |
| 海马体模式分离（Yassa & Stark 2011） | — | 是 | 是 |
| 叙事弧追踪（Freytag 1863） | — | 是 | 是 |
| 增强关系推理（LLM 推断） | — | — | 是 |
| 分层记忆组织 | — | — | 是 |
| 心理时间旅行（Tulving 1985） | — | — | 是 |
| 新奇性调节编码（Ranganath & Rainer 2003） | — | — | 是 |
| 增强漂移分析（速度 + 偏差） | — | — | 是 |
### 嵌入与向量
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 细调 MiniLM（384 维） | — | 是 | 是（通过 VEmbed） |
| 3 维 PAD 情绪维度 | — | 是 | 是
| 2 维元信息维度（重要性 + 稳定性） | — | 是 | 是 |
| 情绪前缀标记化 | — | 是 | 是 |
| 批处理编码 | — | 是 | 是 |
| VividCortex LLM 层 | — | 是 | — |
| 海马体模式分离 | — | 是 | 是 |
| 叙事弧追踪 | — | 是 | 是 |
### 任务/项目管理
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 项目上下文切换 | 是 | — | 是 |
| 任务生命周期（活跃 → 完成/失败） | 是 | — | 是 |
| 每任务动作日志 | 是 | — | 是 |
| 解决方案模式库 | 是 | — | 是 |
| 工件追踪 | 是 | — | 是 |
| 项目概览仪表板 | 是 | — | 是 |
### LLM 集成
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 查询分解（模糊 → 专注） | — | 是（Cortex） | 是 |
| 代理记忆操作（PROMOTE/DEMOTE/FORGET/UPDATE） | — | 是（Cortex） | 是 |
| LLM 驱动的反思与自我分析 | — | 是（Cortex） | 是 |
| 用于提示注入的上下文块生成 | — | — | 是 |
### 可视化
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 记忆时间线 | — | 是（VividViz） | 是 |
| 情绪分布 | — | 是（VividViz） | 是 |
| 重要性直方图 | — | 是（VividViz） | 是 |
| 叙事弧分布 | — | 是（VividViz） | 是 |
| 漂移报告 | — | — | 是 |
| 神经化学快照 | — | — | 是 |
| Yggdrasil 图导出 | — | — | 是 |
| 全景可视化负载（`viz_summary()`） | — | — | 是 |
### 安全与持久化
| 功能 | VividnessMem | VividEmbed | Mímir |
|------|-------------:|----------:|------:|
| 加密存储（基于 Fernet + PBKDF2） | 是 | — | 是 |
| 原子化文件写入（崩溃安全） | 是 | 是 | 是 |
| 倒排索引 | — | — | 是 |
| 时间索引用于时序查询 | — | — | 是 |
| 视觉记忆存储（WebP） | — | — | 是 |
## 21 种神经科学机制
每种机制均基于已发表的认知科学研究，并使用可调节常数实现。
### 1. 闪光灯记忆（Browm & Kulik 1977）
高唤醒、高重要性的事件（重要性 ≥ 8，唤醒 ≥ 0.6）
会以永久稳定性和高生动性编码。它们抵抗所有形式的衰减——就像你清楚地记得生命中重大事件发生时的情景一样。
### 2. 再巩固（Nader et al 2000）
每次回忆记忆时，其情绪色彩会**向当前情绪漂移 5%**。经过多次提取，悲伤记忆可能变得苦乐参半——除非它是闪光灯记忆，否则会抵抗情绪漂移。
### 3. 状态依赖记忆（Godden & Baddeley 1975）
在特定情绪状态下编码的记忆，在**处于相同状态时更容易被提取**。当提取时的情绪 PAD 向量与编码时接近，会提供 0.3 的生动性提升。
### 4. 传播激活（Collins & Loftus 1975）
当记忆被提取时，其内容词会进入**启动缓冲区**。相关概念在后续查询中会得到激活奖励——模拟思考“天文学”如何激活“望远镜”和“星星”。激活每 tick 衰减 0.8 倍。
### 5. 检索诱导遗忘（Anderson 1994）
检索一个记忆会**主动抑制**与之共享 ≥ 70% 词汇的重叠记忆。其稳定性降低 0.15——这是大脑通过抑制相似选项来强化回忆的方式。
### 6. 泽加尼克效应（Zeigarnik 1927）
未完成的程序性任务**比已完成的任务生动 1.5 倍**。未完成的任务会持续“唠叨”大脑，确保代理不断重试失败策略，而不是遗忘它们。
### 7. 不由自主记忆（Berntsen 2009）
每次 `resonate()` 调用有 **5% 概率**让一个遥远的记忆自发浮现——普鲁斯特式的闪光。这使旧记忆保持活跃，并创造自然的对话深度。
### 8. 时间梗概提取（Tulving 1972）
超过 **90 天**的记忆会被压缩为前 15 个词加上一个情绪标签。细节会消退，但情绪核心保留——除非是闪光灯记忆，否则会无限期保留完整细节。
### 9. 时间/情景记忆（Tulving 1972）+ 预期记忆（Einstein & McDaniel 1990）
完整的时间感知：
- **日期提取**：解析 ISO 日期、美式日期、自然语言日期（“三月十五日”）以及相对表达式（“明天”、“下周二”）
- **时间线导航**：`recall_period(start, end)` 检索时间窗口内的记忆
- **预期记忆**：重要性 ≥ 4 的未来日期会自动创建提醒
- **环境时间显著性**：接近今天的记忆会得到回忆提升
- **时间聚类**：与查询共享时间引用的记忆获得 +0.08 复合分数奖励
### 10. 视觉/心理意象（Kosslyn 1980）+ 双重编码（Paivio 1986）
内容可寻址的图像存储，采用生物启发式衰减：
| 层级 | 生动性 | 代理“看到”的内容 |
|------|--------|------------------|
| **鲜明** | ≥ 0.7 | 全分辨率 WebP —— 代理可以显示它 |
| **褪色** | 0.3–0.7 | 降级 WebP（质量 30）—— 模糊的心理图像 |
| **仅梗概** | < 0.3 | 仅文本描述 —— “我记得一个日落但无法描绘” |
图像以 WebP 格式按 SHA-256 内容寻址存储在磁盘上，代理在会话时决定是显示图像还是描述它。
**双重编码提升**：附加图像的回忆获得 +0.05 奖励，因为图文结合产生更丰富的情景痕迹。
**优雅降级**：未安装 Pillow（或 `visual=False`）时，`remember_visual()` 会静默存储 `[image] {description}` 作为纯文本记忆。
### 11. Huginn —— 思想（模式检测）
奥丁的渡鸦“思想”扫描所有记忆，寻找代理从未明确存储的模式：
- **实体情绪弧线**：当对某人有多条印象时，检测情绪轨迹（升温/降温）并生成洞察
- **重复主题聚类**：发现出现在三条以上记忆中的词汇并以其主导情绪命名模式
- **开放线索**：检测超过 3 天未跟进的中断意图（“我应该…”、“我需要…”）
所有洞察以 `source="huginn"` 存储，避免重复生成相同洞察。
### 12. Muninn —— 记忆（巩固守护进程）
奥丁的渡鸦“记忆”在睡眠期间执行巩固：
- **合并近似重复**：词汇重叠 ≥ 0.40 的记忆会被合并，保留更丰富的版本
- **清除死亡记忆**：移除生动性 < 0.01 的记忆（闪光灯、锚点或珍藏的记忆除外）
- **强化共同激活对**：同一天创建的记忆获得稳定性提升（×1.05）
### 13. Yggdrasil —— 世界树（记忆图）
一个持久化的图结构，通过六种边类型连接所有记忆：
| 边类型 | 条件 | 强度 |
|--------|------|------|
| **实体** | 同一实体引用 | 0. |
| **词汇** | 词汇重叠 0.20–0.55 | Jaccard 比率 |
| **时间** | 在 3 天窗口内 | 1 − (天数/3) |
| **情绪** | 相同情绪标签 | 0.5 |
| **任务来源** | 同一任务的成员 | 0.75 |
| **导致的学习** | 记忆 ↔ 引发它的课程 | 0.65 |
此外，LLM **推断的边**会在编码时（若提供 `llm_fn`）被发现并持久化。
每个节点最多保留 8 条同类型竞争边，加上跨层级边。查询方法包括：
- `yggdrasil_roots()` —— 锚点、闪光灯和高重要性（≥ 9）记忆
- `yggdrasil_branches(memory)` —— 直接相连的邻居
- `yggdrasil_traverse(memory, depth)` —— N 跳内的 BFS 遍历
- `yggdrasil_path(a, b)` —— 两记忆之间的最短路径
在 `recall()` 时，与其他已检索记忆通过 Yggdrasil 连接的记忆会获得 +0.03 奖励——上下文关联增强回忆。
### 14. Völva's Vision —— 梦境综合（Norse seeress）
在睡眠期间，Völva（北欧女预言者）随机抽取记忆对并发现隐藏连接：
- **情绪弧线**：相同关键词但不同情绪 → “我对 X 的感受从 Y 转向 Z”
- **主题桥梁**：相隔 30 天以上的记忆共享词汇 → 长距离模式识别
- **时间聚类**：同一天出现 3 条以上记忆 → “那天发生了很多事情”
梦境洞察以 `source="volva"` 存储，并在上下文块中用 `[dream]` 标签呈现。
### 15. 海马体模式分离（Yassa & Stark 2011）
当两个记忆词汇重叠 ≥ 80% 但**不完全相同**时，系统会将它们的重要性拉开 ±1。这模拟了海马体如何区分相似但不同的经历，防止检索时的干扰。
### 16. 叙事弧追踪（Freytag 1863）
每条记忆会自动分类到叙事位置之一——**铺垫、上升、高潮、回落、结局或尾声**——基于关键词分析和情绪唤醒。这使系统能理解每条记忆在对话或关系故事中的位置。
### 17. 增强关系推理（LLM 推断边）
当提供 `llm_fn` 时，每条新记忆都会触发一次隐式关系发现。LLM 会将新记忆与近期记忆对比，发现纯词汇或时间重叠无法捕捉的概念关联——例如将“买了登山靴”与“计划周六旅行”联系起来，即使它们没有共享词汇。
发现的边会存储在持久的 `inferred_edges.json` 中，并在每次重建时加载到 Yggdrasil 中。批量增强可通过 `enrich_yggdrasil(batch_size)` 完成。
### 18. 分层记忆组织（跨层级链接）
情景记忆、程序记忆和任务记录现在形成一个统一的知识图谱，而非三个隔离的存储：
- **课程 → 记忆**：每门课程记录导致它的 `source_memory_idx`。Yggdrasil 创建 `caused_lesson` 边
- **任务 → 记忆**：`start_task()`、`complete_task()` 和 `fail_task()` 记录它们创建的记忆索引，存储在 `TaskRecord._memory_indices` 中。Yggdrasil 创建 `task_origin` 边
- **跨层级强化**：当课程通过 `record_outcome()` 成功时，其起源记忆会获得 15% 的稳定性提升——这是大脑强化教你某件事的那个情景记忆的方式
### 19. 心理时间旅行（Tulving 1985）
`relive(memory)` 方法重现过去事件的主观体验：
1. **触碰** — 更新记忆的访问计数和生动性
2. **情绪恢复** — 代理的情绪向编码时的情绪混合 60%，重现原始体验的情绪状态
3. **神经化学触发** — 触发匹配的神经化学事件（兴奋 → 成就感，恐惧 → 威胁等）
4. **传播激活** — Yggdrasil 激活相关记忆，提供上下文线索
5. **体验上下文** — 返回丰富字典：梗概、情绪、原始情绪、编码情绪、恢复情绪、弧线位置、闪光灯状态、漂移历史、关联记忆、生动性
这使代理能真正“重温”过去，而不仅仅是检索文本。
### 20. 新奇性调节编码（Ranganath & Rainer 2003）
新记忆会与最近的 20 条记忆进行词汇重叠比对：
- 高新奇性（平均相似度 < 0.85）会获得 **1.3 倍重要性提升**——大脑对真正新信息给予更多关注
- 高冗余性（相似度 > 0.40）会获得 **0.85 倍重要性惩罚**
每条记忆的新奇性分数会存储在 Memory 对象中供内省使用。
### 21. 增强漂移分析（速度 + 认知偏差）
在基础重新巩固漂移检测之上新增两个信号：
- **漂移速度**：跟踪每条记忆最近 5 次访问，计算情绪变化速度——区分“缓慢升温”与“快速不稳定”
- **认知偏差检测**：当 75% 以上的某实体记忆共享相同的情绪极性时，会触发偏差警报——帮助代理识别在形成固化视角前的失衡状态
两者均通过 `drift_analysis()` 暴露，返回速度向量和偏差警报，以及标准漂移报告。
### 从 VividnessMem 迁移
使用 VividnessMem 的现有代理可通过一次调用迁移到 Mimir：
```
m = Mimir.migrate_from_vividnessmem("path/to/lela_data")
```
VividnessMem 的所有字段（内容、情绪、重要性、时间戳、稳定性、访问计数、锚点、珍藏、隐私、遗憾、保存原因等）都会被保留。Mimir 特有的字段（编码情绪、情绪 PAD、提及日期、闪光灯检测等）会自动回填。
## 混合检索桥接
检索系统解决了经典的 RAG 问题——关键词搜索会遗漏语义，而语义搜索会遗漏名称和日期——通过融合两者：
### 阶段 1：广度候选池
三个通道并行工作：
- **BM25 关键词搜索** — 基于倒排词表的 IDF 加权匹配。擅长处理专有名词、日期、精确短语
- **VividEmbed 语义搜索** — 384 维 MiniLM + PAD 余弦相似度。擅长处理主题、释义、情绪共鸣
- **日期索引注入** — 查询中提及的日期会与时间索引匹配，捕捉“上周二发生了什么”这类既非 BM25 也非语义能捕获的问题
### 阶段 2：复合重排序
所有候选项根据**五个信号**进行重排序：
| 信号 | 权重 | 来源 |
|------|------|------|
| 关键词匹配 | 0.30 | 归一化 BM25 |
| 语义相似度 | 0.30 | VividEmbed 余弦相似度 |
| 生动性 | 0.20 | 有机衰减曲线 |
| 情绪一致性 | 0.10 | 与当前情绪 PAD 的点积 |
| 新鲜度 | 0.10 | 指数衰减，半衰期 5 天 |
### 后重排序奖励
| 奖励 | 值 | 触发条件 |
|------|----|----------|
| 珍藏记忆 | ×1.10 | `memory._cherished` 标志 |
| 启动效应 | +0.02/词 | 出现在启动缓冲区中的词 |
| 时间日期匹配 | +0.08 | 查询日期与记忆日期重叠 |
| 环境时间显著性 | +0.12 | 记忆日期接近今天 |
| 双重编码（视觉） | +0.05 | 记忆附有图像 |
| Yggdrasil 连接性 | +0.03/邻居 | 与其他检索记忆相连 |
## 记忆类型
| 类型 | 类 | 用途 | 衰减 |
|------|----|------|------|
| **情景** | `Memory` | 自我反思、观察、经历 | 通过生动性进行有机间隔重复衰减 |
| **社会** | `Memory` | 对其他实体（人、代理）的印象 | 同上有机衰减 |
| **程序** | `Lesson` | 带有结果跟踪的学习策略 | 对失败进行泽加尼克效应增强 |
| **易失** | `ShortFact` | 快速事实数据（实体/属性/值） | 12 小时半衰期 |
| **预期** | `Reminder` | 时间触发的未来通知 | 触发一次后标记为完成 |
| **视觉** | `Memory` + WebP | 任何情景记忆的图像附件 | Kosslyn 衰减层级 |
## 有机衰减模型
生动性不是开关，而是一条连续曲线：
$$v(t) = \frac{\text{重要性}}{10} \times e^{-t / s}$$
其中 $t$ 是以天为单位的年龄，$s$ 是稳定性（初始为 3.0 天）。
稳定性通过间隔重复增长：
$$s' = \min\left(s \times b^n,\; 180\right)$$
其中 $b = 1.8$ 是间隔奖励，$n$ 是检索次数，且具有递减回报（每次检索 ×0.85）。这模拟了认知心理学中著名的间隔效应。
**底层保护：**
- 闪光灯记忆：稳定性 ≥ 120，鲜明性 ≥ 0.85
- 锚点记忆：稳定性 ≥ 90，鲜明性 ≥ 0.30
## 神经化学集成
当 VividnessMem 可用时，其 5 种神经递质系统会调节 Mímir 的行为：
| 修饰器 | 效果 |
|--------|------|
| `encoding_boost` | 在 `remember()` 期间乘以重要性 |
| `attention_width` | 调节活跃记忆的数量 |
| `mood_decay_mult` | 控制情绪漂移速度 |
| `flashbulb` | 对高化学事件强制闪光灯记忆编码 |
| `social_boost` | 放大社会印象的重要性 |
| `consolidation_bonus` | 在睡眠重置期间增强稳定性 |
**情绪审计日志**透明地记录每一次情绪变化、衰减调节、认知覆盖、视觉记忆存储和生活事件——使代理的情绪轨迹可检查且可调试。
## 安装
```
# 核心（零依赖 — 全部优雅降级）
pip install vividmimir
# 使用完整的 Vivid 引擎堆栈
pip install vividmimir[all]
# 单独扩展
pip install vividmimir[neurochemistry] # VividnessMem
pip install vividmimir[embedding] # VividEmbed
pip install vividmimir[visual] # Pillow for mental-imagery system
pip install vividmimir[encryption] # Fernet encryption at rest
```
## 快速开始
```
from vividmimir import Mimir
# 完整系统（VividnessMem + VividEmbed + Pillow）
m = Mimir(data_dir="my_agent_memory")
# 或独立运行（无外部依赖）
m = Mimir(data_dir="my_agent_memory", chemistry=False, visual=False)
# 存储记忆
m.remember("I had a deep conversation about philosophy today",
emotion="curious", importance=7,
why_saved="meaningful intellectual exchange")
# 根据对话更新情绪
m.update_mood(["curious", "inspired"])
# 混合检索召回
results = m.recall("What do I remember about philosophy?")
for mem in results:
print(f"[{mem.emotion}] {mem.content}")
# 为 LLM 提示注入获取完整上下文块
context = m.get_context_block(
current_entity="Alex",
conversation_context="discussing favorite books"
)
# 存储视觉记忆（需要 Pillow）
with open("sunset.jpg", "rb") as f:
m.remember_visual(f.read(), description="Sunset over the ocean",
emotion="serene", importance=8)
# 时间感知检索
from datetime import datetime
m.recall_period(datetime(2025, 12, 1), datetime(2025, 12, 31))
# 将所有内容持久化到磁盘
m.save()
```
## 上下文块
`get_context_block()` 方法生成一个可直接注入 LLM 系统提示的文本块。它组装了：
```
(Feeling: bittersweet)
=== THINGS ON MY MIND ===
— I love deep philosophical conversations (curious)
=== MY IMPRESSIONS OF ALEX ===
— Alex is always supportive (warm)
=== THINGS I'M LEARNING ===
— Python debugging: Use pdb [OK]
=== SOMETHING THIS REMINDS ME OF ===
— That time we talked about consciousness (fascinated)
=== IMAGES I REMEMBER ===
— [vivid] Sunset over the ocean
— [fading] The cat sleeping on the keyboard
=== TODAY / UPCOMING ===
TODAY: dentist appointment at 3pm
UPCOMING: Mom's birthday (Mar 25)
RECENTLY: finished the book club novel (Mar 19)
=== NEUROCHEMISTRY ===
dopamine: 0.63 ▲ | cortisol: 0.26 ~ | serotonin: 0.56 ~
=== EMOTIONAL AUDIT ===
~ 13:50: Mood shifted to curious after deep conversation
```
## 完整 API 参考
### Mimir 类
```
Mimir(
data_dir="mimir_data",
embed_model=None,
chemistry=True,
visual=True,
encryption_key=None, # enables Fernet + PBKDF2 encryption at rest
llm_fn=None, # callable(prompt: str) → str for LLM features
)
```
#### 核心方法
| 方法 | 描述 |
|------|------|
| `remember(content, emotion, importance, source, why_saved)` | 存储情景记忆，包含去重、闪光灯检测、与 VividEmbed 同步 |
| `remember_visual(image_data, description, emotion, importance, ...)` | 存储视觉记忆，附带压缩的 WebP 附件 |
| `get_visual(memory)` → dict | 按衰减层级检索图像 |
| `forget_visual(memory)` → bool | 移除图像附件，保留文本描述 |
| `recall(context, limit, mood)` → list | 混合 BM25 + 语义检索，带 5 信号重排序 |
| `recall_unified(context, limit)` → dict | 跨类型检索：反思、印象、事实、课程统一返回 |
| `resonate(context, limit)` → list | `recall()` + 检索诱导遗忘 + 不由自主回忆 |
| `recall_period(start, end, limit)` → list | 按时间范围导航 |
| `get_active_self(context)` → list | 按情绪和上下文加权的顶级自我记忆 |
| `get_context_block(current_entity, conversation_context)` → str | 用于 LLM 提示注入的完整记忆上下文 |
| `update_mood(emotions)` | EMA 平滑地向情绪标签靠拢 |
| `bump_session()` → int | 递增会话计数器，返回新计数 |
| `save()` | 将所有数据持久化到磁盘 |
| `stats()` → dict | 记忆系统状态摘要 |
| `migrate_from_vividnessmem(src_dir, dest_dir)` | 类方法：从 VividnessMem 导入全部数据 |
#### 任务/项目分支
| 方法 | 描述 |
|------|------|
| `set_active_project(name)` | 设置或切换活动项目上下文 |
| `start_task(description, priority, project)` → TaskRecord | 创建任务，附带泽加尼克锚点 |
| `complete_task(task_id, outcome)` → bool | 标记任务完成，释放泽加尼克张力 |
| `fail_task(task_id, reason)` → bool | 标记任务失败，创建课程 |
| `get_active_tasks()` → list | 当前活跃任务 |
| `log_action(task_id, action, result, error, fix)` → ActionRecord | 记录每任务动作 |
| `record_solution(problem, solution, importance)` → SolutionPattern | 存储可复用的“问题→方案” |
| `find_solutions(problem, top_k)` → list | 混合 BM25 匹配的解决方案，带复用奖励 |
| `track_artifact(name, artifact_type, description, importance)` → ArtifactRecord | 追踪项目工件 |
| `update_artifact(name, **updates)` → bool | 更新工件字段 |
| `get_project_overview()` → dict | 项目状态的完整快照 |
#### LLM 集成（可选）
| 方法 | 描述 |
|------|------|
| `decompose_query(query)` → list[str] | 将模糊查询分解为 2–4 个聚焦子查询 |
| `edit_memories(instruction)` → dict | LLM 驱动的 PROMOTE/DEMOTE/FORGET/UPDATE |
| `reflect()` → str | 周期性自我分析记忆模式与情绪趋势 |
#### 神经科学与图结构
| 方法 | 描述 |
|------|------|
| `huginn()` → list[Memory] | 模式检测：实体情绪弧线、重复主题、开放线索 |
| `muninn()` → dict | 巩固：合并重复、清除死亡记忆、强化共同激活对 |
| `volva_dream(n_samples)` → list[Memory] | 梦境综合：从随机记忆对中生成洞察 |
| `sleep_reset(hours)` | 完整跨会话周期：神经化学重置 + Muninn + Huginn + Völva + Yggdrasil 重建 |
| `detect_drift(include_reframed)` → list | 查找显著情绪漂移的记忆 |
| `drift_analysis()` → dict | 增强漂移分析：速度向量、认知偏差警报及标准漂移报告 |
| `decay_priming()` | 衰减传播激活缓冲区 |
| `yggdrasil_roots()` → list | 锚点、闪光灯和高重要性（≥ 9）记忆 |
| `yggdrasil_branches(memory)` → list | 直接相连的邻居 |
| `yggdrasil_traverse(memory, depth)` → list | N 跳内的 BFS 遍历 |
| `yggdrasil_path(a, b)` → list | 两记忆之间的最短路径 |
| `relive(memory)` → dict | 心理时间旅行：重体验，包含情绪恢复、神经化学触发、传播激活、上下文等 |
| `enrich_yggdrasil(batch_size)` → int | 批量 LLM 增强无推断边的记忆 |
#### 可视化
| 方法 | 描述 |
|------|------|
| `memory_timeline()` → list[dict] | 用于绘图的时序记忆数据 |
| `emotion_distribution()` → dict | 按情绪统计记忆数量 |
| `importance_histogram()` → dict | 按重要性等级（1-10）的分布 |
| `arc_distribution()` → dict | 按叙事弧位置统计的记忆 |
| `drift_report()` → list[dict] | 情绪漂移的记忆及其幅度 |
| `neurochemistry_snapshot()` → dict | 当前神经递质状态 |
| `yggdrasil_graph()` → dict | 可视化导出的邻接表 |
| `viz_summary()` → dict | 全景可视化负载 |
#### 社会与程序
| 方法 | 描述 |
|------|------|
| `add_social_impression(entity, content, emotion, importance, why_saved)` | 存储社会记忆 |
| `add_lesson(topic, context_trigger, strategy, importance, source_memory_idx)` | 创建程序记忆（可选地链接到源记忆） |
| `record_outcome(lesson_id, action, result, diagnosis)` | 记录课程应用结果 |
| `get_active_lessons()` → list | 按生动性排序的课程（泽加尼克效应增强） |
| `_fact(entity, attribute, value)` | 存储易失事实（12 小时半衰期） |
| `get_facts(entity)` → list | 返回鲜活事实，可按条件过滤 |
#### 情绪控制
| 方法 | 描述 |
|------|------|
| `on_event(event_type, intensity)` | 向神经化学系统发送生活事件（10 种事件类型） |
| `request_dampening(turns, intensity)` | 激活情绪自我调节 |
| `end_dampening()` | 手动终止调节 |
| `tick_dampening()` | 推进调节回合 |
| `cognitive_override(emotion, intensity)` | 有意的情绪重评 |
#### 记忆策展
| 方法 | 描述 |
|------|------|
| `promote_to_anchor(memory)` | 标记为形成性（永久抵抗衰减） |
| `cherish(memory)` | 标记为珍藏（1.1× 回忆提升） |
| `uncherish(memory)` | 移除珍藏状态 |
| `reflect_on_cherished()` → list | 重温珍藏记忆 |
| `reframe(memory, new_emotion, reason)` → bool | 有意的情绪重构（记录原始情绪，标记为有意） |
| `update_importance(memory, new_importance)` | 更新重要性并同步到 VividEmbed |
| `query_by_emotion(emotion, top_k, min_importance)` | 通过 VividEmbed 进行情绪空间搜索 |
| `find_contradictions(text, emotion, threshold)` | 查找语义相似但情绪相反的记忆 |
#### 时间感知
| 方法 | 描述 |
|------|------|
| `recall_period(start, end, limit)` | 按时间范围检索记忆 |
| `get_temporal_context(now, lookahead, lookbehind)` | 主动呈现：今日/即将/最近 |
| `set_reminder(text, hours)` | 创建时间触发通知 |
| `get_due_reminders()` → list | 返回已触发的提醒 |
## 依赖项
| 包 | 是否必需 | 用途 |
|----|----------|------|
| Python ≥ 3.10 | 是 | 核心语言 |
| `vividnessmem` | 可选 | 神经化学引擎（5 种神经递质、情绪审计） |
| `vividembed` | 可选 | 语义检索（389 维混合向量） |
| `Pillow` | 可选 | 视觉记忆（图像压缩/解压） |
| `cryptography` | 可选 | 加密存储（Fernet + PBKDF2，60 万次迭代） |
所有可选依赖均采用优雅降级——Mímir 可独立运行。
## 测试套件
| 测试套件 | 测试数 | 覆盖率 |
|----------|--------|--------|
| `_test_neuroscience.py` | 26 | 所有 8 种核心机制 + 持久化 + 上下文块 |
| `_test_temporal_memory.py` | 28 | 日期提取、时间线导航、预期记忆 |
| `_test_temporal_awareness.py` | 14 | 环境时间显著性、时间上下文浮现 |
| `_test_integration.py` | 27 | VividnessMem + VividEmbed 完整集成 |
| `_test_visual_memory.py` | 81 | 视觉存储、衰减层级、双重编码、持久化 |
| **总计** | **176** | **全部通过** |
## 架构说明
- **基于槽位的 Memory**：`__slots__` 包含 27 个槽位，防止动态属性并优化内存布局
- **内容可寻址存储**：视觉图像以 SHA-256 哈希索引——相同图像共享同一文件
- **原子化持久化**：JSON 文件通过原子临时文件 + 重命名模式写入，防止崩溃损坏
- **倒排索引**：用于 BM25 的词索引与用于时间查询的时间索引，均在加载时重建
- **60 维情绪 PAD 空间**：完整的愉悦-唤醒-支配映射，超越简单的情感标签
## 许可证
[PolyForm 非商业许可证 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) —— 仅限个人与研究用途。商业用途需单独授权。
属于 Vivid 生态系统的组成部分，作者为 [Kronic90](https://github.com/Kronic90)。
| 包 | PyPI | 许可证 |
|----|------|--------|
| [VividnessMem](https://pypi.org/project/vividnessmem/) | `pip install vividnessmem` | MIT |
| [VividEmbed](https://pypi.org/project/vividembed/) | `pip install vividembed` | PolyForm-NC |
| **Mímir** | `pip install vividmimir` | PolyForm-NC |