gam-agentic-memory

Original：🇺🇸 English

Translated

Build structured hierarchical memory systems for LLM agents using GAM (General Agentic Memory) with support for text, video, and agent trajectories

11installs

Sourcearadotso/ai-agent-skills

Added on2026-05-31

NPX Install

npx skill4agent add aradotso/ai-agent-skills gam-agentic-memory

SKILL.md Content

View Translation Comparison →

GAM (General Agentic Memory) Skill

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.

Installation

bash

# 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

Configuration

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

bash

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

Basic Workflow API

The

Workflow

class is the primary high-level interface:

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
)

# Add content to 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

Incremental Memory Building

Add new content to existing GAM without rebuilding:

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")

Video Memory 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)

Long-Horizon Agent Trajectory

python

from gam import Workflow

# Create long-horizon workflow for agent trajectories
wf = Workflow(
    task_type="long-horizon",
    gam_dir="./agent_memory",
    model="gpt-4o-mini"
)

# Add agent trajectory data
wf.add(input_file="agent_trace.jsonl")

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

Advanced Component Usage

For more control, use individual components:

python

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

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

# Build memory from text
gam.add(input_file="document.pdf")

# Initialize chat agent with different model
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
)

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

CLI Usage

Adding Content to GAM

bash

# 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
gam-add --type long-horizon --gam-dir ./agent_gam --input trace.jsonl

Querying GAM

bash

# 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?"

CLI with Environment Variables

bash

# 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?"

REST API Usage

Starting the API Server

python

# 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

# Start server
python examples/run_api.py --port 5001

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

REST API Client Example

python

import requests

BASE_URL = "http://localhost:5001"

# Add content via 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
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"])

REST API Endpoints

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

Web Interface Usage

Starting the Web Platform

python

# examples/run_web.py
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.

Common Patterns

Multi-Document Knowledge Base

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?")

Video Analysis Pipeline

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?")

Agent Memory with Search/Recall

python

from gam import Workflow

# Agent trajectory memory
agent_mem = Workflow("long-horizon", gam_dir="./agent_traces")

# Add agent execution trace
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?")

Custom Memory Configuration

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")

# 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")

Docker Workspace Support

python

from gam import Workflow

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

# Works seamlessly in containerized environments
wf.add(input_file="/workspace/data/document.pdf")
result = wf.request("Summarize the document")

Troubleshooting

API Key Issues

If you get authentication errors:

python

# 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")

Missing Dependencies

bash

# If video processing fails
pip install -e ".[video]"

# If API server fails
pip install -e ".[api]"

# If web interface fails
pip install -e ".[web]"

# Install everything
pip install -e ".[all]"

Memory Not Found

python

# Ensure GAM directory exists and has content
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.")

Slow Performance

python

# 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
)

# 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")

Model Configuration

python

# 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?")

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

Research Codebase

For academic research and benchmarking:

bash

cd research
pip install -e .

python

from gam_research import MemoryAgent, ResearchAgent

# Dual-agent implementation from paper
memorizer = MemoryAgent(gam_dir="./research_gam")
researcher = ResearchAgent(gam_dir="./research_gam")

# Run benchmarks (LoCoMo, HotpotQA, RULER, NarrativeQA)
# See research/README.md for details

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-agentic-memory

NPX Install

Tags

SKILL.md Content

GAM (General Agentic Memory) Skill

Installation

Configuration

Python SDK Usage

Basic Workflow API

Incremental Memory Building

Video Memory Workflow

Long-Horizon Agent Trajectory

Advanced Component Usage

CLI Usage

Adding Content to GAM

Querying GAM

CLI with Environment Variables

REST API Usage

Starting the API Server

REST API Client Example

REST API Endpoints

Web Interface Usage

Starting the Web Platform

Common Patterns

Multi-Document Knowledge Base

Video Analysis Pipeline

Agent Memory with Search/Recall

Custom Memory Configuration

Docker Workspace Support

Troubleshooting

API Key Issues

Missing Dependencies

Memory Not Found

Slow Performance

Model Configuration

Directory Structure

Research Codebase

Key Concepts