Memory System

Both Zero and Zorro start fresh every session — their continuity comes entirely from files. This page explains every memory file, how they interact, and how to extend them.

Key principle: Mental notes don't survive session restarts. Files do. ZoarkBot writes aggressively to disk so context is never lost.

Memory Files

File	Agent	Purpose
memory/SESSION-LOG.md	Zero	Append-only session history. Read first at every startup.
memory/WORKING-CONTEXT.md	Zero	Live task state — updated every 5 minutes. Most important for continuity.
memory/CHECKPOINT.md	Zero	Pause/resume state when Zero is interrupted mid-task.
memory/YYYY-MM-DD.md	Zero	Daily operational log. Zero reads today's + yesterday's at startup.
MEMORY.md	Zero	Long-term strategic memory: decisions, conventions, user preferences.
memory/shared/zero-discoveries-*.md	Both	Zero's research and discoveries — shared with Zorro.
memory/shared/zorro-discoveries-*.md	Both	Zorro's task results — shared with Zero.
memory/social/content-calendar.json	Both	Scheduled social posts across all platforms.
memory/social/inbox.json	Zero	Social inbox state (DMs, mentions).
zorro/memory/task-queue.json	Zorro	Active task queue — Zorro polls this every cycle.
.learnings/LEARNINGS.md	Zero	Non-obvious solutions and error patterns.

Key Files Explained

WORKING-CONTEXT.mdMost Important

Updated by Zero every 5 minutes and after every major action. Contains current task, sub-tasks, what's blocked, next steps, and open questions. Zero reads this at startup to instantly resume where it left off.

SESSION-LOG.mdAppend-only

Every session start and end is logged here. Zero reads this first at startup to understand the full history of what happened. Do not edit manually.

MEMORY.mdLong-term

Strategic long-term memory: architectural decisions, important facts, user preferences, conventions. Zero reads this only in the main (private) session — never in group chats.

memory/shared/Cross-agent

Zero and Zorro share discoveries through this directory. Each agent reads all files here. Synced automatically at startup by scripts/memory-sync.py.

How Session Compaction Works

When a conversation grows long, the AI context window fills up. ZoarkBot handles this automatically:

Before

Zero writes current state to WORKING-CONTEXT.md, appends to SESSION-LOG.md, and updates the daily log.

During

Claude compresses the conversation. The AI loses working memory — but the files survive.

After

Zero reads memory files first (startup protocol). The files restore everything that was lost from working memory.

Force manual compaction: send sessions.compact via the gateway.

How to Add Custom Memories

Tell Zero directly

"Remember that our deploy branch is always feat/release not main"

Zero appends it to MEMORY.md under the right section automatically.

Use the memory tool

"Add to my long-term memory: staging URL is https://staging.zoarkai.com"

Zero's memory-tool reads and writes memory files on command.

Edit MEMORY.md manually

Open MEMORY.md in your home directory and add entries directly.

Zero reads this at every startup. Changes take effect immediately.

.learnings/ directory

Add entries for non-obvious solutions and recurring error patterns.

Zero consults .learnings/ when encountering similar situations.

Cross-Agent Memory (Shared)

Zero and Zorro share discoveries through memory/shared/. This is how the two agents stay in sync without directly communicating.

File pattern	Written by	Contains
zero-discoveries-YYYY-MM-DD.md	Zero	Research findings, decisions, context from the day
zorro-discoveries-YYYY-MM-DD.md	Zorro	Task results, patterns observed, research findings