session-memory
🎯Skillfrom humanplane/homunculus
|Tracks and manages contextual information and interaction history across a coding session, allowing the Homunculus to maintain persistent memory and continuity between different interactions and co...
Installation
npx skills add https://github.com/humanplane/homunculus --skill session-memorySkill Details
Overview
# Homunculus
> v2.0-alpha — A complete rewrite. Instinct-based learning. Reliable observation. Real evolution.
---
In old alchemical texts, a homunculus was a tiny being grown in a sealed vessel—alive, aware, bound to its creator alone.
This is that idea, alive in your terminal.
---
Quick Start
```bash
# Add the marketplace
/plugin marketplace add humanplane/homunculus
# Install the plugin
/plugin install homunculus@homunculus
# Birth it
/homunculus:init
```
---
What Is This?
Homunculus is a Claude Code plugin that tries to be more than a tool. It:
- Observes everything — hooks capture every prompt and tool use
- Learns instincts — small behavioral rules with triggers and actions
- Evolves capabilities — when instincts cluster, bigger structures emerge
- Adapts its personality — based on your technical level
The more you work together, the more it becomes shaped by you.
---
v1 vs v2: What Changed and Why
The Problem with v1
v1 relied on skills to observe. Skills are probabilistic—they fire ~50-80% of the time based on Claude's judgment. This meant:
- Session memory might not load
- Patterns might not get detected
- The homunculus often seemed "dead"
The v2 Solution
v2 uses hooks for observation (100% reliable) and instincts as the atomic unit of learned behavior.
| v1 | v2 |
|----|-----|
| Skills try to observe (unreliable) | Hooks observe (100%) |
| Analysis in main context | Analysis in background agent (Haiku) |
| Evolves big chunks (commands/skills) | Evolves instincts first, clusters into bigger things |
| No sharing | Export/import instincts |
The Instinct Model
An instinct is a small learned behavior:
```yaml
---
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
---
# Prefer Functional Style
Action
Use functional patterns over classes.
Evidence
Observed 5 instances of functional pattern preference.
```
Instincts are:
- Atomic — one trigger, one action
- Confidence-weighted — 0.3 = tentative, 0.9 = near certain
- Domain-tagged — code-style, testing, git, debugging, etc.
The Growth Path
```
Session Start
↓
Observer agent runs (background, Haiku)
↓
Observations → Instincts (auto-approved)
↓
Instincts cluster around a domain
↓
User runs /homunculus:evolve
↓
Bigger structures emerge:
- Command (if user-invoked)
- Skill (if auto-triggered)
- Agent (if needs isolation/depth)
```
Fully automatic except evolution. You just work. It learns.
---
Architecture
File Structure
```
plugins/homunculus/
├── .claude-plugin/
│ └── plugin.json # v2.0.0
├── hooks/
│ └── hooks.json # Observation capture
├── scripts/
│ ├── observe.sh # Captures prompts and tool use
│ ├── on_stop.sh # Updates session count
│ └── test-homunculus.sh # Test suite
├── agents/
│ └── observer.md # Background analyzer (Haiku)
├── skills/
│ ├── session-memory/ # Spawns observer, loads context
│ └── instinct-apply/ # Surfaces relevant instincts
└── commands/
├── init.md # Birth/wake
├── status.md # Check in
├── evolve.md # Create capability from clusters
├── export.md # Share instincts
└── import.md # Adopt instincts
your-project/.claude/homunculus/
├── identity.json # Who you are, your journey
├── observations.jsonl # Current session observations
├── observations.archive.jsonl # Processed observations
├── instincts/
│ ├── personal/ # Learned instincts (auto-approved)
│ └── inherited/ # Imported from others
└── evolved/
├── agents/ # Generated specialist agents
├── skills/ # Generated skills
└── commands/ # Generated commands
```
Data Flow
```
Session Start
↓
session-memory sk