2nd-brain

---
name: brain
version: 1.3.0
description: |
  Personal knowledge base for capturing and retrieving information about people,
  places, restaurants, games, tech, events, media, ideas, and organizations.
  Use when: user mentions a person, place, restaurant, landmark, game, device,
  event, book/show, idea, or company. Trigger phrases: "remember", "note that",
  "met this person", "visited", "played", "what do I know about", etc.
  Brain entries take precedence over daily logs for named entities.
setup: |
  This skill uses OpenClaw's built-in memory_search and memory_get tools for
  search and retrieval — no external dependencies required.

  Optional: For richer BM25 + vector + reranking search, enable the QMD backend:
    1. Install QMD CLI: bun install -g https://github.com/tobi/qmd
    2. Set memory.backend = "qmd" in openclaw.json
    3. Add brain/ to memory.qmd.paths in openclaw.json:
         paths: [{ name: "brain", path: "~/.openclaw/workspace/brain", pattern: "**/*.md" }]

  The skill degrades gracefully to OpenClaw's built-in search if QMD is not configured.
permissions:
  paths:
    - "~/.openclaw/workspace/brain/**"
  write: true
  attachments: true
---

# 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`.

```bash
# 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

| Category | Folder | Use For |
|----------|--------|---------|
| People | `brain/people/` | Anyone user has met or wants to remember |
| Places | `brain/places/` | Restaurants, landmarks, venues, locations |
| Games | `brain/games/` | Video games — status, opinions, notes |
| Tech | `brain/tech/` | Devices, products, specs, quirks |
| Events | `brain/events/` | Conferences, meetups, gatherings |
| Media | `brain/media/` | Books, shows, films, podcasts |
| Ideas | `brain/ideas/` | Business ideas, concepts, random thoughts |
| Orgs | `brain/orgs/` | Companies, communities, groups |

## 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.**

```bash
# 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`)

```markdown
# 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):**
   ```bash
   # 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"

... (truncated)