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: INLINECODE3

CODEBLOCK0

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:

CODEBLOCK1

INLINECODE7 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:

CODEBLOCK2

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.

CODEBLOCK3

Operational Rules

Creating a New Entry

1. 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 INLINECODE13
3. Possible clash — List all potential matches and ask user to confirm before creating

Updating an Existing Entry

1. 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. 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. 1. Search brain for all matches using INLINECODE17
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?
   

1. 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. 1. Read the appropriate template
2. Fill in known fields
3. Leave unknown fields empty or with placeholder
4. Write to INLINECODE19

Categories Reference

Linking Entities

Use wikilink-style references to connect entities:

• - [[people/raven-duran]] — link to a person
• INLINECODE29 — link to an event
• INLINECODE30 — 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. 1. memory_search("Raven Duran") → no results
2. Read INLINECODE32
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. 1. memory_search("Raven Duran") → finds INLINECODE36
2. Read file via memory_get("brain/people/raven-duran.md"), update age: 26 in frontmatter
3. Add note: INLINECODE39
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. 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.

CODEBLOCK5

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

Structure

Flat file (no attachments):
CODEBLOCK6

Folder structure (with attachments):
CODEBLOCK7

Attachments Index (attachments/index.md)

CODEBLOCK8

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. 1. Find the entry — memory_search("Mamou Prime") → INLINECODE45

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

1. 3. Save media to attachments/ with descriptive filename

1. 4. Update attachments/index.md with file description

⚠️ Always Save Original Files

Do BOTH:

1. 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 INLINECODE48

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, INLINECODE50
• ✅ Update INLINECODE51

Wrong: Only transcribing without saving originals

Naming Attachments

Be descriptive — the index provides context:

• - menu-1.jpg, INLINECODE53
• INLINECODE54
• INLINECODE55
• INLINECODE56
• INLINECODE57

Example: Adding Menu Photos

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

Agent does:

1. 1. Find brain/places/mamou-prime-sm-podium.md via INLINECODE59
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, INLINECODE61
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 |
   

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