dotfiles/dot_claude/commands/cmem-to-beads.md

description

description
Extract insight-type learnings from claude-mem and record them into beads memories

Sync claude-mem insights → beads memories

• Sync claude-mem insights → beads memories
  • Scope (read carefully)
  • Phase 0 — Preflight
  • Phase 1 — Enumerate ALL learnings (the loop)
  • Phase 2 — Triage & record (per-item loop)
  • Phase 3 — Finalize
  • Guardrails

You are migrating durable insights from claude-mem (the session memory store) into beads (bd remember) for this repository. Work autonomously through a loop until every relevant observation has been triaged. Do not invent learnings — only persist what claude-mem actually returns.

Scope (read carefully)

• Record ONLY insights / decisions / gotchas → bd remember.
• Ignore actionable learnings (bugs to fix, tech debt, follow-ups, TODOs). Do not create them as beads issues. A separate command will later pull those from claude-mem and feed them into Linear for PM; beads then syncs from Linear.
• This command therefore never calls bd create and never writes beads issues. The only write to beads is bd remember. Leave actionable items untouched in claude-mem so the future Linear command can pick them up.

---

Phase 0 — Preflight

1. Confirm beads is live in this repo: bd ready (and bd doctor if it errors).
2. Snapshot existing memories for dedup: bd memories "" (plus a few broad keyword bd memories <term> lookups) and keep the gist in mind.
3. Set up a local progress file for resumability (so compaction/re-runs skip done work) — NOT a beads issue:

   ./.claude-mem-sync/processed.json    # { "processed": [<cmem ids>], "skipped_actionable": <count> }
   

   Create it if missing; load it if present. Add .claude-mem-sync/ to .gitignore if it isn't already.

---

Phase 1 — Enumerate ALL learnings (the loop)

claude-mem search is query-based, so a single call won't surface everything. Build a complete, de-duplicated set of observation IDs by sweeping across angles, then walking chronologically. Track seen IDs in a set; never process the same ID twice.

Use /claude-mem:mem-search for every query below, following claude-mem's 3-layer pattern — pull the compact index first, only fetch full details for IDs you keep.

1a. Type sweep — one broad query per observation type, high limit:

/claude-mem:mem-search  (type=insight)
/claude-mem:mem-search  (type=decision)
/claude-mem:mem-search  (type=bugfix)        # scan for the *lesson learned*, not the fix-task
/claude-mem:mem-search  (type=architecture)
/claude-mem:mem-search  (type=feature)       # plus any other types this project uses

You still scan every type — a bugfix or feature observation often contains a durable insight ("X breaks when Y") even though its actionable part is ignored here.

1b. Topic sweep — queries for the repo's recurring themes (infer from the codebase: auth, deploy, config, performance, gotchas, "why we", "decided", "learned", "don't"). Each adds new IDs to the set.

1c. Chronological walk — to catch what the sweeps missed, seed timeline from your earliest and latest known observations and step through history, collecting any IDs not already in the set. Stop when the timeline yields no new IDs in either direction.

Result: a deduplicated list of candidate observation IDs. Print the count.

---

Phase 2 — Triage & record (per-item loop)

Process candidate IDs in batches. For each batch:

1. Fetch details once: get_observations(ids=[...]) (batch IDs — never one-at-a-time).

2. For each observation, classify:

   • Actionable (a thing to do: unfixed bug, tech debt, follow-up, TODO) → IGNORE. Increment skipped_actionable in the progress file and move on. It stays in claude-mem for the Linear command.

   • Insight / decision / gotcha (durable knowledge about how things are) → record it:

     • Dedup check first: bd memories <key terms>. If beads already captures it, skip.
     • Then:

       bd remember "<one-line durable insight, self-contained, no session context> [cmem #<id>]"
       

       Keep it atomic and reusable. Include the source cmem #<id> so it traces back to http://localhost:37777/api/observation/.

   • Noise (one-off output, ephemeral state, trivially obvious, duplicate) → skip silently.

3. Append processed IDs to ./.claude-mem-sync/processed.json.

Repeat until the candidate set is exhausted.

---

Phase 3 — Finalize

1. Sanity pass: bd memories "" — confirm new insights landed and read cleanly.
2. Sync beads memories to remote: bd dolt push.
3. Session close protocol — if any code/files changed (e.g. .gitignore):

   git status
   git add <files>
   git commit -m "chore: record claude-mem insights into beads"
   git push
   

---

Guardrails

• Insights only. Never bd create, never write a beads issue. Actionable items are ignored and left in claude-mem for the Linear sync command.
• Idempotent. Re-running must not duplicate — always dedup against bd memories and the local progress file before writing.
• Atomic memories. One insight per bd remember, self-contained, no "in this session" phrasing.
• Cite the source. Every entry carries its cmem #<id> for traceability.
• No bd edit — it opens an editor and blocks.
• Don't fabricate — if a sweep returns nothing, say so and move on.
• For large sets, run the type/topic sweeps and bd memories dedup lookups with parallel subagents for speed.

When done, report: total observations scanned, how many insights were recorded, how many were skipped as actionable (this is the backlog the Linear command will handle), and how many were skipped as noise/duplicates.