GAM (General Agentic Memory) Skill

GAM（General Agentic Memory）技能

Skill by ara.so — AI Agent Skills collection.

GAM is a modular agentic file system framework that provides structured memory and operating environments for Large Language Models. It automatically chunks content, generates memory summaries, and organizes them hierarchically. Supports text documents, long videos, and agent trajectories with access via Python SDK, CLI, REST API, and Web interface.

由ara.so提供的技能——AI Agent技能合集。

GAM是一个模块化的Agent文件系统框架，为大语言模型（LLM）提供结构化记忆和运行环境。它会自动分割内容、生成记忆摘要，并进行分层组织。支持文本文档、长视频和Agent轨迹，可通过Python SDK、CLI、REST API和Web界面访问。

Installation

安装

bash

undefined

bash

undefined

Full installation with all features

完整安装所有功能

pip install -e ".[all]"

Basic installation (text only)

基础安装（仅支持文本）

pip install -e .

With specific features

安装特定功能

pip install -e ".[video]" # Video support pip install -e ".[api]" # REST API support pip install -e ".[web]" # Web interface support

undefined

pip install -e ".[video]" # 视频支持 pip install -e ".[api]" # REST API支持 pip install -e ".[web]" # Web界面支持

undefined

Configuration

配置

GAM uses environment variables for LLM configuration. Set these to avoid passing API keys in code:

bash

undefined

GAM使用环境变量进行LLM配置。设置这些变量可避免在代码中传递API密钥：

bash

undefined

GAM Agent (for memory building)

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 (for Q&A) — optional, falls back to GAM Agent config

聊天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"

undefined

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"

undefined

Python SDK Usage

Python SDK 使用方法

Basic Workflow API

基础工作流API

The

Workflow

class is the primary high-level interface:

python

from gam import Workflow

Workflow

类是主要的高层接口：

python

from gam import Workflow

Create a text workflow

创建文本工作流

wf = Workflow( task_type="text", gam_dir="./my_gam", model="gpt-4o-mini", # Optional if GAM_MODEL is set api_key=None # Uses GAM_API_KEY env var )

wf = Workflow( task_type="text", gam_dir="./my_gam", model="gpt-4o-mini", # 若已设置GAM_MODEL则可选 api_key=None # 使用GAM_API_KEY环境变量 )

Add content to GAM

向GAM添加内容

wf.add(input_file="research_paper.pdf")

Query the memory

查询记忆

result = wf.request("What is the main conclusion of this paper?") print(result.answer) print(result.context) # Retrieved memory context

undefined

result = wf.request("What is the main conclusion of this paper?") print(result.answer) print(result.context) # 检索到的记忆上下文

undefined

Incremental Memory Building

增量式记忆构建

Add new content to existing GAM without rebuilding:

python

from gam import Workflow

wf = Workflow("text", gam_dir="./knowledge_base")

无需重新构建即可向现有GAM添加新内容：

python

from gam import Workflow

wf = Workflow("text", gam_dir="./knowledge_base")

Add initial document

添加初始文档

wf.add(input_file="doc1.pdf")

Later, add more documents incrementally

后续增量添加更多文档

wf.add(input_file="doc2.pdf") wf.add(input_file="doc3.txt")

Query across all added documents

查询所有添加的文档

result = wf.request("Summarize the key points from all documents")

undefined

result = wf.request("Summarize the key points from all documents")

undefined

Video Memory Workflow

视频记忆工作流

python

from gam import Workflow

python

from gam import Workflow

Create video workflow

创建视频工作流

wf = Workflow( task_type="video", gam_dir="./video_gam", model="gpt-4o-mini" )

Add video content

添加视频内容

wf.add(input_file="lecture.mp4")

Query video content

查询视频内容

result = wf.request("What topics were covered in the first 10 minutes?") print(result.answer)

undefined

result = wf.request("What topics were covered in the first 10 minutes?") print(result.answer)

undefined

Long-Horizon Agent Trajectory

长周期Agent轨迹

python

from gam import Workflow

python

from gam import Workflow

Create long-horizon workflow for agent trajectories

为Agent轨迹创建长周期工作流

wf = Workflow( task_type="long-horizon", gam_dir="./agent_memory", model="gpt-4o-mini" )

Add agent trajectory data

添加Agent轨迹数据

wf.add(input_file="agent_trace.jsonl")

Query trajectory

查询轨迹

result = wf.request("What tool was used to solve the math problem?")

undefined

result = wf.request("What tool was used to solve the math problem?")

undefined

Advanced Component Usage

高级组件使用

For more control, use individual components:

python

from gam.text.core import TextGAM
from gam.text.chat import TextChatAgent

如需更多控制，可使用独立组件：

python

from gam.text.core import TextGAM
from gam.text.chat import TextChatAgent

Initialize GAM with custom config

使用自定义配置初始化GAM

gam = TextGAM( gam_dir="./custom_gam", model="gpt-4o-mini", api_key=None, # Uses env var chunk_size=2000, max_workers=4 )

gam = TextGAM( gam_dir="./custom_gam", model="gpt-4o-mini", api_key=None, # 使用环境变量 chunk_size=2000, max_workers=4 )

Build memory from text

从文本构建记忆

gam.add(input_file="document.pdf")

Initialize chat agent with different model

使用不同模型初始化聊天Agent

chat_agent = TextChatAgent( gam_dir="./custom_gam", model="gpt-4o", # More powerful model for Q&A api_key=None, top_k=10, # Number of memory chunks to retrieve rerank=True # Enable reranking )

chat_agent = TextChatAgent( gam_dir="./custom_gam", model="gpt-4o", # 更强大的模型用于问答 api_key=None, top_k=10, # 要检索的记忆块数量 rerank=True # 启用重排序 )

Query

查询

response = chat_agent.chat("What are the main findings?") print(response)

undefined

response = chat_agent.chat("What are the main findings?") print(response)

undefined

CLI Usage

CLI 使用方法

Adding Content to GAM

向GAM添加内容

bash

undefined

bash

undefined

Add text document

添加文本文档

gam-add --type text --gam-dir ./my_gam --input paper.pdf

Add with custom model

使用自定义模型添加

gam-add --type text --gam-dir ./my_gam --input paper.pdf --model gpt-4o

Add video

添加视频

gam-add --type video --gam-dir ./video_gam --input lecture.mp4

Add agent trajectory

添加Agent轨迹

gam-add --type long-horizon --gam-dir ./agent_gam --input trace.jsonl

undefined

gam-add --type long-horizon --gam-dir ./agent_gam --input trace.jsonl

undefined

Querying GAM

查询GAM

bash

undefined

bash

undefined

Basic query

基础查询

gam-request --type text --gam-dir ./my_gam --question "What is the main conclusion?"

Query with custom chat model

使用自定义聊天模型查询

gam-request --type text --gam-dir ./my_gam --question "Explain the methodology"
--model gpt-4o --top-k 15

Video query

视频查询

gam-request --type video --gam-dir ./video_gam --question "Summarize the lecture"

Long-horizon query

长周期查询

gam-request --type long-horizon --gam-dir ./agent_gam --question "What actions were taken?"

undefined

gam-request --type long-horizon --gam-dir ./agent_gam --question "What actions were taken?"

undefined

CLI with Environment Variables

结合环境变量使用CLI

bash

undefined

bash

undefined

Set once

一次性设置

export GAM_API_KEY="sk-your-key" export GAM_MODEL="gpt-4o-mini"

Then use without specifying credentials

之后无需指定凭据即可使用

gam-add --type text --gam-dir ./my_gam --input doc.pdf gam-request --type text --gam-dir ./my_gam --question "Summary?"

undefined

gam-add --type text --gam-dir ./my_gam --input doc.pdf gam-request --type text --gam-dir ./my_gam --question "Summary?"

undefined

REST API Usage

REST API 使用方法

Starting the API Server

启动API服务器

python

undefined

python

undefined

examples/run_api.py

from gam.api import create_app import uvicorn

app = create_app()

if name == "main": uvicorn.run(app, host="0.0.0.0", port=5001)


```bash

from gam.api import create_app import uvicorn

app = create_app()

if name == "main": uvicorn.run(app, host="0.0.0.0", port=5001)


```bash

Start server

启动服务器

python examples/run_api.py --port 5001

Interactive API docs at http://localhost:5001/docs

交互式API文档地址：http://localhost:5001/docs

undefined

undefined

REST API Client Example

REST API客户端示例

python

import requests

BASE_URL = "http://localhost:5001"

python

import requests

BASE_URL = "http://localhost:5001"

Add content via API

通过API添加内容

add_response = requests.post( f"{BASE_URL}/add", json={ "task_type": "text", "gam_dir": "./api_gam", "input_file": "document.pdf", "model": "gpt-4o-mini" } ) print(add_response.json())

Query via API

通过API查询

query_response = requests.post( f"{BASE_URL}/request", json={ "task_type": "text", "gam_dir": "./api_gam", "question": "What are the key findings?", "model": "gpt-4o", "top_k": 10 } ) result = query_response.json() print(result["answer"]) print(result["context"])

undefined

query_response = requests.post( f"{BASE_URL}/request", json={ "task_type": "text", "gam_dir": "./api_gam", "question": "What are the key findings?", "model": "gpt-4o", "top_k": 10 } ) result = query_response.json() print(result["answer"]) print(result["context"])

undefined

REST API Endpoints

REST API端点

```
POST /add
```
- Add content to GAM
```
POST /request
```
- Query GAM memory
```
GET /health
```
- Health check
```
GET /docs
```
- Interactive API documentation

```
POST /add
```
- 向GAM添加内容
```
POST /request
```
- 查询GAM记忆
```
GET /health
```
- 健康检查
```
GET /docs
```
- 交互式API文档

Web Interface Usage

Web界面使用方法

Starting the Web Platform

启动Web平台

python

undefined

python

undefined

examples/run_web.py

from gam.web import app

if name == "main": app.run(host="0.0.0.0", port=5000, debug=True)


```bash

from gam.web import app

if name == "main": app.run(host="0.0.0.0", port=5000, debug=True)


```bash

Start with environment variables

使用环境变量启动

export GAM_MODEL="gpt-4o-mini" export GAM_API_KEY="sk-your-key" python examples/run_web.py

Or pass directly

或直接传递参数

python examples/run_web.py --model gpt-4o-mini --api-key sk-your-key --port 5000


Access at `http://localhost:5000` for visual GAM management and querying.

python examples/run_web.py --model gpt-4o-mini --api-key sk-your-key --port 5000


访问`http://localhost:5000`进行可视化GAM管理和查询。

Common Patterns

常见模式

Multi-Document Knowledge Base

多文档知识库

python

from gam import Workflow

python

from gam import Workflow

Create knowledge base

创建知识库

kb = Workflow("text", gam_dir="./knowledge_base")

Add multiple documents

添加多个文档

documents = ["finance.pdf", "legal.pdf", "tech.pdf"] for doc in documents: kb.add(input_file=doc)

Query across all documents

查询所有文档

result = kb.request("What are the legal implications mentioned in any document?")

undefined

result = kb.request("What are the legal implications mentioned in any document?")

undefined

Video Analysis Pipeline

视频分析流水线

python

from gam import Workflow

python

from gam import Workflow

Process video lectures

处理视频讲座

wf = Workflow("video", gam_dir="./lectures")

Add multiple lectures

添加多个讲座

wf.add(input_file="lecture1.mp4") wf.add(input_file="lecture2.mp4")

Ask questions about content

查询内容相关问题

topics = wf.request("What are all the topics covered?") timeline = wf.request("When was machine learning discussed?")

undefined

topics = wf.request("What are all the topics covered?") timeline = wf.request("When was machine learning discussed?")

undefined

Agent Memory with Search/Recall

带搜索/召回功能的Agent记忆

python

from gam import Workflow

python

from gam import Workflow

Agent trajectory memory

Agent轨迹记忆

agent_mem = Workflow("long-horizon", gam_dir="./agent_traces")

Add agent execution trace

添加Agent执行轨迹

agent_mem.add(input_file="execution_log.jsonl")

Recall specific actions

召回特定操作

result = agent_mem.request("What was the sequence of tool calls for solving the problem?")

Search for patterns

搜索模式

patterns = agent_mem.request("How many times did the agent retry failed operations?")

undefined

patterns = agent_mem.request("How many times did the agent retry failed operations?")

undefined

Custom Memory Configuration

自定义记忆配置

python

from gam.text.core import TextGAM
from gam.text.chat import TextChatAgent

python

from gam.text.core import TextGAM
from gam.text.chat import TextChatAgent

High-performance memory building

高性能记忆构建

gam = TextGAM( gam_dir="./optimized_gam", model="gpt-4o-mini", chunk_size=3000, # Larger chunks max_workers=8, # More parallel workers embedding_model="text-embedding-3-large" )

gam.add(input_file="large_corpus.txt")

gam = TextGAM( gam_dir="./optimized_gam", model="gpt-4o-mini", chunk_size=3000, # 更大的块 max_workers=8, # 更多并行工作进程 embedding_model="text-embedding-3-large" )

gam.add(input_file="large_corpus.txt")

Precision-focused retrieval

精准检索

chat = TextChatAgent( gam_dir="./optimized_gam", model="gpt-4o", top_k=20, # Retrieve more candidates rerank=True, # Enable reranking temperature=0.0 # Deterministic responses )

response = chat.chat("Find all mentions of quantum computing")

undefined

chat = TextChatAgent( gam_dir="./optimized_gam", model="gpt-4o", top_k=20, # 检索更多候选 rerank=True, # 启用重排序 temperature=0.0 # 确定性响应 )

response = chat.chat("Find all mentions of quantum computing")

undefined

Docker Workspace Support

Docker工作区支持

python

from gam import Workflow

python

from gam import Workflow

Create GAM in Docker container workspace

在Docker容器工作区中创建GAM

wf = Workflow( task_type="text", gam_dir="/workspace/gam", # Container path model="gpt-4o-mini" )

wf = Workflow( task_type="text", gam_dir="/workspace/gam", # 容器路径 model="gpt-4o-mini" )

Works seamlessly in containerized environments

在容器化环境中无缝运行

wf.add(input_file="/workspace/data/document.pdf") result = wf.request("Summarize the document")

undefined

wf.add(input_file="/workspace/data/document.pdf") result = wf.request("Summarize the document")

undefined

Troubleshooting

故障排除

API Key Issues

API密钥问题

If you get authentication errors:

python

undefined

如果遇到身份验证错误：

python

undefined

Check environment variables

检查环境变量

import os print(os.getenv("GAM_API_KEY")) print(os.getenv("GAM_MODEL"))

Or pass explicitly

或显式传递

wf = Workflow("text", gam_dir="./gam", model="gpt-4o-mini", api_key="sk-your-key")

undefined

wf = Workflow("text", gam_dir="./gam", model="gpt-4o-mini", api_key="sk-your-key")

undefined

Missing Dependencies

依赖缺失

bash

undefined

bash

undefined

If video processing fails

如果视频处理失败

pip install -e ".[video]"

If API server fails

如果API服务器启动失败

pip install -e ".[api]"

If web interface fails

如果Web界面启动失败

pip install -e ".[web]"

Install everything

安装所有依赖

pip install -e ".[all]"

undefined

pip install -e ".[all]"

undefined

Memory Not Found

记忆未找到

python

undefined

python

undefined

Ensure GAM directory exists and has content

确保GAM目录存在且包含内容

import os gam_dir = "./my_gam"

if not os.path.exists(gam_dir): print("GAM directory not found. Run add() first.")

if not os.path.exists(f"{gam_dir}/chunks"): print("No chunks found. GAM may be empty.")

undefined

import os gam_dir = "./my_gam"

if not os.path.exists(gam_dir): print("未找到GAM目录，请先运行add()。")

if not os.path.exists(f"{gam_dir}/chunks"): print("未找到块，GAM可能为空。")

undefined

Slow Performance

性能缓慢

python

undefined

python

undefined

Increase parallel workers for faster building

增加并行工作进程以加快构建速度

from gam.text.core import TextGAM

gam = TextGAM( gam_dir="./gam", max_workers=16, # More workers chunk_size=2500 # Adjust chunk size )

from gam.text.core import TextGAM

gam = TextGAM( gam_dir="./gam", max_workers=16, # 更多工作进程 chunk_size=2500 # 调整块大小 )

Use smaller, faster model for building

使用更小、更快的模型构建记忆

gam = TextGAM(gam_dir="./gam", model="gpt-4o-mini")

Use larger model only for querying

仅在查询时使用更大的模型

from gam.text.chat import TextChatAgent chat = TextChatAgent(gam_dir="./gam", model="gpt-4o")

undefined

from gam.text.chat import TextChatAgent chat = TextChatAgent(gam_dir="./gam", model="gpt-4o")

undefined

Model Configuration

模型配置

python

undefined

python

undefined

Use different models for different stages

为不同阶段使用不同模型

from gam import Workflow

Fast model for memory building

使用快速模型构建记忆

wf = Workflow("text", gam_dir="./gam", model="gpt-4o-mini") wf.add(input_file="doc.pdf")

Advanced model for complex queries

使用高级模型处理复杂查询

from gam.text.chat import TextChatAgent chat = TextChatAgent(gam_dir="./gam", model="gpt-4o") response = chat.chat("Complex analytical question?")

undefined

from gam.text.chat import TextChatAgent chat = TextChatAgent(gam_dir="./gam", model="gpt-4o") response = chat.chat("Complex analytical question?")

undefined

Directory Structure

目录结构

After building a GAM, the structure looks like:

./my_gam/
├── chunks/          # Segmented content chunks
├── memories/        # Generated memory summaries
├── taxonomy/        # Hierarchical organization
├── embeddings/      # Vector embeddings for retrieval
└── metadata.json    # GAM configuration

构建GAM后，目录结构如下：

./my_gam/
├── chunks/          # 分割后的内容块
├── memories/        # 生成的记忆摘要
├── taxonomy/        # 分层组织的结构
├── embeddings/      # 用于检索的向量嵌入
└── metadata.json    # GAM配置文件

Research Codebase

研究代码库

For academic research and benchmarking:

bash

cd research
pip install -e .

python

from gam_research import MemoryAgent, ResearchAgent

用于学术研究和基准测试：

bash

cd research
pip install -e .

python

from gam_research import MemoryAgent, ResearchAgent

Dual-agent implementation from paper

论文中的双Agent实现

memorizer = MemoryAgent(gam_dir="./research_gam") researcher = ResearchAgent(gam_dir="./research_gam")

Run benchmarks (LoCoMo, HotpotQA, RULER, NarrativeQA)

运行基准测试（LoCoMo、HotpotQA、RULER、NarrativeQA）

See research/README.md for details

详情请查看research/README.md

undefined

undefined

Key Concepts

核心概念

GAM Directory: File system location where memory is stored
Chunks: Semantically segmented pieces of content
Memories: LLM-generated summaries with TLDR for each chunk
Taxonomy: Hierarchical directory structure organizing memories
Workflow: High-level API combining add and request operations
Incremental Addition: Add new content without rebuilding existing memory

GAM目录：存储记忆的文件系统位置
块（Chunks）：语义分割后的内容片段
记忆（Memories）：LLM生成的摘要，包含每个块的TLDR
分类体系（Taxonomy）：组织记忆的分层目录结构
工作流（Workflow）：整合添加和查询操作的高层API
增量添加：无需重建现有记忆即可添加新内容

gam-agentic-memory

Original

Translation

GAM (General Agentic Memory) Skill

GAM（General Agentic Memory）技能

Installation

安装

Full installation with all features

完整安装所有功能

Basic installation (text only)

基础安装（仅支持文本）

With specific features

安装特定功能

Configuration

配置

GAM Agent (for memory building)

GAM Agent（用于构建记忆）

Chat Agent (for Q&A) — optional, falls back to GAM Agent config

聊天Agent（用于问答）——可选，默认使用GAM Agent配置

Python SDK Usage

Python SDK 使用方法

Basic Workflow API

基础工作流API

Create a text workflow

创建文本工作流

Add content to GAM

向GAM添加内容

Query the memory

查询记忆

Incremental Memory Building

增量式记忆构建

Add initial document

添加初始文档

Later, add more documents incrementally

后续增量添加更多文档

Query across all added documents

查询所有添加的文档

Video Memory Workflow

视频记忆工作流

Create video workflow

创建视频工作流

Add video content

添加视频内容

Query video content

查询视频内容

Long-Horizon Agent Trajectory

长周期Agent轨迹

Create long-horizon workflow for agent trajectories

为Agent轨迹创建长周期工作流

Add agent trajectory data

添加Agent轨迹数据

Query trajectory

查询轨迹

Advanced Component Usage

高级组件使用

Initialize GAM with custom config

使用自定义配置初始化GAM

Build memory from text

从文本构建记忆

Initialize chat agent with different model

使用不同模型初始化聊天Agent

Query

查询

CLI Usage

CLI 使用方法

Adding Content to GAM

向GAM添加内容

Add text document

添加文本文档

Add with custom model

使用自定义模型添加

Add video

添加视频

Add agent trajectory

添加Agent轨迹

Querying GAM

查询GAM

Basic query

基础查询

Query with custom chat model