Universal Memory Module (Monorepo)

这是一个关于 AI 智能体记忆系统的综合项目仓库，包含了从第一代被动记忆系统到第二代主动认知记忆引擎的演进过程。

📂 目录结构 (Project Structure)

本仓库采用 Monorepo 结构，包含以下三个主要模块，每个模块都是独立的 Python 包：

1. umm_legacy (UMM v1.0)

• Package Name: universal_memory_module
• 状态: 维护模式 (Maintenance)
• 描述: 第一代通用记忆模块。
• 特点: 基于 Router 的被动检索架构，包含 ShortTerm, Fact, TimeIndexed, Semantic 四大基础记忆层。

2. umc_core (UMC - Universal Memory Core) 🚀

• Package Name: umc-core
• 状态: Release Ready (v0.2.0)
• 描述: 下一代智能体海马体。
• 特点:
  • Active FSM: 基于 Observe-Plan-Action-Review 的主动认知循环。
  • Dual-Track Retrieval: 支持 叙事 (Narrative) 与 事实 (Fact) 的双轨检索。
  • Memory Lifecycle: 内置记忆折叠与权重衰减机制，模拟生物遗忘。

3. umc_frontend (Frontend Module) 🆕

• Package Name: umc-frontend
• 状态: Prototype / Demo Ready
• 描述: 独立的前端交互模块（临时），负责用户界面与会话管理。
• 特点:
  • 拟人化交互: 实现 异步多流响应 (Multi-stream) 架构，模拟真人“秒回 + 思考后补充”的节奏；支持主动搭话与打断机制。
  • 全链路可视化 (Blackboard Dashboard): 侧边栏实时投屏 UMC 的思维黑板，透明化展示 FSM 的意图分析、检索计划及代码执行日志。
  • 记忆透视 (Memory Inspector): 内置调试面板，支持直接查看后台的短期记忆窗口 (ShortTerm) 及用户/心理画像文件 (Profile)。

4. The-Seed (Reference Architecture) 📚

• Type: Git Submodule
• Location: Root Directory (./The-Seed/)
• 描述: UMC 核心架构 (FSM + Blackboard) 的灵感来源与参考实现。
• 用途: 本项目作为 UMC 的架构蓝本，提供了标准化的 Agent 交互协议设计参考。

---

🚀 快速启动 (Quick Start)

1. 环境准备 (Installation)

推荐使用 Conda 或 venv 创建虚拟环境：

# 创建并激活环境
conda create -n umc python=3.10
conda activate umc

# 安装所有依赖及本地包 (Editable Mode)
pip install -r requirements.txt

⚠️ 智能体开发约束 (Agent Constraint)

• Environment: 所有开发与运行任务必须强制在 umc Conda 环境中执行。
• Verification: 在执行任何 Python 命令 (python, pip, uvicorn) 前，请务必确认当前终端已激活 umc 环境。

requirements.txt 会自动将 umm_legacy, umc_core, umc_frontend 以 -e (editable) 模式安装到你的环境中。

2. 启动演示 (Running the Demo)

前端模块 (umc_frontend) 已经集成了完整的演示环境。

# 切换到前端目录（推荐）
cd umc_frontend

# 启动服务器
# 注意：第一次启动时会自动使用 umc_frontend/config/config.yaml 作为配置文件
python -m server
# 或者
uvicorn server:app --reload

启动成功后，浏览器访问：http://localhost:8000

---

⚙️ 配置说明 (Configuration)

为了保证模块独立性，umc_frontend 拥有独立的配置文件： umc_frontend/config/config.yaml

启动时，server.py 会自动将此路径注入环境变量 UMC_CONFIG_PATH 和 UMM_CONFIG_PATH，从而覆盖底层库的默认配置。

---

📐 架构设计原则 (Design Principles)

为了保证模块间的解耦与数据流的一致性，本项目遵循以下核心原则：

1. 读写分离 (Read-Write Separation)

• Read (Retrieval): 由 UMC (FSM) 负责。通过 Observe -> Plan -> Action 链条主动检索记忆。
• Write (Ingestion): 由 Frontend 触发，后台异步执行。
  • 前端在生成最终回复后，调用 RuntimeAPI.trigger_background_ingestion。
  • 写入过程是 Fire-and-Forget 的，不阻塞用户交互。

2. 参数透传 (Parameter Passthrough)

为了确保底层 umm_legacy 能正确建立索引和画像，上层模块必须严格透传原始上下文：

• User Input: 必须保持用户原始输入的字符串，不做摘要或截断，透传给 ShortTermMemory 和 FactMemory。
• Agent Response: 必须等待 FSM 生成完整的最终回复（Stream 1 + Stream 2 合并后）再传入后台写入接口，确保“对话对 (Turn pair)”的完整性。
• History: FSM 初始化的 short_term_history 必须直接来源于 umm_legacy 的数据库，保证上下文连贯。

3. 黑板中心化 (Blackboard Centric)

• 所有跨节点的临时状态（意图、计划、检索结果）必须存储在 Blackboard 对象中。
• 前端展示（Dashboard）和 Prompt 注入（Generation）都统一从 Blackboard 读取数据，禁止通过私有变量传递隐式状态。

---

📚 致谢与参考 (Acknowledgments)

本项目的架构演进和核心机制深受开源社区的启发，特别致谢以下项目：

• The Seed

  • 贡献: 提供了 FSM (Finite State Machine) + Blackboard 的核心架构蓝本。
  • 影响: UMC 的 "Observe-Plan-Action" 循环与数据黑板机制直接致敬了 The Seed 的设计。

• LifeBook

  • 贡献: 启发了 Phase 2 的 分层记忆折叠 (Hierarchical Folding) 理念。
  • 影响: 我们借鉴了其将碎片化对话（Raw Log）折叠为叙事摘要（Narrative Summary）的思想，解决了长上下文的 Token 爆炸问题。

• N.E.K.O

  • 贡献: 启发了 UMM 的整体 架构设计 (Architecture Design)。
  • 未来展望: 我们计划将 N.E.K.O 的前端交互剥离，作为本项目demo的前端实现。

---

📜 许可证 (License)

本项目采用 MIT License 许可证。

这意味着您可以自由地使用、复制、修改、合并、出版发行、散布、再授权及贩售本软件及其副本。

详见 LICENSE 文件。