Memory CaptureCAUTION

AI conversations that actually remember. Never re-explain your project to your AI again. Join our Discord: https://discord.gg/tyvKNccgqN

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: memory-capture
description: "Capture a working thread's current state into one coherent Basic Memory note; on re-capture, rewrite it in place. Use mid- or end-of-thread when decisions, insights, or context are worth keeping."
---

# Memory Capture

Capture the gist of a working thread — the decisions made, insights surfaced, and context built — into a single coherent Basic Memory note that reflects where the thread has landed.

## Purpose

A thread has a beginning, middle, and end. Things change as the conversation progresses: an early decision gets revised, a problem looks different in light of new information, a trade-off is settled differently than it first seemed. When this skill is invoked, capture the **current state of understanding**, not the history of how it got there.

If the skill is invoked more than once in the same thread, the **same note is rewritten** so it stays coherent — not appended to. The result should read top-to-bottom as a single document about the thread's outcome, with brief prose where a meaningful change is worth acknowledging.

## When to Use

Typical timing is **mid-thread or end-of-thread**, after enough has been settled to be worth preserving.

Use this skill when:
- Key decisions have been made and shouldn't evaporate when the thread closes
- A design, debugging, or planning discussion has produced something concrete
- The user explicitly asks to capture, save, or remember what's been discussed
- Toward the end of a session, to summarize the outcome

It is fine — and expected — to invoke this skill multiple times in the same thread as the conversation evolves.

## Same-Thread Detection

To rewrite the same note on re-capture instead of duplicating, key the note to a stable `thread_id` in its frontmatter.

**If your agent exposes a stable session or thread id**, store it as `thread_id` so subsequent captures within the same thread find and rewrite the same note. Any value that stays constant for the duration of the thread works — a session UUID, a conversation id, a ticket number the work is scoped to.

> **Example (hosts with a JSONL transcript):** some agents write a per-session transcript whose filename is a stable session UUID. If yours does, you can derive the id from the most-recently-modified transcript file and use it as `thread_id`. This is optional — only do it if your host actually exposes such a transcript.

**If no stable id is available**, match the existing note by title/topic instead: search for a note covering the same thread (`search_notes(query="<topic>")`), and if you find the one this thread already produced, rewrite it. Omit `thread_id` and rely on a consistent title.

## Decision Flow

1. **Determine the thread key.** Use a stable session/thread id if your agent exposes one; otherwise plan to match by title/topic.
2. **Search Basic Memory** for the existing thread note.
   - With a thread id, use `metadata_filters` (not `query`) — full-text query doesn't reliably match YAML frontmatter custom fields:
     ```python
     search_notes(
         metadata_filters={"thread_id": "<thread-id>"},
         project="<project>"
     )
     ```
   - Without one, search by topic and identify the note this thread already produced:
     ```python
     search_notes(query="<thread topic>", project="<project>")
     ```
3. **If a match is found:**
   - Read the existing note as JSON (use the full permalink returned by search) and keep its `checksum`
   - Synthesize a new version that integrates the latest understanding from the conversation
   - Overwrite via `write_note` with `overwrite=True` and `expected_checksum` set to that checksum (same title, same `thread_id` if used, same directory). A `NOTE_REVISION_CONFLICT` error means another session changed the note since you read it: read it again and re-synthesize
4. **If no match is found:**
   - Synthesize the note from the conversation
   - If you have a thread id, pass `metadata={"thread_id": "<thread-id>"}` to `write_note` (it surfaces as a custom frontmatter field)
   - Save it. If `write_note` lists similar existing notes, check whether one of them is this thread's note before keeping the new one

## Synthesis Rules

When updating an existing thread note, **synthesize, don't append**:

- Decisions that are still current → keep, possibly refined
- Decisions that have been superseded → replaced inline (the new one goes where the old one was)
- Significant revisions that deserve explanation → a sentence woven into the relevant section, *not* an appended changelog
- Outdated context → removed

Goal: the note reads top-to-bottom as a single coherent document. A reader who never saw the conversation should still understand the outcome from the note alone. There is no `## Changes` section at the bottom; revisions live in the prose where they're relevant.

## Escape Hatch

If the user explicitly asks for a separate note (e.g., "capture this as a new note, don't merge with the existing thread note"), skip the same-thread lookup and create a fresh note without setting `thread_id`. This is rare; the default is to update.

## Note Structure

```markdown
---
title: <descriptive title for the thread>
type: note
thread_id: <thread-id, if your agent exposes one>
tags:
- relevant
- tags
---

# <Title>

## Context

What this thread is about — the situation, problem, or topic being explored.

## <One or more topical sections>

The actual content. Could be decisions, a design rationale, an investigation summary, etc.

## Observations

- [decision] What was decided #tag
- [insight] Key understanding gained #tag
- [tradeoff] Option A chosen over B because... #tag

## Relations

- relates_to [[Related Concept]]
- implements [[Parent Spec]]
```

## Common Observation Categories

- `[decision]` — choices made
- `[insight]` — understanding gained
- `[pattern]` — reusable approaches
- `[learning]` — lessons learned
- `[tradeoff]` — options weighed
- `[problem]` — issues identified
- `[solution]` — fixes applie

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.claude/skills/adversarial-review

.claude/skills/basic-machines-review

.claude/skills/cmux

.claude/skills/cmux-markdown

.claude/skills/cmux-settings

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Memory Capture](https://modelsatlas.com/skills/basicmachines-co/memory-capture/badge.svg)](https://modelsatlas.com/skills/basicmachines-co/memory-capture/)

Not your listing, or something out of date? Claim or update your listing.