OpenClaw + Claude Code: Building a Shared Brain Layer Between Your Coding Agent and Your Persistent Agent

The Problem Nobody Talks About

There's a tweet making the rounds this week:

> *"That shared brain setup between Claude Code and OpenClaw is exactly the vision."*

Everyone nods. Nobody explains how to actually build it.

Here's the situation: you're running OpenClaw as your persistent always-on agent — it knows your calendar, your projects, your preferences, your MEMORY.md. Then you spin up Claude Code to write some feature. Claude Code has zero context. It doesn't know what the project is, what decisions were made last week, what the current architecture looks like. Every session starts from scratch.

Meanwhile your OpenClaw agent is sitting there with all that context and no way to hand it off.

This post fixes that. We'll build a shared memory layer — a set of files and conventions — that lets Claude Code inherit context from OpenClaw, and lets OpenClaw learn from what Claude Code did.

---

The Architecture: Three Files, One Sync Script

The cleanest approach I've found is three files, synced via a small script:

```

~/projects/my-project/

├── AGENTS.md ← OpenClaw reads this, Claude Code reads this

├── CONTEXT.md ← Current sprint context, synced by OpenClaw

└── DECISIONS.md ← Architecture decisions, maintained by both

```

AGENTS.md is already a standard OpenClaw convention — it's what you put in every repo to tell agents how the project works. But if you haven't been writing it for Claude Code's consumption too, you're missing half the benefit.

CONTEXT.md is the live handoff file. OpenClaw updates it. Claude Code reads it before starting any session.

DECISIONS.md is the architectural record. Claude Code writes to it after making non-obvious choices. OpenClaw reads it to stay current on what's happening in the codebase.

---

Step 1: Write AGENTS.md for Two Audiences

Most AGENTS.md files are written for OpenClaw only. Claude Code is a different beast — it doesn't do persistent memory, doesn't read your workspace MEMORY.md, and it starts fresh every time. Your AGENTS.md needs to front-load everything Claude Code needs to function.

Here's a template that works for both:

```markdown

# AGENTS.md

Project: [Your Project Name]

Stack: Next.js 15, TypeScript, Tailwind, Convex, Bun

Deploy: Vercel (auto-deploy on push to main)

Package manager: bun — never npm/yarn/pnpm

Current State (updated by OpenClaw)

See CONTEXT.md for the current sprint context and recent decisions.

Architecture

Key Conventions

For Claude Code (read this first)

Before writing any code: read CONTEXT.md. It has the current task, recent decisions, and what was last worked on.

After any non-obvious architectural decision: append to DECISIONS.md.

For OpenClaw

Watch for updates to DECISIONS.md — sync important decisions back to MEMORY.md.

Update CONTEXT.md after each working session.

```

The "For Claude Code" section is key. It tells Claude Code explicitly what to read and what to write. Claude Code follows AGENTS.md instructions reliably — treat it like a system prompt in file form.

---

Step 2: OpenClaw Writes CONTEXT.md

Add this to your OpenClaw heartbeat or as a manual trigger. After any working session on the project, OpenClaw should update CONTEXT.md:

```markdown

# CONTEXT.md — Last updated: 2026-03-31

Current Sprint

Building the user dashboard — specifically the activity feed component.

Last Session Summary

Next Task

Wire up ActivityFeed.tsx to the /api/activity endpoint.

Add loading state and empty state UI.

Recent Decisions

Known Issues

```

This is the file Claude Code will read before touching anything. Make it surgical. Current state, next task, known gotchas. Not a history lesson.

You can have OpenClaw write this with a simple instruction in its SOUL.md or AGENTS.md:

```

After working on any project in ~/projects/, update that project's CONTEXT.md with current state.

```

Or trigger it explicitly:

```

"Sam, update CONTEXT.md for the dashboard project"

```

---

Step 3: Claude Code Writes DECISIONS.md

The other direction: Claude Code making architectural decisions that OpenClaw needs to know about.

The way to make this stick is the AGENTS.md instruction. Claude Code reads AGENTS.md at the start of every session and follows the instructions there. If you tell it to write decisions to DECISIONS.md, it will.

DECISIONS.md format:

```markdown

# DECISIONS.md

2026-03-31 — Real-time subscriptions over polling

Decision: Using Convex `useQuery` real-time subscriptions for the ActivityFeed instead of polling.

Why: Polling at 5s intervals was causing visible lag. Real-time subscriptions give instant updates with no perceptible delay.

Tradeoff: Slightly more Convex reads, but within free tier limits at current scale.

2026-03-29 — Server components with client islands

Decision: ActivityFeed is a Next.js server component. Individual activity items that need interaction (reactions, expand) are client components.

Why: Better initial load performance, SEO.

Tradeoff: More complex component tree, prop drilling for some shared state.

```

---

Step 4: OpenClaw Monitors DECISIONS.md

Now you need OpenClaw to actually pick up what Claude Code wrote. Two approaches:

Option A: Manual sync — after a Claude Code session, tell OpenClaw: "Read DECISIONS.md in the dashboard project and update your memory." Simple, works fine for occasional use.

Option B: Heartbeat sync — add this to HEARTBEAT.md:

```markdown

Project Memory Sync

```

Option B means every heartbeat cycle, OpenClaw scans for new decisions and absorbs them into its long-term memory. By the time you talk to OpenClaw about the project next, it already knows what Claude Code decided.

---

Step 5: The Full Loop in Practice

Here's what the combined workflow looks like day-to-day:

Morning standup with OpenClaw:

> "What's the status on the dashboard project?"

OpenClaw reads MEMORY.md, CONTEXT.md, DECISIONS.md → gives you a full briefing. You decide: continue the ActivityFeed wiring.

OpenClaw updates CONTEXT.md:

```markdown

Next Task

Wire up ActivityFeed.tsx to /api/activity.

Add loading state (use existing Skeleton component in /components/ui/skeleton.tsx).

```

You open Claude Code in the project:

Claude Code reads AGENTS.md → gets the stack, conventions, and instruction to read CONTEXT.md.

Claude Code reads CONTEXT.md → knows exactly what's been done and what to do next.

Claude Code writes the code. Makes a non-obvious decision about error handling.

Claude Code appends to DECISIONS.md.

Next heartbeat, OpenClaw scans DECISIONS.md:

Sees the new entry. Absorbs it. Now knows why error handling works the way it does.

Tomorrow morning:

You ask OpenClaw about the project again. It knows what Claude Code did. Full context. No gaps.

---

The Edge Cases

What if Claude Code doesn't read AGENTS.md?

It does — Claude Code processes AGENTS.md at context load time. But if you're using it in a directory without AGENTS.md, it has no instructions. Make sure every project has one.

What if CONTEXT.md gets stale?

It will, if OpenClaw doesn't update it. The heartbeat approach handles this — but you can also add a simple cron job: every night, OpenClaw checks if CONTEXT.md is older than 2 days and pings you to update it.

What about sensitive information?

Don't put credentials, tokens, or PII in CONTEXT.md or DECISIONS.md — Claude Code sessions may have different security boundaries than your OpenClaw workspace. Keep secrets in .env files, which both agents respect as off-limits for reading.

What if I work on multiple projects?

Each project gets its own AGENTS.md, CONTEXT.md, and DECISIONS.md. OpenClaw knows which project is active from its MEMORY.md ("currently focused on: dashboard project"). You can tell it to switch focus.

---

What You're Actually Building

This isn't a fancy framework. It's three markdown files and a convention.

But the result is two agents that feel like they share a brain:

The tweet was right: this is the vision. A shared brain between your coding agent and your persistent agent. You just have to build it — and now you know how.

---

Quick Start Checklist

1. Add AGENTS.md to every project you work on — write it for both audiences

2. Create CONTEXT.md — have OpenClaw update it after each working session

3. Create DECISIONS.md — tell Claude Code (via AGENTS.md) to write to it

4. Add a heartbeat task: OpenClaw scans DECISIONS.md for new entries

5. Try the loop once: morning briefing → OpenClaw updates CONTEXT.md → Claude Code session → Claude Code writes DECISIONS.md → OpenClaw absorbs

That's the whole system. No vector databases, no embeddings, no external services. Just files and two agents that know how to read them.

Full setup documented in the OpenClaw Setup Playbook.

Auch auf Deutsch verfügbar. 🇩🇪