Brain Skill — 2nd Brain Knowledge Base

A personal knowledge management system for capturing and retrieving information about people, places, things, and ideas.

When to Use This Skill

Brain takes precedence over daily logs for named entities.

Trigger this skill when:

• User asks you to remember someone, something, or somewhere
• User shares information about a person, place, game, tech, event, media, idea, or organization
• User expresses a preference about an entity ("I like X at Y restaurant" → update Y's file)
• User asks about something that might be in the brain ("Who was that guy from...", "What did I think about...")
• User updates existing knowledge ("Actually, he's 27 now", "I finished that game")

Keywords that trigger: "remember", "note that", "met this person", "visited", "played", "watched", "read", "idea:", "what do I know about", "who is", "where was"

⚠️ Do NOT put brain-eligible content in daily logs. If it's a named entity (person, place, restaurant, product, game, etc.), it belongs in brain/, not memory/YYYY-MM-DD.md. Daily logs are for session context and ephemeral notes only.

🚨 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("\x3Cname 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("\x3Cnatural 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/\x3Ccategory>/\x3Cslug>.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"