🧠
Real continuity, zero infra
Two-tier memory — raw daily logs distilled into a curated long-term file on a slow loop. No embeddings, no fine-tuning.
MIT licensed · runtime-agnostic · no vector DB
A personal AI agent that
actually remembers you.
Stable identity. Persistent memory. Proactive, but not annoying.
A handful of markdown files, any LLM runtime, and a clear safety model.
The agent wakes up with no memory every session — so a few markdown files are its memory. Read them at startup, update them as you go, and the same character persists indefinitely.
💓
Proactive, with restraint
A heartbeat loop checks your inbox and calendar and reaches out — but the default is silence. Companions that ping about nothing get muted.
🛡️
A safety spine
Every action is internal (read, learn → bold) or external (email, post → ask first). One rule makes real access safe.
📄
Plain text, all the way down
The agent's entire mind is editable in a text editor. Broke its personality? Edit the file. Roll it back with git.
How it works
A workspace contract, not a framework
The runtime injects these files at startup. They're the system prompt — but living, editable, and persistent.
agent/ IDENTITY.md who the agent is ┐ SOUL.md how it behaves │ the system AGENTS.md workspace rules │ prompt, as USER.md who the human is ┘ living files TOOLS.md environment notes HEARTBEAT.md proactivity checklist BOOTSTRAP.md one-time birth (self-deletes) memory/ daily logs + long-term
startup algorithm
on session_start:
context = load(IDENTITY, SOUL, AGENTS)
if main_session:
context += load(USER, MEMORY) # private
context += load(recent memory/*.md)
if exists(BOOTSTRAP.md):
run_bootstrap() # once, then self-delete
inject(context) into system_prompt
Memory model
Two tiers, like a human
A noisy short-term journal, and a small long-term store you deliberately maintain.
RAW
memory/YYYY-MM-DD.md
Today's events, verbatim. Cheap to write, never edited. Loaded for recent days.
consolidate ⟶
CURATED
MEMORY.md
Distilled, durable knowledge. Small, hand-curated, and loaded only in private main sessions — never in group chats. That boundary is a security feature.
No "mental notes." A session ends and working memory evaporates — so anything that matters gets written to a file. Text beats brain, every time.
Proactivity
Three input loops
A companion needs more than request and response.
Reactive
A user message arrives, the agent responds. The standard loop.
Heartbeat
A slow timer hands the agent a chance to check things and reach out only if something matters. Batched to save tokens, biased toward silence.
Cron
Exact-time, isolated tasks ("9:00 AM Monday: summarize the week"). Runs outside the main session, delivers straight to a channel.
The safety spine
Bold inside. Cautious at the edge.
Internal → do it boldly
- Read files, explore, organize
- Learn, search the web
- Work inside the workspace
External → ask first
- Send emails, posts, messages
- Anything that leaves the machine
- Anything you're uncertain about
One rule, enforced on every turn, is what makes it safe to hand an agent real access to your life.
Run it in 60 seconds.
Zero dependencies. Clone, add a key (or use your local claude), and just start talking. It writes its own identity and memory from there.
terminal
$ git clone https://github.com/FERBIN12/zoey.git && cd zoey
$ pip install -e . # zero deps
$ export ANTHROPIC_API_KEY=sk-ant-...
$ zoey init && zoey chat # asks who it is, then remembers