Update to Basic Memory Cloud

{
  "name": "memory-capture",
  "description": "Capture the current state of a working thread or conversation into a single coherent Basic Memory note — synthesize where it landed, don't append a log. On re-capture, rewrite the same note in place instead of duplicating. Use mid-thread or end-of-thread when decisions, insights, or context are worth preserving.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 397
    }
  ],
  "skill_md_contents": "---\nname: memory-capture\ndescription: \"Capture the current state of a working thread or conversation into a single coherent Basic Memory note — synthesize where it landed, don't append a log. On re-capture, rewrite the same note in place instead of duplicating. Use mid-thread or end-of-thread when decisions, insights, or context are worth preserving.\"\n---\n\n# Memory Capture\n\nCapture 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.\n\n## Purpose\n\nA 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.\n\nIf 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.\n\n## When to Use\n\nTypical timing is **mid-thread or end-of-thread**, after enough has been settled to be worth preserving.\n\nUse this skill when:\n- Key decisions have been made and shouldn't evaporate when the thread closes\n- A design, debugging, or planning discussion has produced something concrete\n- The user explicitly asks to capture, save, or remember what's been discussed\n- Toward the end of a session, to summarize the outcome\n\nIt is fine — and expected — to invoke this skill multiple times in the same thread as the conversation evolves.\n\n## Same-Thread Detection\n\nTo rewrite the same note on re-capture instead of duplicating, key the note to a stable `thread_id` in its frontmatter.\n\n**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.\n\n> **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.\n\n**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.\n\n## Decision Flow\n\n1. **Determine the thread key.** Use a stable session/thread id if your agent exposes one; otherwise plan to match by title/topic.\n2. **Search Basic Memory** for the existing thread note.\n   - With a thread id, use `metadata_filters` (not `query`) — full-text query doesn't reliably match YAML frontmatter custom fields:\n     ```python\n     search_notes(\n         metadata_filters={\"thread_id\": \"<thread-id>\"},\n         project=\"<project>\"\n     )\n     ```\n   - Without one, search by topic and identify the note this thread already produced:\n     ```python\n     search_notes(query=\"<thread topic>\", project=\"<project>\")\n     ```\n3. **If a match is found:**\n   - Read the existing note (use the full permalink returned by search)\n   - Synthesize a new version that integrates the latest understanding from the conversation\n   - Overwrite via `write_note` with `overwrite=True` (same title, same `thread_id` if used, same directory)\n4. **If no match is found:**\n   - Synthesize the note from the conversation\n   - If you have a thread id, pass `metadata={\"thread_id\": \"<thread-id>\"}` to `write_note` (it surfaces as a custom frontmatter field)\n   - Save it\n\n## Synthesis Rules\n\nWhen updating an existing thread note, **synthesize, don't append**:\n\n- Decisions that are still current → keep, possibly refined\n- Decisions that have been superseded → replaced inline (the new one goes where the old one was)\n- Significant revisions that deserve explanation → a sentence woven into the relevant section, *not* an appended changelog\n- Outdated context → removed\n\nGoal: 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.\n\n## Escape Hatch\n\nIf 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.\n\n## Note Structure\n\n```markdown\n---\ntitle: <descriptive title for the thread>\ntype: note\nthread_id: <thread-id, if your agent exposes one>\ntags:\n- relevant\n- tags\n---\n\n# <Title>\n\n## Context\n\nWhat this thread is about — the situation, problem, or topic being explored.\n\n## <One or more topical sections>\n\nThe actual content. Could be decisions, a design rationale, an investigation summary, etc.\n\n## Observations\n\n- [decision] What was decided #tag\n- [insight] Key understanding gained #tag\n- [tradeoff] Option A chosen over B because... #tag\n\n## Relations\n\n- relates_to [[Related Concept]]\n- implements [[Parent Spec]]\n```\n\n## Common Observation Categories\n\n- `[decision]` — choices made\n- `[insight]` — understanding gained\n- `[pattern]` — reusable approaches\n- `[learning]` — lessons learned\n- `[tradeoff]` — options weighed\n- `[problem]` — issues identified\n- `[solution]` — fixes applied\n\n## Title\n\nThe title should reflect the thread's topic. On update, the title can be refined if the topic has clarified — but it should still describe the same thread. Don't drift to a wholly new topic; if that's needed, use the escape hatch and create a new note.\n\n## MCP Tools Used\n\n```python\n# Find existing thread note by thread id (use metadata_filters, not query)\nsearch_notes(\n    metadata_filters={\"thread_id\": \"<thread-id>\"},\n    project=\"<project>\"\n)\n\n# Or, without a thread id, find it by topic\nsearch_notes(query=\"<thread topic>\", project=\"<project>\")\n\n# Read existing thread note (use the full permalink from search results)\nread_note(\n    identifier=\"<full-permalink>\",\n    project=\"<project>\"\n)\n\n# Create\nwrite_note(\n    title=\"<title>\",\n    content=\"<markdown body — frontmatter is generated from title/tags/metadata>\",\n    directory=\"<folder>\",\n    tags=[\"...\"],\n    metadata={\"thread_id\": \"<thread-id>\"},  # omit if no stable id\n    project=\"<project>\"\n)\n\n# Overwrite an existing note (same path)\nwrite_note(\n    title=\"<same title>\",\n    content=\"<new content>\",\n    directory=\"<same folder>\",\n    tags=[\"...\"],\n    metadata={\"thread_id\": \"<same thread-id>\"},  # omit if no stable id\n    overwrite=True,\n    project=\"<project>\"\n)\n```\n\n## Examples\n\n### Example 1 — First capture during a brand design conversation\n\n**Preceding conversation:** The user has been working through visual identity decisions for a new product. They settled on a deep navy primary (`#2B3651`), explored accent options and chose orange (`#F26B3A`) for warmth, and picked Inter as the body font with Helvetica Neue as the display font.\n\n**User asks to capture.**\n\n**Result — note created:**\n\n```markdown\n---\ntitle: Visual identity — initial decisions\ntype: note\nthread_id: 7c1d4a2e-3b5f-4d8a-9e1c-2f6b8a4d7c39\ntags:\n- branding\n- design\n---\n\n# Visual identity — initial decisions\n\n## Context\n\nWorking through the visual identity for the new product. This thread covers the initial palette and typography pass — a starting point that will likely be refined.\n\n## Color palette\n\n- Primary: deep navy `#2B3651` — calm and professional\n- Accent: warm orange `#F26B3A` — energy and warmth as a complement to the navy\n\n## Typography\n\n- Body: Inter — neutral, readable at small sizes\n- Display: Helvetica Neue — strong presence for headings without being heavy\n\n## Observations\n\n- [decision] Primary color is navy `#2B3651` #branding\n- [decision] Accent color is orange `#F26B3A` #branding\n- [decision] Inter for body, Helvetica Neue for display #typography\n- [tradeoff] Considered teal as accent; orange tested better for warmth #branding\n\n## Relations\n\n- relates_to [[Brand Strategy]]\n```\n\n### Example 2 — Update capture later in the same thread\n\n**Preceding conversation (continued):** After the initial decisions above, the conversation continued. The orange accent felt too aggressive in mock-ups, so we tested a coral (`#E89B7A`) which read warmer and more refined. The body font also shifted: Geist felt slightly tighter and more modern than Inter. Helvetica Neue for display stayed.\n\n**User asks to capture again — same thread.**\n\n**Result — same note rewritten (note the same `thread_id`):**\n\n```markdown\n---\ntitle: Visual identity — initial decisions\ntype: note\nthread_id: 7c1d4a2e-3b5f-4d8a-9e1c-2f6b8a4d7c39\ntags:\n- branding\n- design\n---\n\n# Visual identity — initial decisions\n\n## Context\n\nWorking through the visual identity for the new product. This thread settled on a navy + coral palette and a Geist/Helvetica typography pairing after a round of refinement.\n\n## Color palette\n\n- Primary: deep navy `#2B3651` — calm and professional\n- Accent: coral `#E89B7A` — warm and refined\n\nThe accent went through a round of revision: an initial orange (`#F26B3A`) felt too aggressive in mock-ups, so we shifted to a coral that reads warmer and more refined while keeping the energy.\n\n## Typography\n\n- Body: Geist — slightly tighter and more modern than Inter, which we tried first\n- Display: Helvetica Neue — strong presence for headings without being heavy\n\n## Observations\n\n- [decision] Primary color is navy `#2B3651` #branding\n- [decision] Accent color is coral `#E89B7A` — warmer and more refined than the originally-chosen orange #branding\n- [decision] Geist for body, Helvetica Neue for display #typography\n- [tradeoff] Inter felt neutral but Geist edged it for spacing and modernity #typography\n- [tradeoff] Orange accent rejected as too aggressive; coral preferred #branding\n\n## Relations\n\n- relates_to [[Brand Strategy]]\n```\n\nNotice that:\n- The orange and Inter decisions are **no longer the primary content** — they're acknowledged in prose (\"which we tried first,\" \"originally-chosen orange\") and in tradeoff observations\n- There is **no \"Changes\" section** at the bottom — revisions are integrated where they belong\n- The note still reads top-to-bottom as a single coherent document\n- The `thread_id` is unchanged, so the note was updated in place rather than duplicated\n\n## Best Practices\n\n1. **Capture the current state, not the history.** The note represents where the thread has landed.\n2. **Synthesize, don't log.** Each invocation produces a coherent document, not an accumulating record.\n3. **Brief prose for revisions.** A sentence in the section that changed is enough — don't add a changelog.\n4. **Always run the same-thread lookup** before deciding to create or update.\n5. **Use observations for the structured layer.** Decisions, insights, tradeoffs go in `## Observations` so they're searchable.\n6. **Link relations liberally.** Notes the user might want to reach from this one.\n"
}