DuMF-Agent-Assistant

基于双记忆系统（Dual Memory Framework）的认知智能体助手项目。

项目简介

本项目实现了一个具有长短期记忆的认知智能体系统，支持角色扮演和个性化对话。智能体能够：

• 维护短期情节记忆（FAISS 向量索引）
• 构建长期语义知识图谱（Neo4j 图数据库）
• 自动进行记忆巩固（将短期记忆转化为长期知识）
• 根据问题类型选择不同的回答策略
• 保持角色一致性和个性化对话风格

核心特性

双记忆系统

• 短期记忆 (STES)：基于 FAISS 的向量检索，存储最近的对话历史
• 长期记忆 (LTSS)：基于 Neo4j 的知识图谱，存储结构化的语义知识
• 记忆巩固：自动将短期记忆提炼为长期知识三元组

智能问题分类

• 时间相关问题（TEMPORAL）
• 数量统计问题（COUNTING）
• 事实查询问题（FACTUAL）
• 最近对话问题（RECENT）
• 一般对话问题（GENERAL）

角色扮演系统

• 支持从 PNG 元数据导入角色卡
• 可配置角色性格、说话风格、世界观
• 自动学习角色对话示例
• 保持角色一致性

项目结构

.
├── agent/                      # 智能体核心模块
│   ├── agent.py               # 认知智能体主类
│   ├── assistant.py           # 助手封装类
│   ├── context_builder.py     # 上下文构建
│   ├── contextual_focus_framework.py  # CFF 框架
│   └── retrievers.py          # 检索器
├── memory/                     # 记忆系统
│   ├── dual_memory_system.py # 双记忆系统
│   ├── stores.py              # 存储接口
│   ├── structured_memory.py   # 结构化记忆
│   └── ltss_writer.py         # 长期记忆写入
├── prompts/                    # 提示词模板
│   ├── answer_prompts.py      # 回答提示词
│   ├── question_classifier.py # 问题分类器
│   └── consolidation_prompts.py  # 巩固提示词
├── utils/                      # 工具函数
│   ├── bootstrap_character.py # 角色导入
│   ├── extract_png_metadata.py  # PNG 元数据提取
│   ├── embedding.py           # 嵌入服务
│   └── llm.py                 # LLM 配置
├── data/                       # 数据目录
│   ├── agents/                # 智能体记忆存储
│   ├── books/                 # 角色书和世界书
│   └── world_knowledge/       # 世界知识
├── config.py                   # 配置文件
├── The_agent.py               # 主程序入口
└── requirements.txt           # Python 依赖

安装配置

1. 环境要求

• Python 3.10+
• Neo4j 数据库（推荐使用 AuraDB 免费版）
• OpenAI API Key 或兼容的 LLM API

2. 安装依赖

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows:
.\.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

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

3. 配置环境变量

创建 .env 文件：

# LLM API 配置
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1

# Neo4j 数据库配置
NEO4J_URI=neo4j://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password

# 可选：LangSmith 追踪
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls__...

4. 配置参数

编辑 config.py 调整智能体参数：

# 记忆巩固阈值（每 N 轮对话触发一次）
memory_consolidation_threshold = 8

# 短期记忆窗口大小
SHORT_TERM_MEMORY_WINDOW = 100

# 是否启用短期记忆
ENABLE_SHORT_TERM_MEMORY = 1

使用方法

基础使用

from agent.assistant import Assistant

# 创建助手实例
with Assistant("RaidenShogun") as assistant:
    # 对话
    response = assistant.chat("你好")
    print(response)

命令行使用

# 启动对话
python The_agent.py --character RaidenShogun

# 导入角色书
python utils/bootstrap_character.py RaidenShogun

# 从 PNG 提取角色卡
python utils/extract_png_metadata.py data/books/character.png

创建自定义角色

1. 在 data/books/ 创建角色书文件 character_book_YourCharacter.txt
2. 按照格式填写角色信息：

name
Your Character Name

core_identity
角色的核心身份描述

personality_traits
性格特质1
性格特质2

speech_style
说话风格描述

example_dialogues
用户：示例问题
角色：示例回答

character_quotes
经典语录1
经典语录2

3. 导入角色：

python utils/bootstrap_character.py YourCharacter

技术架构

认知循环

用户输入 → 感知 → 构建上下文 → 生成回答 → 执行 → (巩固记忆)

检索策略

• 语义检索：使用 FAISS 向量相似度检索相关记忆
• 关键词检索：使用 Neo4j 全文索引匹配关键词
• 原文兜底：保留原始对话文本作为补充

问题分类

基于规则的快速分类器，支持中英文：

• 正则匹配关键词（如"什么时候"、"多少次"）
• 毫秒级响应，无需调用 LLM
• 可扩展的分类规则

开发指南

添加新的问题类型

1. 在 prompts/question_classifier.py 添加新类型：

class QuestionType(Enum):
    YOUR_TYPE = "your_type"

2. 在 prompts/answer_prompts.py 添加对应模板：

_YOUR_TYPE_PROMPT = """..."""

3. 更新分类规则和模板映射

自定义检索策略

继承 agent/retrievers.py 中的基类，实现自定义检索逻辑。

常见问题

Q: 如何清空记忆？

python utils/clear_short_long_memory.py

Q: 如何调整角色说话风格？

编辑角色书的 speech_style 和 example_dialogues 部分。

Q: 记忆巩固太频繁/太少？

调整 config.py 中的 memory_consolidation_threshold 参数。

许可证

MIT License

致谢

本项目基于认知架构智能体的理论框架实现。