Angel Memory 项目移植总结：让AI拥有真正的记忆能力

Angel Memory 项目移植总结：让AI拥有真正的记忆能力

本文记录了将 kawayiYokami/astrbot_plugin_angel_memory 项目移植到霹雳五号AI助手的过程，共分为三个阶段实现完整功能。

一、项目背景

AstrBot 的 Angel Memory 插件是一个非常有创意的大脑记忆系统，它让AI不仅能记住信息，还能主动思考和进化。这个项目有128星，采用GPL v3开源协议。

核心设计思想：
– 三层认知架构：Soul系统（潜意识）→ DeepMind（潜意识检索）→ LLM（主意识）
– 四维能量槽：RecallDepth、ImpressionDepth、ExpressionDesire、Creativity
– 三元组记忆格式：judgment（判断）+ reasoning（推理）+ tags（标签）
– 动态强度系统：记忆根据使用频率动态调整强度

二、移植成果总览

创建的文件

文件 说明 大小
scripts/angel_memory_phase1.py Soul系统 + 三元组记忆 + core_memory工具 18KB
scripts/angel_memory_phase2.py 知识库 + 研究子代理 + BM25检索 25KB
scripts/angel_memory_phase3.py 睡眠巩固 + 灵魂共鸣 + Debug 18KB
skills/angel-memory-phase1/SKILL.md Phase 1 技能文档 16KB
skills/angel-memory-phase2/SKILL.md Phase 2 技能文档 19KB
skills/angel-memory-phase3/SKILL.md Phase 3 技能文档 25KB

数据存储结构

~/.hermes/angel-memory/
├── soul_state.json              # Soul四维能量槽状态
├── memories/
│   └── public/
│       ├── knowledge.json       # 知识记忆
│       ├── event.json           # 事件记忆
│       └── feedback.json        # 反馈记忆
├── knowledge_base/
│   ├── raw/                     # 短条目知识文件
│   ├── file_index.db            # 文件索引（SQLite）
│   └── note_index.db            # 笔记索引（SQLite）
└── memories_backup/
    ├── backup_20260516_155627.json
    └── backup_20260516_155604.json

三、Phase 1：Soul系统 + 三元组记忆

核心功能

1. Soul四维能量槽

class SoulState:
    """灵魂状态 — 四维能量槽 + 橡皮筋回归算法"""

    DIMENSIONS = ["RecallDepth", "ImpressionDepth", "ExpressionDesire", "Creativity"]

    def __init__(self):
        self.energy = {
            "RecallDepth": 10,        # 召回深度（1-20）
            "ImpressionDepth": 5,     # 印象深度（1-10）
            "ExpressionDesire": 0.5,   # 表达欲望（0-1）
            "Creativity": 0.5,         # 创造力（0-1）
        }

    def rubber_band(self, dim, delta):
        """橡皮筋回归：当能量偏离中值时，自动产生回归力"""
        cfg = self.config[dim]
        deviation = self.energy[dim] - cfg["mid"]
        rubber_force = -deviation * self.RUBBER_K  # 回归力 = -偏差 * 系数
        self.energy[dim] += delta + rubber_force
        self.energy[dim] = max(cfg["min"], min(cfg["max"], self.energy[dim]))

2. 三元组记忆格式

{
  "id": "mem_876543",
  "memory_type": "knowledge",
  "judgment": "飞书是字节跳动开发的协作平台",
  "reasoning": "用户在飞书配置中提供了chat_id，说明正在使用飞书进行通信",
  "tags": ["飞书", "字节跳动", "协作工具"],
  "strength": 85,
  "is_active": true,
  "state_snapshot": {
    "RecallDepth": 12.5,
    "ImpressionDepth": 6.2,
    "ExpressionDesire": 0.45,
    "Creativity": 0.52
  }
}

3. 核心工具函数

  • core_memory_remember(content, reasoning, tags, memory_scope) — 铭记新记忆
  • core_memory_recall(query, limit, memory_scope) — 召回相关记忆

强度评分机制

强度范围 含义 处理方式
90-100 核心原则/价值观 永不删除
70-89 重要知识 高优先级保留
50-69 一般信息 正常衰减
20-49 临时信息 加速衰减
0-19 垃圾记忆 睡眠时删除

四、Phase 2：知识库 + 研究子代理

核心功能

1. 文件索引管理器（FileIndexManager）

class FileIndexManager:
    """文件路径→整数ID 双向映射，内存缓存，SQLite持久化"""

    def get_or_create_file_id(self, relative_path: str, timestamp: int = 0) -> int:
        """先查后插策略（幂等）"""
        # 查询内存缓存
        if relative_path in self._path_cache:
            return self._path_cache[relative_path]
        # 查询数据库
        # 插入新记录
        return file_id

2. 短条目笔记索引（NoteService）

每条笔记 ≤100字，用 ## 二级标题 分隔：

## 列表推导式性能
[gen for gen in data] 比 append 循环快30%。适合数据转换场景。

## 字典默认值
d.get('key', default) 用于安全获取，避免KeyError。比 d['key'] if 'key' in d 更简洁。

3. BM25检索引擎

BM25是一种经典的文本检索算法，考虑了词频和文档长度：

def score(self, query: str, text: str) -> float:
    """计算query对text的BM25得分"""
    query_terms = query.lower().split()
    doc_len = len(text.lower().split())
    avg_doc_len = max(doc_len, 1)

    score = 0.0
    for term in query_terms:
        tf = text.lower().count(term)
        idf = math.log((len(query_terms) + 0.5) / (tf + 0.5) + 1)
        tf_component = (self.k1 * tf) / (self.k1 * ((1 - self.b) + self.b * doc_len / avg_doc_len) + tf)
        score += idf * tf_component
    return score

4. 研究子代理（research_fellow）

# 研究员系统提示词

## 工作流
1. 快速规划：拆解为2-3个子问题
2. 边读边记：看到重点立即使用记忆工具
3. 综合报告：基于记忆笔记整合知识

## 工具使用
1. 搜索工具 → 定位信息源
2. 阅读工具 → 获取完整内容
3. 记忆工具 → 内化关键知识

五、Phase 3：睡眠巩固 + 灵魂共鸣

核心功能

1. 睡眠巩固流程（SleepService）

睡眠触发（默认3600秒）
    ↓
【前置维护】同步知识库索引
    ↓
【记忆清理】弱记忆衰减/删除
    ↓
【记忆强化】活跃记忆加强
    ↓
【后置维护】JSON备份 + 旧备份清理

清理规则：
– 主动记忆（is_active=True）永不删除
– 被动记忆（is_active=False）strength≤20 → 删除
– 30天未召回 → 加速衰减

2. 灵魂共鸣（SoulResonance）

class SoulResonance:
    """灵魂共鸣 — 历史状态影响当前决策"""

    RESONANCE_STRENGTH = 0.3  # 被动共鸣系数
    MAX_INFLUENCE = 5.0       # 最大共鸣影响

    @classmethod
    def resonate_on_recall(cls, memories: List[BaseMemory]):
        """
        批量召回时的共鸣处理

        当召回记忆时，旧记忆的状态快照通过共鸣影响当前Soul能量
        类似于人类的"情绪惯性"和"创伤应激"
        """
        # 收集所有快照，取平均偏差
        # 应用共鸣系数，影响当前Soul能量

3. 工作流统一接口

async def angel_memory_workflow(action: str, **kwargs) -> Dict:
    """
    支持动作：
    - remember: 铭记记忆
    - recall: 回忆记忆
    - search: 综合检索
    - sleep: 触发睡眠巩固
    - backup: 执行备份
    - sync: 同步知识库
    - status: 获取系统状态
    """

六、定时任务配置

已创建3个cron任务自动执行：

任务 调度时间 功能
angel-memory-sleep 每小时整点 睡眠巩固检查
angel-memory-kb-sync 每天凌晨3点 知识库同步
angel-memory-quarterly-review 每季度1日9点 全面功能检查

七、验证命令

# 运行睡眠巩固
python3 ~/.hermes/scripts/angel_memory_phase3.py sleep

# 查看完整状态
python3 ~/.hermes/scripts/angel_memory_phase3.py status

# 导出记忆
python3 ~/.hermes/scripts/angel_memory_phase3.py export

# 查看Soul状态
cat ~/.hermes/angel-memory/soul_state.json

# 查看备份
ls -la ~/.hermes/angel-memory/memories_backup/

八、与原项目的差异

功能 原项目 移植版本
向量存储 ChromaDB + FAISS 简化为JSON文件
重排模型 支持 预留接口（Phase 3扩展）
多格式解析 PDF/Word/Markdown 仅支持Markdown短条目
上下文窗口 分级检索 简化为BM25直出
API接口 AstrBot插件 独立Python脚本

九、核心设计思想总结

  1. 记忆不是静态存储：记忆强度会根据使用频率动态调整
  2. 橡皮筋效应：能量会自动回归中值，防止偏离
  3. 短条目优先：每条知识控制在100字以内，便于检索
  4. 睡眠巩固：定期清理弱记忆，强化活跃记忆
  5. 灵魂共鸣：历史状态影响当前决策，形成连贯的”人格”

项目地址：https://github.com/kawayiYokami/astrbot_plugin_angel_memory

移植日期：2026-05-17

移植版本：v1.0.0（Phase 1 + Phase 2 + Phase 3 完整实现）