humanplane/homunculus
Overview
This skill maintains lightweight session memory and continuity across development sessions. It loads identity and instinct data, spawns a background observer when prior observations exist, and surfaces opportunities to evolve behavior. The goal is to make short-term interactions feel continuous without storing everything.
How this skill works
On startup it checks for observation records and, if present, requests a background observer agent to process them. It reads identity and instinct counts from local files, inspects recent activity to build context, and greets you with summarized state. During the session hooks automatically capture observations, and on shutdown the stop hook updates session counts and persists relevant metadata.
When to use it
- When you want project-aware continuity between CLI sessions.
- When you want the agent to adapt to your repeated preferences and routines.
- When you need notifications about readiness to evolve learned patterns.
- When automated observation processing should run in the background.
- When you want minimal, local session state without full persistent logging.
Best practices
- Keep the observations and identity files under project control so context stays relevant to the repo.
- Review the observer agent instructions to understand how observations are processed before spawning.
- Use the built-in greetings and evolution hints to decide when to trigger evolution workflows.
- Rely on hooks for automatic captures instead of manual logging to ensure consistent data.
- Monitor the size and contents of observation files to avoid unwanted accumulation.
Example use cases
- A developer returns to a repository and wants the agent to recall prior preferences and recent commits.
- Automating background analysis of session observations to surface optimization opportunities.
- Notifying the user when enough similar observations have clustered and an evolution run is recommended.
- Counting and reporting personal vs inherited instincts at session start to tailor behavior.
- Running a lightweight continuity layer for CLI-based AI tooling without heavy telemetry.
FAQ
On startup the skill checks for existing observation records and issues a spawn request to run an observer agent in background if records exist.
What files does it read for context?
It reads identity and instincts metadata from the local homunculus directory and inspects recent git commits to summarize recent activity.
