Skip to content

Bruno-Cunha-Souza/ValarMindSkills / skills/obsidian-brain

obsidian-brain

Verified

Project memory in Obsidian vault — brain/<slug>-brain.md index + atomic sessions/topics/decisions. Auto-activates when CLAUDE.md/AGENTS.md refs vault.

FileKindSize
SKILL.mdskill md23.9 KB
references/READING_AND_SEARCHING.mdmarkdown10.4 KB
references/SESSION_LIFECYCLE.mdmarkdown8.9 KB
references/STRUCTURE.mdmarkdown12.0 KB
references/WRITING_RULES.mdmarkdown12.7 KB

references/STRUCTURE.md

View on GitHub
> Reference companion for the [obsidian-brain](../SKILL.md) skill.

# Structure

The exact disk layout, frontmatter, naming, and templates for every note type the brain produces.

## Disk layout

```
<vault-doc-root>/
├── <existing project docs — untouched>
└── brain/                              ← created on first run
    ├── <slug>-brain.md                 ← INDEX (≤500 tokens; sole entrypoint)
    ├── sessions/
    │   ├── .gitkeep
    │   └── YYYY-MM-DD-<short-slug>.md  ← append-only daily log
    ├── topics/
    │   ├── .gitkeep
    │   └── <topic>.md                  ← atomic note, atomic-rewrite
    ├── decisions/
    │   ├── .gitkeep
    │   └── NNNN-<short-slug>.md        ← immutable ADR
    └── brain.base                      ← optional, on-demand only
```

Rules:

- `brain/` lives **inside** the project's existing vault folder, beside the existing MOC. Never at the vault root.
- Subdirs are flat — no nested `topics/<area>/<topic>.md`. Use tags for area separation.
- `.gitkeep` files preserve empty directories in version control.
- `brain.base` is optional and only created when the user explicitly asks for a dashboard.

## Frontmatter — every note type

The brain inherits the vault's frontmatter conventions documented in `<vault>/CLAUDE.md`. Below are the additional brain-specific fields.

### Index (`<slug>-brain.md`)

```yaml
---
aliases:
  - Brain
  - Memória do Projeto
tags:
  - brain-index
  - projeto/<slug>
type: brain-index
status: active
project: <slug>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

### Session (`sessions/YYYY-MM-DD-<short-slug>.md`)

```yaml
---
tags:
  - brain-session
  - brain/session
type: brain-session
date: YYYY-MM-DD
session_id: <YYYY-MM-DD>-<short-slug>
topics:
  - "[[topic-x]]"
  - "[[topic-y]]"
decisions:
  - "[[NNNN-z]]"
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

### Topic (`topics/<topic>.md`)

```yaml
---
aliases:
  - <Optional human-readable alias>
tags:
  - brain-topic
  - brain/topic
  - topic/<area>
type: brain-topic
related:
  - "[[other-topic]]"
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

### Decision (`decisions/NNNN-<short-slug>.md`)

```yaml
---
tags:
  - brain-decision
  - brain/adr
  - decision/<status>
type: brain-decision
decision_id: NNNN
status: accepted        # accepted | superseded | deprecated
date: YYYY-MM-DD
supersedes: ""          # wikilink to prior decision if applicable
superseded_by: ""       # wikilink to newer decision if applicable
---
```

## Naming conventions

| Note type | Pattern | Example |
| :--- | :--- | :--- |
| Index | `<slug>-brain.md` | `valarmindskills-brain.md` |
| Session | `YYYY-MM-DD-<short-slug>.md` | `2026-04-24-obsidian-brain.md` |
| Topic | `<topic>.md` (lowercase, kebab-case, ≤32 chars) | `rsc-rendering.md`, `auth-middleware.md` |
| Decision | `NNNN-<short-slug>.md` (4-digit zero-padded sequence) | `0001-pick-bases-over-dataview.md` |

Decision IDs are **monotonically assigned** per project. Get the next ID with:

```bash
obsidian search property="type=brain-decision" total
# fallback:
ls brain/decisions | grep -E '^\d{4}-' | tail -1
```

## Tags

Hierarchical, lowercase, hyphenated (no spaces, per vault convention).

| Tag | Applied to | Purpose |
| :--- | :--- | :--- |
| `brain-index` | Index | Identifies the index file uniquely. |
| `brain-session` | Sessions | Bulk filter for "all sessions". |
| `brain-topic` | Topics | Bulk filter for "all topics". |
| `brain-decision` | Decisions | Bulk filter for "all ADRs". |
| `brain/session` | Sessions | Hierarchical — Bases-friendly. |
| `brain/topic` | Topics | Hierarchical. |
| `brain/adr` | Decisions | Hierarchical. |
| `topic/<area>` | Topics | Sub-classify topics by area (e.g., `topic/security`, `topic/rendering`). |
| `decision/<status>` | Decisions | `decision/accepted`, `decision/superseded`, `decision/deprecated`. |
| `projeto/<slug>` | Index | Co-tag with the project tag the rest of the vault uses. |

Use the **dash form** (`brain-index`) for top-level filters and the **slash form** (`brain/session`) for hierarchical Bases queries. Both work — pick by Bases query needs.

## Callouts

| Callout | Where it appears | Purpose |
| :--- | :--- | :--- |
| `> [!summary]` | First block of every session note; "Critical facts" block of the index | Executive summary, ≤6 bullets. |
| `> [!decision]` | Body of every ADR; inline in session notes when a decision was made | Frame a chosen trade-off; references the formal ADR via wikilink. |
| `> [!todo]` | Session notes only | Pending task that survives the session. |
| `> [!question]` | Session notes; topic notes when a question is open | Open question to revisit. |
| `> [!warning]` | Topic notes; index | Gotcha, footgun, or constraint that matters across sessions. |
| `> [!tip]` | Topic notes | Non-obvious win, shortcut, or pattern. |

Stay within this set — do not invent custom callouts. Bases ignores callouts, so they are a human-readability aid only.

## Wikilink format rule

> [!important] Filename-only, never path-prefixed
> Obsidian resolves wikilinks **from the vault root**, not from the file's own directory. Use the filename only, never a path prefix:
>
> - ✅ `[[2026-04-25-ci-cd-generator|2026-04-25]]` — Obsidian resolves by filename across the entire vault
> - ❌ `[[sessions/2026-04-25-ci-cd-generator|2026-04-25]]` — would only resolve if `sessions/` lived at the vault root, which it doesn't (the brain lives nested under `Projetos/<slug>/brain/sessions/`)
> - ✅ `[[0001-pick-bases-over-dataview|0001]]` — for ADRs
> - ❌ `[[decisions/0001-pick-bases-over-dataview|0001]]` — same problem
>
> Filenames must be **unique across the vault** for this to work. The brain's naming conventions (`<slug>-brain.md`, `YYYY-MM-DD-<short-slug>.md`, `NNNN-<short-slug>.md`) are designed to be globally unique on purpose.
>
> This rule applies to every wikilink in every brain note — index, sessions, topics, decisions. It applies equally to the index template, the session-note template, and the topic/decision templates below.

## Index template

This is the seed used by Phase 1 bootstrap. Replace `<slug>` and `<Project name>` literally. Keep the total under 500 tokens.

````markdown
---
aliases:
  - Brain
  - Memória do Projeto
tags:
  - brain-index
  - projeto/<slug>
type: brain-index
status: active
project: <slug>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# <Project name> — Brain

> [!summary] Critical facts (≤150 tokens)
> - Project: <one line — what this project is>
> - Source of truth do código/docs: caminhos em prosa (e.g., `Projetos/<slug>/`), backticks para nomes de docs externos. **Sem wikilinks para fora do brain.**
> - Read this index first; lazy-load the rest via wikilinks.
> - Brain is for **what happened**; main docs are for **how it works**. Os dois grafos são separados — brain não wikilinka para docs e docs não wikilinkam para o brain.

## Topics (brain-internal)

_Topic notes próprias do brain. Docs externos do projeto são mencionados em backticks na seção Keywords abaixo, sem wikilinks._

- `[[<topic-1>|<Topic 1>]]` — <one-line summary>
- `[[<topic-2>|<Topic 2>]]` — <one-line summary>

## Recent sessions (last 10)

- `[[YYYY-MM-DD-<slug>|YYYY-MM-DD]]` — <one-line summary>

## Decisions (ADRs)

- `[[0001-<slug>|0001]]` — <one-line summary>

## Keywords

_Mapa mental para orientar busca — referências externas em backticks (sem wikilinks); referências intra-brain em `[[<topic>]]`._

- `<keyword>` → `[[<brain-topic>]]` (intra-brain)
- `<keyword>` → `` `nome-do-doc-externo` `` (doc do projeto, sem wikilink)

## Pending

- `> [!todo]` items rolled up from active sessions (refreshed by Phase 4 sync).
````

## Session note template

```markdown
---
tags: [brain-session, brain/session]
type: brain-session
date: YYYY-MM-DD
session_id: YYYY-MM-DD-<short-slug>
topics: ["[[<topic>]]"]
decisions: []
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# YYYY-MM-DD — <One-line title>

> [!summary]
> - <bullet 1>
> - <bullet 2>
> - <bullet 3>

## Asked

- <user request, paraphrased to one line>

## Found

- <non-obvious finding 1> → `[[<topic>]]`
- <non-obvious finding 2>

## Done

- <action 1>
- <action 2>

## Pending

> [!todo]
> - [ ] <task that survives the session>

## Decisions made

- `[[NNNN-<slug>|NNNN]]` — <one-line summary>

## Related

- `[[<slug>-brain|Brain]]` — link back to the project's brain index (mandatory for graph connectivity)
- `[[<topic>]]` — every topic referenced above, repeated here as an explicit body wikilink
- `[[<NNNN-...>]]` or `[[<YYYY-MM-DD-...>]]` — sibling brain notes (decisions, other sessions) referenced in the body
```

> [!warning] Related section is mandatory
> Obsidian's graph view does not by default follow wikilinks declared **only in frontmatter** (`topics:`, `decisions:`, `related:`). A session whose only links are in `topics:` will appear as an orphan in the graph. The `## Related` section guarantees the session is reachable both visually (graph) and structurally (backlinks pane).

> [!important] Brain isolation rule
> Brain notes — **including the index** (`<slug>-brain.md`), sessions, topics, and decisions — **must not** wikilink to project docs (`Skills/<slug>`, `Arquitetura`, MOCs, `Manual de Uso`, etc.). The reverse is also forbidden: project docs must not wikilink to any node under `brain/`. Brain is a **closed graph**, separated from the documentation graph by design. Mention project skills/docs in body prose with backticks (`` `prompt-engineering` ``), never with wikilinks. The brain captures *what happened*; project docs capture *how things work* — keeping the graphs separate prevents the brain from polluting the documentation graph.

## Topic note template

```markdown
---
aliases: ["<alias>"]
tags: [brain-topic, brain/topic, topic/<area>]
type: brain-topic
related: ["[[<other-topic>]]"]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# <Topic title>

> [!summary]
> <one-sentence definition>

## Key facts

- <fact 1>
- <fact 2>

## Constraints

> [!warning]
> <constraint or gotcha>

## Sessions where this came up

- `[[YYYY-MM-DD-<slug>]]`

## Related

- `[[<slug>-brain|Brain]]`
- `[[<other-topic>]]`
```

> [!important] Topic notes follow the same boundary rule
> Do **not** wikilink to project docs (`Skills/<slug>`, MOCs, etc.) from a topic note. Use backticks (`` `prompt-engineering` ``) for textual mention. The index follows the same rule — there is no boundary node; the entire brain is closed.

## Decision note template (ADR)

```markdown
---
tags: [brain-decision, brain/adr, decision/accepted]
type: brain-decision
decision_id: NNNN
status: accepted
date: YYYY-MM-DD
supersedes: ""
superseded_by: ""
---

# NNNN — <One-line title>

> [!decision]
> <One-sentence statement of the decision.>

## Context

- <why we had to decide>

## Options considered

- **<Option A>** — <trade-off>
- **<Option B>** — <trade-off>

## Decision

- We chose **<X>** because <Y>.

## Consequences

- <consequence 1>
- <consequence 2>

## Sessions where this was decided

- `[[YYYY-MM-DD-<slug>]]`

## Related

- `[[<slug>-brain|Brain]]`
- `[[<topic>]]` — topic this decision crystallizes (if any)
```

> [!important] Decisions follow the same boundary rule
> Do **not** wikilink to project docs from an ADR. Use backticks for textual mention. Brain (incluindo o index) é um grafo fechado — a regra vale para todos os tipos de nota.

## brain.base (optional dashboard)

On-demand only. When the user wants a visual dashboard, hand off to `@obsidian-bases` to create:

```yaml
filters:
  and:
    - tag: brain-session
views:
  - name: Recent sessions
    type: table
    order:
      - date DESC
    properties:
      - file.name
      - date
      - topics
  - name: Topics
    type: cards
    filters:
      tag: brain-topic
  - name: Decisions
    type: table
    filters:
      tag: brain-decision
    order:
      - decision_id ASC
    properties:
      - decision_id
      - status
      - date
      - file.name
```

This is illustrative — the actual schema is owned by `@obsidian-bases`. Confirm syntax with that skill before writing.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall