Skip to content

VectorSpaceLab/general-agentic-memory

Repository files navigation

General Agentic Memory (GAM)

arXiv HuggingFace

A general memory system for agents, powered by deep-research

δΈ­ζ–‡ζ–‡ζ‘£ | English

πŸŽ‰ If you like our project, please give us a star ⭐ on GitHub for the latest update.

General Agentic Memory (GAM) provides a next-generation memory framework for AI agents, combining long-term retention with dynamic reasoning. Following the Just-in-Time (JIT) principle, it preserves full contextual fidelity offline while performing deep research online to build adaptive, high-utility context. With its dual-agent architectureβ€”Memorizer and Researcherβ€”GAM integrates structured memory with iterative retrieval and reflection, achieving state-of-the-art performance across LoCoMo, HotpotQA, RULER, and NarrativeQA benchmarks.

✨ Key Features

  • 🧠 Just-in-Time (JIT) Memory Optimization
    Unlike conventional Ahead-of-Time (AOT) systems, GAM performs intensive Memory Deep Research at runtime, dynamically retrieving and synthesizing high-utility context to meet real-time agent needs.

  • πŸ” Dual-Agent Architecture: Memorizer & Researcher
    A cooperative framework where the Memorizer constructs structured memory from raw sessions, and the Researcher performs iterative retrieval, reflection, and summarization to deliver precise, adaptive context.

  • πŸš€ Superior Performance Across Benchmarks
    Achieves state-of-the-art results on LoCoMo, HotpotQA, RULER, and NarrativeQA, surpassing prior systems such as A-MEM、Mem0、 MemoryOS and LightMem in both F1 and BLEU-1 metrics.

  • 🧩 Modular & Extensible Design
    Built to support flexible plug-ins for memory construction, retrieval strategies, and reasoning toolsβ€”facilitating easy integration into multi-agent frameworks or standalone LLM deployments.

  • 🌐 Cross-Model Compatibility
    Compatible with leading LLMs such as GPT-4, GPT-4o-mini, and Qwen2.5, supporting both cloud-based and local deployments for research or production environments.

πŸ“£ Latest News

  • 2025-11: Released GAM framework with modular evaluation suite
  • 2025-11: Support for HotpotQA, NarrativeQA, LoCoMo, and RULER benchmarks

πŸ“‘ Table of Contents

πŸ—οΈ System Architecture

logo

πŸ—οΈ Project Structure

general-agentic-memory/
β”œβ”€β”€ gam/                          # Core GAM package
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ agents/                   # Agent implementations
β”‚   β”‚   β”œβ”€β”€ memory_agent.py      # MemoryAgent - memory construction
β”‚   β”‚   └── research_agent.py    # ResearchAgent - deep research
β”‚   β”œβ”€β”€ generator/                # LLM generators
β”‚   β”‚   β”œβ”€β”€ openai_generator.py  # OpenAI API generator
β”‚   β”‚   └── vllm_generator.py    # VLLM local generator
β”‚   β”œβ”€β”€ retriever/                # Retrievers
β”‚   β”‚   β”œβ”€β”€ index_retriever.py   # Index retrieval
β”‚   β”‚   β”œβ”€β”€ bm25.py              # BM25 keyword retrieval
β”‚   β”‚   └── dense_retriever.py   # Dense semantic retrieval
β”‚   β”œβ”€β”€ prompts/                  # Prompt templates
β”‚   β”œβ”€β”€ schemas/                  # Data models
β”‚   └── config/                   # Configuration management
β”œβ”€β”€ eval/                         # Evaluation suite
β”‚   β”œβ”€β”€ hotpotqa_test.py        # HotpotQA evaluation script
β”‚   β”œβ”€β”€ narrativeqa_test.py     # NarrativeQA evaluation script
β”‚   β”œβ”€β”€ locomo_test.py          # LoCoMo evaluation script
β”‚   └── ruler_test.py           # RULER evaluation script
β”œβ”€β”€ scripts/                      # Shell scripts
β”‚   β”œβ”€β”€ eval_hotpotqa.sh
β”‚   β”œβ”€β”€ eval_narrativeqa.sh
β”‚   β”œβ”€β”€ eval_locomo.sh
β”‚   β”œβ”€β”€ eval_ruler.sh
β”‚   └── download_data.sh
β”œβ”€β”€ download_data/                # Data download scripts
β”‚   β”œβ”€β”€ download_narrativeqa.py  # NarrativeQA download script
β”‚   └── download_ruler.py       # RULER download script
β”œβ”€β”€ examples/                     # Usage examples
β”‚   └── quickstart/              # Quick start examples
β”‚       β”œβ”€β”€ README.md            # Examples documentation
β”‚       β”œβ”€β”€ basic_usage.py       # Basic usage example
β”‚       └── model_usage.py       # Model selection example
β”œβ”€β”€ assets/                       # Resource files
β”œβ”€β”€ docs/                         # Documentation
β”œβ”€β”€ setup.py                      # Installation config
β”œβ”€β”€ pyproject.toml               # Modern project config
β”œβ”€β”€ requirements.txt             # Dependencies
└── README.md                    # This file

🎯 Quick Start

πŸš€ Installation

# Clone the repository
git clone https://github.com/VectorSpaceLab/general-agentic-memory.git
cd general-agentic-memory

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

πŸ’‘ Basic Usage

import os
from gam import (
    MemoryAgent,
    ResearchAgent,
    OpenAIGenerator,
    OpenAIGeneratorConfig,
    InMemoryMemoryStore,
    InMemoryPageStore,
    DenseRetrieverConfig,
    DenseRetriever,
    IndexRetrieverConfig,
    IndexRetriever,
    BM25RetrieverConfig,
    BM25Retriever
)

# 1. Configure and create generator
gen_config = OpenAIGeneratorConfig(
    model_name="gpt-4o-mini",
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url="https://api.openai.com/v1",
    temperature=0.3,
    max_tokens = 256
)
generator = OpenAIGenerator.from_config(gen_config)

# 2. Create memory and page stores
memory_store = InMemoryMemoryStore()
page_store = InMemoryPageStore()

# 3. Create MemoryAgent
memory_agent = MemoryAgent(
    generator=generator,
    memory_store=memory_store,
    page_store=page_store
)

# 4. Memorize documents
documents = [
    "Artificial Intelligence is a branch of computer science...",
    "Machine Learning is a subset of AI...",
    "Deep Learning uses neural networks..."
]

for doc in documents:
    memory_agent.memorize(doc)

# 5. Get memory state
memory_state = memory_store.load()
print(f"Built {len(memory_state.abstracts)} memory abstracts")

# 6. Create ResearchAgent for Q&A

retrievers={}
index_dir = './tmp'
try:
    page_index_dir = os.path.join(index_dir, "page_index")
    if os.path.exists(page_index_dir):
        import shutil
        shutil.rmtree(page_index_dir)
    
    index_config = IndexRetrieverConfig(
        index_dir=page_index_dir
    )
    index_retriever = IndexRetriever(index_config.__dict__)
    index_retriever.build(page_store)
    retrievers["page_index"] = index_retriever
except Exception as e:
    print(f"[WARN] page retriever error: {e}")

try:
    bm25_index_dir = os.path.join(index_dir, "bm25_index")
    if os.path.exists(bm25_index_dir):
        import shutil
        shutil.rmtree(bm25_index_dir)
    
    bm25_config = BM25RetrieverConfig(
        index_dir=bm25_index_dir,
        threads=1
    )
    bm25_retriever = BM25Retriever(bm25_config.__dict__)
    bm25_retriever.build(page_store)
    retrievers["keyword"] = bm25_retriever
except Exception as e:
    print(f"[WARN] BM25 retriever error: {e}")

try:
    dense_index_dir = os.path.join(index_dir, "dense_index")
    if os.path.exists(dense_index_dir):
        import shutil
        shutil.rmtree(dense_index_dir)
    
    dense_config = DenseRetrieverConfig(
        index_dir=dense_index_dir,
        model_name="BAAI/bge-m3"
    )
    dense_retriever = DenseRetriever(dense_config.__dict__)
    dense_retriever.build(page_store)
    retrievers["vector"] = dense_retriever
except Exception as e:
    print(f"[WARN] Dense retriever error: {e}")

research_agent_kwargs = {
    "page_store": page_store,
    "memory_store": memory_store,
    "retrievers": retrievers,
    "generator": generator,
    "max_iters": 5
}

research_agent = ResearchAgent(**research_agent_kwargs)

# 7. Perform research
research_result = research_agent.research(
    request="What is the difference between ML and DL?"
)

research_summary = research_result.integrated_memory


print(f"[OK] Research completed! Iteration count: {len(research_result.raw_memory.get('iterations', []))}")
print(f"Research Summary: {research_summary}")

πŸ“š Complete Examples

For detailed examples and advanced usage:

πŸ”¬ How to Reproduce the Results in the Paper

We provide a complete evaluation framework to reproduce the experimental results in the paper.

Datasets

Because the datasets are large, they are not stored in this repository.
Please download them from the original sources and place them under the data/ directory as follows:

Quick Start

# 1. Prepare datasets
mkdir -p data
# Download the datasets from the links above and place them under data/
# following the suggested directory structure.
bash scripts/download_data.sh

# 2. Set environment variables
export OPENAI_API_KEY="your_api_key_here"

# 3. Run evaluations

# HotpotQA
bash scripts/eval_hotpotqa.sh

# NarrativeQA
bash scripts/eval_narrativeqa.sh

# LoCoMo
bash scripts/eval_locomo.sh

# RULER
bash scripts/eval_ruler.sh

Using Python Directly

You can also run the evaluation scripts directly:

# HotpotQA
python eval/hotpotqa_test.py \
    --data data/hotpotqa/eval_400.json \
    --outdir ./results/hotpotqa \
    --memory-api-key $OPENAI_API_KEY \
    --memory-model gpt-4o-mini \
    --research-api-key $OPENAI_API_KEY \
    --research-model gpt-4o-mini \
    --working-api-key $OPENAI_API_KEY \
    --working-model gpt-4o-mini \
    --embedding-model-path BAAI/bge-m3

# NarrativeQA
python eval/narrativeqa_test.py \
    --data-dir data/narrativeqa \
    --split test \
    --outdir ./results/narrativeqa \
    --memory-api-key $OPENAI_API_KEY \
    --memory-model gpt-4o-mini \
    --research-api-key $OPENAI_API_KEY \
    --research-model gpt-4o-mini \
    --working-api-key $OPENAI_API_KEY \
    --working-model gpt-4o-mini \
    --embedding-model-path BAAI/bge-m3

# LoCoMo
python eval/locomo_test.py \
    --data data/locomo10.json \
    --outdir ./results/locomo \
    --memory-api-key $OPENAI_API_KEY \
    --memory-model gpt-4o-mini \
    --research-api-key $OPENAI_API_KEY \
    --research-model gpt-4o-mini \
    --working-api-key $OPENAI_API_KEY \
    --working-model gpt-4o-mini

# RULER
python eval/ruler_test.py \
    --data data/ruler/qa_1.jsonl \
    --outdir ./results/ruler/qa_1 \
    --memory-api-key $OPENAI_API_KEY \
    --memory-model gpt-4o-mini \
    --research-api-key $OPENAI_API_KEY \
    --research-model gpt-4o-mini \
    --working-api-key $OPENAI_API_KEY \
    --working-model gpt-4o-mini \
    --embedding-model-path BAAI/bge-m3

Supported Datasets

Dataset Task Type Metrics Script
HotpotQA Multi-hop QA F1 eval/hotpotqa_test.py
NarrativeQA Narrative QA F1 eval/narrativeqa_test.py
LoCoMo Conversation Memory F1, BLEU-1 eval/locomo_test.py
RULER Long Context Accuracy eval/ruler_test.py

πŸ“– Documentation

More detailed documentation is coming soon πŸš€. Check these resources in the meantime:

πŸ“£ Citation

If you find this project useful, please consider citing our paper:

@article{yan2025general,
  title={General Agentic Memory Via Deep Research},
  author={Yan, BY and Li, Chaofan and Qian, Hongjin and Lu, Shuqi and Liu, Zheng},
  journal={arXiv preprint arXiv:2511.18423},
  year={2025}
}

🀝 Community

🎯 Contact Us

🌟 Star History

Star History Chart

🀝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ™ Acknowledgments

We thank the authors of the following datasets:

  • HotpotQA
  • NarrativeQA
  • LoCoMo
  • RULER

Disclaimer

This is a research project. Please use it responsibly and ethically.


Made with ❀️ by the GAM Team

About

A general memory system for agents, powered by deep-research

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published