MemoRizz 项目详细介绍

项目概述

MemoRizz 是一个专为 AI 应用设计的 Python 内存管理库，为 AI 智能体提供持久化、上下文感知和语义搜索的信息存储能力。该项目通过 MongoDB 与向量嵌入技术的无缝集成，赋予智能体复杂的认知功能，包括对话历史跟踪、工具使用管理和一致的角色维护。

⚠️ 重要警告：MemoRizz 是一个实验性库，仅用于教育目的。不建议在生产环境或敏感数据中使用。

核心特性

🧠 持久化内存

• 让 AI 智能体在会话间保持记忆
• 支持长期信息存储和检索
• 上下文感知的内存管理

🔍 语义搜索

• 使用自然语言查找相关信息
• 基于向量嵌入的相似性搜索
• MongoDB Atlas 向量搜索集成

🛠️ 工具集成

• 自动发现和执行函数
• 将 Python 函数转换为 LLM 可调用工具
• 工具的语义索引和自然语言发现

👤 角色系统

• 创建一致的专业化智能体角色
• 自定义智能体行为和响应风格
• 角色背景和目标设定

📊 向量搜索

• MongoDB Atlas 向量搜索高效检索
• 自动嵌入和索引存储信息
• 支持多种内存类型分类

系统架构

┌─────────────────┐
│ MemAgent        │ ← 高级智能体接口
├─────────────────┤
│ Persona         │ ← 智能体个性和行为
├─────────────────┤
│ Toolbox         │ ← 函数注册和发现
├─────────────────┤
│ Memory Provider │ ← 存储抽象层
├─────────────────┤
│ Vector Search   │ ← 语义相似性和检索
├─────────────────┤
│ MongoDB         │ ← 持久化存储后端
└─────────────────┘

安装要求

• Python 3.7+
• MongoDB Atlas 账户（或本地 MongoDB 与向量搜索）
• OpenAI API 密钥（用于嵌入和 LLM 功能）

安装方法

pip install memorizz

基本使用示例

1. 基础智能体设置

import os
from memorizz.memory_provider.mongodb.provider import MongoDBConfig, MongoDBProvider
from memorizz.memagent import MemAgent
from memorizz.llms.openai import OpenAI

# 设置 API 密钥
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# 配置 MongoDB 内存提供器
mongodb_config = MongoDBConfig(uri="your-mongodb-atlas-uri")
memory_provider = MongoDBProvider(mongodb_config)

# 创建 MemAgent
agent = MemAgent(
    model=OpenAI(model="gpt-4"),
    instruction="You are a helpful assistant with persistent memory.",
    memory_provider=memory_provider
)

# 开始对话 - 智能体将在会话间保持记忆
response = agent.run("Hello! My name is John and I'm a software engineer.")
print(response)

# 稍后在另一个会话中...
response = agent.run("What did I tell you about myself?")
print(response)  # 智能体记得 John 是软件工程师

2. 角色系统使用

from memorizz.persona import Persona

# 创建技术专家角色
tech_expert = Persona(
    name="TechExpert",
    role="Senior Software Engineer",
    goals="Help developers solve complex technical problems with detailed explanations.",
    background="10+ years experience in Python, AI/ML, and distributed systems."
)

# 将角色应用到智能体
agent.set_persona(tech_expert)
agent.save()

# 现在智能体将以技术专家的身份响应
response = agent.run("How should I design a scalable microservices architecture?")

3. 工具集成

from memorizz.database.mongodb import MongoDBTools, MongoDBToolsConfig

# 配置工具数据库
tools_config = MongoDBToolsConfig(
    uri="your-mongodb-atlas-uri",
    database_name="my_tools_db"
)

# 使用装饰器注册工具
with MongoDBTools(tools_config) as tools:
    toolbox = tools.mongodb_toolbox()
    
    @toolbox
    def calculate_compound_interest(principal: float, rate: float, time: int) -> float:
        """Calculate compound interest for financial planning."""
        return principal * (1 + rate) ** time
    
    @toolbox
    def get_weather(city: str) -> str:
        """Get current weather for a city."""
        # 你的天气 API 集成代码
        return f"Weather in {city}: 72°F, sunny"

# 向智能体添加工具
agent.add_tool(toolbox=tools)

# 智能体现在可以自动发现和使用这些工具
response = agent.run("What's the weather in San Francisco and calculate interest on $1000 at 5% for 3 years?")

内存类型

MemoRizz 支持不同的内存类别来组织信息：

• Conversation: 聊天历史和对话上下文
• Task: 目标导向的信息和进度跟踪
• Workflow: 多步骤流程信息
• General: 事实知识和声明性信息
• Working: 临时处理空间（LLM 上下文）

高级特性

内存存储和检索

# 存储带有自动嵌入的信息
agent.store_memory("I prefer Python for backend development", memory_type="general")

# 稍后，语义相关的查询将检索这些信息
response = agent.run("What programming languages do I like?")
# 智能体将找到并使用存储的偏好

带元数据的内存控制

# 存储带有元数据的信息
agent.store_memory(
    content="Completed project X with React and Node.js",
    memory_type="task",
    metadata={"project": "X", "technologies": ["React", "Node.js"]}
)

# 检索特定内存
memories = agent.retrieve_memories(
    query="projects with React",
    memory_type="task",
    limit=5
)

环境配置

# 必需
export OPENAI_API_KEY="your-openai-api-key"
export MONGODB_URI="your-mongodb-atlas-uri"

# 可选
export MONGODB_DB_NAME="memorizz"  # 默认数据库名

设置步骤

1. 创建 MongoDB Atlas 集群
2. 在集群上启用向量搜索
3. 为你的智能体创建数据库和集合
4. 获取连接字符串

常见问题

• MongoDB 连接: 确保你的 IP 在 Atlas 中被列入白名单
• 向量搜索: 验证集群上已启用向量搜索
• API 密钥: 检查 OpenAI API 密钥是否有效且有积分

示例项目

在 examples/ 目录中查看完整的工作示例：

• 基础智能体: 带内存的简单对话智能体
• 专业智能体: 具有角色的技术专家
• 工具集成: 带自定义函数调用的智能体
• 内存管理: 高级内存存储和检索

技术学习价值

该库演示了以下关键概念：

• AI 智能体架构: 内存、推理和工具使用
• 向量数据库: 语义搜索和检索
• LLM 集成: 函数调用和上下文管理
• 软件设计: 清晰的抽象和可扩展架构