# ExperienceMaker

ExperienceMaker Logo

Python Version PyPI Version License GitHub Stars

A comprehensive framework for AI agent experience generation and reuse
Empowering agents to learn from the past and excel in the future

--- ## ๐Ÿ“ฐ What's New - **[2025-08]** ๐ŸŽ‰ ExperienceMaker v0.1.0 is now available on [PyPI](https://pypi.org/project/experiencemaker/)! - **[2025-07]** ๐Ÿ“š Complete documentation and quick start guides released - **[2025-07]** ๐Ÿš€ Multi-backend vector store support (Elasticsearch & ChromaDB) --- ## ๐ŸŒŸ What is ExperienceMaker? ExperienceMaker is a revolutionary framework that transforms how AI agents learn and improve through **experience-driven intelligence**. By automatically extracting, storing, and intelligently reusing experiences from agent trajectories, it enables continuous learning and progressive skill enhancement. ### ๐Ÿ’ก Why ExperienceMaker? Traditional AI agents start from scratch with every new task, wasting valuable learning opportunities. ExperienceMaker changes this paradigm by: - **๐Ÿง  Learning from History**: Automatically extract actionable insights from both successful and failed attempts - **๐Ÿ”„ Intelligent Reuse**: Apply relevant past experiences to solve new, similar challenges more effectively - **๐Ÿ“ˆ Continuous Improvement**: Build a growing knowledge base that makes agents progressively smarter - **โšก Faster Problem Solving**: Dramatically reduce trial-and-error by leveraging proven strategies ### โœจ Core Capabilities #### ๐Ÿ” **Intelligent Experience Summarizer** - **Success Pattern Recognition**: Identify what works and understand the underlying principles - **Failure Analysis**: Learn from mistakes to avoid repeating them in future tasks - **Comparative Insights**: Understand the critical differences between successful and failed approaches - **Multi-step Trajectory Processing**: Break down complex tasks into learnable, actionable segments #### ๐ŸŽฏ **Smart Experience Retriever** - **Semantic Search**: Find relevant experiences using advanced embedding models and semantic understanding - **Context-Aware Ranking**: Prioritize the most applicable experiences for current task contexts - **Dynamic Rewriting**: Intelligently adapt past experiences to fit new situations and requirements - **Multi-modal Support**: Handle various input types including queries, conversations, and trajectories #### ๐Ÿ—„๏ธ **Scalable Experience Management** - **Multiple Storage Backends**: Choose from Elasticsearch (production-ready), ChromaDB (development), or file-based storage (testing) - **Workspace Isolation**: Organize experiences by projects, domains, or teams with complete separation - **Deduplication & Validation**: Ensure high-quality, unique experience storage with automated quality control - **Batch Operations**: Efficiently handle large-scale experience processing with optimized performance #### ๐Ÿ”ง **Developer-Friendly Architecture** - **REST API Interface**: Seamless integration with existing systems through clean API design - **Modular Pipeline Design**: Compose custom workflows from atomic operations with maximum flexibility - **Flexible Configuration**: YAML files and command-line overrides for easy customization ### ๐Ÿ—๏ธ Framework Architecture

ExperienceMaker Architecture

ExperienceMaker follows a modular, production-ready architecture designed for scalability: #### ๏ฟฝ๏ฟฝ **API Layer** - **๐Ÿ” Retriever API**: Query-based and conversation-based experience retrieval with intelligent matching - **๐Ÿ“Š Summarizer API**: Trajectory-to-experience conversion and automated storage management - **๐Ÿ—„๏ธ Vector Store API**: Database management and workspace operations with full CRUD support - **๐Ÿค– Agent API**: ReAct-based agent execution enhanced with experience-driven decision making #### โš™๏ธ **Processing Pipeline** Our atomic operations can be seamlessly composed into powerful processing pipelines: **Retrieval Pipeline**: ``` build_query_op->recall_vector_store_op->merge_experience_op ``` **Summarization Pipeline**: ``` simple_summary_op->update_vector_store_op ``` #### ๐Ÿ”Œ **Extensible Components** - **LLM Integration**: OpenAI-compatible APIs with flexible model switching and provider support - **Embedding Models**: Pluggable embedding providers for sophisticated semantic search capabilities - **Vector Stores**: Multiple backends optimized for different deployment scenarios and scales - **Tools & Operators**: Comprehensive, extensible library of processing operations --- ## ๐Ÿ› ๏ธ Installation ### Option 1: Install from PyPI (Recommended) ```bash pip install experiencemaker ``` ### Option 2: Install from Source ```bash git clone https://github.com/modelscope/ExperienceMaker.git cd ExperienceMaker pip install . ``` ## โš™๏ธ Environment Setup Create a `.env` file in your project directory: ```bash # Required: LLM API configuration LLM_API_KEY="sk-xxx" LLM_BASE_URL="https://xxx.com/v1" # Required: Embedding model configuration EMBEDDING_MODEL_API_KEY="sk-xxx" EMBEDDING_MODEL_BASE_URL="https://xxx.com/v1" # Optional: Elasticsearch configuration (if using Elasticsearch backend) ``` ## ๐Ÿš€ Quick Start For testing and development, use the `local_file` backend: ```bash experiencemaker \ http_service.port=8001 \ llm.default.model_name=qwen3-32b \ embedding_model.default.model_name=text-embedding-v4 \ vector_store.default.backend=local_file ``` ๐Ÿ’ก **Pro Tip**: Check out our [Advanced Guide](./doc/advanced_guide.md) for detailed configuration topics including custom pipelines, operation parameters, and advanced configuration methods. The service will start on `http://localhost:8001` ### ๐Ÿ” Production Setup with Elasticsearch Backend ```bash experiencemaker \ llm.default.model_name=qwen3-32b \ embedding_model.default.model_name=text-embedding-v4 \ vector_store.default.backend=elasticsearch ``` **Setup Elasticsearch:** ```bash export ES_HOSTS="http://localhost:9200" # Quick setup using Elastic's official script curl -fsSL https://elastic.co/start-local | sh ``` ๐Ÿ“– **Need Help?** Refer to [Vector Store Setup](./doc/vector_store_setup.md) for comprehensive deployment guidance. ## ๐Ÿ“ Your First ExperienceMaker Script Here's how to get started! The `load_dotenv()` function loads environment variables from your `.env` file, or you can manually export them. The `base_url` points to your ExperienceMaker service, and `workspace_id` serves as your experience storage namespace. Experiences in different workspaces remain completely isolated and cannot access each other. ### ๐Ÿ“Š Call Summarizer Examples ```python import requests from dotenv import load_dotenv load_dotenv() base_url = "http://0.0.0.0:8001/" workspace_id = "test_workspace" def run_summary(messages: list): response = requests.post(url=base_url + "summarizer", json={ "workspace_id": workspace_id, "traj_list": [ {"messages": messages, "score": 1.0} ] }) response = response.json() experience_list = response["experience_list"] for experience in experience_list: print(experience) ``` ### ๐Ÿ” Call Retriever Examples ```python import requests from dotenv import load_dotenv load_dotenv() base_url = "http://0.0.0.0:8001/" workspace_id = "test_workspace" def run_retriever(query: str): response = requests.post(url=base_url + "retriever", json={ "workspace_id": workspace_id, "query": query, }) response = response.json() experience_merged: str = response["experience_merged"] print(f"experience_merged={experience_merged}") ``` ### ๐Ÿ’พ Dump Experiences From Vector Store ```python import requests from dotenv import load_dotenv load_dotenv() base_url = "http://0.0.0.0:8001/" workspace_id = "test_workspace1" def dump_experience(): response = requests.post(url=base_url + "vector_store", json={ "workspace_id": workspace_id, "action": "dump", "path": "./", }) print(response.json()) ``` ### ๐Ÿ“ฅ Load Experiences To Vector Store ```python import requests from dotenv import load_dotenv load_dotenv() base_url = "http://0.0.0.0:8001/" workspace_id = "test_workspace1" def load_experience(): response = requests.post(url=base_url + "vector_store", json={ "workspace_id": "test_workspace1", "action": "load", "path": "./", }) print(response.json()) ``` ๐ŸŽญ **Want to See It in Action?** We've prepared a [simple react agent](./cookbook/simple_demo/simple_demo.py) that demonstrates how to enhance agent capabilities by integrating summarizer and retriever components, achieving significantly better performance. --- ## ๐Ÿงช Experiments ### ๐ŸŒ Experiment on Appworld Coming Soon! Stay tuned for comprehensive evaluation results. ### ๐Ÿ”ง Experiment on BFCL-V3 Detailed benchmarking results and performance analysis coming soon. --- ## ๐Ÿ›ฃ๏ธ Future Roadmap Exciting features and improvements are on the horizon! Check out our detailed [Future Roadmap](./doc/future_roadmap.md) for upcoming enhancements. --- ## ๐Ÿช Ready-made Experience Store Pre-built experience collections for common domains and use cases are coming soon. This will include ready-to-use experiences for web automation, data processing, API interactions, and more. --- ## ๐Ÿ“š Additional Resources - **[Vector Store Setup](./doc/vector_store_setup.md)**: Complete production deployment guide - **[Configuration Guide](./doc/configuration_guide.md)**: Advanced configuration options and best practices - **[Advanced Guide](./doc/advanced_guide.md)**: Custom pipelines, operation parameters, and advanced configuration methods - **[Operations Documentation](./doc/operations_documentation.md)**: Comprehensive operations configuration reference - **[Example Collection](./cookbook)**: Practical examples and use cases - **[Future RoadMap](./doc/future_roadmap.md)**: Our vision and upcoming features --- ## ๐Ÿค Contributing We warmly welcome contributions from the community! Here's how you can help make ExperienceMaker even better: ### ๐Ÿ› **Report Issues** - Bug reports with detailed reproduction steps - Feature requests and enhancement suggestions - Documentation improvements and clarifications - Performance optimization ideas ### ๐Ÿ’ป **Code Contributions** - New operations and tools development - Backend implementations and optimizations - API enhancements and new endpoints - Test coverage improvements and quality assurance ### ๐Ÿ“ **Documentation** - Usage examples and comprehensive tutorials - Best practices guides and design patterns - Translation and localization efforts **Getting Started**: Fork the repository, create a feature branch, and submit a pull request. Please follow our coding standards and include comprehensive tests for new functionality. --- ## ๐Ÿ“„ Citation If you use ExperienceMaker in your research or projects, please cite: ```bibtex @software{ExperienceMaker, title = {ExperienceMaker: A Comprehensive Framework for AI Agent Experience Generation and Reuse}, author = {The ExperienceMaker Team}, url = {https://github.com/modelscope/ExperienceMaker}, month = {08}, year = {2025}, } ``` --- ## โš–๏ธ License This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details. ---