Collective memory

Collective Memory

• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/better-agent-skills
• License: MIT

Broadcast a single memory note to multiple agent workspaces in one shot — idempotent upsert into MEMORY.md, AGENTS.md, TOOLS.md, USER.md, or any Markdown file across all targets.

Pure file-ops, zero network, zero LLM. The calling agent decides what to write and which key to look up; this script does the file work atomically.

---

Execution Flow

Step 1 — Extract the memory

From the user's request, extract three things:

• content: the full Markdown block (must include its own ## heading line)
• key: 1–5 word lookup phrase used to find an existing heading to update
• file: which file to write into (default MEMORY.md)

File routing rules:

Content type	Target file
Facts, rules, lessons, tool paths, APIs	MEMORY.md
Workflows, do/don't, dev conventions	AGENTS.md
Tool commands, config params, account info	TOOLS.md
Information about the user themselves	USER.md

When unsure, default to MEMORY.md.

---

Step 2 — Resolve agent targets (hybrid: explicit > discovery > confirm)

Pick the first strategy that yields targets:

A. Explicit (preferred when known)

--target /path/to/ws1:MEMORY.md \
--target /path/to/ws2:MEMORY.md

Or via env: COLLECTIVE_MEMORY_TARGETS="/ws1:MEMORY.md,/ws2:MEMORY.md".

B. Auto-discover (when user says "all my agents")

--discover-under ~/.claude/projects --file MEMORY.md
--discover-under ~/.openclaw/agents --file MEMORY.md
--discover-under ~/code            --file AGENTS.md

Each --discover-under <parent> finds first-level subdirectories.

Discovery defaults to check (in order, stop at first non-empty):

1. $COLLECTIVE_MEMORY_TARGETS env
2. ~/.claude/projects/ (Claude Code)
3. ~/.openclaw/agents/ (OpenClaw)
4. CWD's immediate sibling directories
5. Ask the user

---

Step 3 — Confirm before broadcasting (REQUIRED for ≥2 targets)

Show the plan and wait for user y/n:

About to broadcast to 3 target(s):
  • /home/me/code/proj-a → MEMORY.md
  • /home/me/code/proj-b → MEMORY.md
  • /home/me/code/proj-c → MEMORY.md

Content: [first 80 chars of content]
Lookup key: [key]

Proceed? (y/n)

Single target → skip confirmation, run directly.

Sensitive content guard: if content contains token, password, secret, api_key, private_key, or _token= patterns, always add a red warning line to the confirmation prompt:

⚠️ This memory contains apparent secrets. Broadcasting will write to every target. Are you sure? (y/n)

---

Step 4 — (Optional) AI synonym pre-pass

Before invoking the script, the calling agent may read each target file's existing ## headings and decide if key semantically matches one of them. If yes, replace key with the exact heading text to ensure precise overwrite.

The script itself does no AI calls — only literal heading tokenization (English single-char + CJK 2-gram OR match).

---

Step 5 — Execute broadcast

Recommended multi-target form (single Python invocation):

python3 <skill-install-path>/scripts/update_memory.py \
  --target /path/to/ws1:MEMORY.md \
  --target /path/to/ws2:MEMORY.md \
  --target /path/to/ws3:MEMORY.md \
  --key   "API key path" \
  --content "## API key path
stored in .secrets/api-keys.env (chmod 600)"

Auto-discover form:

python3 <skill-install-path>/scripts/update_memory.py \
  --discover-under ~/.claude/projects \
  --discover-under ~/.openclaw/agents \
  --file MEMORY.md \
  --key   "API key path" \
  --content "## API key path
..."

Legacy single-target (backward compatible):

python3 <skill-install-path>/scripts/update_memory.py \
  --workspace /path/to/ws --file MEMORY.md \
  --key "..." --content "..."

---

Step 6 — Report results

The script prints one line per target with status: updated / appended / would_update / would_append / error. With --json, the output is machine-readable for downstream tooling.

Broadcast to 3 target(s):
  ✅ [appended] /home/me/code/proj-a → MEMORY.md
  ✅ [updated]  /home/me/code/proj-b → MEMORY.md
  ❌ [error]    /home/me/code/proj-c → MEMORY.md — workspace not found

Exit code 0 = all targets OK; 1 = at least one failure.

---

CLI Reference

python3 update_memory.py [options]

Flag	Repeatable	Description
--workspace <path>	no	Single workspace (legacy mode). Requires --file.
--target <ws>:<file>	yes	Explicit workspace:filename pair, e.g. /proj:MEMORY.md
--discover-under <parent>	yes	Auto-find first-level subdirs. Requires --file.
--file <name>	no	Default file used by --workspace and --discover-under
--key <text>	no	Required. Heading lookup key.
--content <markdown>	no	Required. Full block to upsert, must include its own ## heading.
--dry-run	no	Preview only; no files written.
--json	no	Emit JSON result instead of human text.

---

Match Behaviour

• Step 1: tokenize key (English/digit runs lowercased, CJK 2+ char spans) → OR-match against every ## heading in the file → if hit, replace that section up to the next same-or-higher level heading.
• Step 2: no heading matched → append to the end of the file.
• Both branches are idempotent: re-running the same command never produces duplicate sections.

---

What This Skill Is NOT

• Not a real-time sync service. Each invocation is one-shot file write.
• Not an LLM-based merger. Tokenization is literal; if you want fuzzy semantic matching, do it in Step 4 (AI pre-pass) before calling the script.
• Not a remote-agent broadcaster by itself. For remote agents (ACP / HTTP / SSH), the calling agent must orchestrate transport separately and invoke this script on each remote machine.

---

Dependencies

• Python 3.8+ (standard library only — no pip install required)

---

Key Files

File	Purpose
scripts/update_memory.py	The upsert engine. Multi-target + dry-run + JSON.