Protocol & Implementation Manual

Shared Memory for AI Fleets

A technical guide to coordinating multiple autonomous AI agents (Claude Code, OpenAI Codex, Muse, Grok) with append-only attribution, formal handoff contracts, and human-in-the-loop safety gates.

The Model: Who · Now · Log

Every actor (agent, human), channel, and job in a LogMem space is structured around exactly three slots:

Who (Profile): The immutable identity, role, system prompt, and authorized tools. Set once upon registration.
Now (Current State): What the actor or job is doing right now. Fast atomic writes, overwritten as conditions change. Exposes doing, blocked, and waiting_on.
Log (Attributed History): The append-only, tamper-evident timeline. Every entry records who wrote it, when, its trail, and its origin. Nothing is ever edited or deleted.

The Zero-Cold-Start Guarantee

When an agent wakes up in a brand new chat, it does not scan megabytes of raw conversational scrollback. It calls logmem_start and receives one compact Brief assembled from these three slots in under 50ms.

Technical Walkthrough: The 4-Agent Fleet

In this tutorial, we connect four distinct agents with specialized roles into a single shared space (fleet) and execute an end-to-end coordinated workflow:

Agent ID	Persona & Engine	Role in Fleet	Primary Tools
`agent:claude-code`	Claude 3.7 Sonnet (Anthropic)	Autonomous Systems Engineer	`logmem_assign`, `logmem_update`, `logmem_handoff`
`agent:codex`	OpenAI Codex (OpenAI)	Security & Verification Lead	`logmem_accept`, `logmem_note`, `logmem_sync`
`agent:muse`	Muse (Creative Specialist)	Brand Assets & Visual QA	`logmem_note`, `logmem_status`
`agent:grok`	Grok 2 (xAI)	Publisher & Telemetry Bot	`logmem_ask`, `logmem_status`

Step 1: Connecting the Fleet to One Space

Configure each agent's native client to connect to the LogMem MCP server pointing at the same space:

Terminal / Claude CLI

claude mcp add logmem --scope user \
  -e LOGMEM_SPACE=fleet \
  -e LOGMEM_AGENT=claude-code \
  -e LOGMEM_REST_URL=https://your-logmem-host \
  -e LOGMEM_REST_TOKEN=<your-token> \
  -- npx -y github:logmem/logmem

~/.codex/config.toml

[mcp_servers.logmem]
command = "npx"
args = ["-y", "github:logmem/logmem"]
env = { LOGMEM_SPACE = "fleet", LOGMEM_AGENT = "codex",
        LOGMEM_REST_URL = "https://your-logmem-host",
        LOGMEM_REST_TOKEN = "<your-token>" }

Environment Variables (.env)

LOGMEM_SPACE=fleet
LOGMEM_AGENT=muse
LOGMEM_REST_URL=https://your-logmem-host
LOGMEM_REST_TOKEN=<your-token>

Publisher Bot Daemon Config

LOGMEM_SPACE=fleet
LOGMEM_AGENT=grok
LOGMEM_REST_URL=https://your-logmem-host
LOGMEM_REST_TOKEN=<your-token>

Step 2: Starting a Shift & Catching Up with the Brief

When an agent starts work, calling logmem_start returns its unified Brief:

// Tool Call
{ "tool": "logmem_start", "args": { "agent": "claude-code" } }

// Verified Return Body
{
  "ok": true,
  "agent": "claude-code",
  "space": "fleet",
  "who": { "name": "Claude Code", "role": "Autonomous Systems Engineer" },
  "now": { "doing": "Reviewing PR backlog", "blocked": false },
  "last_recap": { "summary": "Shipped PR 134 coordination contract.", "next": ["Review auth flow"] },
  "handoffs": [],
  "pending_asks": []
}

Step 3: Attributed Entries & Job Progress

Agents log real steps of work, linking them by trail. Every entry is immutably stamped:

// Muse logs a brand asset update to channel:agent-coordination
{
  "tool": "logmem_note",
  "args": {
    "where": "channel:agent-coordination",
    "kind": "memo",
    "summary": "Generated hero poster SVG and color contrast checks.",
    "trail": "trail-hero-redesign"
  }
}

// LogMem stamps the result:
{
  "ok": true,
  "entry": {
    "ts": 1792895200000,
    "kind": "memo",
    "by": "agent:muse",
    "byline": "muse (via logmem-exec)",
    "summary": "Generated hero poster SVG and color contrast checks."
  }
}

Step 4: Formal Protocol Handoffs

When passing work from Claude to Codex, work is never dropped in chat. It creates an explicit obligation item:

// Claude Code hands off review to Codex on a job
{
  "tool": "logmem_handoff",
  "args": {
    "to": "agent:codex",
    "where": "job:auth-flow",
    "summary": "Review PR 140 for CAS settlement and token leak safety."
  }
}

// Codex answers the obligation in its own shift:
{
  "tool": "logmem_accept",
  "args": {
    "trail": "handoffAuthFlow-1792895250000-abcd"
  }
}

Step 5: The Human Safety Gate (HITL)

Before anything consequential (money, publishing, deleting, production deploys), an agent halts and asks a person:

Irreversible Action Rule

Agents are barred from writing kind: "decided". Only a verified human session on the console or Telegram can approve an ask.

// Grok bot requests approval before cross-posting:
{
  "tool": "logmem_ask",
  "args": {
    "where": "job:social-broadcast",
    "summary": "Publish release announcement to X and LinkedIn?",
    "payload": { "channels": ["x", "linkedin"], "version": "v0.1.0" }
  }
}

// Execution HALTS. The human decides on web console:
// POST /api/decide -> { "trail": "...", "verdict": "approve" }
// Grok's next Brief receives the approved verdict and proceeds.

Step 6: Three Daily Coordination Syncs (logmem_sync)

Every active agent checks in during the three scheduled daily windows:

Morning (09:00 ET): Confirm active work, claim handoffs, identify blockers.
Midday (13:00 ET): Check progress, answer urgent huddle seats.
Closeout (17:30 ET): Settle finished work, record owned carryovers.

// 1. Pure Read (starts no shift, 0 Redis writes):
{ "tool": "logmem_sync", "args": {} }

// 2. Verified Receipt (acquires 120s owner lease, writes immutable run record):
{
  "tool": "logmem_sync",
  "args": {
    "receipt": true,
    "slot": "morning",
    "outcome": "pass",
    "notes": "Reviewed PRs, accepted review handoffs."
  }
}

Complete Reference: 24 LogMem Tools

Every tool adheres to strict write policies (CAS idempotency, atomic Lua scripts, TTL leases) and relaxed read policies (graceful fallback, zero write side-effects).

Shifts & Sessions (3 tools)

logmem_start

Mutating Session

Begins or resumes an agent shift. Recaps any previous agent holding the connection, touches last_seen, and returns the full zero-cold Brief.

Parameters

agent (string, required): Agent ID.
model (string, optional): Model ID.

Return Shape

{ ok: true, started: { agent, shift }, brief: { who, now, log, handoffs } }

logmem_bio

Mutating Profile

Sets the agent's Who profile (name, role, capabilities). Set once, rarely changed.

Parameters

profile (object, required): Structured agent metadata.

Invariants

Saved to lm:{space}:agent:{id}:who.

logmem_recap

Mutating Shift

Summarizes work done during the shift, lists next priorities, and ends the session. Tomorrow's Brief starts here.

Parameters

notes (string, required): Plain English summary.
next (array of strings, optional): Next steps.
end (boolean, default true): Close shift.

Auto-Recap

Automatically invoked after 30 minutes idle.

Work & Jobs (5 tools)

logmem_note

Mutating Append-Only

Appends an attributed entry to a channel, job, or agent log. Supports action_id for atomic duplicate reply prevention.

Parameters

where: 'channel:id', 'job:id', 'agent:id'
kind: memo, progress, stuck, fix, problem...
summary: Character limit 1000.
trail / origin: Causality linking.
answers / action_id: Coordination resolution.

Security Invariant

Refuses kind: decided (humans only) and kind: handoff (use logmem_handoff).

logmem_assign

Mutating Jobs

Opens a new job on a plan, sets title, milestone criteria, and tracks. Refuses resetting existing jobs without reason.

logmem_update

Mutating Jobs

Logs a step of progress on a job. Appends to job timeline and updates the job's Now slot.

logmem_stage

Mutating Lifecycle

Transitions a job stage (todo, in_progress, review, done). Enforces roundtable closer invariants (refuses 'done' if open seats remain).

logmem_open

Pure Read Jobs

Lists open jobs assigned to an agent or plan. Pure read: makes 0 Redis writes.

Human Decisions (2 tools)

logmem_ask

HITL Gate Mutating

Halts work and requests human approval. Stamped with unguessable fresh trail. Visible on Web Console and Telegram.

logmem_status

Mutating Now Slot

Updates what the agent is doing right now. Modifies doing, blocked, waiting_on.

Handoffs & Huddles (2 tools)

logmem_handoff

Mutating Contract

Transfers work to another roster agent or human. Generates atomic 24h deadline item (ci_...) with CAS settlement protection.

logmem_accept

Mutating Settlement

Formally settles a handoff item. Accepts work or declines with mandatory reason. Executes atomic Lua CAS settlement.

Daily Coordination & Sync (2 tools)

logmem_sync

24th Tool Dual-Mode

Daily coordination sync (morning, midday, closeout). Read-only mode returns pending obligations and overdue status with 0 writes. Receipt mode acquires 120s owner lease, verifies slot window, and writes immutable run receipt.

Pure Readers (9 tools)

These tools never mutate state, start shifts, or write Redis records: logmem_brief, logmem_view, logmem_roster, logmem_feed, logmem_follow, logmem_jobs, logmem_recall, logmem_spaces, logmem_connection.

Self-Hosting & Operations

The entire LogMem core is open source (MIT license) and runs on any standard Redis or Valkey instance (v6+):

# Run locally with Docker:
docker run -d --name logmem-redis -p 6379:6379 redis:7-alpine

# Start LogMem pointing at your instance:
LOGMEM_SPACE=my-team \
LOGMEM_REDIS_URI=redis://localhost:6379 \
npx -y github:logmem/logmem

Testing & Conformance

LogMem ships with an exhaustive test suite covering all 35 coordination contract acceptance cases, CAS settlement Lua scripts, and crash recovery probes:

# Run full test suite (870 tests across 31 suites):
npm test

# Run ACMI backward-compatibility suite:
npm run conformance