self-improving-agent

name self-improving-agent description Instinct-based continuous learning system. Captures atomic learnings (instincts) with confidence scoring, supports project-scoped vs global scope, and evolves instincts into skills/commands/agents. Use when: (1) A command fails, (2) User corrects you, (3) Discovering patterns, (4) Need to review or evolve learned behaviors. Supports both v1 (markdown-based) and v2 (instinct-based) modes. metadata {"version":"2.1","origin":"ECC + OpenClaw"} Self-Improving Agent Skill An advanced learning system that turns Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring and project scope isolation. v2.1 adds project-scoped instincts — React patterns stay in your React project, Python conventions stay in your Python project, and universal patterns are shared globally. Quick Reference Situation Action Command/operation fails Log instinct or v1 learning User corrects you Create instinct with correction trigger Discovering patterns Log instinct with confidence score Review learned behaviors /instinct-status Evolve instincts to skills /evolve Promote project → global /promote Setup observation hooks Enable PreToolUse/PostToolUse hooks Two Learning Modes Mode 1: Instinct-Based (v2) - RECOMMENDED Atomic, confidence-weighted behaviors with project isolation: --- id: prefer-functional-style trigger: "when writing new functions" confidence: 0.7 domain: "code-style" scope: project project_id: "a1b2c3d4e5f6" --- # Prefer Functional Style ## Action Use functional patterns over classes when appropriate. ## Evidence - Observed 5 instances of functional pattern preference - User corrected class-based approach on 2025-01-15 Mode 2: Markdown-Based (v1) - LEGACY Traditional learning entries for complex, narrative learnings: ## [LRN-YYYYMMDD-XXX] category **Priority** : high | **Status** : pending | **Area** : backend ### Summary Detailed description of what was learned ### Details Full context and explanation Use v2 (instincts) for behavioral patterns, v1 (markdown) for complex incident analysis. Instinct-Based Learning (v2) The Instinct Model An instinct is a small, atomic learned behavior: Properties: Atomic — one trigger, one action Confidence-weighted — 0.3 = tentative, 0.9 = near certain Domain-tagged — code-style, testing, git, debugging, workflow, security, etc. Evidence-backed — tracks what observations created it Scope-aware — project (default) or global Confidence Scoring Score Meaning Behavior 0.3 Tentative Suggested but not enforced 0.5 Moderate Applied when relevant 0.7 Strong Auto-approved for application 0.9 Near-certain Core behavior Confidence increases when: Pattern is repeatedly observed User doesn't correct the suggested behavior Similar instincts from other sources agree Confidence decreases when: User explicitly corrects the behavior Pattern isn't observed for extended periods Contradicting evidence appears Scope Decision Guide Pattern Type Scope Examples Language/framework conventions project "Use React hooks", "Follow Django REST patterns" File structure preferences project "Tests in __tests__ /", "Components in src/components/" Code style project "Use functional style", "Prefer dataclasses" Security practices global "Validate user input", "Sanitize SQL" General best practices global "Write tests first", "Always handle errors" Tool workflow preferences global "Grep before Edit", "Read before Write" Git practices global "Conventional commits", "Small focused commits" Project Detection The system automatically detects your current project: CLAUDE_PROJECT_DIR env var (highest priority) git remote get-url origin — hashed to create a portable project ID git rev-parse --show-toplevel — fallback using repo path Global fallback — if no project detected, instincts go to global scope Each project gets a 12-character hash ID (e.g., a1b2c3d4e5f6 ). v2 Commands Command Description /instinct-status Show all instincts (project-scoped + global) with confidence /evolve Cluster related instincts into skills/commands, suggest promotions /instinct-export Export instincts (filterable by scope/domain) /instinct-import <file> Import instincts with scope control /promote [id] Promote project instincts to global scope /projects List all known projects and their instinct counts /instinct-status Example Project: my-react-app (a1b2c3d4e5f6) ├─ prefer-functional-style.yaml (0.7) [project] ├─ use-react-hooks.yaml (0.9) [project] └─ jest-testing-patterns.yaml (0.6) [project] Global Instincts: ├─ always-validate-input.yaml (0.85) [global] ├─ grep-before-edit.yaml (0.6) [global] └─ conventional-commits.yaml (0.75) [global] /evolve Workflow Clusters related instincts and generates: Skills — domain-specific workflows Commands — slash commands for common tasks Agents — specialized sub-agents /evolve # Analyzes instincts and suggests: # - "Create skill: react-testing-workflow.md" # - "Create command: /test-component" # - "Promote prefer-functional-style to global (seen in 3 projects)" /promote Workflow Promote project-scoped instincts to global when proven across projects: /promote prefer-explicit-errors # Promotes the instinct from current project to global scope Auto-promotion criteria: Same instinct ID in 2+ projects Average confidence >= 0.8 File Structure (v2) ~/.claude/homunculus/ ├── identity.json # Your profile, technical level ├── projects.json # Registry: project hash → name/path/remote ├── observations.jsonl # Global observations (fallback) ├── instincts/ │ ├── personal/ # Global auto-learned instincts │ └── inherited/ # Global imported instincts ├── evolved/ │ ├── agents/ # Global generated agents │ ├── skills/ # Global generated skills │ └── commands/ # Global generated commands └── projects/ ├── a1b2c3d4e5f6/ # Project hash │ ├── observations.jsonl │ ├── observations.archive/ │ ├── instincts/ │ │ ├── personal/ # Project-specific auto-learned │ │ └── inherited/ # Project-specific imported │ └── evolved/ │ ├── skills/ │ ├── commands/ │ └── agents/ └── f6e5d4c3b2a1/ # Another project Enabling Observation Hooks (v2) Add to your ~/.claude/settings.json : { "hooks" : { "PreToolUse" : [ { "matcher" : "*" , "hooks" : [ { "type" : "command" , "command" : "~/.claude/skills/self-improving-agent/hooks/observe.sh" } ] } ] , "PostToolUse" : [ { "matcher" : "*" , "hooks" : [ { "type" : "command" , "command" : "~/.claude/skills/self-improving-agent/hooks/observe.sh" } ] } ] } } Why hooks? Hooks fire 100% of the time , deterministically. Skills fire ~50-80% based on Claude's judgment. OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading. Installation Via ClawdHub (recommended): clawdhub install self-improving-agent Manual: git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent Remade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement Workspace Structure OpenClaw injects these files into every session: ~/.openclaw/workspace/ ├── AGENTS.md # Multi-agent workflows, delegation patterns ├── SOUL.md # Behavioral guidelines, personality, principles ├── TOOLS.md # Tool capabilities, integration gotchas ├── MEMORY.md # Long-term memory (main session only) ├── memory/ # Daily memory files │ └── YYYY-MM-DD.md └── .learnings/ # This skill's log files ├── LEARNINGS.md ├── ERRORS.md └── FEATURE_REQUESTS.md Create Learning Files mkdir -p ~/.openclaw/workspace/.learnings Then create the log files (or copy from assets/ ): LEARNINGS.md — corrections, knowledge gaps, best practices ERRORS.md — command failures, exceptions FEATURE_REQUESTS.md — user-requested capabilities Promotion Targets When learnings prove broadly applicable, promote them to workspace files: Learning Type Promote To Example Behavioral patterns SOUL.md "Be concise, avoid disclaimers" Workflow improvements AGENTS.md "Spawn sub-agents for long tasks" Tool gotchas TOOLS.md "Git push needs auth configured first" Inter-Session Communication OpenClaw provides tools to share learnings across sessions: sessions_list — View active/recent sessions sessions_history — Read another session's transcript sessions_send — Send a learning to another session sessions_spawn — Spawn a sub-agent for background work Optional: Enable Hook For automatic reminders at session start: # Copy hook to OpenClaw hooks directory cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement # Enable it openclaw hooks enable self-improvement See references/openclaw-integration.md for complete details. Generic Setup (Other Agents) For Claude Code, Codex, Copilot, or other agents, create .learnings/ in your project: mkdir -p .learnings Copy templates from assets/ or create files with headers. Add reference to agent files AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md to remind yourself to log learnings. (this is an alternative to hook-based reminders) Self-Improvement Workflow When errors or corrections occur: Log to .learnings/ERRORS.md , LEARNINGS.md , or FEATURE_REQUESTS.md Review and promote broadly applicable learnings to: CLAUDE.md - project facts and conventions AGENTS.md - workflows and automation .github/copilot-instructions.md - Copilot context Logging Formats v2: Instinct Format (RECOMMENDED for behavioral patterns) Create atomic instinct files in ~/.claude/homunculus/instincts/personal/ or project-scoped: --- id: unique-instinct-id trigger: "when to apply this instinct" confidence: 0.7 domain: "code-style|testing|git|debugging|workflow|security|infra" source: "session-observation|user-correction|pattern-detection" scope: "project|global" project_id: "a1b2c3d4e5f6" # if scope: project project_name: "my-project" created_at: "2025-01-15T10:00:00Z" updated_at: "2025-01-15T10:00:00Z" evidence_count: 3 --- # Instinct Title ## Action What to do when triggered. ## Rationale Why this behavior is preferred. ## Examples ### Positive ```typescript // Good example Negative // Bad example Evidence Observed 3 instances of this pattern User corrected opposite approach on 2025-01-10 **File naming:** `~/.claude/homunculus/instincts/personal/{instinct-id}.yaml` ### v1: Markdown Format (for complex learnings) #### Learning Entry Append to `.learnings/LEARNINGS.md`: ```markdown ## [LRN-YYYYMMDD-XXX] category **Logged**: ISO-8601 timestamp **Priority**: low | medium | high | critical **Status**: pending **Area**: frontend | backend | infra | tests | docs | config ### Summary One-line description of what was learned ### Details Full context: what happened, what was wrong, what's correct ### Suggested Action Specific fix or improvement to make ### Metadata - Source: conversation | error | user_feedback | simplify-and-harden - Related Files: path/to/file.ext - Tags: tag1, tag2 - See Also: LRN-20250110-001 - Pattern-Key: simplify.dead_code | harden.input_validation --- v2 vs v1 Comparison | Feature | v1 (Markdown) | v2 (Instincts) |