Spaces:
Sleeping
Sleeping
File size: 5,365 Bytes
116524e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | # OpenClaw + ACE Integration
Learn from [OpenClaw](https://docs.openclaw.ai) session transcripts and build a
self-improving skillbook of reusable strategies.
For the full setup guide, see [docs/integrations/openclaw.md](../../docs/integrations/openclaw.md).
## Quick Start (Docker — Recommended)
Extend your OpenClaw Docker image with ACE pre-installed. The agent runs
`ace-learn` at session start automatically.
```bash
# 1. Copy Dockerfile.ace into your OpenClaw directory
cp examples/openclaw/Dockerfile.ace /path/to/your/openclaw/
# 2. Build (from the OpenClaw directory)
docker build -t openclaw:base .
docker build -t openclaw:local --build-arg OPENCLAW_IMAGE=openclaw:base -f Dockerfile.ace .
# 3. Point OpenClaw at the new image (in your .env file)
# OPENCLAW_IMAGE=openclaw:local
# 4. Pass your LLM API key in docker-compose.yml (see docs for all providers)
# environment:
# AWS_BEARER_TOKEN_BEDROCK: ${AWS_BEARER_TOKEN_BEDROCK}
# 5. Add auto-learning to AGENTS.md (see AGENTS.md.snippet)
# 6. Restart the gateway
docker compose down && docker compose up -d openclaw-gateway
```
### Verify
```bash
# Dry run — parses sessions without making LLM calls
docker run --rm -v ~/.openclaw:/home/node/.openclaw openclaw:local ace-learn --dry-run
# Full run
docker run --rm \
-v ~/.openclaw:/home/node/.openclaw \
-e AWS_BEARER_TOKEN_BEDROCK="$AWS_BEARER_TOKEN_BEDROCK" \
openclaw:local ace-learn
```
## Quick Start (Host)
Run ACE on the host machine. Useful if you don't want to customize Docker.
```bash
# 1. Install
git clone https://github.com/Kayba-ai/agentic-context-engine.git
cd agentic-context-engine
uv sync
# 2. Set your LLM API key
export ANTHROPIC_API_KEY="your-key"
# 3. Dry run (no LLM calls, just parse sessions)
uv run python examples/openclaw/kayba-ace/learn_from_traces.py --dry-run
# 4. Learn from all new sessions
uv run python examples/openclaw/kayba-ace/learn_from_traces.py
```
## How It Works
```
OpenClaw sessions --> JSONL transcripts on disk
|
ace-learn / learn_from_traces.py
|
LoadTracesStep --> OpenClawToTraceStep
|
TraceAnalyser (Reflect -> Tag -> Update -> Apply)
|
+---------------+----------------+
| |
ace_skillbook.json ace_skillbook.md
|
AGENTS.md tells agent to read skillbook
|
Agent loads strategies into context
```
1. OpenClaw writes session transcripts to `~/.openclaw/agents/<id>/sessions/*.jsonl`
2. `LoadTracesStep` reads JSONL files into raw event lists
3. `OpenClawToTraceStep` converts events to structured traces
4. `TraceAnalyser` runs the ACE learning pipeline (Reflect -> Tag -> Update -> Apply)
5. Updated skillbook is saved; the agent reads `ace_skillbook.md` into its context
## CLI Usage
```bash
# Learn from all new sessions (default agent: main)
ace-learn # Docker
uv run python examples/openclaw/kayba-ace/learn_from_traces.py # Host
# Process specific trace files
ace-learn <trace.jsonl> [<trace2.jsonl> ...]
# Reprocess all sessions (ignore already-processed log)
ace-learn --reprocess
# Custom output directory
ace-learn --output ./out
# Enable Opik observability logging
ace-learn --opik
# Use a different agent ID
ace-learn --agent other-agent
```
## Files
| File | Description |
|---|---|
| `kayba-ace/` | Skill folder: `learn_from_traces.py`, `SKILL.md` (copied to OpenClaw workspace by `setup.py`) |
| `Dockerfile.ace` | Extends OpenClaw image with Python 3.12 + ACE |
| `ace-learn.sh` | Wrapper script (reference copy; Dockerfile inlines it) |
| `AGENTS.md.snippet` | Paste into your AGENTS.md for auto-learning |
| `setup.py` | Automated setup: copies skill folder, patches AGENTS.md |
## Configuration
| Variable | Default | Description |
|---|---|---|
| `ACE_MODEL` | `bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0` | LLM for reflection and skill extraction |
| `OPENCLAW_AGENT_ID` | `main` | Agent ID for session discovery |
| `OPENCLAW_HOME` | `$HOME/.openclaw` | Used by `ace-learn` only; do not set as a gateway env var |
| `LITELLM_API_KEY` | - | API key (for non-Bedrock providers) |
| `SPH_LITELLM_KEY` | - | Alternative API key variable |
| `AWS_BEARER_TOKEN_BEDROCK` | - | AWS Bedrock bearer token |
| `ANTHROPIC_API_KEY` | - | Anthropic API key |
| `OPENROUTER_API_KEY` | - | OpenRouter API key |
## Outputs
| File | Format | Description |
|---|---|---|
| `ace_skillbook.json` | JSON | Full skillbook (machine-readable, persists across runs) |
| `ace_skillbook.md` | Markdown | Human-readable skillbook grouped by section |
| `ace_processed.txt` | Text | Tracks which sessions have already been processed |
## Automate with Cron (Host Only)
```bash
*/30 * * * * cd /path/to/agentic-context-engine && uv run python examples/openclaw/kayba-ace/learn_from_traces.py >> /tmp/ace-openclaw.log 2>&1
```
|