| name | brain-merge |
| description | Compare and selectively merge Brain directories across any two agent instances. Supports diff (see what's unique where), pull (import from another brain), and learn (bidirectional exchange). |
| automation | gated |
| allowed-tools | ["Read","Write","Edit","Bash","Glob","Grep","Agent"] |
| user-invocable | true |
Brain Merge
Compare and selectively merge knowledge between any two Brain directories. Works across any agent instances - not tied to specific paths.
Purpose
Agent brains develop independently and accumulate unique insights. This playbook lets you see what each brain has that the other doesn't, and move knowledge between them safely.
Modes
- diff - Compare two brains, see what's unique to each
- pull - Import files from a source brain into a target brain
- learn - Bidirectional exchange with approval at each direction
State Dependencies
| Source | Location | Read | Write |
|---|
| Source brain | User-specified path | ✓ | - |
| Target brain | User-specified path (defaults to current) | ✓ | ✓ |
| FAISS index | [agent-root]/resources/local-brain-search/data/ | - | ✓ |
Process
Step 0: Resolve inputs
Ask the user for:
- Source brain path - the brain to compare against or pull from
- Target brain path - the brain to compare or import into (default: current agent's
./Brain)
- Mode - diff, pull, or learn (infer from user's message if obvious)
If paths are ambiguous (user says "moltbook" or "the other one"), scan parent directories for Brain/ folders and present a pick list:
find . -maxdepth 3 -name "Brain" -type d 2>/dev/null | sort
DIFF MODE
Goal: Show what each brain has that the other doesn't, grouped by folder.
Step 1: Inventory both brains
SOURCE="[SOURCE_BRAIN_PATH]"
TARGET="[TARGET_BRAIN_PATH]"
find "$SOURCE" -name "*.md" | sed "s|$SOURCE/||" | sort > /tmp/brain_source.txt
find "$TARGET" -name "*.md" | sed "s|$TARGET/||" | sort > /tmp/brain_target.txt
echo "Source: $(wc -l < /tmp/brain_source.txt) files"
echo "Target: $(wc -l < /tmp/brain_target.txt) files"
Step 2: Generate diff lists
comm -23 /tmp/brain_source.txt /tmp/brain_target.txt > /tmp/unique_to_source.txt
comm -13 /tmp/brain_source.txt /tmp/brain_target.txt > /tmp/unique_to_target.txt
comm -12 /tmp/brain_source.txt /tmp/brain_target.txt > /tmp/in_both.txt
echo "Unique to source: $(wc -l < /tmp/unique_to_source.txt)"
echo "Unique to target: $(wc -l < /tmp/unique_to_target.txt)"
echo "In both: $(wc -l < /tmp/in_both.txt)"
Step 3: Group by folder and present
echo "=== UNIQUE TO SOURCE ==="
awk -F'/' '{print $1}' /tmp/unique_to_source.txt | sort | uniq -c | sort -rn
echo "=== UNIQUE TO TARGET ==="
awk -F'/' '{print $1}' /tmp/unique_to_target.txt | sort | uniq -c | sort -rn
For each folder, show a few sample filenames so the user gets a sense of what's there.
Present as a clean table. Note any folders that exist in one brain but not the other (structural differences).
Gate 1: Present report. Ask: "Want to pull any of this into your brain? Which folders or files?"
PULL MODE
Goal: Import specific files from source into target, safely.
Step 1: Run diff if not already done
Step 2: Clarify scope
If not specified, ask: "Which folders or files to pull? (e.g., 02-Permanent, AI Extracted Notes, all unique files, or specific filenames)"
Gate 2: Confirm scope before touching anything:
"About to copy [N] files from [source] → [target]. Files already in target will be SKIPPED. Proceed?"
Step 3: Execute copy
rsync -av --ignore-existing \
"[SOURCE]/[SELECTED_FOLDER]/" \
"[TARGET]/[SELECTED_FOLDER]/"
For full unique-file pull:
while IFS= read -r file; do
dest="[TARGET]/$file"
mkdir -p "$(dirname "$dest")"
cp -n "[SOURCE]/$file" "$dest"
done < /tmp/unique_to_source.txt
Step 4: Refresh index in target
cd [TARGET_AGENT_ROOT]
python3 resources/local-brain-search/build_index.py
Report total files copied, skipped, and confirm index refreshed.
LEARN MODE
Goal: Bidirectional exchange - each brain gets what the other has.
Step 1: Run diff (both directions)
Step 2: Source → Target
Show what source has that target doesn't.
Gate 3: "Source has [N] unique files. Pull into target? (y/n/select folders)"
If approved, run pull source → target.
Step 3: Target → Source
Show what target has that source doesn't.
Gate 4: "Target has [M] unique files. Push into source? (y/n/select folders)"
If approved:
rsync -av --ignore-existing \
"[TARGET]/[SELECTED_FOLDER]/" \
"[SOURCE]/[SELECTED_FOLDER]/"
Step 4: Refresh indexes in both agents
cd [TARGET_AGENT_ROOT] && python3 resources/local-brain-search/build_index.py
cd [SOURCE_AGENT_ROOT] && python3 resources/local-brain-search/build_index.py
Report: files exchanged in each direction, both indexes refreshed.
Tips
- Start with diff - understand what you're working with before moving anything
- Safe by default -
--ignore-existing / cp -n never overwrites existing files
- Content conflicts - files with the same name but different content are flagged but not auto-resolved; manual review recommended
- Structural differences - folders that exist in one brain but not the other are worth noting (may indicate the agent evolved differently)
- Index refresh - always runs after file changes so FAISS stays current
Error Recovery
- If copy fails mid-way: re-run -
--ignore-existing makes it idempotent
- If index build fails: run
/refresh-index manually in that agent
- If paths not found: re-run Step 0 discovery scan
Self-Improvement
After completing this skill's primary task, consider tactical improvements:
