shared-memory

name	shared-memory
description	Use when Claude and Codex need repo-scoped shared memory, clean handoff notes, safe retrieval, and cross-session alignment without cross-repo contamination.

Shared Memory

This skill keeps Claude aligned with Codex 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 required. 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:

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

2. Audit the memory surface before trusting ancestor notes:

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

3. If the audit shows safe repairs are available, heal them:

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

4. Build a bounded context pack instead of reading broad note sets:

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

5. Open only the top 1-3 underlying note files when deeper detail is actually needed.

6. 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

End-of-task workflow

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

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

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

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.
• 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.