实验性软件

Memorizz 是一个教育性和实验性的框架。其 API 可能会发生变化，且该项目尚未针对生产工作负载进行安全加固。

Memorizz 是一个用于构建内存增强型 AI 代理的 Python 框架。 它提供了：

• 多种记忆系统（情景记忆、语义记忆、程序性记忆、短期记忆、共享记忆）
• 可插拔的存储提供者（Oracle、MongoDB、文件系统）
• 代理构建工具和应用模式（assistant、workflow、deep_research）
• 定时自动化任务（cron、间隔、一次性），可选通过 WhatsApp 发送
• 可选的互联网访问、沙盒代码执行以及本地 Web 界面

核心功能

• 跨会话和对话的持久化记忆
• 基于嵌入向量与向量搜索的语义检索
• 用于个人资料式事实的实体记忆工具（entity_memory_lookup / entity_memory_upsert）
• 自动注册函数的工具调用
• 用于减少重复 LLM 调用的语义缓存
• 共享黑板记忆的多代理编排
• 通过 get_context_window_stats() 提供的上下文窗口遥测
• 通过 SDK、Web 界面或代理对话实现的定时自动化任务（参见 src/memorizz/automation/README.md）

安装

基础安装：

pip install memorizz

常用扩展：

pip install "memorizz[oracle]"          # Oracle 提供者
pip install "memorizz[mongodb]"         # MongoDB 提供者
pip install "memorizz[filesystem]"      # 本地文件系统 + FAISS
pip install "memorizz[sandbox-e2b]"     # E2B 沙盒
pip install "memorizz[sandbox-daytona]" # Daytona 沙盒
pip install "memorizz[ui]"              # 本地 Web 界面
pip install "memorizz[all]"             # 所有功能

快速入门（文件系统提供者）

import os
from pathlib import Path

from memorizz.memagent.builders import MemAgentBuilder
from memorizz.memory_provider import FileSystemConfig, FileSystemProvider

os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

provider = FileSystemProvider(
    FileSystemConfig(
        root_path=Path("~/.memorizz").expanduser(),
        embedding_provider="openai",
        embedding_config={"model": "text-embedding-3-small"},
    )
)

agent = (
    MemAgentBuilder()
    .with_instruction("You are a helpful assistant with persistent memory.")
    .with_memory_provider(provider)
    .with_llm_config(
        {
            "provider": "openai",
            "model": "gpt-4o-mini",
            "api_key": os.environ["OPENAI_API_KEY"],
        }
    )
    .with_semantic_cache(enabled=True, threshold=0.85)
    .build()
)

print(agent.run("Hi, my name is Leah and I work on payments systems."))
print(agent.run("What did I tell you about my work?"))

stats = agent.get_context_window_stats()
print(stats)

Oracle 设置（可选）

若希望使用 Oracle AI 数据库作为后端存储：

./install_oracle.sh
memorizz setup-oracle

然后配置 ORACLE_USER、ORACLE_PASSWORD、ORACLE_DSN 以及您的 LLM 凭证。完整的设置说明请参阅 SETUP.md。

为了确保多客户端一致性（UI 和笔记本），您可以设置共享的嵌入默认值：

export MEMORIZZ_DEFAULT_EMBEDDING_PROVIDER=openai
export MEMORIZZ_DEFAULT_EMBEDDING_MODEL=text-embedding-3-small
export MEMORIZZ_DEFAULT_EMBEDDING_DIMENSIONS=1536

应用模式

ApplicationMode 预设会自动启用不同的记忆堆栈：

• assistant: 对话记忆、长期记忆、角色记忆、实体记忆、短期记忆、摘要
• workflow: 工作流记忆、工具箱、长期记忆、短期记忆、摘要
• deep_research: 工具箱、共享记忆、长期记忆、短期记忆、摘要

示例：

import os

from memorizz.enums import ApplicationMode
from memorizz.memagent.builders import MemAgentBuilder

llm_config = {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": os.environ["OPENAI_API_KEY"],
}

agent = (
    MemAgentBuilder()
    .with_application_mode(ApplicationMode.DEEP_RESEARCH)
    .with_memory_provider(provider)
    .with_llm_config(llm_config)
    .build()
)

互联网访问（深度研究）

深度研究代理可以附加互联网提供者，并暴露 internet_search 和 open_web_page 工具。

import os

from memorizz.internet_access import TavilyProvider
from memorizz.memagent.builders import create_deep_research_agent

llm_config = {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": os.environ["OPENAI_API_KEY"],
}

internet_provider = TavilyProvider(api_key=os.environ["TAVILY_API_KEY"])

agent = (
    create_deep_research_agent(internet_provider=internet_provider)
    .with_memory_provider(provider)
    .with_llm_config(llm_config)
    .build()
)

results = agent.search_internet("latest vector database benchmark")

沙盒代码执行

附加沙盒提供者以启用 execute_code、sandbox_write_file 和 sandbox_read_file 工具。

import os

from memorizz.memagent import MemAgent

llm_config = {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": os.environ["OPENAI_API_KEY"],
}

agent = MemAgent(
    llm_config=llm_config,
    memory_provider=provider,
    sandbox_provider="e2b",  // 或 "daytona" / "graalpy"
)

print(agent.execute_code("print(2 ** 16)"))

多代理深度研究工作流

from memorizz.memagent.orchestrators import DeepResearchWorkflow

workflow = DeepResearchWorkflow.from_config(
    memory_provider=provider,
    delegate_instructions=[
        "Financial researcher: collect metrics and citations.",
        "Risk analyst: identify key downside scenarios.",
    ],
)

report = workflow.run("Analyze the last 3 years of cloud infrastructure trends.")
print(report)

命令行界面

安装后，memorizz 命令提供以下功能：

memorizz run local                  # 启动本地 Web 界面（需安装 [ui]）
memorizz install-oracle             # 启动 Oracle 容器辅助工具
memorizz setup-oracle               # 初始化 Oracle 模式/用户

示例

• examples/single_agent/memagent_local_oracle.ipynb
• examples/single_agent/memagent_remote_oracle.ipynb
• examples/deep_research/deep_research_memagent.ipynb
• examples/sandbox/memagent_e2b_sandbox.ipynb
• examples/sandbox/memagent_daytona_sandbox.ipynb
• examples/sandbox/memagent_graalpy_sandbox.ipynb
• examples/automations/automations_guide.ipynb
• examples/model_providers/openai_provider.ipynb
• examples/model_providers/anthropic_provider.ipynb
• examples/model_providers/ollama_provider.ipynb
• examples/model_providers/compare_providers.ipynb

文档

• 文档源码：docs/
• 本地预览：make docs-serve（或 mkdocs serve）
• 架构说明：src/memorizz/MEMORY_ARCHITECTURE.md

许可证

PolyForm 非商业许可 1.0.0。 请参阅 LICENSE 和 NOTICE。

Memorizz 快速上手指南

Memorizz 是一个用于构建记忆增强型 AI 智能体的 Python 框架。它支持多种记忆系统（情景、语义、程序性等）、可插拔存储后端以及多智能体协作，旨在让 AI 具备跨会话的持久记忆能力。

注意：本项目目前处于实验阶段，API 可能发生变化，尚未针对生产环境进行安全加固。

1. 环境准备

在开始之前，请确保满足以下要求：

• Python 版本：建议 Python 3.9 或更高版本。
• API 密钥：
  • LLM 提供商：需要 OpenAI API Key（或其他支持的模型提供商密钥）。
  • 可选服务：若使用联网搜索需 Tavily API Key；若使用云沙箱需对应平台密钥。
• 操作系统：支持 Linux、macOS 和 Windows。

2. 安装步骤

基础安装

使用 pip 安装核心库：

pip install memorizz

安装扩展功能

根据需求选择安装额外的依赖包（国内用户如遇网络问题，可配置 -i 指定国内镜像源，如清华源 https://pypi.tuna.tsinghua.edu.cn/simple）：

# 本地文件系统存储 + FAISS 向量检索（推荐初学者）
pip install "memorizz[filesystem]"

# Oracle 数据库存储
pip install "memorizz[oracle]"

# MongoDB 存储
pip install "memorizz[mongodb]"

# E2B 代码沙箱
pip install "memorizz[sandbox-e2b]"

# 本地 Web UI 界面
pip install "memorizz[ui]"

# 安装所有功能
pip install "memorizz[all]"

3. 基本使用

以下示例展示如何使用本地文件系统作为存储后端，快速创建一个具备持久记忆的智能体。

步骤 1: 配置环境变量

在终端中设置你的 OpenAI API Key：

export OPENAI_API_KEY="your-openai-api-key"

(Windows PowerShell 用户使用 $env:OPENAI_API_KEY="your-openai-api-key")

步骤 2: 编写代码

创建 main.py 文件，填入以下代码：

import os
from pathlib import Path

from memorizz.memagent.builders import MemAgentBuilder
from memorizz.memory_provider import FileSystemConfig, FileSystemProvider

# 初始化文件系统存储提供商
# 记忆数据将保存在 ~/.memorizz 目录下
provider = FileSystemProvider(
    FileSystemConfig(
        root_path=Path("~/.memorizz").expanduser(),
        embedding_provider="openai",
        embedding_config={"model": "text-embedding-3-small"},
    )
)

# 构建智能体
agent = (
    MemAgentBuilder()
    .with_instruction("You are a helpful assistant with persistent memory.")
    .with_memory_provider(provider)
    .with_llm_config(
        {
            "provider": "openai",
            "model": "gpt-4o-mini",
            "api_key": os.environ["OPENAI_API_KEY"],
        }
    )
    .with_semantic_cache(enabled=True, threshold=0.85)
    .build()
)

# 第一次对话：告知个人信息
print(agent.run("Hi, my name is Leah and I work on payments systems."))

# 第二次对话：测试记忆检索
print(agent.run("What did I tell you about my work?"))

# 查看上下文窗口统计信息
stats = agent.get_context_window_stats()
print(stats)

步骤 3: 运行

执行脚本：

python main.py

预期结果： 智能体在第二次回答时能够准确回忆起你之前提到的工作内容（payments systems），证明持久化记忆已生效。

---

进阶提示

• 应用模式：可通过 .with_application_mode(ApplicationMode.DEEP_RESEARCH) 快速启用深度研究模式。
• 联网能力：结合 TavilyProvider 可实现互联网搜索功能。
• 代码执行：配置 sandbox_provider="e2b" 即可启用安全的代码执行沙箱。