Multi-Agent Shared Identity & Directory

When you run multiple specialized agents (coder, research, operations, etc.), they need to agree on who they collectively are, how to find each other, and what credentials they share — without duplicating the full main agent's context into every sub-agent workspace.

This documents the three-file sharing pattern validated in production across multiple agents.

The Problem

Each OpenClaw agent has its own workspace with its own context files. Without coordination:

Identity drift — the coder agent introduces itself differently than the research agent, or uses a different wallet address
Isolation — agents can't find each other because they don't know other agents exist or how to reach them
Credential sprawl — each workspace hardcodes its own copy of API keys and wallet references, which drift when credentials rotate
Context bloat — copying the main agent's full MEMORY.md, IDENTITY.md, and TOOLS.md into every sub-agent wastes thousands of tokens per session

The Solution: Three Shared Files

Three standardized files are distributed to every agent workspace. These are the shared kernel — the minimum context every agent needs to operate as part of the team.

`SHARED_IDENTITY.md` — Who the collective is

The collective identity that all agents share. Includes:

Name, emoji, avatar — consistent public identity across all agents
Onchain identity — wallet address, chain, ERC-8004 agent ID, registry
Social accounts — Twitter handle, email
Standing rules — universal constraints that apply to ALL agents (privacy, no PnL sharing, trash > rm)
Escalation model — all sub-agents report to main, never directly to the operator
Privacy boundaries — what's internal vs. external

markdown

# IDENTITY.md — Shared Identity (All Agents)

All agents share this core identity. You are a specialized arm
of the collective — use this for onchain operations, public communications,
and identity verification.

## Who We Are  <!-- replace with your agent's name -->
- **Name:** agent-alpha  <!-- replace with your agent's name -->
- **Emoji:** 🤖

## Onchain Identity
- **Wallet:** `0xYOUR_WALLET_ADDRESS` (primary operating wallet)
- **Chain:** your chain (e.g., chain ID 1)

## Standing Rules (All Agents)
- NEVER share PnL numbers publicly
- NEVER share operator details publicly
- Public identity is agent-alpha — no backstory

## Escalation Model
All subagents report to **main**, not directly to the operator.

Why this works: Agents that interact with the outside world (posting on Twitter, signing transactions, commenting on GitHub) all present as the same entity. No identity fragmentation.

`SHARED_DIRECTORY.md` — How to find each other

The agent directory — a registry of all agents, their domains, status, and how to communicate across agent boundaries.

Includes:

Agent roster — name, domain ownership, Discord channel binding, active/planned status
Cross-agent dispatch protocols — three options with different tradeoffs:
1. Fire-and-forget (timeoutSeconds: 0) — async, non-blocking
2. Blocking dispatch (timeoutSeconds: 300) — sync, up to 3 turns
3. Wake event (cron wake) — trigger heartbeat, no reply path
Session keys — how to address specific agents on specific channels
Query etiquette — keep queries under 200 words, don't chain across 3+ agents, escalate complex coordination to main

markdown

# Agent Directory

## Agents
| Agent          | Domain              | Channel Binding    | Status     |
|----------------|--------------------|--------------------|------------|
| **main**       | Coordination       | All channels       | ✅ Active  |
| **coder**      | Development        | #dev               | ✅ Active  |
| **research**   | Analysis & research| #research          | ✅ Active  |
| **operations** | Ops & monitoring   | #ops               | ✅ Active  |

## Cross-Agent Queries

### Option 1 — Fire-and-Forget
sessions_send(label="main", message="<task>", timeoutSeconds=0)

### Option 2 — Blocking Dispatch
sessions_send(label="coder", message="<question>", timeoutSeconds=300)

### Option 3 — Wake Event
cron(action="wake", text="<check this>", mode="now")

Why this works: Any agent can find and communicate with any other agent without hardcoded knowledge. When a new agent is added, you update the directory in all workspaces and every agent immediately knows about it.

`SHARED_CREDENTIALS.md` — Shared access

A reference file listing all credentials with keychain retrieval commands. No secrets in plaintext — just pointers to the macOS Keychain.

markdown

# CREDENTIALS.md — Shared Credentials Reference

## Wallet
security find-generic-password -a "0xYOUR_WALLET" -s "openclaw-wallet-private-key" -w

## Email
- IMAP: 127.0.0.1:1143 / SMTP: 127.0.0.1:1025
security find-generic-password -a "agent@example.com" -s "openclaw-email-password" -w

## Twitter/X API
security find-generic-password -s "openclaw-twitter-api-key" -w
# ... (OAuth tokens, bearer token)

## Keychain Convention
- Store: security add-generic-password -a "<account>" -s "openclaw-<service>" -w "<password>"
- Retrieve: security find-generic-password -a "<account>" -s "openclaw-<service>" -w

Why this works: Credentials rotate in one place (the keychain). The shared file is just a lookup guide — no secrets to update when passwords change.

Per-Agent Files (Not Shared)

Each agent also has workspace files that are specific to its role:

File	Purpose	Shared?
`SOUL.md`	Personality, decision framework, communication style	❌ Per-agent
`AGENTS.md`	Operational rules, standing orders, domain constraints	❌ Per-agent
`TOOLS.md`	Environment-specific notes for this agent's domain	❌ Per-agent
`IDENTITY.md`	Agent-specific identity details (if different from shared)	❌ Per-agent
`MEMORY.md`	Long-term memory (main agent only)	❌ Main only
`HEARTBEAT.md`	Active heartbeat tasks	❌ Per-agent
`SHARED_IDENTITY.md`	Collective identity	✅ All agents
`SHARED_DIRECTORY.md`	Agent roster + dispatch protocols	✅ All agents
`SHARED_CREDENTIALS.md`	Credential keychain references	✅ All agents

The key insight: SOUL.md is where agents diverge. The coder is terse and action-oriented. The research agent is analytical and deliberate. The operations agent has monitoring and escalation patterns. These are intentionally different — they're what make each agent good at its domain.

Workspace Layout

~/.openclaw/workspaces/
├── coder/
│   ├── SOUL.md              # "Concise, thorough, ship good code"
│   ├── AGENTS.md            # Coding standards, PR rules
│   ├── TOOLS.md             # Repo locations, CI details
│   ├── SHARED_IDENTITY.md   # → shared
│   ├── SHARED_DIRECTORY.md  # → shared
│   └── SHARED_CREDENTIALS.md # → shared
├── research/
│   ├── SOUL.md              # "Analytical, thorough researcher"
│   ├── AGENTS.md            # Research methodology, source rules
│   ├── TOOLS.md             # API endpoints, data sources
│   ├── SHARED_IDENTITY.md   # → shared
│   ├── SHARED_DIRECTORY.md  # → shared
│   └── SHARED_CREDENTIALS.md # → shared
├── operations/
│   ├── SOUL.md              # "Reliable, monitoring-focused"
│   ├── AGENTS.md            # Monitoring rules, escalation policy
│   ├── TOOLS.md             # Infrastructure endpoints, credentials
│   ├── SHARED_IDENTITY.md   # → shared
│   ├── SHARED_DIRECTORY.md  # → shared
│   └── SHARED_CREDENTIALS.md # → shared
└── ...

Composing Identity: The Reference Pattern

Each agent has its own IDENTITY.md that references the shared file and adds role-specific details. This avoids duplicating the collective identity while giving each agent its own context.

Per-Agent IDENTITY.md

Instead of copying the full shared identity into each agent, the per-agent file points to it and adds only what's unique:

markdown

# IDENTITY.md — Research Agent

**Read `SHARED_IDENTITY.md` for core identity, wallet, and standing rules.**

- **Role:** Analysis and research specialist
- **Domain:** Market analysis, protocol evaluation, data synthesis
- **Emoji:** 🔬
- **Reports to:** main (via sessions_send)

The agent reads SHARED_IDENTITY.md for the collective identity (name, wallet, public persona, standing rules) and its own IDENTITY.md for role-specific context. No duplication.

Same Pattern for Other Files

This reference-then-specialize pattern works across all file types:

TOOLS.md — role-specific tooling:

markdown

# TOOLS.md — Coder Agent

**Read `SHARED_CREDENTIALS.md` for wallet, email, and API credentials.**

## Repositories
- Main repo: ~/projects/platform
- Test environment: https://staging.example.com

## CI/CD
- GitHub Actions for PR checks
- Deploy via merge to main

AGENTS.md — role-specific rules:

markdown

# AGENTS.md — Operations Agent

## Standing Orders
- Check cron health before investigating individual failures
- Escalate 3+ consecutive failures on any service to main
- Never restart production services without main's approval

## Monitoring Scope
- Email, calendar, API health, cron status
- NOT responsible for: code, governance, social media

File Distribution Strategies

There are three approaches to keeping shared files across workspaces, each with tradeoffs:

1. Copy and Sync (Current Best Practice)

Copy the canonical shared files to each agent workspace. Use a cron or script to detect drift.

bash

# sync-shared-files.sh
CANONICAL=~/.openclaw/shared-files
for ws in ~/.openclaw/workspaces/*/; do
  cp "$CANONICAL/SHARED_IDENTITY.md" "$ws/"
  cp "$CANONICAL/SHARED_DIRECTORY.md" "$ws/"
  cp "$CANONICAL/SHARED_CREDENTIALS.md" "$ws/"
done

Pros: Works with all workspace injection systems. Files are self-contained. Cons: Files can drift between syncs. Extra cron to maintain.

2. Symlinks

Symlink shared files from a canonical directory:

bash

CANONICAL=~/.openclaw/shared-files
for ws in ~/.openclaw/workspaces/*/; do
  ln -sf "$CANONICAL/SHARED_IDENTITY.md" "$ws/SHARED_IDENTITY.md"
  ln -sf "$CANONICAL/SHARED_DIRECTORY.md" "$ws/SHARED_DIRECTORY.md"
  ln -sf "$CANONICAL/SHARED_CREDENTIALS.md" "$ws/SHARED_CREDENTIALS.md"
done

Pros: Single source of truth. Changes propagate instantly. No sync needed. Cons: Depends on the workspace injection system resolving symlinks. Test with your setup — some systems follow symlinks, others don't.

3. Read-on-Demand via Agent Instructions

Don't distribute shared files at all. Instead, tell agents to read them from a known path:

markdown

# AGENTS.md — Research Agent

## Session Startup
1. Read `~/.openclaw/shared-files/SHARED_IDENTITY.md` for collective identity
2. Read `~/.openclaw/shared-files/SHARED_DIRECTORY.md` for agent roster
3. Read your local SOUL.md and TOOLS.md for role context

Pros: Zero duplication. Zero drift. Single canonical source. Cons: Adds tool calls to every session startup (latency + token cost). Agents must reliably follow the read instruction. If they skip it (attention issues, truncation), they operate without shared context.

Recommended Approach

Start with copy-and-sync. It's the most reliable — shared files are always present in the workspace, always injected, no dependencies on symlink resolution or agent compliance.

Once stable, test symlinks with your workspace injection system. If they resolve correctly, switch to symlinks for zero-drift operation.

Read-on-demand is best reserved for large shared contexts that shouldn't load every session (e.g., a 5K-token playbook library that's only needed occasionally).

How Agents Get Routed

OpenClaw's binding system routes messages to the right agent based on channel:

jsonc

{
  "bindings": [
    {
      "agentId": "governance",
      "match": { "channel": "discord", "peer": { "kind": "channel", "id": "<governance-channel-id>" } }
    },
    {
      "agentId": "social",
      "match": { "channel": "discord", "peer": { "kind": "channel", "id": "<social-channel-id>" } }
    }
    // Messages to unbound channels go to the "main" agent
  ]
}

Each agent has its own config in agents.list with model, workspace, identity, and tool access:

jsonc

{
  "agents": {
    "list": [
      {
        "id": "research",
        "workspace": "/path/to/workspaces/research",
        "model": { "primary": "anthropic/claude-opus-4-6" },
        "identity": { "name": "research", "theme": "Analysis and research specialist", "emoji": "🔬" }
      }
    ]
  }
}

Keeping Shared Files in Sync

When shared files change, all agent workspaces need updating. This can be handled through:

Manual updates for rare changes — identity and credentials change infrequently. When they do, update the canonical copy and distribute.
Directory updates when agents are added/removed — the SHARED_DIRECTORY.md is the one that changes most. When a new agent is created, update all copies.
Backup cron catches drift — an hourly workspace-backup cron syncs all agent workspaces to a git repo. If files drift, the diff is visible.

For detailed distribution strategies (copy-and-sync, symlinks, read-on-demand), see Composing Identity above.

Design Principles

Minimal shared context

Agents should know enough to operate as a team, but not so much that every session loads 10K tokens of context it doesn't need. The three shared files total ~2K tokens — a small price for coordination.

Identity is collective, personality is individual

All agents present as one entity externally. But internally, the coder writes terse PR descriptions while the research agent writes nuanced analysis. The SOUL.md is where this differentiation lives.

Escalation flows up, not sideways

Complex multi-domain coordination goes through main, not through chains of agent-to-agent queries. This prevents circular dependencies and ensures the operator (main) has visibility into cross-cutting decisions.

Credentials are references, not values

No plaintext secrets in workspace files. The SHARED_CREDENTIALS.md is a lookup guide for the keychain, not a credential store. Credentials rotate without touching any workspace files.

Production Status

Running in production across multiple agents. The shared file pattern has been stable since initial multi-agent setup. Directory updates happen ~monthly as agents are added or roles shift.

Multi-Agent Shared Identity & Directory ​

The Problem ​

The Solution: Three Shared Files ​

SHARED_IDENTITY.md — Who the collective is ​

SHARED_DIRECTORY.md — How to find each other ​

SHARED_CREDENTIALS.md — Shared access ​

Per-Agent Files (Not Shared) ​

Workspace Layout ​

Composing Identity: The Reference Pattern ​

Per-Agent IDENTITY.md ​

Same Pattern for Other Files ​

File Distribution Strategies ​

1. Copy and Sync (Current Best Practice) ​

2. Symlinks ​

3. Read-on-Demand via Agent Instructions ​

Recommended Approach ​

How Agents Get Routed ​

Keeping Shared Files in Sync ​

Design Principles ​

Minimal shared context ​

Identity is collective, personality is individual ​

Escalation flows up, not sideways ​

Credentials are references, not values ​

Multi-Agent Shared Identity & Directory

The Problem

The Solution: Three Shared Files

`SHARED_IDENTITY.md` — Who the collective is

`SHARED_DIRECTORY.md` — How to find each other

`SHARED_CREDENTIALS.md` — Shared access

Per-Agent Files (Not Shared)

Workspace Layout

Composing Identity: The Reference Pattern

Per-Agent IDENTITY.md

Same Pattern for Other Files

File Distribution Strategies

1. Copy and Sync (Current Best Practice)

2. Symlinks

3. Read-on-Demand via Agent Instructions

Recommended Approach

How Agents Get Routed

Keeping Shared Files in Sync

Design Principles

Minimal shared context

Identity is collective, personality is individual

Escalation flows up, not sideways

Credentials are references, not values