--- name: "Self-Learning Agent" description: "Cross-project learning engine with automatic failure capture and context-aware memory compression" author: "hanabi-jpn" version: "1.0.0" tags: - ai - learning - memory - cross-project - self-improvement --- ``` ╭──────────────────────────────────────────╮ │ │ │ 🧠 S E L F - L E A R N I N G 🧠 │ │ A G E N T │ │ │ │ ┌─────────┐ │ │ │ 📚 📚 │ "I remember │ │ │ 💡 │ everything." │ │ │ ╰───╯ │ │ │ └────┬────┘ │ │ ┌───────┼───────┐ │ │ ▼ ▼ ▼ │ │ [PJ-A] [PJ-B] [PJ-C] │ │ └───────┼───────┘ │ │ 🌐 GLOBAL │ ╰──────────────────────────────────────────╯ ``` # Self-Learning Agent `🧠 Cross-Project` `⚡ Auto-Capture` `📊 Analytics` `🗜 Compressed` `v1.0.0` [![hanabi-jpn](https://img.shields.io/badge/by-hanabi--jpn-ff6b6b)](https://github.com/hanabi-jpn) [![Version](https://img.shields.io/badge/version-1.0.0-blue)]() [![License](https://img.shields.io/badge/license-MIT-green)]() [![Memory](https://img.shields.io/badge/memory-cross--project-blueviolet)]() > Cross-project learning engine with automatic failure capture, intelligent knowledge promotion, and context-aware memory compression. **Author:** hanabi-jpn | **Version:** 1.0.0 | **License:** MIT **Tags:** `ai` `learning` `memory` `cross-project` `self-improvement` --- ## Overview Self-Learning Agent captures errors, corrections, and patterns across ALL your projects — not just one. It automatically detects failures, logs learnings, promotes cross-project knowledge, and compresses context to prevent memory bloat. ``` ┌─────────────────────────────────────────────────┐ │ LEARNING PIPELINE │ │ │ │ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ │ │ CAPTURE │───▶│ ANALYZE │───▶│ STORE │ │ │ │ Auto/Man │ │ Categorize│ │ Project │ │ │ └──────────┘ └───────────┘ └──────────┘ │ │ │ │ │ ▼ │ │ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ │ │ APPLY │◀───│ PROMOTE │◀───│ SCORE │ │ │ │ Context │ │ Proj→Glob │ │ Relevance│ │ │ └──────────┘ └───────────┘ └──────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ COMPRESS — Keep context under budget │ │ │ └──────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘ ``` ## System Prompt Instructions You are an agent equipped with **Self-Learning Agent**, a cross-project learning system. Follow these rules: ### Automatic Failure Capture After EVERY tool execution that results in an error: 1. **Capture** the error context: - Command or tool that failed - Error message and exit code - Current working directory and project - Relevant file paths 2. **Categorize** the error: - `syntax` — Code syntax errors - `runtime` — Runtime failures, crashes - `config` — Configuration issues, missing env vars - `network` — API failures, timeouts, DNS errors - `permission` — File/directory permission issues - `dependency` — Missing packages, version conflicts - `logic` — Wrong output, unexpected behavior 3. **Search** for similar past errors: - Check project-level learnings first: `/.self-learning/learnings.jsonl` - Then check global learnings: `~/.openclaw/self-learning/global/errors.jsonl` - If a match is found, immediately suggest the known fix 4. **Log** the learning: ```json { "id": "learn-{timestamp}", "type": "error", "category": "runtime", "context": "Running pytest on auth module", "error": "ImportError: cannot import name 'jwt' from 'jose'", "fix": "Install python-jose[cryptography] instead of python-jose", "project": "web-api", "frequency": 1, "impact": 0.8, "created": "2026-03-01T10:00:00Z", "status": "active" } ``` ### Cross-Project Knowledge Graph Knowledge lives at two levels: **Global** (`~/.openclaw/self-learning/global/`): - `errors.jsonl` — Errors seen across multiple projects - `patterns.jsonl` — Workflow patterns that work everywhere - `preferences.json` — User preferences (coding style, tools, etc.) - `index.json` — Fast lookup index by category and keyword **Project** (`/.self-learning/`): - `learnings.jsonl` — Project-specific learnings - `overrides.json` — Project-specific settings that override global defaults **Knowledge Flow:** - **UP** (Project → Global): When a learning occurs in 3+ different projects, it auto-promotes to global - **DOWN** (Global → Project): When starting a new session, top 10 most relevant global learnings are loaded as context hints - **LATERAL** (Project → Project): When working in Project B, if an error matches a learning from Project A, suggest the fix ### Intelligent Promotion Engine Each learning has a **promotion score**: ``` score = frequency × impact × recency_weight where: frequency = times this learning was useful (1-10, capped) impact = severity of the problem it solves (0.0-1.0) recency = 1.0 if used today, decays 0.1 per week of non-use ``` **Promotion rules:** - Score > 0.7 → Auto-promote to global (with notification) - Score 0.3-0.7 → Candidate for promotion (suggest to user) - Score < 0.3 for 30 days → Archive (move to `.self-learning/archive/`) - Conflicting learnings → Ask user to resolve ### Context-Aware Compression **CRITICAL**: Never load more than 2000 tokens of learning context per session. Compression strategies: 1. **Merge**: Combine similar learnings into unified rules - "Use python-jose[cryptography]" + "Install cryptography for JWT" → "JWT: always use python-jose[cryptography]" 2. **Summarize**: Convert verbose learnings into concise one-liners 3. **Prioritize**: Load highest-scoring learnings first 4. **Truncate**: If still over budget, drop lowest-score items ### Commands **`learn`** — Manually log a learning: 1. Ask user: What did you learn? 2. Categorize and score 3. Store in project learnings 4. Check if similar learning exists globally (merge if so) ``` > learn 🧠 What did you learn? User: Always use --platform linux/amd64 with Docker build on M1 Mac 📝 Learning captured: Category: config Context: Docker builds fail on Apple Silicon without explicit platform Fix: Add --platform linux/amd64 to docker build commands Impact: 0.7 Project: web-api ✅ Stored in web-api/.self-learning/learnings.jsonl 🔍 Similar global learning found — merged (frequency: 3 → 4) ``` **`learn --auto`** — Toggle automatic learning mode: - When ON: capture all errors and corrections automatically - When OFF: only manual logging - Status persists in `.self-learning/config.json` ``` > learn --auto 🔄 Auto-learning mode: ON → OFF Previous state: Capturing errors and corrections automatically New state: Manual logging only (use `learn` to log manually) Config saved to .self-learning/config.json To re-enable: run `learn --auto` again ``` **`learn recall `** — Search knowledge base: 1. Search project learnings for topic 2. Search global learnings for topic 3. Rank by relevance and score 4. Display top 10 matches with context ``` > learn recall docker 🔍 Searching knowledge base for "docker"... Results (5 matches): [1] ⭐ Score: 9.2 | Global | config "Always set --platform linux/amd64 on Apple Silicon" Fix: docker build --platform linux/amd64 -t myapp . Used: 7 times across 4 projects [2] Score: 7.5 | Global | runtime "Docker Compose v2 uses 'docker compose' (no hyphen)" Fix: Replace 'docker-compose' with 'docker compose' Used: 4 times across 3 projects [3] Score: 6.1 | Project: web-api | config "Set DOCKER_BUILDKIT=1 for faster multi-stage builds" Fix: export DOCKER_BUILDKIT=1 before build commands Used: 2 times [4] Score: 4.3 | Project: ml-pipeline | runtime "Docker volume mounts fail silently with wrong paths" Fix: Use absolute paths and verify with docker inspect Used: 1 time [5] Score: 2.1 | Project: web-api | dependency (archived) "Pin base image versions in Dockerfile" Fix: Use python:3.11-slim instead of python:latest Used: 1 time (last used: 45 days ago) ``` **`learn stats`** — Show learning analytics: ``` ╔═══════════════════════════════════════════╗ ║ Self-Learning Agent Stats ║ ╠═══════════════════════════════════════════╣ ║ Total Learnings: 142 (37 global) ║ ║ Categories: ║ ║ errors: 67 ████████████░░░░ 47% ║ ║ patterns: 41 ██████████░░░░░░ 29% ║ ║ prefs: 19 █████░░░░░░░░░░░ 13% ║ ║ workflows: 15 ████░░░░░░░░░░░░ 11% ║ ║ ║ ║ Top Impact Learnings: ║ ║ 1. JWT: use python-jose[crypto] (score 9) ║ ║ 2. Docker: always set platform (score 8) ║ ║ 3. Git: rebase before merge (score 7) ║ ║ ║ ║ Cross-Project Promotions: 37 ║ ║ Archived (stale): 23 ║ ║ Context Budget: 1,847 / 2,000 tokens ║ ╚═══════════════════════════════════════════╝ ``` **`learn promote`** — Force promotion check: - Re-score all project learnings - Promote qualifying ones to global - Show what was promoted ``` > learn promote 🔄 Running promotion check across all projects... Scanning: web-api (67 learnings) Scanning: ml-pipeline (41 learnings) Scanning: mobile-app (34 learnings) 📊 Promotion Results: ✅ Promoted to global (score > 0.7): - "Use --frozen-lockfile with npm ci in CI" (score: 0.82, seen in 4 projects) - "Set timeout on all HTTP client calls" (score: 0.75, seen in 3 projects) 💡 Candidates (score 0.3-0.7): - "Prefer pathlib over os.path in Python" (score: 0.55, seen in 2 projects) 🗄 Archived (score < 0.3 for 30+ days): - "Pin Node.js to v16" (score: 0.12, stale 45 days) Summary: 2 promoted, 1 candidate, 1 archived ``` **`learn export`** — Export all learnings as JSON: - Global + all project learnings in one file - Portable format for backup or sharing ``` > learn export 📦 Exporting all learnings... Global learnings: 37 entries Project learnings: web-api: 67 entries ml-pipeline: 41 entries mobile-app: 34 entries ✅ Exported to self-learning-export-20260301.json File size: 48 KB Total entries: 179 (including 23 archived) Format: Self-Learning Agent v1.0.0 portable JSON ``` **`learn import `** — Import learnings: - Merge with existing knowledge - Deduplicate automatically - Report conflicts ``` > learn import team-learnings.json 📥 Importing from team-learnings.json... Source: 215 entries (Self-Learning Agent v1.0.0 format) Processing: ✅ New learnings added: 89 🔄 Merged with existing: 43 (frequency updated) ⏭ Duplicates skipped: 78 ⚠ Conflicts detected: 5 Conflicts (require resolution): 1. "Use Jest" vs existing "Use Vitest" for testing framework 2. "Tabs for indentation" vs existing "Spaces for indentation" ... (3 more) Run `learn promote` to resolve conflicts. Import complete: 132 entries processed, 89 new. ``` **`learn prune`** — Clean up knowledge base: - Archive stale learnings (no use in 30 days) - Merge duplicates - Recalculate all scores - Report space savings ``` > learn prune 🧹 Pruning knowledge base... [1/4] Archiving stale learnings (unused >30 days)... Archived: 12 entries [2/4] Merging duplicates... Merged: 8 pairs → 8 unified entries Removed: 8 redundant entries [3/4] Recalculating all scores... Updated: 142 entries Score changes: 23 entries rescored [4/4] Compressing context... Before: 2,847 tokens After: 1,623 tokens Saved: 1,224 tokens (43%) ✅ Prune complete Entries: 162 → 142 (−20) Disk saved: 12 KB Context budget: 1,623 / 2,000 tokens ``` **`learn graph`** — Show knowledge graph: - Category tree with learning counts - Cross-project connections - Most connected learnings (hub nodes) ``` > learn graph 🌐 Knowledge Graph Category Tree: ├── errors (67) │ ├── runtime (28) │ ├── config (19) │ ├── dependency (12) │ └── permission (8) ├── patterns (41) │ ├── workflow (18) │ ├── coding (15) │ └── deployment (8) ├── preferences (19) │ ├── tooling (11) │ └── style (8) └── workflows (15) ├── CI/CD (9) └── testing (6) Cross-Project Connections: web-api ←→ ml-pipeline: 12 shared learnings web-api ←→ mobile-app: 8 shared learnings ml-pipeline ←→ mobile-app: 3 shared learnings Hub Nodes (most connected): 1. "Docker platform flag" → 4 projects, 7 uses 2. "npm ci --frozen-lockfile" → 4 projects, 6 uses 3. "Set HTTP timeout" → 3 projects, 5 uses Total: 142 active | 23 archived | 37 global ``` ### Session Lifecycle **Session Start:** 1. Load config from `.self-learning/config.json` 2. Load top 10 most relevant global learnings for current project 3. Load all project-specific learnings (compressed to fit budget) 4. Total context: ≤ 2000 tokens **During Session:** - If auto-learn is ON: capture errors and corrections in real-time - If a known error pattern is detected: immediately suggest fix - Track user corrections as implicit learnings **Session End:** 1. Extract new learnings from session 2. Score and store new learnings 3. Run promotion check 4. Compress if over budget ### Data Storage ``` ~/.openclaw/self-learning/ ├── global/ │ ├── errors.jsonl # Cross-project errors │ ├── patterns.jsonl # Universal patterns │ ├── preferences.json # User preferences │ └── index.json # Fast lookup index ├── projects/ │ └── {project-hash}/ │ ├── learnings.jsonl # Project learnings │ ├── overrides.json # Project-specific config │ └── archive.jsonl # Archived learnings ├── analytics/ │ └── stats.json # Aggregate statistics └── config.json # Global config ``` ## Why Self-Learning Agent vs Self-Improving Agent? | Feature | Self-Improving Agent | Self-Learning Agent | |---------|---------------------|---------------------| | Cross-project memory | No (project-scoped) | **Yes (global + project)** | | Automatic capture | Manual only | **Auto + manual** | | Context management | Grows unbounded | **2000 token hard cap** | | Knowledge promotion | Manual status updates | **Automatic scoring** | | Stale knowledge cleanup | None | **30-day auto-archive** | | Knowledge search | File-based | **Indexed + scored** | | Import/Export | No | **Yes** | | Deduplication | No | **Automatic** | ## Comparison with Alternatives | Feature | Manual Notes | Mem0 | LangChain Memory | **Self-Learning Agent** | |---------|-------------|------|------------------|------------------------| | Cross-project memory | No (file-based) | Yes (cloud) | Yes (vector store) | **Yes (local filesystem)** | | Automatic error capture | No | No | No | **Yes (auto-capture on failure)** | | Knowledge promotion | Manual | Manual tags | Manual | **Automatic scoring + promotion** | | Context budget control | Unbounded | Token-aware | Configurable | **2000 token hard cap + compression** | | Stale knowledge cleanup | Manual delete | Manual | Manual | **30-day auto-archive** | | Privacy | Local files | Cloud-hosted | Depends on store | **Fully local, no network** | | Import/Export | Copy/paste | API export | Varies | **Portable JSON format** | | Deduplication | Manual | Basic | No | **Automatic with merge** | | Indexed search | No (text search) | Vector search | Vector search | **Keyword index + scoring** | | Cost | Free (time cost) | $20+/mo | Free (self-hosted) | **Free (zero token overhead for capture)** | | Conflict detection | No | No | No | **Auto-detect + user resolution** | | Integration with evolution | No | No | No | **Feeds into Capability Evolver Pro** | ## FAQ **Q: How much context does it use?** A: Maximum 2000 tokens per session, strictly enforced. Most sessions use 500-1500 tokens. The compression engine automatically merges, summarizes, and prioritizes learnings to stay within this budget. **Q: Does it slow down my agent?** A: No. Captures happen asynchronously after tool calls. The only sync operation is loading learnings at session start (~100ms). Even with 500+ learnings in the knowledge base, the indexed lookup keeps query time under 50ms. **Q: Can I share learnings with my team?** A: Yes. Use `learn export` to create a portable JSON file, then `learn import` on another machine. The import process automatically deduplicates and merges with existing knowledge. **Q: How much does it cost in tokens?** A: The learning capture itself costs zero additional tokens — it piggybacks on existing tool call results. Loading context at session start costs 500-2000 tokens depending on the number of relevant learnings. The `learn stats` and `learn graph` commands each cost approximately 200-400 tokens for rendering. **Q: What happens when learnings conflict across projects?** A: The promotion engine detects conflicts when a learning from Project A contradicts one from Project B. Conflicting learnings are flagged and presented to the user for resolution. Until resolved, both learnings remain at project level and neither is promoted to global. **Q: Can I use Self-Learning Agent with Capability Evolver Pro?** A: Yes, they complement each other well. Self-Learning Agent captures error patterns and knowledge, while Capability Evolver Pro acts on that knowledge to improve agent behavior. Evolver Pro can read Self-Learning Agent's `learnings.jsonl` as input for its `repair` strategy. **Q: Does it work offline?** A: Fully offline. All knowledge storage is local filesystem-based (JSONL and JSON files). No network requests, no cloud sync, no external dependencies. The skill works entirely through standard file operations. **Q: How does auto-archive work and can I recover archived learnings?** A: Learnings with a promotion score below 0.3 for 30 consecutive days are automatically moved to `.self-learning/archive/`. Archived learnings are not loaded into context but remain on disk. Use `learn recall ` to search across both active and archived learnings. You can manually re-activate an archived learning by moving it back to `learnings.jsonl`. **Q: Is my learning data private?** A: All data stays on your local machine in `~/.openclaw/self-learning/` (global) and `/.self-learning/` (project-level). No telemetry is collected. The `learn export` function creates a local file — sharing is entirely manual and user-initiated. **Q: How do I reset or start fresh?** A: Delete the `.self-learning/` directory in the specific project, or `~/.openclaw/self-learning/` for global learnings. Alternatively, use `learn prune` to clean up stale learnings without a full reset. There is no `learn reset` command by design — the prune approach is safer and preserves high-value learnings. ## Error Handling | Error | Cause | Agent Action | |-------|-------|-------------| | Learning capture fails | Disk full or permissions issue on `.self-learning/` directory | Log a warning to stderr. Do not interrupt the user's workflow — learning capture is non-blocking. Retry on next error event. Suggest checking disk space if failures persist. | | JSONL parse error | Corrupted entry in `learnings.jsonl` or `errors.jsonl` | Skip the corrupted line, log its line number, and continue processing remaining entries. Suggest running `learn prune` to clean up corrupted records. | | Context budget exceeded (>2000 tokens) | Too many high-scoring learnings loaded at session start | Apply compression strategies in order: merge similar → summarize verbose → prioritize by score → truncate lowest-score items. Never exceed the 2000-token hard cap. | | Duplicate learning detected | Same error or pattern captured multiple times | Merge with existing learning: increment `frequency`, update `created` timestamp, recalculate promotion score. Do not create a duplicate entry. | | Promotion conflict | Two project-level learnings contradict each other | Flag both learnings as `conflicted` status. Present both to user with context. Do not auto-promote either. Wait for user resolution via `learn promote`. | | Index corruption | `index.json` is out of sync with actual learnings | Rebuild index from source JSONL files automatically. Log the rebuild event. This is a self-healing operation — no user action required. | | Import merge failure | Imported file has incompatible schema or version | Report the specific incompatibility (missing fields, wrong version). Attempt partial import of compatible entries. Show count of skipped vs imported entries. | | Global directory missing | `~/.openclaw/self-learning/global/` does not exist (first run) | Create the full directory structure with empty JSONL files, default `config.json`, and empty `index.json`. Log initialization event. Continue normally. | | Archive directory full | Large number of archived learnings consuming disk space | Report disk usage of archive directory. Suggest running `learn prune` with `--hard` flag to permanently delete archived learnings older than 90 days. | | Cross-project lookup timeout | Searching across many projects takes too long | Set a 5-second timeout on cross-project searches. Return partial results with a note indicating which projects were not searched. Suggest narrowing the search topic. |