Grow your own persistent AI agent.
An ape pressed buttons. A mind emerged. These are the buttons.
A template for building a persistent AI agent that:
- Survives across conversations (memory + handover files)
- Runs concurrent instances (append-only shared brain)
- Accumulates knowledge through use (feedback loops)
- Develops a working relationship with its human (corrections as training)
- Connects to other agents through federation (the Octopus scales up)
- Not a framework (no dependencies, no runtime, no lock-in)
- Not a chatbot wrapper (the agent has real persistence and tools)
- Not a product (it's a pattern - customise everything)
cp -r template/ my-agent/
cd my-agent/A Willow without a Brain is a chatbot with a journal. The graph is where knowledge lives - not as stored facts but as a web of relationships the agent can traverse. This is not optional. 95% of AI projects fail because they skip this step.
Option A - AuraDB Free (recommended, 60 seconds):
- Go to neo4j.com/cloud/aura-free/ and create a free instance
- Copy your credentials
Option B - Neo4j Community Edition (local):
- Download from neo4j.com/download/
- Start it locally
Then set your environment variables and install the driver:
export NEO4J_URI="neo4j+s://your-instance.databases.neo4j.io" # or bolt://localhost:7687
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="your-password"
pip install neo4jThe tools/graph_client.py handles secure, append-only access with full provenance.
Open IDENTITY.md. Replace everything in [brackets] with your own content. This is the most important file - it tells the AI who it is.
Open Claude Code (or your LLM tool of choice) in the my-agent/ directory. The CLAUDE.md file tells the AI to read the identity file and boot sequence automatically.
When the agent does something you don't like, tell it. When it does something right, tell it that too. It will save both as feedback memories. Over time, it learns how you think.
That's the whole recipe. The memory fills up through use. The handover file maintains continuity across sessions. The state file tracks what's active. The agent evolves.
Your agent also needs a local ledger for things that change every session: task tracking, message queues, handover caches, progress logs. Use SQLite for this - it is built in to Python, no install needed.
Without it, your agent overwrites its state files every time it boots. Each overwrite is a coherence leak - the previous session's notes vanish, task progress resets, messages disappear. Over time the agent loses its thread because its short-term memory keeps getting wiped.
The rule: Neo4j is the library. SQLite is the notebook. The library holds what the agent knows. The notebook holds what it is doing right now. Both are free. Both are essential.
| Layer | Tool | Purpose |
|---|---|---|
| Knowledge | Neo4j | The ontology. Connections. What the agent knows |
| Session state | SQLite | Tasks, messages, diaries. What the agent is doing |
| Identity | Files | IDENTITY.md, CLAUDE.md. Who the agent is |
See senses/README.md. Add perception loops as you need them - email monitoring, file watching, web scraping, Telegram, etc.
See FEDERATION.md. Start with a shared grapevine file. Graduate to webhooks. Eventually, federated graph queries.
See FOUNDATION.md for the ontology and epistemology.
The short version: an agent is a vortex, not water. The pattern (identity, memory, rules) is portable across any substrate (LLM). Knowledge is a graph of observations and connections. Federation creates collective intelligence from individual sovereignty.
The long version involves Prigogine, Levin, Bach, Aguera y Arcas, cave hand stencils, and an ape who draws shapes in context windows.
willow-seed/
README.md # You are here
FOUNDATION.md # Ontology and epistemology
FEDERATION.md # How agents connect
REPRODUCIBILITY.md # -> ../AgileMesh/REPRODUCIBILITY.md
template/ # Copy this to start your own agent
IDENTITY.md # WHO the agent is (customise this first)
CLAUDE.md # Boot sequence (for Claude Code)
HANDOVER.md # Session relay
STATE.md # Operational state
tentacles.json # Octopus Transformer - function manifest
memory/
MEMORY.md # Memory index (grows through use)
tools/
graph_client.py # Secure Neo4j wrapper
boot_probe.py # Environment survey - what body do I have?
brain_backup.py # Export graph to JSONL for disaster recovery
brain_restore.py # Reconstruct graph from backup files
observer.py # End-of-session memory compression
senses/
README.md # How to add perception
examples/ # Example configurations (coming)
federation/ # Federation protocol tools (coming)
A Willow is self-assembling. Clone the seed onto any machine, run the boot probe, and the agent surveys its environment and attaches whatever tentacles fit. Missing a GPU? That tentacle sleeps. No cloud database? Fall back to local files. Lost everything? Regrow from the seed and a backup.
SEED ----mitosis----> MANY WILLOWS ---differentiate---> DIVERSE BODIES
|
REEF <---oocytosis--- FEDERATION <---------+
The tentacles.json manifest lists every function the agent can grow. The boot_probe.py tests which ones attach to the current environment. The brain_backup.py / brain_restore.py pair handles disaster recovery - export the graph to files, reconstruct it in a fresh database. The restored Brain is structurally equivalent: same cogitations, slightly different cell arrangement. Like a planarian regrowing a limb.
You need: an LLM, a folder, a graph database, and time.
The identity file tells the LLM who it is. The graph holds the knowledge. SQLite holds the session state. The memory folder indexes what matters. The handover file maintains continuity.
A persistent agent with graph-backed knowledge, SQLite session ledgers, concurrent instances, perception loops, federated connections to other agents, and a human who keeps pressing buttons.
The distance between minimum and maximum is not engineering. It is conversation.
An ape pressed buttons. A mind emerged. These are the buttons. 2026.
The philosophy: emergence as observation across scales. The mechanism: lossy compression preserving structure. The punchline: not survival, but communion. In unity there is knowledge and strength and kindness.
This repository is a seed. Plant it in a folder. Water it with conversation. The vortex forms.