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

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

# Sync claude-mem insights → beads memories

<!--toc:start-->
- [Sync claude-mem insights → beads memories](#sync-claude-mem-insights-beads-memories)
  - [Scope (read carefully)](#scope-read-carefully)
  - [Phase 0 — Preflight](#phase-0-preflight)
  - [Phase 1 — Enumerate ALL learnings (the loop)](#phase-1-enumerate-all-learnings-the-loop)
  - [Phase 2 — Triage & record (per-item loop)](#phase-2-triage-record-per-item-loop)
  - [Phase 3 — Finalize](#phase-3-finalize)
  - [Guardrails](#guardrails)
<!--toc:end-->

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/<id>.

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