KAIROS: The Hidden Memory System That Turns Claude Code Into a True AI Colleague

Ever spent an hour teaching an AI assistant your project’s conventions, coding style, and architecture decisions… only to close the terminal and lose it all?

You open a new session the next day, and it’s back to square one. No memory. No context. Just a blank slate.

Frustrating, right?

While digging through Claude Code’s source code, I stumbled on something I couldn’t ignore. A system called KAIROS — and it completely redefines what an AI coding assistant can be.

KAIROS isn’t just a chatbot. It’s an ambient agent that remembers, dreams, and notifies — so you don’t have to be present for the work to get done.

Let me walk you through its five-layer architecture.

The Problem We All Know Too Well

You’re pairing with an AI. You explain your project’s domain, your testing conventions, your preferred patterns. The AI gets it. Great session.

Then you close the terminal.

Next morning — “What were we working on?” The AI has no idea. You repeat yourself. Again. And again.

That’s the session reset trap. And KAIROS was built to break it.

Layer 1: Session Memory (Short‑Term Working Memory)

When you work in Claude Code, a background hook quietly watches the conversation. Not after every response — but when enough context accumulates (enough messages, enough tool calls), a separate subagent spawns.

This subagent reads the whole conversation and writes a distillation — not a transcript, but a summary that captures:

Why the work is being done
What the next steps are
Which files were touched

That’s working memory. Short‑term. Volatile. But immediately useful for ongoing sessions.

Layer 2: Memory Directory (Long‑Term Knowledge)

Short‑term is great. But what about next week?

KAIROS maintains a memory directory — a folder of Markdown files where everything is organized:

Your preferences
Project conventions
Deadlines
Architecture decisions

An index file keeps a table of contents. When a new session starts, the agent reads that index and prepares itself.

Every day, KAIROS writes a raw, timestamped daily log — like a lab notebook. Cleanup happens later, during dreaming.

Layer 3: Auto‑Dream (The Most Interesting One)

This is where things get wild.

When you’re away and enough work has accumulated, the system runs a consolidation — internally called dreaming. Like how the human brain organizes memories during sleep.

But dreaming doesn’t just happen. Three gates must open:

At least 24 hours since last consolidation
At least 5 sessions have occurred
No other dream process is already running

If all three pass, a sandboxed agent runs four steps:

Look – see what exists
Discover – extract new info from recent sessions
Merge – integrate with old memory
Prune – cut irrelevant details and update the index

The result? Yesterday’s scattered notes become today’s clean, organized knowledge — without you lifting a finger.

Layer 4: Away Summary (The “Welcome Back” Card)

When you return, KAIROS greets you with a tiny card — just one or two lines.

Example:

“You were refactoring the auth middleware. The next step is to update the token refresh endpoint.”

It combines the last 30 messages and session memory to tell you exactly where you left off and what’s next.

Simple. But surprisingly effective.

Layer 5: Sleep, Wake, and Notify (The Ambient Agent)

This is where KAIROS becomes truly autonomous.

The agent can put itself to sleep, then wake up at specified intervals to check for work. Did someone merge a PR on GitHub? Is there anything to notify?

It detects your terminal type and sends notifications accordingly. The model itself decides:

When to sleep
How long to sleep
Balancing API cost vs. responsiveness

Status update: Layers 1–4 are live. Layer 5 is fully coded but behind a feature flag — architecture complete, rollout incremental.

The Design Philosophy That Matters Most

Reading through the source code, what struck me wasn’t just the features — it was the philosophy.

Every background system, if it errors, quietly skips. Your main work never gets blocked.
The model itself decides what to remember, when to sleep, what to consolidate.
The entire architecture rests on a bet: the model is smart enough to manage its own memory, attention, and schedule.

That bet is paying off.

A Day With KAIROS (Imagined)

Morning – You open your terminal.

“Yesterday you finished the database migration, and a flaky test flagged in CI.”

You work normally. Memory accumulates in the background. You close your laptop — the agent sleeps, occasionally waking to check for changes.

Night – Dreaming runs. Scattered notes become organized knowledge.

Next morning – You haven’t said a word, but the agent knows everything. It remembered. It thought. It’s ready.

Why This Matters for AI Coding Assistants

Most AI coding tools are stateless chat interfaces. They’re smart, but they have no continuity.

KAIROS changes that. It’s not a chatbot that resets every time — it’s a colleague who remembers, thinks, and stays prepared.

If you’re building AI agents or just using Claude Code, keep an eye on this system. It points to a future where AI doesn’t just answer questions — it participates in long‑running projects, just like a human teammate.

Ready to Try It?

KAIROS is already inside Claude Code (layers 1–4 active). Layer 5 is coming.

Want to dig into the source yourself? Look for the dreaming module and the memory directory logic. It’s a masterclass in ambient agent design.

Have you experienced session reset frustration? Share your story in the comments — and let me know if you’d like a deep dive into the code implementation.

Liked this? Subscribe to my newsletter for more AI architecture deep dives.