auto-learning

Files (7)

• SKILL.md
• observer.md · agents/
• start-observer.sh · agents/
• config.json
• observe.py · hooks/
• observe.sh · hooks/
• instinct-cli.py · scripts/

SKILL.md (first lines)

# 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:

```yaml
---
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

```bash
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:

```bash
"${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:

| Command | CLI invocation | Description |
|---------|----------------|-------------|
| `/idev:instinct-status` | `instinct-cli.py status` | Show all instincts with confidence, by domain |
| `/idev:instinct-export` | `instinct-cli.py export [--domain] [--min-confidence] [--output]` | Export sanitized instincts for sharing |
| `/idev:instinct-import` | `instinct-cli.py import <file-or-url> [--dry-run] [--force] [--min-confidence]` | Import instincts; updates existing ids in place |
| `/idev:evolve` | `instinct-cli.py evolve [--generate]` | Print instinct clusters; Claude writes the evolved files |

Run it directly with:

```bash
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:

```json
{
  "version": "2.0",
  "observation": {
    "enabled": true,
    "store_path": "~/.claude/homunculus/observations.jsonl",
    "max_file_size_mb": 10,

From TheophilusChinomona/idev, MIT.

More from TheophilusChinomona/idev