Brain

🚨 MEDIA FILES MUST BE SAVED. When user sends photos/audio/video/PDFs about a brain entry, you MUST save the actual file to attachments/. Transcribing content is NOT the same as saving the file. Do BOTH.

Data Location

All brain data lives in: ~/.openclaw/workspace/brain/

brain/
  people/       # Contacts, people you've met
  places/       # Restaurants, landmarks, venues
  games/        # Video games and interactions
  tech/         # Devices, products, specs, gotchas
  events/       # Conferences, meetups, gatherings
  media/        # Books, shows, films, podcasts
  ideas/        # Business ideas, concepts, thoughts
  orgs/         # Companies, communities, groups

Search & Retrieval

This skill uses OpenClaw's built-in memory_search and memory_get tools, which work out of the box with any configured memory backend.

Searching

Use memory_search for all brain lookups:

memory_search("Raven Duran")              # find a person
memory_search("Mamou Prime restaurant")   # find a place
memory_search("what games has Raven played") # natural language

memory_search works transparently whether the backend is the built-in SQLite indexer or QMD. No direct CLI calls needed.

Reading a File

Use memory_get to read a specific brain file once you know its path:

memory_get("brain/people/raven-duran.md")
memory_get("brain/places/mamou-prime-sm-podium/mamou-prime-sm-podium.md")

Direct CLI (Optional / Advanced Only)

Only use the qmd CLI directly when searching a non-workspace collection (e.g., the skills collection). For all brain lookups, use memory_search.

# Only for skills collection or non-workspace paths:
export PATH="$HOME/.bun/bin:$PATH"
qmd search "keyword" -c skills

Operational Rules

Creating a New Entry

1. Search first — Run memory_search("<name or topic>") to check for existing entries
2. No match — Create new file using the appropriate template from skills/brain/templates/
3. Possible clash — List all potential matches and ask user to confirm before creating

Updating an Existing Entry

1. Find the file — Use memory_search or direct path if known
2. Surgical edit — Update only the relevant section, don't rewrite the whole file
3. Log the date — Add timestamp to Notes or Interactions section
4. Update frontmatter — Bump last_updated field

Searching / Retrieving

1. Query memory_search — memory_search("<natural language question>") for semantic search
2. Ambiguous results — Surface all candidates to user, ask which one
3. No results — Tell user nothing found, offer to create entry

Disambiguation Protocol

When user references something ambiguous (e.g., "John"):

1. Search brain for all matches using memory_search("John")
2. If multiple results: list them with context

   Found 2 matches for "John":
   1. John Smith (Symph colleague, met 2024)
   2. John Doe (GeeksOnABeach speaker, met 2026)
   Which one?
   

3. Wait for confirmation before updating

Templates

Templates live in skills/brain/templates/. Each has:

• YAML frontmatter with structured fields
• Markdown body with standard sections

When creating a new entry:

1. Read the appropriate template
2. Fill in known fields
3. Leave unknown fields empty or with placeholder
4. Write to brain/<category>/<slug>.md

Categories Reference

Linking Entities

Use wikilink-style references to connect entities:

• [[people/raven-duran]] — link to a person
• [[events/geeksonabeach-2026]] — link to an event
• [[orgs/symph]] — link to an org

This makes relationships explicit and searchable.

Example Workflow

User says: "Hey, I just met this guy called Raven Duran. He's positioning himself as an Agentic coder, met him at GeeksOnABeach PH last February."

Agent does:

1. memory_search("Raven Duran") → no results
2. Read skills/brain/templates/person.md
3. Create brain/people/raven-duran.md with filled template
4. Optionally check/create brain/events/geeksonabeach-ph-2026.md and link

User says: "The Raven Duran guy, he's still 26 years old"

Agent does:

1. memory_search("Raven Duran") → finds brain/people/raven-duran.md
2. Read file via memory_get("brain/people/raven-duran.md"), update age: 26 in frontmatter
3. Add note: - **2026-02-21**: Confirmed still 26 years old
4. Update last_updated field

Attachments

Brain entries can have attachments: photos, PDFs, videos, audio, transcripts, etc.

🚨 MANDATORY: Save All Media Files

When user sends ANY media (photos, audio, video, PDF) related to a brain entry:

1. ALWAYS save the actual file to attachments/ — this is NON-NEGOTIABLE
2. THEN analyze/transcribe the content into the profile
3. NEVER skip saving the file just because you processed its content

"Saved" means the FILE exists in attachments/, not just that content was transcribed.

# REQUIRED: Copy the file
cp /path/to/inbound/media.jpg brain/places/entry/attachments/descriptive-name.jpg

If you transcribed content but didn't save the file → YOU DID IT WRONG. Go back and save it.

Structure

Flat file (no attachments):

brain/places/manam.md

Folder structure (with attachments):

brain/places/mamou-prime-sm-podium/
  mamou-prime-sm-podium.md      # Profile (keeps original name)
  attachments/
    index.md                    # Describes each attachment
    menu-page-1.jpg
    menu-page-2.jpg
    receipt.pdf
    storefront.mp4

Attachments Index (attachments/index.md)

# Attachments

| File | Description | Added |
|------|-------------|-------|
| menu-page-1.jpg | Menu first page, mains section | 2026-02-21 |
| menu-page-2.jpg | Menu second page, desserts | 2026-02-21 |
| receipt.pdf | Receipt from Feb visit, ₱2,400 | 2026-02-21 |
| storefront.mp4 | Quick video of the entrance | 2026-02-21 |

QMD (if enabled) indexes this file, making attachments searchable by description.

Adding Attachments

When user sends media about an entity (e.g., "Here's the menu for Mamou Prime"):

1. Find the entry — memory_search("Mamou Prime") → brain/places/mamou-prime-sm-podium.md

2. Convert to folder structure (if flat file):

   # Create folder
   mkdir -p brain/places/mamou-prime-sm-podium/attachments
   # Move profile into folder
   mv brain/places/mamou-prime-sm-podium.md brain/places/mamou-prime-sm-podium/
   # Create attachments index
   touch brain/places/mamou-prime-sm-podium/attachments/index.md
   

3. Save media to attachments/ with descriptive filename

4. Update attachments/index.md with file description

⚠️ Always Save Original Files

Do BOTH:

1. Analyze/transcribe the content → add processed text to the profile (e.g., menu tables, business card info, transcript)
2. Save the original files → preserve in attachments/

The text is searchable and processable. The originals are preserved artifacts.

Never discard attachments unless user explicitly says "cleanup", "remove", or "delete" the files.

Example: User sends menu photos

• ✅ Transcribe menu into markdown tables in profile
• ✅ Save original photos to attachments/menu-1.jpg, menu-2.jpg
• ✅ Update attachments/index.md

Wrong: Only transcribing without saving originals

Naming Attachments

Be descriptive — the index provides context:

• menu-1.jpg, menu-2.jpg
• business-card.jpg
• product-demo.mp4
• meeting-transcript.md
• voice-memo-2026-02-21.mp3

Example: Adding Menu Photos

User sends: 2 photos with message "Menu at Mamou Prime"

Agent does:

1. Find brain/places/mamou-prime-sm-podium.md via memory_search("Mamou Prime")
2. Convert to folder structure (if needed)
3. Analyze photos → transcribe menu items, prices into markdown tables
4. Update profile with transcribed menu section
5. Save original photos as attachments/menu-1.jpg, attachments/menu-2.jpg
6. Update attachments/index.md:

   # Attachments
   
   | File | Description | Added |
   |------|-------------|-------|
   | menu-1.jpg | Menu page 1 (transcribed to profile) | 2026-02-21 |
   | menu-2.jpg | Menu page 2 (transcribed to profile) | 2026-02-21 |
   

7. Confirm to user: "Transcribed menu and saved 2 photos to Mamou Prime"