Metadata-Version: 2.4
Name: trae-evolve
Version: 0.2.0
Summary: Universal self-evolution layer for AI agents — brings Hermes-style skills, memory, and self-improvement to any agent
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0

# trae-evolve 🧬

**Universal self-evolution layer for AI agents — brings Hermes-style skills, memory, and self-improvement to Trae IDE and beyond.**

Your AI agent learns from experience. After completing complex tasks, it automatically saves reusable workflows as skills and remembers facts about your project. Next time, it loads that knowledge and gets better.

---

## Quick Start

### 1. Install

```bash
pip install trae-evolve
```

### 2. Initialize your project

```bash
cd your-project
trae-evolve init
trae-evolve trae-sync
```

### 3. Restart Trae IDE

That's it. Your AI agent now automatically evolves.

---

## How It Works

```
Agent completes a complex task
         ↓
Automatically calls MCP tools → skill_manage(action='create', ...)
         ↓
Knowledge saved to .evolve/skills/ → synced to .trae/skills/
         ↓
Next session → Agent reads skills → reuses proven workflows
         ↓
Curator tracks usage → stale after 30 days → archived after 90 days
```

### MCP Tools (Agent calls these automatically)

| Tool | What it does | When Agent calls it |
|------|-------------|-------------------|
| `skill_manage` | Create/patch/delete skills | After complex tasks |
| `memory` | Add/update/remove memory | After learning new facts |
| `skill_view` | Read a skill's full content | Before starting tasks |
| `skills_list` | List all available skills | Before starting tasks |

---

## Commands

### Skills (procedural knowledge — "how to do X")

```bash
trae-evolve skills list                    # List all skills
trae-evolve skills view <name>             # View a skill
trae-evolve skills create <name> -d "..." -c "..."  # Create
trae-evolve skills patch <name> -o "old" -n "new"    # Patch
trae-evolve skills delete <name> -y       # Delete
```

### Memory (declarative knowledge — facts)

```bash
trae-evolve memory read                    # Read all
trae-evolve memory read memory             # Agent notes only
trae-evolve memory read user               # User profile only
trae-evolve memory add memory "..."        # Add agent note
trae-evolve memory add user "..."          # Add user preference
trae-evolve memory replace memory "old" "new"  # Replace
trae-evolve memory remove memory "..."     # Remove
```

### Trae Integration

```bash
trae-evolve trae-sync          # Generate .trae/ files (rules + skills + mcp.json)
trae-evolve inject             # Generate AGENTS.md / CLAUDE.md / .cursorrules
```

### Lifecycle Management

```bash
trae-evolve curator status     # Show skill lifecycle status
trae-evolve curator run        # Run maintenance cycle
trae-evolve curator pin <name> # Prevent skill from being archived
trae-evolve status             # Overall status
```

---

## Directory Structure

### Global (shared across projects)

```
~/.evolve/
├── skills/          ← Global skills
├── memories/
│   ├── MEMORY.md    ← Agent notes (2200 char limit)
│   └── USER.md      ← User profile (1375 char limit)
└── .archive/        ← Archived skills
```

### Per-project (created by `trae-evolve init`)

```
your-project/
├── .evolve/
│   ├── skills/      ← Project-specific skills
│   └── memories/    ← Project-specific memory
└── .trae/           ← Created by `trae-evolve trae-sync`
    ├── mcp.json     ← MCP Server config
    ├── rules/
    │   └── evolve-project-rules.md  ← Always-apply rules
    └── skills/      ← Synced Trae-native skills
```

---

## SKILL.md Format

```markdown
---
name: deploy-to-prod
description: How to safely deploy to production
version: 1.0.0
category: devops
tags: [deployment, production]
---

# Deploy to Production

## Steps
1. Run tests: `pytest -x`
2. Build: `make build`
3. Deploy: `./deploy.sh`

## Pitfalls
- Never deploy on Fridays
- Check DB migrations first
```

## Memory Format

Entries separated by `§`:

```
Uses Edge browser
§
NVIDIA GPU + CUDA
§
Project uses FastAPI + PostgreSQL
```

---

## Trae IDE Integration

`trae-evolve trae-sync` generates:

1. **`.trae/mcp.json`** — Connects Trae to evolve MCP Server
2. **`.trae/rules/evolve-project-rules.md`** — Always-apply rules with skill index + memory
3. **`.trae/skills/`** — Skills in Trae-native format

After restart, Trae's AI agent gets 4 new MCP tools and reads the rules. It will:
- Automatically save skills after complex tasks
- Automatically remember user preferences
- Load existing skills before starting work

---

## Agent Compatibility

| Agent | Integration | Command |
|-------|------------|---------|
| **Trae IDE** | MCP + Rules + Skills (native) | `trae-evolve trae-sync` |
| Claude Code | CLAUDE.md | `trae-evolve inject` |
| Codex | AGENTS.md | `trae-evolve inject` |
| OpenCode | AGENTS.md | `trae-evolve inject` |
| Cursor | .cursorrules | `trae-evolve inject` |

---

## Requirements

- Python 3.9+
- pyyaml (installed automatically)

---

## License

MIT
