• 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

thread_id

thread_id

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.

search_notes(query="<topic>")

thread_id

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 (use the full permalink returned by search)
   • Synthesize a new version that integrates the latest understanding from the conversation
   • Overwrite via

     write_note

     with

     overwrite=True

     (same title, same

     thread_id

     if used, same directory)
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

• 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

## Changes

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

• relates_to [[Related Concept]]
• implements [[Parent Spec]]

undefined

• [decision]

  — choices made

• [insight]

  — understanding gained

• [pattern]

  — reusable approaches

• [learning]

  — lessons learned

• [tradeoff]

  — options weighed

• [problem]

  — issues identified

• [solution]

  — fixes applied

• Primary: deep navy

  #2B3651

  — calm and professional
• Accent: warm orange

  #F26B3A

  — energy and warmth as a complement to the navy

• Body: Inter — neutral, readable at small sizes
• Display: Helvetica Neue — strong presence for headings without being heavy

• [decision] Primary color is navy

  #2B3651

  #branding
• [decision] Accent color is orange

  #F26B3A

  #branding
• [decision] Inter for body, Helvetica Neue for display #typography
• [tradeoff] Considered teal as accent; orange tested better for warmth #branding

• relates_to [[Brand Strategy]]

undefined

• Primary: deep navy

  #2B3651

  — calm and professional
• Accent: coral

  #E89B7A

  — warm and refined

#F26B3A

• Body: Geist — slightly tighter and more modern than Inter, which we tried first
• Display: Helvetica Neue — strong presence for headings without being heavy

• [decision] Primary color is navy

  #2B3651

  #branding
• [decision] Accent color is coral

  #E89B7A

  — warmer and more refined than the originally-chosen orange #branding
• [decision] Geist for body, Helvetica Neue for display #typography
• [tradeoff] Inter felt neutral but Geist edged it for spacing and modernity #typography
• [tradeoff] Orange accent rejected as too aggressive; coral preferred #branding

• relates_to [[Brand Strategy]]

Notice that:
- 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
- There is **no "Changes" section** at the bottom — revisions are integrated where they belong
- The note still reads top-to-bottom as a single coherent document
- The `thread_id` is unchanged, so the note was updated in place rather than duplicated

1. Capture the current state, not the history. The note represents where the thread has landed.
2. Synthesize, don't log. Each invocation produces a coherent document, not an accumulating record.
3. Brief prose for revisions. A sentence in the section that changed is enough — don't add a changelog.
4. Always run the same-thread lookup before deciding to create or update.
5. Use observations for the structured layer. Decisions, insights, tradeoffs go in

   ## Observations

   so they're searchable.
6. Link relations liberally. Notes the user might want to reach from this one.