DeepMemory

对话记忆提取与记忆驱动对话系统

🧠 记住用户说的话 | 💬 生成个性化回复 | 🎭 6种AI角色 | 🚀 开箱即用

---

⭐ 快速体验

🌐 Streamlit Web 界面（推荐）

# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置 API Key
cp .env.example .env
# 编辑 .env，填入 GLM_API_KEY

# 3. 启动 Web 界面
./start_web.sh

# 或手动启动
streamlit run streamlit_app.py

访问 http://localhost:8501 开始对话，体验 6 种不同性格的 AI 角色！

🔌 FastAPI REST API 服务

# 启动 API 服务
python app.py

# 访问 API 文档
# http://localhost:8000/docs

详细指南: 📖 FASTAPI_GUIDE.md - 从零开始的手把手教程

---

概述

DeepMemory 提供三种使用方式：

1️⃣ Streamlit Web 界面 ⭐ NEW

• 🎭 多角色系统: 6种 MBTI 性格类型可选
• 💬 记忆驱动对话: 基于历史记忆生成个性化回复
• 🧠 智能记忆提取: 自动提取和评分重要信息
• 🔄 角色记忆隔离: 每个角色独立的记忆空间

适用场景: 个人使用、对话体验、角色扮演

2️⃣ FastAPI REST API 服务

• 🚀 开箱即用: 无需编写代码，直接启动服务
• ⚡ 异步架构: 立即响应用户请求，记忆提取在后台执行
• 🔌 REST API: 标准 HTTP 接口，易于集成
• 📊 完整功能: 对话、记忆、用户管理一应俱全

适用场景: Web 应用、移动应用、第三方集成

3️⃣ Python 库

• 🐍 编程接口: 灵活集成到现有项目
• 🔧 完全可控: 自定义配置和流程
• 📦 模块化设计: 按需使用组件

适用场景: 深度定制、批量处理、研究开发

---

🎭 角色系统 (v0.5.0 新增)

可用角色

角色	MBTI	特点	适用场景
Prometheus	INTJ	🧊 冷酷理性、逻辑至上	工作规划、问题分析、效率提升
小暖	ISFJ	🌞 温暖陪伴、情感支持	日常聊天、情感分享、寻求安慰
Debate Master	ENTP	⚡ 思维敏捷、多角度分析	头脑风暴、观点辩论、思维碰撞
Soul Healer	INFP	💚 理想主义、深度共情	情感支持、人生困惑、内心疗愈
Executive	ESTJ	📊 务实高效、结果导向	项目规划、目标设定、执行方案
Commander	ENTJ	🎯 战略思维、天生领导	创业指导、团队管理、战略决策

核心特性

• ✅ 角色记忆隔离: 每个角色有独立的记忆空间
• ✅ 动态角色切换: 随时切换不同性格的 AI
• ✅ 自定义对话风格: 独特的词汇、句式、思维模式
• ✅ 智能记忆检索: 根据角色特点筛选相关记忆
• ✅ 角色详情展示: 查看角色的完整配置和风格

角色系统指南: 📖 ROLE_SYSTEM_GUIDE.md - 详细的配置和使用教程

---

功能特性

记忆提取

• 结构化记忆提取: 将纯文本对话转换为 JSON 格式的记忆片段
• 自动重要性评分: 基于多维度的评分系统（1-10分）
• ⭐ GLM-4 支持: 原生支持智谱AI的 GLM-4 模型
• 双向记忆: 同时记住用户的话和 AI 的承诺
• ⭐ 角色适配: 不同角色有不同的评分标准和偏好

记忆驱动对话

• ChromaDB 向量存储: 持久化存储记忆，支持语义检索
• 语义相似度检索: 基于向量相似度智能召回相关记忆
• 混合排序策略: 相似度 + 重要性 + 时间衰减
• 对话管理器: 自动提取记忆、检索相关记忆、生成个性化回复
• 多用户/会话支持: 用户隔离、会话管理
• ⭐ 角色记忆隔离: 按角色隔离存储和检索记忆

技术特性

• 异步处理: FastAPI 异步架构，高并发支持
• Pydantic 模型: 类型安全的数据结构
• LLM 驱动: 使用 GLM-4 进行智能提取
• OpenAI 兼容: 支持标准 chat completions 格式

安装

pip install -r requirements.txt

设置你的 API 密钥：

# OpenAI
export OPENAI_API_KEY="your-api-key"

# GLM-4（推荐用于陪伴型 AI）
export GLM_API_KEY="your-glm-api-key"

快速开始

⭐ 记忆驱动对话系统（推荐）

交互式聊天演示：

python demo_interactive_chat.py

编程方式使用：

from src.conversation.conversation_manager import ConversationManager
from src.storage import UserManager, SessionManager, MemoryStorage
from src.utils.glm_client import GLMClient

# 初始化系统
user_manager = UserManager()
session_manager = SessionManager()
memory_storage = MemoryStorage(embedding_model="simple")
glm_client = GLMClient(api_key="your-api-key", model="glm-4-flash")

conversation_manager = ConversationManager(
    user_manager=user_manager,
    session_manager=session_manager,
    memory_storage=memory_storage,
    glm_client=glm_client
)

# 创建用户和会话
user = user_manager.create_user("张三")
session = session_manager.create_session(user_id=user.user_id, title="第一次对话")

# 开始对话
response = conversation_manager.chat(
    user_id=user.user_id,
    session_id=session.session_id,
    user_message="你好，我是张三"
)
print(response)  # AI 会记住用户的名字

# 继续对话
response = conversation_manager.chat(
    user_id=user.user_id,
    session_id=session.session_id,
    user_message="我喜欢吃火锅"
)
# 系统会自动提取这个偏好，下次对话时会记得

记忆提取（独立使用）

from src.utils.glm_client import GLMClient

# 初始化 GLM 客户端
client = GLMClient(api_key="your-glm-api-key", model="glm-4-flash")

# 提取记忆并使用陪伴型评分
conversation = """
User: 我只敢和你说这个秘密
Assistant: 我会保密的
User: 我从小就害怕社交，今天终于鼓起勇气和人说话了
"""

fragments = client.extract_memory_with_scoring(conversation)

# 查看结果
for frag in fragments:
    print(f"{frag['importance_score']}/10 - {frag['content']}")

使用 OpenAI API

from src.pipeline import MemoryPipeline

# 初始化管道
pipeline = MemoryPipeline(use_llm=True)

# 处理对话
conversation = """
User: 我最喜欢的编程语言是 Python
Assistant: 为什么喜欢 Python?
User: 因为语法简洁,而且有强大的生态系统
"""

fragments = pipeline.process(conversation)

# 输出 JSON
json_output = pipeline.process_to_json(conversation, output_file="output.json")
print(json_output)

命令行

python -m src.pipeline.memory_pipeline examples/sample_conversation.txt

记忆片段结构

每个记忆片段包含：

{
  "content": "用户最喜欢的编程语言是 Python,因为语法简洁且有强大的生态系统",
  "timestamp": "2026-01-12T10:00:00Z",
  "type": "preference",
  "entities": ["Python"],
  "topics": ["编程语言", "技术偏好"],
  "sentiment": "positive",
  "importance_score": 7,
  "confidence": 0.92,
  "metadata": {"source": "chat"}
}

关键字段

• importance_score (int, 1-10): 关键字段 - 重要性评分
• type: "event" | "preference" | "fact" | "relationship"
• sentiment: "positive" | "neutral" | "negative"
• entities: 人、地点、组织列表
• topics: 主题或话题列表

重要性评分逻辑

评分基于三个维度计算：

1. 情感强度 (0-3分)

   • 高强度 (非常/超级): 3分
   • 中强度: 2分
   • 低强度: 1分

2. 信息密度 (0-4分)

   • 5+ 实体/主题: 4分
   • 3-4 实体/主题: 3分
   • 1-2 实体/主题: 2分

3. 任务相关性 (0-3分)

   • 目标导向内容: 较高分
   • 关键词: 必须/重要/目标/任务/计划

测试

运行单元测试：

pytest tests/ -v

运行记忆系统测试：

python test_memory_system.py

运行陪伴型演示：

python demo_companion_memory.py

运行交互式聊天：

python demo_interactive_chat.py

查看 test_results/ 获取包含62个真实对话片段的综合测试结果。

项目结构

personality/
├── src/
│   ├── models/              # Pydantic 模型
│   │   ├── memory_fragment.py  # 记忆片段模型
│   │   └── user.py             # ⭐ 用户、会话、消息模型
│   ├── extractors/          # 实体、主题、情感提取器
│   ├── scorers/             # 重要性评分逻辑
│   ├── pipeline/            # 主提取管道
│   ├── storage/             # ⭐ 存储层
│   │   ├── user_manager.py      # 用户管理
│   │   ├── session_manager.py   # 会话管理
│   │   └── memory_storage.py    # ChromaDB 向量存储
│   ├── retrieval/           # ⭐ 检索层
│   │   └── memory_retriever.py  # 语义检索器
│   ├── conversation/        # ⭐ 对话层
│   │   └── conversation_manager.py  # 对话编排器
│   └── utils/
│       ├── glm_client.py    # GLM-4 客户端（陪伴型评分）
│       └── llm_client.py    # OpenAI 客户端封装
├── tests/                   # 单元测试
├── test_results/            # 综合测试结果
├── examples/                # 示例对话
├── data/                    # ⭐ 数据目录
│   ├── users/               # 用户数据
│   ├── sessions/            # 会话数据
│   └── chromadb/            # 向量数据库
├── demo_companion_memory.py # 陪伴型演示
├── demo_interactive_chat.py # ⭐ 交互式聊天演示
├── test_memory_system.py    # ⭐ 记忆系统测试
└── requirements.txt         # 依赖项

配置

管道选项

pipeline = MemoryPipeline(
    api_key="your-key",      # OpenAI API 密钥
    model="gpt-4o-mini",     # 使用的模型
    min_importance=5,        # 最小重要性评分 (1-10)
    use_llm=True             # 使用 LLM (True) 或启发式 (False)
)

系统要求

• Python 3.8+
• OpenAI API 密钥（用于 OpenAI LLM 驱动提取，可选）
• GLM API 密钥（用于 GLM-4 陪伴型评分，推荐）
• requirements.txt 中的依赖项：
  • chromadb: 向量数据库
  • sentence-transformers: 语义检索（可选，支持本地简单 embedding）
  • pydantic: 数据验证
  • zhipuai: GLM-4 SDK

文档

• 📖 FASTAPI_GUIDE.md - FastAPI 完全使用指南（小白友好）
• 📚 API.md - REST API 完整文档
• 🔧 CLAUDE.md - AI 助手项目指南

更新日志

v0.6.0 (2026-01-18) - 流式输出 + 动作描写系统

• ⭐ 新增流式输出功能
  • 实时逐字显示 AI 回复，提升对话体验
  • 减少"等待焦虑"，增加"在场感"
  • Streamlit 原生支持流式显示
  • FastAPI 新增 /v1/chat/stream SSE 接口
• ⭐ 新增动作描写系统
  • 每个角色自动添加符合 MBTI 特质的动作描写
  • 使用 *动作* 格式，如 *推了推眼镜*
  • 让角色对话更加生动立体
  • 6 种角色各具特色的动作风格
• ✅ 修复记忆提取 bug
  • 改进第一人称陈述检测
  • 优化问题判断逻辑，避免误判
  • 动作描写不影响记忆提取
• 📝 更新项目文档

v0.5.0 (2026-01-15) - 多角色系统

• ⭐ 新增 6 种 MBTI 角色系统
  • Prometheus (INTJ) - 冷酷理性的反熵增引擎
  • 小暖 (ISFJ) - 温暖贴心的陪伴者
  • Debate Master (ENTP) - 思维敏捷的辩论家
  • Soul Healer (INFP) - 理想主义的治愈者
  • Executive (ESTJ) - 务实高效的总经理
  • Commander (ENTJ) - 天然领导者
• ⭐ 角色记忆隔离：每个角色独立的记忆空间
• ⭐ 动态角色切换：随时切换不同性格的 AI
• ⭐ 自定义对话风格：独特的词汇、句式、思维模式
• 📝 新增角色系统配置指南

v0.4.0 (2026-01-15) - FastAPI REST API 服务

• ⭐ 新增 FastAPI REST API 服务
  • 开箱即用的 Web 服务
  • 异步架构，立即响应用户请求
  • 完整的 REST API 接口（对话、记忆、用户管理）
  • OpenAI 兼容的 chat completions 接口
  • 交互式 API 文档（Swagger UI）
• ⭐ 新增依赖注入系统（单例模式）
• ⭐ 新增后台异步记忆提取
• ⭐ 生产环境强制使用 GLM Embedding-3
• 📝 新增详细的使用文档（FASTAPI_GUIDE.md）

v0.3.0 (2026-01-14)

• ⭐ 新增记忆驱动对话系统
  • ChromaDB 向量存储
  • 语义相似度检索
  • 对话管理器（自动提取记忆、检索、生成回复）
  • 多用户/会话支持
• ⭐ 新增交互式聊天演示（demo_interactive_chat.py）
• ⭐ 新增记忆系统测试（test_memory_system.py）
• 📝 更新项目文档

v0.2.0 (2026-01-14)

• ⭐ 新增 GLM-4 支持及陪伴型评分
• ⭐ 新增四维陪伴型评分系统
• ⭐ 新增综合测试结果（10个场景，62个片段）
• 📝 新增 demo_companion_memory.py 用于陪伴型 AI

v0.1.0

• 初始版本，支持 OpenAI
• 多维度重要性评分
• 启发式回退模式

许可证

MIT