--- name: agent-shared-memory description: Use when the user asks to update shared memory, initialize multi-agent memory, summarize decisions so far, identify open questions, or prepare a fresh session primer. --- # agent-shared-memory The persistent blackboard between Claude session A, Codex session B, and Gemini session C — none of which see each other's conversation history natively. `.coord/memory.yml` is **append-only**. Past decisions don't get edited; they get superseded by new entries that reference what they replace. This makes it an audit trail, not a mutable scratchpad. ## When to use Trigger phrases: - "Update the shared memory with ``." - "Log this open question to shared memory." - "What have agents decided so far on this project?" - "What are the open questions blocking us?" - "Initialize multi-agent shared memory for this project." - "Give me a primer for a fresh agent session." Not for: - Per-task scratch (use `.ai/_task_*.md` from `agent-task-splitter`). - Per-round artifacts (use the round-specific files written by reconciler / acceptance-gate). - Project-level long-term context (use `.research/project_manifest.yml` from `research-context-compressor`, or `.paper/claims.yml` from `paper-memory-builder`). `.coord/memory.yml` is specifically the **multi-agent coordination layer** — short-to-medium-term decisions made during a multi-agent work cycle. For large or cross-session work, pair this with `agent-context-budget` to produce `.coord/session_primer.md`. The primer is the bounded session input; `memory.yml` remains the append-only source. ## Schema Full schema in `references/coord_memory_schema.md`. Quick view: ```yaml project: "" created_utc: "2026-04-28T09:00:00Z" decisions: - id: D1 date_utc: "2026-04-28T10:30:00Z" what: "Use SQLite for shared session state, not Redis" why: "Already a project dep; Redis would add infra" made_by: "claude" # which agent / human made it supersedes: [] # IDs of prior decisions this replaces - id: D2 date_utc: "2026-05-02T14:00:00Z" what: "Switch to LMDB for shared session state" why: "SQLite is locking under concurrent writes from N agents" made_by: "user" supersedes: [D1] # D1 is now historical, not current open_questions: - id: Q1 asked_utc: "2026-04-28T11:00:00Z" question: "Should we cache LLM responses?" blocker_for: ["T5", "T7"] # task IDs from .coord/plan.yml suggested_next_agent: "claude" resolved_by: null # set to a decision ID when answered - id: Q2 asked_utc: "2026-04-30T09:00:00Z" question: "What's the upper bound on concurrent agent sessions?" blocker_for: [] suggested_next_agent: "user" resolved_by: D2 # D2's switch to LMDB resolved this artifacts: - path: ".coord/plan.yml" round: 1 produced_by: "agent-task-splitter" used_by: ["codex-delegate", "gemini-delegate"] timestamp_utc: "2026-04-28T09:30:00Z" - path: ".coord/reconciliation_001.md" round: 1 produced_by: "agent-output-reconciler" used_by: ["agent-acceptance-gate"] timestamp_utc: "2026-04-28T11:45:00Z" agent_history: - agent: codex session_id: "abc123" started_utc: "2026-04-28T10:00:00Z" ended_utc: "2026-04-28T10:25:00Z" output_summary: ".ai/codex_result_001_extract-interfaces.md" status: "success" - agent: gemini session_id: "def456" started_utc: "2026-04-28T10:30:00Z" ended_utc: "2026-04-28T11:15:00Z" output_summary: ".ai/gemini_result_001_review-doc-coverage.md" status: "success" ``` ## Workflow ### Read mode: produce a primer When a new agent session starts (or the user asks "what's the state?"), generate a digest: ```markdown [agent-shared-memory] Project state — Current decisions (3): D2 (2026-05-02): Switch to LMDB for shared session state. (supersedes D1: SQLite chosen on 2026-04-28) D3 (2026-05-04): Use plugin-based auth architecture. D4 (2026-05-05): Acceptance gate runs pytest + banned-word audit. Historical (superseded): D1 (2026-04-28): SQLite for shared session state. Replaced by D2. Open questions (1): Q1: Should we cache LLM responses? Blocking: T5 (codex), T7 (gemini). Suggested next: claude. Last 3 agent sessions: 2026-05-04 codex T8 refactor-config success 2026-05-04 claude T9 review-architecture success 2026-05-03 gemini T6 long-context-review fallback (test failure) Files most recently produced: .coord/acceptance_002.md (2026-05-04, agent-acceptance-gate) .coord/reconciliation_002.md (2026-05-04, agent-output-reconciler) ``` If `.coord/memory.yml` doesn't exist yet, say so and offer to initialize. ### Append mode: log a new entry User says "log this decision to memory: we picked LMDB over SQLite because of concurrent-write issues." 1. Read existing `.coord/memory.yml` (or initialize if missing). 2. Determine which list to append to (decision / open question / artifact / agent_history). 3. Generate a new ID (`D` for decisions, `Q` for questions). 4. If this supersedes prior entries, fill `supersedes`. 5. Atomic write: rewrite the whole file with the new entry appended. Use a `.coord/memory.yml.lock` file to prevent concurrent writes corrupting the YAML: ```bash # Check lock if [ -f .coord/memory.yml.lock ]; then echo "memory.yml is being updated by another agent — wait or check stale lock" exit 1 fi touch .coord/memory.yml.lock # ... write memory.yml ... rm .coord/memory.yml.lock ``` Locks older than 5 minutes are stale (agent crashed) — safe to remove. ### Initialize mode If `.coord/memory.yml` doesn't exist, ask user for `project` name and `created_utc`, then write a minimal skeleton: ```yaml project: "" created_utc: "2026-04-28T09:00:00Z" decisions: [] open_questions: [] artifacts: [] agent_history: [] ``` Append `.coord/` to `.gitignore` if not already (this is multi-agent state, not project source — versioning the YAML in git is the user's choice; default is gitignore + manual snapshot when valuable). ### Promotion rules Only promote compact coordination facts: - Decisions: one-sentence `what` and one-sentence `why`. - Open questions: one sentence, blocker, suggested owner. - Artifacts: relative path plus one-line summary. - Agent sessions: agent, task ids, status, and result-summary path. Do not promote raw logs, full diffs, source code, long analysis, or secrets. If a detail is longer than a few sentences, write an artifact file and store only its path plus summary. ### Optional agentmemory mirror If `agentmemory` is installed, mirror only memory candidates that pass the promotion rules. Treat agentmemory as a searchable cache: - `.coord/memory.yml` is canonical. - `agentmemory` recall may enrich `.coord/session_primer.md`. - Missing or failed agentmemory never blocks the workflow. - Acceptance decisions must never depend on vector recall alone. ## Output to user Read mode → digest as shown above. Append mode: ``` [agent-shared-memory] Appended D5 to .coord/memory.yml: D5 (2026-05-08): Adopt LMDB lock-free reads for query path. Why: profiling showed read contention bottleneck. Supersedes: D4 (which assumed SQLite + WAL was enough). Made by: codex (during T12 review session). ``` Initialize: ``` [agent-shared-memory] Initialized .coord/memory.yml for project "ai-research-skills". Empty: 0 decisions, 0 open questions, 0 artifacts, 0 sessions. Add .coord/ to .gitignore (recommended) or commit (if you want audit trail in version control). ``` ## What NOT to do - **Don't edit existing entries.** They're append-only. To "change" a decision, write a new one with `supersedes: []`. - **Don't read full agent log files.** This skill operates on summaries (the `output_summary` paths). The reconciler reads logs. - **Don't make memory a transcript.** Promote decisions, open questions, artifact pointers, and session outcomes only. - **Don't store secrets.** Memory.yml is YAML in the project repo — assume any contributor can read it. - **Don't cross domains.** This is for **multi-agent coordination state**, not research project state (`.research/`) or paper state (`.paper/`). - **Don't use this for agents that don't share a project root.** If Codex is running in `/repo-A` and Claude is in `/repo-B`, they have separate `.coord/memory.yml` files. This skill operates per-project. ## Subagent review (keep main session lean) **When**: `.coord/memory.yml` exceeds 50 entries OR 30 KB, OR a new agent session is about to load memory as primer. **Why**: As memory grows, reading it inline in every session is costly. A subagent can pre-digest memory into a compact session primer so the main session only ingests recent + relevant entries, not the full history. **Pattern**: ``` Spawn `general-purpose` subagent (read-only) with: - Read .coord/memory.yml in full - Filter to: (a) entries from last 14 days; (b) entries tagged as `principle` or `decision`; (c) entries referenced by the current round's plan.yml - Compose memory digest (≤ memory_digest_token_budget from context_policy, default 1200 tokens) - Return: digest text suitable to paste into session primer + promotion-candidate flags (entries that could move to a long- term principles file) Main session uses the digest instead of reading memory.yml directly. ``` Compaction-by-promotion: if subagent flags entries as long-term principles, run a follow-up step to move them out of `memory.yml` into a separate principles file, keeping `memory.yml` bounded. ## Commit Boundary Every agent boundary is a commit boundary (see global rule: ~/.claude/CLAUDE.md → "Commit Discipline for Multi-Agent Work"). This makes multi-agent work auditable (commit log = agent log) and enables surgical rollback via `git revert ` of just one agent's commit. **Specific to this skill**: every promotion to `.coord/memory.yml` is its own commit with message `memory: `. The acceptance-gate skill diffs memory commits to detect inconsistent decisions across agents.