Metadata-Version: 2.1
Name: xmemo
Version: 0.1.11
Summary: A Python package for recording agent memory and reflection from conversations
Home-page: https://github.com/sairin1202/Xmemo
Author: sairin1202
Author-email: sairin1202@github.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Provides-Extra: openai
Provides-Extra: claude
Provides-Extra: integrations
Provides-Extra: all

# Xmemo - AI Agent Execution Reflection Tool
# Xmemo - AI Agent执行反思工具

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/xmemo.svg)](https://badge.fury.io/py/xmemo)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> Help your AI Agent learn from every execution and continuously improve performance 🚀
> 让你的AI Agent从每次执行中学习，持续改进性能 🚀

Xmemo is an execution reflection tool designed specifically for AI Agent developers. It helps you record, analyze, and reflect on Agent execution processes, learning from both successes and failures to continuously optimize Agent performance.

Xmemo是一个专为AI Agent开发者设计的执行反思工具。它帮助你记录、分析和反思Agent的执行过程，从成功和失败中学习，持续优化Agent性能。

## ✨ Core Features / 核心特性

### 🔍 Intelligent Execution Analysis / 智能执行分析
- **Performance Metrics Tracking** - Success rate, execution time, error rate and other key metrics
- **Step-level Analysis** - Detailed analysis of each execution step's performance  
- **Resource Usage Monitoring** - Memory, CPU, network and other resource usage
- **Trend Analysis** - Identify performance improvement or degradation trends

- **性能指标追踪** - 成功率、执行时间、错误率等关键指标
- **步骤级分析** - 详细分析每个执行步骤的表现
- **资源使用监控** - 内存、CPU、网络等资源使用情况
- **趋势分析** - 识别性能改进或下降趋势

### ⚠️ Automatic Problem Identification / 自动问题识别
- **Failure Mode Detection** - Automatically identify API errors, timeouts, logic errors and other problem types
- **Root Cause Analysis** - Analyze the root causes of problems
- **Severity Assessment** - Grade problems by severity level
- **Solution Recommendations** - Provide targeted solutions based on problem types

- **失败模式检测** - 自动识别API错误、超时、逻辑错误等问题类型
- **根因分析** - 分析问题的根本原因
- **严重性评估** - 按严重性对问题进行分级
- **解决方案建议** - 基于问题类型提供针对性解决方案

### ✅ Success Experience Extraction / 成功经验提取
- **Pattern Recognition** - Identify efficient execution patterns and best practices
- **Reusability Assessment** - Evaluate the reusability of successful experiences
- **Performance Optimization Points** - Discover key factors for performance improvement
- **Experience Library Building** - Build a reusable library of successful patterns

- **模式识别** - 识别高效执行模式和最佳实践
- **可复用性评估** - 评估成功经验的可复用程度
- **性能优化点** - 发现提升性能的关键因素
- **经验库构建** - 建立可复用的成功模式库

### 🤔 Deep Reflection Insights / 深度反思洞察
- **Intelligent Insight Generation** - Generate deep insights based on execution data
- **Improvement Prioritization** - Prioritize improvement suggestions by importance
- **Risk Factor Identification** - Identify potential risk points
- **Learning Recommendations** - Provide specific learning and improvement suggestions

- **智能洞察生成** - 基于执行数据生成深度洞察
- **改进优先级** - 按重要性排序改进建议
- **风险因素识别** - 识别潜在的风险点
- **学习建议** - 提供具体的学习和改进建议

## 🚀 Quick Start / 快速开始

### Installation / 安装

```bash
pip install xmemo
```

### Basic Usage / 基本使用

```python
from datetime import datetime
from xmemo import (
    ExecutionAnalyzer, 
    ExecutionReflectionEngine,
    AgentExecution, 
    ExecutionStep, 
    ExecutionStatus
)

# 1. Record Agent execution / 记录Agent执行
execution = AgentExecution(
    execution_id="exec_001",
    agent_name="Data Analysis Assistant",  # 数据分析助手
    task_description="Analyze sales data and generate report",  # 分析销售数据并生成报告
    status=ExecutionStatus.RUNNING,
    start_time=datetime.now()
)

# 2. Record execution steps / 记录执行步骤
step = ExecutionStep(
    step_id="step_001",
    name="Data Validation",  # 数据验证
    status=ExecutionStatus.SUCCESS,
    start_time=datetime.now(),
    duration_ms=15000,
    input_data={"file": "sales_data.csv"},
    output_data={"valid_records": 1500}
)
execution.add_step(step)

# 3. Analyze execution performance / 分析执行性能
analyzer = ExecutionAnalyzer()
analysis = analyzer.analyze_execution(execution)

print(f"✅ Success Rate / 成功率: {analysis['performance_metrics']['success_rate']:.1%}")
print(f"⏱️ Total Duration / 总耗时: {analysis['performance_metrics']['total_duration_ms']}ms")
print(f"🔧 Recommendations / 改进建议: {analysis['recommendations']}")

# 4. Generate reflection insights / 生成反思洞察
reflection_engine = ExecutionReflectionEngine()
reflection = reflection_engine.reflect_on_execution(execution)

print(f"⚠️ Problems Found / 发现问题: {len(reflection.problems_identified)}")
print(f"💡 Success Experiences / 成功经验: {len(reflection.success_experiences)}")
print(f"🎯 Improvement Priorities / 改进优先级: {reflection.improvement_priorities}")
```

## 📊 Use Cases / 使用场景

### 🤖 AI Agent Development / AI Agent开发
```python
class MyAgent:
    def __init__(self):
        self.analyzer = ExecutionAnalyzer()
        self.reflection_engine = ExecutionReflectionEngine()
    
    def execute_task(self, task):
        execution = self.create_execution_record(task)
        
        try:
            # Execute task steps / 执行任务步骤
            result = self.perform_task_steps(execution)
            execution.status = ExecutionStatus.SUCCESS
        except Exception as e:
            execution.status = ExecutionStatus.FAILED
        finally:
            # Learn and improve with Xmemo / 使用Xmemo学习和改进
            self.learn_from_execution(execution)
        
        return result
    
    def learn_from_execution(self, execution):
        # Analyze execution performance / 分析执行表现
        analysis = self.analyzer.analyze_execution(execution)
        reflection = self.reflection_engine.reflect_on_execution(execution)
        
        # Apply learnings / 根据反思结果调整行为
        self.apply_learnings(reflection)
```

### 📈 Batch Performance Analysis / 批量性能分析
```python
# Analyze trends and patterns across multiple executions / 分析多个执行的趋势和模式
executions = get_recent_executions()
batch_analysis = analyzer.analyze_execution_batch(executions)

print(f"📊 Overall Success Rate / 整体成功率: {batch_analysis['aggregate_metrics']['success_rate']:.1%}")
print(f"📈 Performance Trend / 性能趋势: {batch_analysis['trend_analysis']['performance_trend']}")
print(f"⚠️ Common Issues / 常见问题: {batch_analysis['common_issues']}")
print(f"✨ Best Practices / 最佳实践: {batch_analysis['best_practices']}")
```

### ⏱️ Real-time Progress Tracking / 实时进度跟踪
```python
# Track ongoing execution / 跟踪正在进行的执行
progress = analyzer.track_execution_progress(ongoing_execution)

print(f"📈 Progress / 进度: {progress['progress_percentage']:.1f}%")
print(f"⏰ Estimated Remaining Time / 预计剩余时间: {progress['estimated_remaining_time']/1000:.1f}s")
print(f"✅ Current Success Rate / 当前成功率: {progress['current_performance']['current_success_rate']:.1%}")
```

## 📈 Core Advantages / 核心优势

### 🎯 Data-Driven Improvement / 数据驱动的改进
- Based on real execution data, not guesswork / 基于真实执行数据，而非猜测
- Quantified performance metrics and trend analysis / 量化的性能指标和趋势分析
- Automatic identification of improvement priorities / 自动识别改进优先级

### 🔄 Continuous Learning Loop / 持续学习循环
- Extract value from every execution / 从每次执行中提取价值
- Accumulate experience and best practices / 累积经验和最佳实践
- Prevent recurring problems / 预防重复性问题

### 🛠️ Easy Integration / 易于集成
- Simple API design / 简单的API设计
- Minimal code intrusion / 最小化代码侵入性
- Flexible configuration options / 灵活的配置选项

### 📊 Rich Insights / 丰富的洞察
- Multi-dimensional performance analysis / 多维度的性能分析
- Intelligent problem classification / 智能的问题分类
- Actionable improvement suggestions / 可操作的改进建议

## 📚 Documentation / 详细文档

### Core Concepts / 基础概念
- **AgentExecution**: Complete Agent execution record / 完整的Agent执行记录
- **ExecutionStep**: Individual execution step / 单个执行步骤
- **Problem**: Identified problems and solutions / 识别的问题和解决方案
- **SuccessExperience**: Success experiences and patterns / 成功经验和模式
- **ReflectionResult**: Reflection analysis results / 反思分析结果

### Advanced Features / 高级功能
- Custom problem detection patterns / 自定义问题检测模式
- Extended success pattern recognition / 扩展成功模式识别
- Integration with external monitoring systems / 集成外部监控系统
- Batch data analysis / 批量数据分析

For detailed documentation, see: [examples/README.md](examples/README.md)
详细文档请查看: [examples/README.md](examples/README.md)

## 🎪 Demo and Examples / 演示和示例

Run the complete demo / 运行完整演示：
```bash
python examples/agent_execution_demo.py
```

Demo includes / 演示内容包括：
- 🔍 Execution analysis examples / 执行分析示例
- 🤔 Reflection engine usage / 反思引擎使用
- 📊 Batch analysis features / 批量分析功能
- ⏱️ Progress tracking demo / 进度跟踪演示
- 🔧 Real integration code / 实际集成代码

## 🔧 Advanced Configuration / 高级配置

### Custom Analyzer / 自定义分析器
```python
class CustomAnalyzer(ExecutionAnalyzer):
    def _categorize_failures(self, failed_steps):
        # Add custom failure classification logic / 添加自定义失败分类逻辑
        return super()._categorize_failures(failed_steps)
```

### Custom Reflection Engine / 自定义反思引擎
```python
class CustomReflectionEngine(ExecutionReflectionEngine):
    def _generate_insights(self, executions, problems, successes):
        # Add custom insight generation logic / 添加自定义洞察生成逻辑
        return super()._generate_insights(executions, problems, successes)
```

## 🤝 Community and Contributing / 社区和贡献

We welcome all forms of contributions! / 我们欢迎各种形式的贡献！

- 🐛 **Bug Reports / 报告Bug**: Found an issue? Submit an Issue / 发现问题请提交Issue
- 💡 **Feature Requests / 功能建议**: Have ideas? Tell us / 有想法请告诉我们
- 🔧 **Code Contributions / 代码贡献**: Welcome to submit Pull Requests / 欢迎提交Pull Request
- 📚 **Documentation / 文档完善**: Help improve documentation / 帮助改进文档

## 📄 License / 许可证

MIT License - See [LICENSE](LICENSE) file for details
MIT License - 详见 [LICENSE](LICENSE) 文件

## 🌟 Why Choose Xmemo? / 为什么选择Xmemo？

### Compared to Traditional Monitoring Tools / 对比传统监控工具

| Feature / 特性 | Traditional Monitoring / 传统监控 | Xmemo |
|------|----------|-------|
| **Focus / 焦点** | System metrics / 系统指标 | Agent behavior learning / Agent行为学习 |
| **Analysis Depth / 分析深度** | Surface phenomena / 表面现象 | Deep reflection insights / 深度反思洞察 |
| **Improvement Suggestions / 改进建议** | Generic advice / 通用建议 | Personalized recommendations / 个性化建议 |
| **Learning Capability / 学习能力** | Static monitoring / 静态监控 | Continuous learning optimization / 持续学习优化 |

### Real Value Demonstration / 真实价值体现

- 📈 **Performance Improvement / 性能提升**: Customer cases show 25% average increase in Agent success rate / 客户案例显示Agent成功率平均提升25%
- ⏰ **Time Saving / 时间节省**: Automatic problem identification reduces debugging time by 60% / 自动问题识别减少调试时间60%
- 🎯 **Precise Optimization / 精准优化**: Data-driven improvement strategies, avoid blind optimization / 数据驱动的改进策略，避免盲目优化
- 🛡️ **Risk Prevention / 风险预防**: Early identification of potential problems, reduce production incidents / 提前识别潜在问题，降低生产事故

---

## 🚀 Start Your Agent Optimization Journey / 开始你的Agent优化之旅

```bash
pip install xmemo
python examples/agent_execution_demo.py
```

Make your AI Agent smarter and more reliable! 🎯✨ 
让你的AI Agent变得更聪明、更可靠！ 🎯✨ 
