GAM (基于智能体文件系统深度研究的通用智能体记忆)

英文 | 中文版

一个高度模块化的智能体文件系统（agentic file system）框架，为大型语言模型（LLMs）提供结构化记忆和运行环境。GAM 支持文本和视频模态（modalities），提供四种访问级别：Python SDK（软件开发工具包）、CLI（命令行界面）、REST API（表述性状态转移接口）和Web 平台。

功能特性

1. 核心功能

• 📝 智能分块（Intelligent Chunking）：基于大型语言模型（LLM）的文本分割，自动识别语义边界。
• 🧠 记忆生成（Memory Generation）：为每个文本块生成结构化记忆摘要（Memory + TLDR）。
• 📂 层级组织（Hierarchical Organization）：自动将记忆组织成层级目录结构（分类体系 Taxonomy）。
• ➕ 增量添加（Incremental Addition）：将新内容追加到现有的 GAM 实例中，无需重建。
• 🐳 多环境支持（Multi-environment Support）：支持本地文件系统和 Docker（容器平台）容器工作区。
• 🔌 灵活的 LLM 后端（Flexible LLM Backends）：兼容 OpenAI、SGLang 和其他推理引擎。

2. 支持的任务

• 📄 长文本（Long Text）：长文档的层级记忆组织和探索性问答（QA）。
• 🎥 长视频（Long Video）：自动检测、分割和描述，用于构建长视频记忆。
• 🎞️ 长程（智能体轨迹）（Long-horizon (Agent Trajectory)）：高效压缩和组织长序列智能体（Agent）轨迹（例如复杂推理步骤、工具调用日志），使智能体能够在广泛的操作中管理上下文。

3. 实现方法

• 🐍 Python SDK（软件开发工具包）：高级 Python SDK，易于集成到智能体工作流中。
• 💻 CLI 工具（命令行界面）：统一的 gam-add 和 gam-request 命令，用于命令行交互。
• 🚀 REST API（表述性状态转移接口）：高性能 RESTful API（FastAPI + Uvicorn），带有自动生成的 OpenAPI 文档、请求验证和 CORS（跨域资源共享）支持。
• 🌐 Web 平台：基于 Flask 的可视化管理界面。

快速开始

安装

# Full installation with all features
pip install -e ".[all]"

使用概览

GAM 可以通过 Python SDK、CLI、REST API 或 Web 界面使用。

1. Python SDK（工作流 API）

from gam import Workflow
wf = Workflow("text", gam_dir="./my_gam", model="gpt-4o-mini", api_key="sk-xxx")
wf.add(input_file="paper.pdf")
result = wf.request("What is the main conclusion?")
print(result.answer)

2. CLI 工具

# Add content
gam-add --type text --gam-dir ./my_gam --input paper.pdf
# Query content
gam-request --type text --gam-dir ./my_gam --question "What is the main conclusion?"

3. REST API

# Start REST API server (FastAPI + Uvicorn)
python examples/run_api.py --port 5001
# Interactive docs available at http://localhost:5001/docs
# See usage example
python examples/rest_api_client.py

4. Web 界面

python examples/run_web.py --model gpt-4o-mini --api-key sk-xxx

配置

设置环境变量以避免重复输入参数。GAM 智能体（Agent）（记忆构建）和 Chat 智能体（Agent）（问答）可以独立配置：

# GAM Agent (memory building)
export GAM_API_KEY="sk-your-api-key"
export GAM_MODEL="gpt-4o-mini"
export GAM_API_BASE="https://api.openai.com/v1"

# Chat Agent (Q&A) — falls back to GAM Agent config when not set
export GAM_CHAT_API_KEY="sk-your-chat-api-key"
export GAM_CHAT_MODEL="gpt-4o"
export GAM_CHAT_API_BASE="https://api.openai.com/v1"

文档

各组件的详细使用说明可在以下指南中找到：

• 🐍 Python SDK 使用：Workflow API 和高级组件用法。
• 💻 CLI 使用指南：详细的 gam-add 和 gam-request 命令。
• 🚀 REST API 使用：RESTful API 访问和程序化集成。
• 🌐 Web 使用指南：设置和运行可视化管理平台。

示例

查看 examples/ 目录以获取示例项目和使用指南：

示例	描述
long_text/	文本 GAM 构建与问答。
long_video/	视频 GAM 构建与问答。
long_horizon/	长程智能体轨迹压缩，包含搜索/记忆/召回。

研究

research/ 目录包含 GAM 论文 的原始研究代码库，包括基准评估脚本（LoCoMo, HotpotQA, RULER, NarrativeQA）和双智能体（Memorizer + Researcher）实现：

cd research
pip install -e .

from gam_research import MemoryAgent, ResearchAgent

更多详情，请参阅 研究 README。

许可证

本项目采用 MIT 许可证许可 - 详见 LICENSE 文件。

general-agentic-memory 快速上手指南

GAM (General Agentic Memory) 是一个高度模块化的代理文件系统框架，为大型语言模型（LLM）提供结构化记忆和操作环境。支持文本和视频模态，可通过 Python SDK、CLI、REST API 或 Web 平台使用。

环境准备

• 系统要求：支持本地文件系统或 Docker 容器工作空间（Linux/macOS/Windows）。

• 前置依赖：

  • Python 环境（建议 3.8+）
  • Git（用于获取源代码）
  • LLM API Key（支持 OpenAI、SGLang 等推理引擎）

• 环境变量配置： 为避免重复输入参数，建议在使用前配置以下环境变量。GAM Agent（记忆构建）和 Chat Agent（问答）可独立配置：

  # GAM Agent (记忆构建)
  export GAM_API_KEY="sk-your-api-key"
  export GAM_MODEL="gpt-4o-mini"
  export GAM_API_BASE="https://api.openai.com/v1"
  
  # Chat Agent (问答) — 未设置时将回退到 GAM Agent 配置
  export GAM_CHAT_API_KEY="sk-your-chat-api-key"
  export GAM_CHAT_MODEL="gpt-4o"
  export GAM_CHAT_API_BASE="https://api.openai.com/v1"
  

安装步骤

1. 获取项目源代码。

2. 在项目根目录下执行以下命令进行完整安装（包含所有功能）：

   pip install -e ".[all]"
   

基本使用

GAM 支持多种交互方式，以下是最常用的 Python SDK 和 CLI 工具示例。

1. Python SDK (Workflow API)

适用于将 GAM 集成到代理工作流中。

from gam import Workflow
wf = Workflow("text", gam_dir="./my_gam", model="gpt-4o-mini", api_key="sk-xxx")
wf.add(input_file="paper.pdf")
result = wf.request("What is the main conclusion?")
print(result.answer)

2. CLI 工具

适用于命令行快速交互。

# 添加内容
gam-add --type text --gam-dir ./my_gam --input paper.pdf
# 查询内容
gam-request --type text --gam-dir ./my_gam --question "What is the main conclusion?"

3. 其他访问方式

• REST API: 运行 python examples/run_api.py --port 5001 启动服务，访问 http://localhost:5001/docs 查看文档。
• Web 平台: 运行 python examples/run_web.py --model gpt-4o-mini --api-key sk-xxx 启动可视化管理界面。