ZMemory

Shared project memory for AI agents.

ZMemory is a lightweight coordination layer that allows multiple AI coding agents (Codex, Claude Code, OpenCode, Cursor, Kilo, Kimi, etc.) to safely collaborate inside the same repository.

It provides a shared operational memory where agents can:

• see who is working on which files
• coordinate edits
• track activity and decisions
• recover context across sessions

ZMemory stores all coordination state inside the project in a .zmemory/ folder.

Install

Requirements:

• Node.js >=20

npm install -g zmemory

Then run the interactive setup:

zmemory setup

This configures ZMemory for supported AI coding tools (Codex CLI, Claude Code, OpenCode, Cursor, Kilo Code, etc.) and optionally initializes the repository.

Initialize a Repository

Inside a project:

zmemory init

This creates:

.zmemory/
  agents/
  claims/
  logs/
  runs/
  skills/

The .zmemory directory contains all coordination state for the project.

Typical Agent Workflow

When an agent starts working in a repository:

zmemory resume

This returns:

• active agents
• open file claims
• recent activity
• current run state

Before editing files:

zmemory who <file>

When beginning work on a module:

zmemory claim src/auth/* --session <agent-session>

Record meaningful work:

zmemory event --summary "implemented auth middleware" --files src/auth/middleware.js

Release ownership when done:

zmemory release --session <agent-session>

Debugging Coordination

To understand why a file is claimed:

zmemory explain <file>

Example output:

Active claims
  src/auth/*
    codex‑a1 implement auth middleware (expires in: 7m)

Recent related activity
  executor: implementing middleware
  reviewer: reviewing middleware

Diagnostics

Check system health:

zmemory doctor

Updating

zmemory update

or

zmemory upgrade

Both install the latest version and run diagnostics.

Commands

zmemory setup
zmemory init
zmemory resume
zmemory claim
zmemory who
zmemory event
zmemory explain
zmemory doctor
zmemory update

License

MIT