shared-memory

name	shared-memory
description	Use when the user wants persistent memory, Claude and Codex repo handoff, cross-agent alignment, or to read and update shared Claude project memory files plus optional shared MCP memory state.

Shared Memory

This skill keeps Codex aligned with Claude by using two compatible memory surfaces:

1. Claude project memory files under ~/.claude/projects/<project>/memory/
2. An optional MCP memory server registered as memory in both tools

The file-based layer is the required part. The MCP layer is optional and gives you durable structured memory on top.

Start-of-task workflow

1. Resolve the repo-specific shared memory directory for the current repo:

python3 ~/.codex/skills/shared-memory/scripts/shared_memory.py locate --cwd "$PWD" --prefer-repo-root --create

2. Read the index:

sed -n '1,220p' <memory_dir>/MEMORY.md

3. Build a bounded shared-memory context pack for the task:

python3 ~/.codex/skills/shared-memory/scripts/shared_memory.py context \
  --cwd "$PWD" \
  --prefer-repo-root \
  --include-ancestor-scopes \
  repo-name feature bug-keyword

4. When you need the raw ranked note list, query it directly:

python3 ~/.codex/skills/shared-memory/scripts/shared_memory.py query \
  --cwd "$PWD" \
  --prefer-repo-root \
  --include-ancestor-scopes \
  repo-name feature bug-keyword

Open the top 1-3 note files instead of bulk-loading the entire memory directory.

5. If a shared memory MCP server is available, use it for durable recall:

• At session start or resume: get_context or recall
• After important fixes or decisions: remember

Keep MCP memory entries short, factual, and scoped to things worth reusing.

6. On first use in a repo, or when retrieval seems noisy, audit the memory surface:

python3 ~/.codex/skills/shared-memory/scripts/shared_memory.py status \
  --cwd "$PWD" \
  --prefer-repo-root \
  --include-ancestor-scopes

7. If the audit shows many notes missing repo metadata, heal the strong matches:

python3 ~/.codex/skills/shared-memory/scripts/shared_memory.py backfill-repo-metadata \
  --cwd "$PWD" \
  --prefer-repo-root \
  --include-ancestor-scopes \
  --write

End-of-task workflow

1. Update an existing note with apply_patch when continuing the same workstream.
2. Create a fresh note when the task is a new milestone, feature, audit, or handoff:

python3 ~/.codex/skills/shared-memory/scripts/shared_memory.py new-note \
  --cwd "$PWD" \
  --prefer-repo-root \
  --title "Short task title" \
  --description "One-line handoff summary" \
  --type project

3. If you create a new note, the helper script adds a concise index bullet to MEMORY.md.

Every handoff note should capture:

• What changed
• Current state
• Verification done
• Next steps or blockers

Guardrails

• Prefer repo-root scopes for real repos.
• During migration, use --include-ancestor-scopes so older parent-scope notes remain searchable.
• Automatic retrieval ignores ambiguous ancestor notes that do not identify the current repo.
• backfill-repo-metadata only tags notes when current-repo affinity is strong enough to be safe.
• Bootstrap a repo-specific scope once with:

python3 ~/.codex/skills/shared-memory/scripts/shared_memory.py bootstrap-repo --cwd "$PWD"

• Keep MEMORY.md short; details belong in note files.
• Do not duplicate the same long summary in both file memory and MCP memory.
• If your Claude memory directory is not under ~/.claude/projects, set SHARED_MEMORY_CLAUDE_PROJECTS_DIR.