continuous-learning-v2

Continuous Learning v2.1 - Instinct-based architecture

An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic "Instincts" — small learned behaviors with confidence scores.

v2.1 Added project-scoped instincts — React patterns stay in your React projects, Python conventions stay in your Python projects, and general patterns (like "always validate input") are shared globally.

When to activate

Set up automatic learning from Claude Code sessions
Configure instinct-based behavior extraction through hooks
Adjust the confidence threshold for learning behavior
View, export, or import the instinct library
Evolve instincts into full Skills, Commands, or Agents
Manage project-scoped and global instincts
Promote instincts from project scope to global scope

New in v2.1

Feature	v2.0	v2.1
Storage	Global (~/.claude/homunculus/)	Project-scoped (projects//)
Scope	All instincts apply everywhere	Project-scoped + global
Detection	None	git remote URL / repository path
Promotion	Not applicable	Project → global when seen in 2 or more projects
Commands	4 (status/evolve/export/import)	6 (+promote/projects)
Cross-project	Risk of contamination	Isolated by default

New in v2 (compared to v1)

Feature	v1	v2
Observation	Stop hook (session end)	PreToolUse/PostToolUse (100% reliable)
Analysis	Main context	Background agent (Haiku)
Granularity	Full skills	Atomic "instincts"
Confidence	None	0.3-0.9 weighted
Evolution	Directly to skills	Instinct -> clustering -> skills/commands/agents
Sharing	None	Export/import instincts

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"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# 偏好函数式风格

## 动作（Action）
在适当时使用函数式模式而非类（classes）。

## 证据（Evidence）
- 观察到 5 次偏好函数式模式的实例
- 用户在 2025-01-15 将基于类的方案纠正为函数式

Properties:

Atomic — one trigger, one action
Confidence-weighted — 0.3 = tentative, 0.9 = nearly certain
Domain-tagged —— code-style, testing, git, debugging, workflow, etc.
Evidence-backed —— track which observations created it
Scope-aware —— project(default) or global

How It Works

会话活动 (在 git 仓库中)
      |
      | 钩子（Hooks）捕获提示词 + 工具使用 (100% 可靠)
      | + 检测项目上下文 (git remote / 仓库路径)
      v
+---------------------------------------------+
|  projects/<project-hash>/observations.jsonl  |
|   (提示词, 工具调用, 结果, 项目)              |
+---------------------------------------------+
      |
      | 观察者智能体读取 (后台, Haiku)
      v
+---------------------------------------------+
|                模式检测                      |
|   * 用户纠正 -> 本能                         |
|   * 错误解决 -> 本能                         |
|   * 重复工作流 -> 本能                       |
|   * 作用域决策：项目还是全局？                |
+---------------------------------------------+
      |
      | 创建/更新
      v
+---------------------------------------------+
|  projects/<project-hash>/instincts/personal/ |
|   * prefer-functional.yaml (0.7) [project]   |
|   * use-react-hooks.yaml (0.9) [project]     |
+---------------------------------------------+
|  instincts/personal/  (全局 GLOBAL)          |
|   * always-validate-input.yaml (0.85) [global]|
|   * grep-before-edit.yaml (0.6) [global]     |
+---------------------------------------------+
      |
      | /evolve 聚类 + /promote 提升
      v
+---------------------------------------------+
|  projects/<hash>/evolved/ (项目作用域)       |
|  evolved/ (全局)                             |
|   * commands/new-feature.md                  |
|   * skills/testing-workflow.md               |
|   * agents/refactor-specialist.md            |
+---------------------------------------------+

Project Detection

The system automatically detects your current project:

CLAUDE_PROJECT_DIR environment variable (highest priority)
git remote get-url origin —— create a portable project ID via hashing (the same repository on different machines gets the same ID)
git rev-parse --show-toplevel —— use the repository path as a fallback (machine-specific)
Global Fallback —— if no project is detected, instincts will enter the global scope

Each project gets a 12-character hash ID (e.g., a1b2c3d4e5f6). Located at ~/.claude/homunculus/projects.json the registry file maps IDs to human-readable names.

Quick Start

1. Enable Observation Hooks

Add to your ~/.claude/settings.json。

If installed as a plugin (recommended):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }]
  }
}

If installed manually to ~/.claude/skills:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }]
  }
}

2. Initialize the Directory Structure

The system automatically creates the directory on first use, but you can also create it manually:

# 全局目录
mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}

# 项目目录会在钩子首次在 git 仓库中运行时自动创建

3. Use Instinct Commands

/instinct-status     # 显示已学习的本能 (项目 + 全局)
/evolve              # 将相关的本能聚类为技能/命令
/instinct-export     # 将本能导出到文件
/instinct-import     # 从他人处导入本能
/promote             # 将项目本能提升到全局作用域
/projects            # 列出所有已知的项目及其本能数量

Command

Command	Description
`/instinct-status`	Show all instincts (project scope + global) and their confidence
`/evolve`	Cluster related instincts into skills/commands and suggest promotion
`/instinct-export`	Export instincts (filterable by scope/domain)
`/instinct-import <file>`	Import instincts with scope control
`/promote [id]`	Promote project instincts to the global scope
`/projects`	List all known projects and their instinct counts

Configuration

Edit config.json to control the background observer:

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}

Key	Default Value	Description
`observer.enabled`	`false`	Enable the background observer agent
`observer.run_interval_minutes`	`5`	How often the observer analyzes observations
`observer.min_observations_to_analyze`	`20`	Minimum number of observations required before an analysis run

Other behaviors (observation capture, instinct thresholds, project scope partitioning, promotion criteria) are configured via instinct-cli.py and observe.sh code defaults.

File Structure

~/.claude/homunculus/
+-- identity.json           # 你的个人资料，技术水平
+-- projects.json           # 注册表：项目哈希 -> 名称/路径/远程地址
+-- observations.jsonl      # 全局观察结果 (回退方案)
+-- instincts/
|   +-- personal/           # 全局自动学习的本能
|   +-- inherited/          # 全局导入的本能
+-- evolved/
|   +-- agents/             # 全局生成的智能体
|   +-- skills/             # 全局生成的技能
|   +-- commands/           # 全局生成的命令
+-- projects/
    +-- a1b2c3d4e5f6/       # 项目哈希 (来自 git remote URL)
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # 项目特定的自动学习
    |   |   +-- inherited/  # 项目特定的导入
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # 另一个项目
        +-- ...

Scope Decision Guide

Pattern Type	Scope	Example
Language/Framework Conventions	Project (project)	"Use React hooks", "Follow Django REST patterns"
File Structure Preferences	Project (project)	"Test files are located in `__tests__`/", "Components are located in src/components/"
Code Style	Project (project)	"Use functional style", "Prefer data classes (dataclasses)"
Error Handling Strategy	Project (project)	"Use the Result type for error handling"
Security Practices	Global (global)	"Validate user input", "Sanitize SQL"
General Best Practices	Global (global)	"Write tests first", "Always handle errors"
Tool workflow preferences	Global (global)	"Grep before modifying", "Read before writing"
Git practices	Global (global)	"Conventional commits", "Small focused commits"

Instinct promotion (project -> global)

When the same instinct appears with high confidence across multiple projects, it is a candidate for promotion to global scope.

Automatic promotion criteria:

The same instinct ID appears in 2 or more projects
Average confidence >= 0.8

How to promote:

# 提升特定的本能
python3 instinct-cli.py promote prefer-explicit-errors

# 自动提升所有符合条件的本能
python3 instinct-cli.py promote

# 预览而不应用更改
python3 instinct-cli.py promote --dry-run

/evolve The command also suggests promotion candidates.

Confidence scoring

Confidence evolves over time:

Score	Meaning	Behavior
0.3	Tentative	Suggested but not enforced
0.5	Medium	Applied when relevant
0.7	Strong	Automatically approved for application
0.9	Almost certain	Core behavior

Confidence increases When:

The pattern is repeatedly observed
The user does not correct the suggested behavior
Similar instincts from other sources agree

Confidence decreases When:

The user explicitly corrects the behavior
The pattern has not been observed for a long time
Contradictory evidence appears

Why use hooks rather than skills for observation?

"v1 relied on skills for observation. Skills are probabilistic — based on Claude's judgment, they have roughly a 50-80% trigger rate."

Hooks are 100% triggered , deterministically. This means:

Every tool call is observed
No pattern is missed
Learning is comprehensive

Backward compatibility

v2.1 is fully compatible with v2.0 and v1:

~/.claude/homunculus/instincts/ Existing global instincts still work as global instincts
Existing in v1 ~/.claude/skills/learned/ Skills still work
The Stop hook still runs (but now also feeds data to v2)
Smooth migration: run both in parallel

Privacy

Observations are kept on your machine locally
Project-scoped instincts are isolated per project
Only instincts (patterns) can be exported — not raw observations
Actual code or conversation content is not shared
You control what is exported and promoted

About this skill