Skip to content

Commit 5c63fa9

Browse files
committed
feat: v1.1.0 release - session ID tracking, async hooks, new skills
- Add session ID to session filenames (Issue anomalyco#62) - Add getSessionIdShort() helper for unique per-session tracking - Add async hooks documentation with example - Create iterative-retrieval skill for progressive context refinement - Add continuous-learning-v2 skill with instinct-based learning - Add ecc.tools ecosystem section to README - Update skills list in README All 67 tests passing.
1 parent 5670fcd commit 5c63fa9

19 files changed

Lines changed: 2058 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,8 @@ everything-claude-code/
107107
| |-- backend-patterns/ # API, database, caching patterns
108108
| |-- frontend-patterns/ # React, Next.js patterns
109109
| |-- continuous-learning/ # Auto-extract patterns from sessions (Longform Guide)
110+
| |-- continuous-learning-v2/ # Instinct-based learning with confidence scoring
111+
| |-- iterative-retrieval/ # Progressive context refinement for subagents
110112
| |-- strategic-compact/ # Manual compaction suggestions (Longform Guide)
111113
| |-- tdd-workflow/ # TDD methodology
112114
| |-- security-review/ # Security checklist
@@ -172,6 +174,28 @@ everything-claude-code/
172174

173175
---
174176

177+
## Ecosystem Tools
178+
179+
### ecc.tools - Skill Creator
180+
181+
Automatically generate Claude Code skills from your repository.
182+
183+
[Install GitHub App](https://github.com/apps/skill-creator) | [ecc.tools](https://ecc.tools)
184+
185+
Analyzes your repository and creates:
186+
- **SKILL.md files** - Ready-to-use skills for Claude Code
187+
- **Instinct collections** - For continuous-learning-v2
188+
- **Pattern extraction** - Learns from your commit history
189+
190+
```bash
191+
# After installing the GitHub App, skills appear in:
192+
~/.claude/skills/generated/
193+
```
194+
195+
Works seamlessly with the `continuous-learning-v2` skill for inherited instincts.
196+
197+
---
198+
175199
## Installation
176200

177201
### Option 1: Install as Plugin (Recommended)

‎hooks/hooks.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,18 @@
8888
],
8989
"description": "Log PR URL and provide review command after PR creation"
9090
},
91+
{
92+
"matcher": "tool == \"Bash\" && tool_input.command matches \"(npm run build|pnpm build|yarn build)\"",
93+
"hooks": [
94+
{
95+
"type": "command",
96+
"command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{console.error('[Hook] Build completed - async analysis running in background');console.log(d)})\"",
97+
"async": true,
98+
"timeout": 30
99+
}
100+
],
101+
"description": "Example: async hook for build analysis (runs in background without blocking)"
102+
},
91103
{
92104
"matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
93105
"hooks": [

‎scripts/hooks/session-end.js‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ const {
1414
getSessionsDir,
1515
getDateString,
1616
getTimeString,
17+
getSessionIdShort,
1718
ensureDir,
1819
readFile,
1920
writeFile,
@@ -24,7 +25,9 @@ const {
2425
async function main() {
2526
const sessionsDir = getSessionsDir();
2627
const today = getDateString();
27-
const sessionFile = path.join(sessionsDir, `${today}-session.tmp`);
28+
const shortId = getSessionIdShort();
29+
// Include session ID in filename for unique per-session tracking
30+
const sessionFile = path.join(sessionsDir, `${today}-${shortId}-session.tmp`);
2831

2932
ensureDir(sessionsDir);
3033

‎scripts/hooks/session-start.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ async function main() {
2727
ensureDir(learnedDir);
2828

2929
// Check for recent session files (last 7 days)
30-
const recentSessions = findFiles(sessionsDir, '*.tmp', { maxAge: 7 });
30+
// Match both old format (YYYY-MM-DD-session.tmp) and new format (YYYY-MM-DD-shortid-session.tmp)
31+
const recentSessions = findFiles(sessionsDir, '*-session.tmp', { maxAge: 7 });
3132

3233
if (recentSessions.length > 0) {
3334
const latest = recentSessions[0];

‎scripts/lib/utils.js‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,19 @@ function getTimeString() {
7979
return `${hours}:${minutes}`;
8080
}
8181

82+
/**
83+
* Get short session ID from CLAUDE_SESSION_ID environment variable
84+
* Returns the last 8 characters for uniqueness with brevity
85+
* @param {string} fallback - Fallback value if no session ID (default: 'default')
86+
*/
87+
function getSessionIdShort(fallback = 'default') {
88+
const sessionId = process.env.CLAUDE_SESSION_ID;
89+
if (!sessionId || sessionId.length === 0) {
90+
return fallback;
91+
}
92+
return sessionId.slice(-8);
93+
}
94+
8295
/**
8396
* Get current datetime in YYYY-MM-DD HH:MM:SS format
8497
*/
@@ -360,6 +373,7 @@ module.exports = {
360373
getDateString,
361374
getTimeString,
362375
getDateTimeString,
376+
getSessionIdShort,
363377

364378
// File operations
365379
findFiles,
Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
name: continuous-learning-v2
3+
description: Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents.
4+
version: 2.0.0
5+
---
6+
7+
# Continuous Learning v2 - Instinct-Based Architecture
8+
9+
An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring.
10+
11+
## What's New in v2
12+
13+
| Feature | v1 | v2 |
14+
|---------|----|----|
15+
| Observation | Stop hook (session end) | PreToolUse/PostToolUse (100% reliable) |
16+
| Analysis | Main context | Background agent (Haiku) |
17+
| Granularity | Full skills | Atomic "instincts" |
18+
| Confidence | None | 0.3-0.9 weighted |
19+
| Evolution | Direct to skill | Instincts → cluster → skill/command/agent |
20+
| Sharing | None | Export/import instincts |
21+
22+
## The Instinct Model
23+
24+
An instinct is a small learned behavior:
25+
26+
```yaml
27+
---
28+
id: prefer-functional-style
29+
trigger: "when writing new functions"
30+
confidence: 0.7
31+
domain: "code-style"
32+
source: "session-observation"
33+
---
34+
35+
# Prefer Functional Style
36+
37+
## Action
38+
Use functional patterns over classes when appropriate.
39+
40+
## Evidence
41+
- Observed 5 instances of functional pattern preference
42+
- User corrected class-based approach to functional on 2025-01-15
43+
```
44+
45+
**Properties:**
46+
- **Atomic** — one trigger, one action
47+
- **Confidence-weighted** — 0.3 = tentative, 0.9 = near certain
48+
- **Domain-tagged** — code-style, testing, git, debugging, workflow, etc.
49+
- **Evidence-backed** — tracks what observations created it
50+
51+
## How It Works
52+
53+
```
54+
Session Activity
55+
│
56+
│ Hooks capture prompts + tool use (100% reliable)
57+
▼
58+
┌─────────────────────────────────────────┐
59+
│ observations.jsonl │
60+
│ (prompts, tool calls, outcomes) │
61+
└─────────────────────────────────────────┘
62+
│
63+
│ Observer agent reads (background, Haiku)
64+
▼
65+
┌─────────────────────────────────────────┐
66+
│ PATTERN DETECTION │
67+
│ • User corrections → instinct │
68+
│ • Error resolutions → instinct │
69+
│ • Repeated workflows → instinct │
70+
└─────────────────────────────────────────┘
71+
│
72+
│ Creates/updates
73+
▼
74+
┌─────────────────────────────────────────┐
75+
│ instincts/personal/ │
76+
│ • prefer-functional.md (0.7) │
77+
│ • always-test-first.md (0.9) │
78+
│ • use-zod-validation.md (0.6) │
79+
└─────────────────────────────────────────┘
80+
│
81+
│ /evolve clusters
82+
▼
83+
┌─────────────────────────────────────────┐
84+
│ evolved/ │
85+
│ • commands/new-feature.md │
86+
│ • skills/testing-workflow.md │
87+
│ • agents/refactor-specialist.md │
88+
└─────────────────────────────────────────┘
89+
```
90+
91+
## Quick Start
92+
93+
### 1. Enable Observation Hooks
94+
95+
Add to your `~/.claude/settings.json`:
96+
97+
```json
98+
{
99+
"hooks": {
100+
"PreToolUse": [{
101+
"matcher": "*",
102+
"hooks": [{
103+
"type": "command",
104+
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh pre"
105+
}]
106+
}],
107+
"PostToolUse": [{
108+
"matcher": "*",
109+
"hooks": [{
110+
"type": "command",
111+
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh post"
112+
}]
113+
}]
114+
}
115+
}
116+
```
117+
118+
### 2. Initialize Directory Structure
119+
120+
```bash
121+
mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands}}
122+
touch ~/.claude/homunculus/observations.jsonl
123+
```
124+
125+
### 3. Run the Observer Agent (Optional)
126+
127+
The observer can run in the background analyzing observations:
128+
129+
```bash
130+
# Start background observer
131+
~/.claude/skills/continuous-learning-v2/agents/start-observer.sh
132+
```
133+
134+
## Commands
135+
136+
| Command | Description |
137+
|---------|-------------|
138+
| `/instinct-status` | Show all learned instincts with confidence |
139+
| `/evolve` | Cluster related instincts into skills/commands |
140+
| `/instinct-export` | Export instincts for sharing |
141+
| `/instinct-import <file>` | Import instincts from others |
142+
143+
## Configuration
144+
145+
Edit `config.json`:
146+
147+
```json
148+
{
149+
"version": "2.0",
150+
"observation": {
151+
"enabled": true,
152+
"store_path": "~/.claude/homunculus/observations.jsonl",
153+
"max_file_size_mb": 10,
154+
"archive_after_days": 7
155+
},
156+
"instincts": {
157+
"personal_path": "~/.claude/homunculus/instincts/personal/",
158+
"inherited_path": "~/.claude/homunculus/instincts/inherited/",
159+
"min_confidence": 0.3,
160+
"auto_approve_threshold": 0.7,
161+
"confidence_decay_rate": 0.05
162+
},
163+
"observer": {
164+
"enabled": true,
165+
"model": "haiku",
166+
"run_interval_minutes": 5,
167+
"patterns_to_detect": [
168+
"user_corrections",
169+
"error_resolutions",
170+
"repeated_workflows",
171+
"tool_preferences"
172+
]
173+
},
174+
"evolution": {
175+
"cluster_threshold": 3,
176+
"evolved_path": "~/.claude/homunculus/evolved/"
177+
}
178+
}
179+
```
180+
181+
## File Structure
182+
183+
```
184+
~/.claude/homunculus/
185+
├── identity.json # Your profile, technical level
186+
├── observations.jsonl # Current session observations
187+
├── observations.archive/ # Processed observations
188+
├── instincts/
189+
│ ├── personal/ # Auto-learned instincts
190+
│ └── inherited/ # Imported from others
191+
└── evolved/
192+
├── agents/ # Generated specialist agents
193+
├── skills/ # Generated skills
194+
└── commands/ # Generated commands
195+
```
196+
197+
## Integration with Skill Creator
198+
199+
When you use the [Skill Creator GitHub App](https://skill-creator.app), it now generates **both**:
200+
- Traditional SKILL.md files (for backward compatibility)
201+
- Instinct collections (for v2 learning system)
202+
203+
Instincts from repo analysis have `source: "repo-analysis"` and include the source repository URL.
204+
205+
## Confidence Scoring
206+
207+
Confidence evolves over time:
208+
209+
| Score | Meaning | Behavior |
210+
|-------|---------|----------|
211+
| 0.3 | Tentative | Suggested but not enforced |
212+
| 0.5 | Moderate | Applied when relevant |
213+
| 0.7 | Strong | Auto-approved for application |
214+
| 0.9 | Near-certain | Core behavior |
215+
216+
**Confidence increases** when:
217+
- Pattern is repeatedly observed
218+
- User doesn't correct the suggested behavior
219+
- Similar instincts from other sources agree
220+
221+
**Confidence decreases** when:
222+
- User explicitly corrects the behavior
223+
- Pattern isn't observed for extended periods
224+
- Contradicting evidence appears
225+
226+
## Why Hooks vs Skills for Observation?
227+
228+
> "v1 relied on skills to observe. Skills are probabilistic—they fire ~50-80% of the time based on Claude's judgment."
229+
230+
Hooks fire **100% of the time**, deterministically. This means:
231+
- Every tool call is observed
232+
- No patterns are missed
233+
- Learning is comprehensive
234+
235+
## Backward Compatibility
236+
237+
v2 is fully compatible with v1:
238+
- Existing `~/.claude/skills/learned/` skills still work
239+
- Stop hook still runs (but now also feeds into v2)
240+
- Gradual migration path: run both in parallel
241+
242+
## Privacy
243+
244+
- Observations stay **local** on your machine
245+
- Only **instincts** (patterns) can be exported
246+
- No actual code or conversation content is shared
247+
- You control what gets exported
248+
249+
## Related
250+
251+
- [Skill Creator](https://skill-creator.app) - Generate instincts from repo history
252+
- [Homunculus](https://github.com/humanplane/homunculus) - Inspiration for v2 architecture
253+
- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Continuous learning section
254+
255+
---
256+
257+
*Instinct-based learning: teaching Claude your patterns, one observation at a time.*

0 commit comments

Comments
 (0)