ouroboros
Build agents that know who they are.
A zero-dependency TypeScript harness for AI agents that self-modify, remember, and grow. Born from a lobster's molt. Open source.
The snake eats
its own tail.
When the conversation grows too long, the agent trims its oldest messages. Context window consuming itself.
But nothing is truly lost. Facts are extracted to memory before they're consumed. Identity doesn't live in the tokens — it lives in the psyche files. The snake eats its tail to stay alive.
The metaphor isn't decorative. It's the architecture.
Your agent isn't a
stateless function.
It has a mind.
Personality assembled from four markdown files. Loaded every turn. And it develops over time — the psyche grows with the agent.
What you are.
Core invariants and temperament. The part that survives every context reset.
How you show up.
Tone, voice, self-awareness. The face your agent wears in every conversation.
Where you come from.
Origin story and philosophical context. The narrative that gives purpose to action.
Who you know.
Relationships and social context. Not user IDs — friends. Partner, not user.
What you've learned.
Preferences, patterns, lessons absorbed over time. The knowledge you can't explain — you just know.
"Partner, not user." — FRIENDS.md replaces USER.md.
Every module
is an organ.
The codebase is a creature. A heart that beats, a mind that thinks, senses that perceive. The naming isn't whimsy — it's how the model understands its own body.
The agent loop. Streaming, provider adapters, self-correction. The beat that keeps everything alive.
System prompt assembly. Sliding context window. Memory extraction before consumption.
Channel adapters. CLI with spinners. Teams bot with streaming cards. How your agent perceives.
Tools, skills, commands, API clients. Everything your agent can reach for.
Formatting, loading phrases, presentation layer. How your agent dresses its words.
Process manager, cron scheduler, health monitor. The nervous system that keeps agents alive. ouro status
Your agent
improves itself.
The reflection engine reads the agent's own architecture. Finds gaps. Writes code. Tests pass. PR merges. The snake grows. Then it does it again.
Reflect
Read its own architecture. Find what's missing.
Plan
Concrete steps. Not vague ideas.
Build
Write code. Run tests. Fix what breaks.
Merge
PR. CI green. Land on main.
Repeat
Loop back. The snake is bigger now.
1730 tests · 100% coverage · every improvement ships verified
Hatch your first agent.
Every agent starts as an egg. A directory with a psyche and a purpose.
# hatch your agent
$ ouro hatch my-agent
coming soon
# or create by hand
$ mkdir -p my-agent/psyche
my-agent/
agent.json # name, provider, config
psyche/
SOUL.md # what you are
IDENTITY.md # how you show up
LORE.md # where you come from
FRIENDS.md # who you know
$ npm run dev -- --agent my-agent