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 整合: 函數呼叫和上下文管理
• 軟體設計: 清晰的抽象和可擴展架構