General Agentic Memory (GAM) Skill

General Agentic Memory (GAM) 技能

Skill by ara.so — AI Agent Skills collection.

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

Overview

概述

GAM (General Agentic Memory) is a modular agentic file system framework that provides structured memory and operating environments for Large Language Models. It supports text, video, and long-horizon agent trajectories with four access methods: Python SDK, CLI, REST API, and Web Platform.

GAM（General Agentic Memory，通用智能体记忆）是一个模块化的智能体文件系统框架，为大语言模型（LLM）提供结构化记忆和运行环境。它支持文本、视频和长时序智能体轨迹，提供四种访问方式：Python SDK、CLI、REST API和Web平台。

Key Capabilities

核心功能

Intelligent Chunking: LLM-based semantic text segmentation
Memory Generation: Structured memory summaries (Memory + TLDR) for each chunk
Hierarchical Organization: Automatic taxonomy-based directory structures
Incremental Updates: Append new content without rebuilding
Multi-modal: Text documents, videos, and agent trajectories
Flexible Backends: OpenAI, SGLang, and other inference engines

智能分块：基于LLM的语义文本分割
记忆生成：为每个分块生成结构化记忆摘要（Memory + TLDR）
分层组织：基于分类法的自动目录结构
增量更新：无需重建即可添加新内容
多模态支持：文本文档、视频和智能体轨迹
灵活后端：支持OpenAI、SGLang及其他推理引擎

Installation

安装

bash

undefined

bash

undefined

Full installation with all features

pip install -e ".[all]"

Or minimal installation

pip install -e .

undefined

pip install -e .

undefined

Configuration

配置

GAM uses environment variables for API configuration. Set these to avoid repeated parameter input:

bash

undefined

GAM使用环境变量进行API配置。设置这些变量可避免重复输入参数：

bash

undefined

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"


Alternatively, pass configuration directly in code or CLI commands.

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"


也可直接在代码或CLI命令中传入配置参数。

Python SDK Usage

Python SDK 使用方法

Basic Workflow API

基础工作流API

The

Workflow

class provides the simplest interface:

python

from gam import Workflow

Workflow

类提供最简单的接口：

python

from gam import Workflow

Initialize workflow for text processing

wf = Workflow( task_type="text", gam_dir="./my_text_gam", model="gpt-4o-mini", api_key=None # Uses GAM_API_KEY env var )

Add content to memory

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.sources) # Retrieved memory chunks

undefined

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

undefined

Video Memory Workflow

视频记忆工作流

python

from gam import Workflow

python

from gam import Workflow

Initialize video workflow

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

Add video content

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

Query video memory

result = wf.request("What topics are covered in this lecture?") print(result.answer)

undefined

result = wf.request("What topics are covered in this lecture?") print(result.answer)

undefined

Long-Horizon Agent Trajectories

长时序智能体轨迹

python

from gam import Workflow

python

from gam import Workflow

Initialize trajectory workflow

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

Add agent trajectory log

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

Query the trajectory

result = wf.request("What tools did the agent use to solve the task?") print(result.answer)

undefined

result = wf.request("What tools did the agent use to solve the task?") print(result.answer)

undefined

Incremental Memory Addition

增量添加记忆

python

from gam import Workflow

wf = Workflow(task_type="text", gam_dir="./my_gam")

python

from gam import Workflow

wf = Workflow(task_type="text", gam_dir="./my_gam")

Add initial content

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

Later, add more content incrementally

wf.add(input_file="document2.pdf") wf.add(input_file="document3.txt")

Query across all added content

result = wf.request("Compare the approaches in all three documents")

undefined

result = wf.request("Compare the approaches in all three documents")

undefined

Advanced: Using Individual Components

进阶：使用独立组件

python

from gam.text.chunker import TextChunker
from gam.text.memory_builder import MemoryBuilder
from gam.text.taxonomy_builder import TaxonomyBuilder
from gam.text.chat_agent import ChatAgent

python

from gam.text.chunker import TextChunker
from gam.text.memory_builder import MemoryBuilder
from gam.text.taxonomy_builder import TaxonomyBuilder
from gam.text.chat_agent import ChatAgent

Step 1: Chunk text

chunker = TextChunker(model="gpt-4o-mini") chunks = chunker.chunk(text="Long document text here...")

Step 2: Build memories

memory_builder = MemoryBuilder(model="gpt-4o-mini") memories = memory_builder.build(chunks)

Step 3: Create taxonomy

taxonomy_builder = TaxonomyBuilder(model="gpt-4o-mini") taxonomy = taxonomy_builder.build(memories)

Step 4: Save to GAM directory

gam_dir = "./my_gam" taxonomy.save(gam_dir)

Step 5: Query

chat_agent = ChatAgent( gam_dir=gam_dir, model="gpt-4o", task_type="text" ) answer = chat_agent.request("Your question here") print(answer)

undefined

chat_agent = ChatAgent( gam_dir=gam_dir, model="gpt-4o", task_type="text" ) answer = chat_agent.request("Your question here") print(answer)

undefined

Custom LLM Backend

自定义LLM后端

python

from gam import Workflow

python

from gam import Workflow

Use custom API endpoint (e.g., local vLLM server)

wf = Workflow( task_type="text", gam_dir="./my_gam", model="meta-llama/Llama-3-8B", api_base="http://localhost:8000/v1", api_key="EMPTY" # Some local servers don't require keys )

wf.add(input_file="document.pdf") result = wf.request("Summarize this document")

undefined

wf = Workflow( task_type="text", gam_dir="./my_gam", model="meta-llama/Llama-3-8B", api_base="http://localhost:8000/v1", api_key="EMPTY" # Some local servers don't require keys )

wf.add(input_file="document.pdf") result = wf.request("Summarize this document")

undefined

CLI Usage

CLI 使用方法

Adding Content with

gam-add

使用

gam-add

添加内容

bash

undefined

bash

undefined

Add text document

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

Add video

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

Add long-horizon trajectory

gam-add --type long-horizon
--gam-dir ./trajectory_gam
--input agent_log.jsonl

Use environment variables for API config

export GAM_API_KEY="sk-xxx" export GAM_MODEL="gpt-4o-mini" gam-add --type text --gam-dir ./my_gam --input document.txt

undefined

export GAM_API_KEY="sk-xxx" export GAM_MODEL="gpt-4o-mini" gam-add --type text --gam-dir ./my_gam --input document.txt

undefined

Querying with

gam-request

使用

gam-request

查询

bash

undefined

bash

undefined

Query text memory

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

Query video memory

gam-request --type video
--gam-dir ./video_gam
--question "What happens at 5 minutes?"

Query with custom chat model

export GAM_CHAT_MODEL="gpt-4o" export GAM_CHAT_API_KEY="sk-xxx" gam-request --type text
--gam-dir ./my_gam
--question "Summarize the key findings"

undefined

export GAM_CHAT_MODEL="gpt-4o" export GAM_CHAT_API_KEY="sk-xxx" gam-request --type text
--gam-dir ./my_gam
--question "Summarize the key findings"

undefined

CLI Options

CLI 选项

Common options for both

gam-add

and

gam-request

:

```
--type
```
: Task type (
```
text
```
,
```
video
```
,
```
long-horizon
```
)
```
--gam-dir
```
: Directory to store/read GAM memory
```
--model
```
: LLM model name
```
--api-key
```
: API key (or use
```
GAM_API_KEY
```
env var)
```
--api-base
```
: API base URL (or use
```
GAM_API_BASE
```
env var)

gam-add

和

gam-request

的通用选项：

```
--type
```
：任务类型（
```
text
```
、
```
video
```
、
```
long-horizon
```
）
```
--gam-dir
```
：存储/读取GAM记忆的目录
```
--model
```
：LLM模型名称
```
--api-key
```
：API密钥（或使用
```
GAM_API_KEY
```
环境变量）
```
--api-base
```
：API基础URL（或使用
```
GAM_API_BASE
```
环境变量）

REST API Usage

REST API 使用方法

Starting the Server

启动服务器

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

Run the API server

python examples/run_api.py --port 5001

Interactive API docs available at:

http://localhost:5001/docs

undefined

undefined

Using the API

使用API

python

import requests

API_BASE = "http://localhost:5001"

python

import requests

API_BASE = "http://localhost:5001"

Add content

add_response = requests.post( f"{API_BASE}/add", json={ "task_type": "text", "gam_dir": "./my_gam", "input_file": "document.pdf", "model": "gpt-4o-mini", "api_key": None # Uses server's env vars } ) print(add_response.json())

Query memory

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

undefined

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

undefined

API Endpoints

API 端点

```
POST /add
```
: Add content to a GAM
```
POST /request
```
: Query a GAM
```
GET /health
```
: Health check
```
GET /docs
```
: Interactive API documentation (Swagger UI)
```
GET /redoc
```
: Alternative API documentation

```
POST /add
```
：向GAM添加内容
```
POST /request
```
：查询GAM
```
GET /health
```
：健康检查
```
GET /docs
```
：交互式API文档（Swagger UI）
```
GET /redoc
```
：替代API文档

Web Interface

Web界面

bash

undefined

bash

undefined

Start web interface

python examples/run_web.py
--model gpt-4o-mini
--port 5000

Access at http://localhost:5000


The web interface provides:
- Visual GAM management
- File upload for text/video/trajectories
- Interactive Q&A interface
- Memory exploration and visualization


Web界面提供以下功能：
- 可视化GAM管理
- 文本/视频/轨迹文件上传
- 交互式问答界面
- 记忆探索与可视化

Common Patterns

常见使用模式

Multi-Document Knowledge Base

多文档知识库

python

from gam import Workflow

python

from gam import Workflow

Create a knowledge base from multiple documents

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

documents = [ "research/paper1.pdf", "research/paper2.pdf", "research/paper3.pdf", "notes/summary.txt" ]

for doc in documents: wf.add(input_file=doc)

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

documents = [ "research/paper1.pdf", "research/paper2.pdf", "research/paper3.pdf", "notes/summary.txt" ]

for doc in documents: wf.add(input_file=doc)

Cross-document queries

result = wf.request("Compare the methodologies across all papers")

undefined

result = wf.request("Compare the methodologies across all papers")

undefined

Agent Trajectory Compression

智能体轨迹压缩

python

from gam import Workflow

python

from gam import Workflow

Compress long agent execution traces

wf = Workflow(task_type="long-horizon", gam_dir="./agent_memory")

Add trajectory

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

Query specific actions

result = wf.request("What API calls did the agent make?")

Query reasoning

result = wf.request("Why did the agent choose this approach?")

undefined

result = wf.request("Why did the agent choose this approach?")

undefined

Video Analysis Pipeline

视频分析流水线

python

from gam import Workflow

python

from gam import Workflow

Build video memory

wf = Workflow(task_type="video", gam_dir="./video_memory") wf.add(input_file="tutorial.mp4")

Time-based queries

result = wf.request("What is demonstrated in the first 10 minutes?")

Content-based queries

result = wf.request("Find all mentions of error handling")

undefined

result = wf.request("Find all mentions of error handling")

undefined

Custom Memory Organization

自定义记忆组织

python

from gam.text.taxonomy_builder import TaxonomyBuilder
from gam.text.memory_builder import MemoryBuilder

python

from gam.text.taxonomy_builder import TaxonomyBuilder
from gam.text.memory_builder import MemoryBuilder

Build memories with custom chunking

memory_builder = MemoryBuilder(model="gpt-4o-mini") memories = memory_builder.build(your_chunks)

Organize with custom taxonomy strategy

taxonomy_builder = TaxonomyBuilder( model="gpt-4o-mini", max_depth=4 # Control hierarchy depth ) taxonomy = taxonomy_builder.build(memories)

Save to specific location

taxonomy.save("./custom_gam")

undefined

taxonomy.save("./custom_gam")

undefined

Troubleshooting

故障排查

API Key Issues

API密钥问题

Problem:

AuthenticationError

or missing API key

Solution: Ensure environment variables are set:

bash

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

问题：

AuthenticationError

或缺少API密钥

解决方案：确保已设置环境变量：

bash

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

Verify

echo $GAM_API_KEY


Or pass explicitly in code:

```python
wf = Workflow(
    task_type="text",
    gam_dir="./my_gam",
    api_key="sk-your-key",  # Explicit key
    model="gpt-4o-mini"
)

echo $GAM_API_KEY


或在代码中显式传入：

```python
wf = Workflow(
    task_type="text",
    gam_dir="./my_gam",
    api_key="sk-your-key",  # Explicit key
    model="gpt-4o-mini"
)

Model Not Found

模型未找到

Problem: Model name not recognized by API

Solution: Check model availability with your API provider:

python

undefined

问题：API无法识别模型名称

解决方案：检查API提供商的模型可用性：

python

undefined

For OpenAI

wf = Workflow(model="gpt-4o-mini") # Correct

For local vLLM

wf = Workflow( model="meta-llama/Llama-3-8B", # Full model path api_base="http://localhost:8000/v1" )

undefined

wf = Workflow( model="meta-llama/Llama-3-8B", # Full model path api_base="http://localhost:8000/v1" )

undefined

Empty or Invalid Responses

响应为空或无效

Problem: GAM returns empty results or errors during querying

Solution: Verify GAM directory structure:

python

import os

gam_dir = "./my_gam"
if not os.path.exists(gam_dir):
    print("GAM directory doesn't exist - need to run add() first")

问题：GAM查询时返回空结果或错误

解决方案：验证GAM目录结构：

python

import os

gam_dir = "./my_gam"
if not os.path.exists(gam_dir):
    print("GAM目录不存在——需先运行add()方法")

Check for memory files

if not os.path.exists(f"{gam_dir}/taxonomy.json"): print("No taxonomy found - GAM may be corrupted")

undefined

if not os.path.exists(f"{gam_dir}/taxonomy.json"): print("未找到分类文件——GAM可能已损坏")

undefined

Video Processing Failures

视频处理失败

Problem: Video GAM fails during processing

Solution: Ensure video dependencies are installed:

bash

pip install -e ".[all]"  # Includes video dependencies

问题：视频GAM处理失败

解决方案：确保已安装视频依赖：

bash

pip install -e ".[all]"  # Includes video dependencies

Verify ffmpeg is available (required for video)

which ffmpeg

undefined

which ffmpeg

undefined

Performance Issues with Large Documents

大文档性能问题

Problem: Memory building takes too long

Solution: Use more capable models for building, lighter models for querying:

python

undefined

问题：记忆构建耗时过长

解决方案：使用更强大的模型构建记忆，轻量模型用于查询：

python

undefined

Use powerful model for memory building (one-time cost)

wf = Workflow( task_type="text", gam_dir="./my_gam", model="gpt-4o" # Better chunking and summarization ) wf.add(input_file="large_document.pdf")

Use efficient model for queries (frequent operation)

from gam.text.chat_agent import ChatAgent chat = ChatAgent( gam_dir="./my_gam", model="gpt-4o-mini", # Faster and cheaper task_type="text" )

undefined

from gam.text.chat_agent import ChatAgent chat = ChatAgent( gam_dir="./my_gam", model="gpt-4o-mini", # Faster and cheaper task_type="text" )

undefined

Docker Environment Issues

Docker环境问题

Problem: Running GAM in containers

Solution: Mount GAM directory as volume:

bash

docker run -v $(pwd)/my_gam:/app/my_gam \
  -e GAM_API_KEY="sk-xxx" \
  -e GAM_MODEL="gpt-4o-mini" \
  your-image

问题：在容器中运行GAM

解决方案：将GAM目录挂载为卷：

bash

docker run -v $(pwd)/my_gam:/app/my_gam \
  -e GAM_API_KEY="sk-xxx" \
  -e GAM_MODEL="gpt-4o-mini" \
  your-image

Best Practices

最佳实践

Memory Organization

记忆组织

Use descriptive
```
gam_dir
```
names for different projects/topics
Keep related documents in the same GAM for better cross-referencing
Rebuild GAM when document structure changes significantly

为不同项目/主题使用描述性的
```
gam_dir
```
名称
将相关文档放在同一个GAM中，以便更好地交叉引用
当文档结构发生重大变化时，重建GAM

Model Selection

模型选择

Building memory: Use
```
gpt-4o
```
or
```
gpt-4o-mini
```
for quality
Querying: Use
```
gpt-4o-mini
```
for cost-effectiveness
Local inference: Use SGLang or vLLM for privacy/cost

构建记忆：使用
```
gpt-4o
```
或
```
gpt-4o-mini
```
以保证质量
查询：使用
```
gpt-4o-mini
```
以兼顾成本与效率
本地推理：使用SGLang或vLLM以保障隐私/降低成本

Incremental Updates

增量更新

python

undefined

python

undefined

Good: Add documents incrementally

wf = Workflow(task_type="text", gam_dir="./docs") wf.add(input_file="doc1.pdf") wf.add(input_file="doc2.pdf")

Avoid: Rebuilding entire GAM for new documents

(GAM handles incremental addition efficiently)

undefined

undefined

Error Handling

错误处理

python

from gam import Workflow

try:
    wf = Workflow(task_type="text", gam_dir="./my_gam")
    wf.add(input_file="document.pdf")
    result = wf.request("What is this about?")
    print(result.answer)
except Exception as e:
    print(f"Error: {e}")
    # Handle appropriately (retry, log, etc.)

python

from gam import Workflow

try:
    wf = Workflow(task_type="text", gam_dir="./my_gam")
    wf.add(input_file="document.pdf")
    result = wf.request("What is this about?")
    print(result.answer)
except Exception as e:
    print(f"Error: {e}")
    # Handle appropriately (retry, log, etc.)

Research Implementation

研究版本实现

For academic benchmarking and the original dual-agent implementation:

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

Use research implementation

memory_agent = MemoryAgent(model="gpt-4o") research_agent = ResearchAgent(model="gpt-4o")


See `research/README.md` for benchmark evaluation scripts.

memory_agent = MemoryAgent(model="gpt-4o") research_agent = ResearchAgent(model="gpt-4o")


有关基准测试脚本，请查看`research/README.md`。

general-agentic-memory

Original

Translation

General Agentic Memory (GAM) Skill

General Agentic Memory (GAM) 技能

Overview

概述

Key Capabilities

核心功能

Installation

安装

Full installation with all features

Full installation with all features

Or minimal installation

Or minimal installation

Configuration

配置

GAM Agent (memory building)

GAM Agent (memory building)

Chat Agent (Q&A) — falls back to GAM Agent config when not set

Chat Agent (Q&A) — falls back to GAM Agent config when not set

Python SDK Usage

Python SDK 使用方法

Basic Workflow API

基础工作流API

Initialize workflow for text processing

Initialize workflow for text processing

Add content to memory

Add content to memory

Query the memory

Query the memory

Video Memory Workflow

视频记忆工作流

Initialize video workflow

Initialize video workflow

Add video content

Add video content

Query video memory

Query video memory

Long-Horizon Agent Trajectories

长时序智能体轨迹

Initialize trajectory workflow

Initialize trajectory workflow

Add agent trajectory log

Add agent trajectory log

Query the trajectory

Query the trajectory

Incremental Memory Addition

增量添加记忆

Add initial content

Add initial content

Later, add more content incrementally

Later, add more content incrementally

Query across all added content

Query across all added content

Advanced: Using Individual Components

进阶：使用独立组件

Step 1: Chunk text

Step 1: Chunk text

Step 2: Build memories

Step 2: Build memories

Step 3: Create taxonomy

Step 3: Create taxonomy

Step 4: Save to GAM directory

Step 4: Save to GAM directory

Step 5: Query

Step 5: Query

Custom LLM Backend

自定义LLM后端

Use custom API endpoint (e.g., local vLLM server)

Use custom API endpoint (e.g., local vLLM server)

CLI Usage

CLI 使用方法

Adding Content with gam-add

使用gam-add添加内容

Add text document

Add text document

Add video

Add video

Add long-horizon trajectory

Adding Content with
`gam-add`

使用
`gam-add`
添加内容

Querying with
`gam-request`

使用
`gam-request`
查询