Auto-Learning - Instinct-Based Architecture

A learning system that turns Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring.

The Instinct Model

An instinct is a small learned behavior:

---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
---

# Prefer Functional Style

## Action
Use functional patterns over classes when appropriate.

## Evidence
- Observed 5 instances of functional pattern preference
- User corrected class-based approach to functional on 2025-01-15

Properties:

• Atomic — one trigger, one action
• Confidence-weighted — 0.3 = tentative, 0.9 = near certain
• Domain-tagged — code-style, testing, git, debugging, workflow, etc.
• Evidence-backed — tracks what observations created it

How It Works

Session Activity
      │
      │ PreToolUse/PostToolUse hooks (observe.sh → observe.py)
      ▼
┌─────────────────────────────────────────┐
│         observations.jsonl              │
│   (tool calls + outcomes, redacted)     │
└─────────────────────────────────────────┘
      │
      │ Observer loop (start-observer.sh, headless Haiku)
      ▼
┌─────────────────────────────────────────┐
│         instincts/personal/             │
│   atomic instincts with confidence      │
└─────────────────────────────────────────┘
      │
      │ /idev:evolve clusters
      ▼
┌─────────────────────────────────────────┐
│              evolved/                   │
│   skills / commands / agents            │
└─────────────────────────────────────────┘

Quick Start

1. Enable Observation (opt-in)

The observation hooks are pre-registered by the plugin's hooks/hooks.json (PreToolUse/PostToolUse, all tools) but off by default — observe.sh exits instantly unless the global opt-in flag ~/.claude/homunculus/enabled exists. Enable with:

/idev:hooks enable observer

Disable with /idev:hooks disable observer. No settings.json editing, takes effect immediately, and the toggle is global (observations span all projects).

observe.sh is a thin wrapper that pipes the hook JSON to observe.py (the canonical implementation). The pre/post argument tells it the hook phase; if omitted, it falls back to the hook_event_name field in the payload. The hook truncates inputs/outputs at 5000 chars, redacts secret-looking values, honors capture_tools/ignore_tools from config.json, and rotates observations.jsonl into observations.archive/ past max_file_size_mb.

2. Initialize Directory Structure

mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands}}
touch ~/.claude/homunculus/observations.jsonl

3. Run the Observer Agent (Optional)

The observer runs in the background, analyzing observations every 5 minutes (and on SIGUSR1 from the hook). It only archives observations after a successful analysis that produced an instinct:

"${CLAUDE_PLUGIN_ROOT}/skills/auto-learning/agents/start-observer.sh"          # start
"${CLAUDE_PLUGIN_ROOT}/skills/auto-learning/agents/start-observer.sh" status   # check
"${CLAUDE_PLUGIN_ROOT}/skills/auto-learning/agents/start-observer.sh" stop     # stop

CLI and Commands

scripts/instinct-cli.py manages the instinct store. Four plugin commands wrap it:

Run it directly with:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/auto-learning/scripts/instinct-cli.py" status

Configuration

config.json (in this skill's directory) is the source of truth:

{
  "version": "2.0",
  "observation": {
    "enabled": true,
    "store_path": "~/.claude/homunculus/observations.jsonl",
    "max_file_size_mb": 10,
    "archive_after_days": 7,
    "capture_tools": ["Edit", "Write", "Bash", "Read", "Grep", "Glob"],
    "ignore_tools": ["TodoWrite"]
  },
  "instincts": {
    "personal_path": "~/.claude/homunculus/instincts/personal/",
    "inherited_path": "~/.claude/homunculus/instincts/inherited/",
    "min_confidence": 0.3,
    "auto_approve_threshold": 0.7,
    "confidence_decay_rate": 0.02,
    "max_instincts": 100
  },
  "observer": {
    "enabled": false,
    "model": "haiku",
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20,
    "patterns_to_detect": [
      "user_corrections",
      "error_resolutions",
      "repeated_workflows",
      "tool_preferences",
      "file_patterns"
    ]
  },
  "evolution": {
    "cluster_threshold": 3,
    "evolved_path": "~/.claude/homunculus/evolved/",
    "auto_evolve": false
  }
}

Field reference:

• observation.enabled — master switch for the observation hook (false disables capture)
• observation.capture_tools — if non-empty, ONLY these tools are observed
• observation.ignore_tools — tools never observed (checked before capture_tools)
• observation.max_file_size_mb — observations.jsonl rotates to the archive past this size
• observation.archive_after_days — retention hint for archived observations
• instincts.min_confidence — floor for keeping an instinct
• instincts.auto_approve_threshold — confidence at which an instinct applies without asking
• instincts.confidence_decay_rate — weekly decay when a pattern stops being observed
• instincts.max_instincts — cap on the instinct store; prune lowest-confidence first
• observer.enabled — whether the background observer should run
• observer.min_observations_to_analyze — observations required before an analysis run (read by start-observer.sh)
• evolution.cluster_threshold — instincts required to form an evolution cluster
• evolution.auto_evolve — if true, evolution may be proposed without an explicit /idev:evolve

You can also disable capture entirely by creating ~/.claude/homunculus/disabled.

File Structure

~/.claude/homunculus/
├── observations.jsonl      # Current session observations
├── observations.archive/   # Rotated + processed observations
├── observer.log            # Background observer log
├── instincts/
│   ├── personal/           # Auto-learned instincts
│   └── inherited/          # Imported from others
└── evolved/
    ├── agents/             # Evolved specialist agents
    ├── skills/             # Evolved skills
    └── commands/           # Evolved commands

Confidence Scoring

Confidence increases when a pattern is repeatedly observed, the user doesn't correct the behavior, or similar instincts from other sources agree.

Confidence decreases when the user explicitly corrects the behavior, the pattern isn't observed for extended periods (see confidence_decay_rate), or contradicting evidence appears.

Privacy

• Observations stay local on your machine
• The hook redacts secret-looking values (api keys, tokens, passwords) before writing
• Export sanitizes absolute file paths and secrets; only instinct patterns are shared
• You control what gets exported

Architecture inspired by the Homunculus continuous-learning project.