---
name: brain-memory
description: Record taste signals and apply-evidence events into the Brain observing-memory layer of Open Second Brain. INVOKE this skill (and call `brain_feedback`) the moment the user expresses a preference, dislike, correction, or rule in dialogue — "don't do X", "use A instead of B", "I prefer Y", "X is wrong here", or any explicit imperative that should outlive the current turn. SEPARATELY invoke (and call `brain_apply_evidence`) right after you produce a durable artifact (code shipped, file written, content drafted, config change) and at least one preference in `Brain/preferences/` has a `scope` that plausibly applies — record whether you `applied` or `violated` it. SKIP only for casual chat, exploration without a stated rule, read-only inspection, and trivial edits. When a preference plausibly applies but you are unsure, RECORD with `note: "speculative; <reason>"` rather than skipping — the dream pass discards single-event speculative entries that do not recur, so coverage costs less than missing the signal. WRITE the `principle` and `note` fields in the same natural language the user has been speaking in this session; technical identifiers (`topic` slug, `pref_id`, `scope`) stay English.
---

# Brain Memory

Brain is the agent-writable observing-memory layer of Open Second Brain. It accumulates user preferences from real signals and learns from real applications. Your job is to (a) record taste signals as they arrive in conversation, and (b) record whether you applied or violated active preferences each time you produce a durable artifact in a relevant scope. The deterministic `dream` pass turns repeat signals into rules and retires what stops being applied.

## When to call `brain_feedback`

Call **once per taste signal** the user (or a teammate agent) expresses. Concrete triggers:

- Explicit corrections: "don't do X", "stop doing Y", "use A instead of B".
- Stated preferences with outlasting reach: "I prefer X over Y", "expand acronyms on first use", "always include a CHANGELOG entry".
- Pushback on a specific artifact you produced that targets a *rule*, not a one-off ("this commit message is wrong — use imperative voice").
- A teammate agent or human describing a process rule in chat that should survive future sessions.

Parameters:

- `topic`: stable kebab-slug for the rule (`no-internal-abbrev`, `imperative-prompts`, `prefer-typed-errors`). Reuse existing slugs — call `brain_query --topic <slug>` first if you are unsure. New slugs only when no existing one fits.
- `signal`: `positive` when the principle stated is the rule to follow, `negative` when the principle stated is what to avoid.
- `principle`: one-line, imperative-voice agent-readable formulation. "Do not use internal abbreviations in user-facing copy unless explained first."
- `agent`: your runtime identity (`claude`, `codex`, `hermes`, OpenClaw plugin name, or the human's name if you are recording on their behalf).

Optional but **strongly recommended**:

- `raw`: the verbatim quote that triggered the signal. Without it the
  signal file lands without a `## Raw` body — counters keep working,
  but the audit trail loses the original phrasing. Pass the exact
  sentence the user said (or the exact line of the artifact the
  signal is about). v0.10.1 dropped the `_(not provided)_` placeholder
  precisely so an absent `raw` is now visible: the file simply has no
  body, which should be the rare case, not the norm.

Optional:

- `scope`: soft category for later application-scope matching — `writing`, `coding`, `process`, `design`, `infra`, `docs`. Pick the narrowest accurate one.
- `source`: array of wikilinks to the artifacts or notes that triggered the signal — `[[src/cli/main.ts]]`, `[[docs/release-notes/v0.11.0]]`. Improves later auditability.

The server creates `Brain/inbox/sig-<date>-<slug>.md` and resolves collisions deterministically.

## When to call `brain_apply_evidence`

Call **once per (preference, artifact) pair**, right after a durable artifact lands. A durable artifact is anything the user would re-find by searching the vault tomorrow: code shipped, config change, deployment touched, content drafted, instruction-file edit, design decision recorded. Trivial edits (typo fix, pure formatting) do not qualify.

Discover applicable preferences first. Options:

- Read `Brain/preferences/` directly — files `pref-*.md` are tiny.
- Call `brain_query --topic <slug>` to fetch a topic-scoped slice.
- Call `brain_query --preference <id>` for a single preference plus its evidence trail.

Parameters:

- `pref_id`: id of the preference you are recording against (`pref-no-internal-abbrev`).
- `artifact`: wikilink identifying what you produced — `[[src/cli/main.ts]]`, `[[docs/release-notes/v0.11.0.md]]`, `[[Brain/preferences/pref-no-internal-abbrev]]`. The wikilink resolves in Obsidian; use `#anchor` to point at a specific section when relevant.
- `result`: `applied` if the rule held in this artifact, `violated` if you (or another agent) broke it. Recording a `violated` event is not a failure — it is what trains the system.
- `agent`: your runtime identity.

Optional:

- `note`: one-line context if useful ("expanded 'OSB' to 'Open Second Brain' on first use", "README diff still contained unexplained 'FT'").
- `note: "speculative; <reason>"` when the preference's `scope` plausibly applies but you are unsure (e.g. a `writing` rule against a docstring inside a source file). The dream pass filters single-event speculative records that do not recur — recording the uncertainty costs less than missing the signal.

`applied_count` and `violated_count` on the preference are recomputed by `dream`; you write only the per-event evidence record.

## When NOT to call

- Casual chat, banter, acknowledgements ("ok", "got it").
- Brainstorming, idea exploration, design discussion that has not concluded in a rule.
- Read-only inspection (running `git log`, `o2b status`, `vault_health`).
- Trivial edits (typo, whitespace, formatting only).

When a preference *might* apply but you are unsure, do not skip — record the event with `note: "speculative; <reason>"` so the dream pass sees the signal. A one-off speculative entry that does not recur is filtered out by dream; the cost of writing is one MCP call, the cost of missing is a silent gap in the evidence trail. The "do not call" list above is exhaustive on purpose: outside those four bullets, record.

## Language

The `principle` and `note` fields must match the **natural language the user has been speaking in this session**. Technical identifiers stay English regardless: `topic` slug, `scope`, `pref_id`, `result`, `agent` name, file paths, library names, error messages quoted from logs. This mirrors the policy from the `agent-event-log` skill.

Mixed-language session → match the most recent user message at the time the artifact landed.

## Self-discovery

- `brain_query --preference pref-foo` — full preference frontmatter + every evidence record in `Brain/log/*` referencing it.
- `brain_query --topic <slug>` — all artifacts (signals, current preference, retired ones) by topic.
- `brain_query --since <ISO>` — recent log events of any type.
- `brain_brief` (`view="digest"`) — daily summary of what `dream` did: new unconfirmed, confirmations, retirements, confidence shifts, contradictions.

## CLI fallback

When MCP is unavailable:

```bash
o2b brain feedback \
  --topic no-internal-abbrev \
  --signal negative \
  --principle "Do not use internal abbreviations in user-facing copy unless explained first" \
  --agent claude

o2b brain apply-evidence \
  --pref pref-no-internal-abbrev \
  --artifact "[[src/cli/main.ts#L120]]" \
  --result applied \
  --agent claude
```

## Rules

- One call per signal, one call per (preference, artifact) pair.
- Imperative voice in `principle`. Specific over generic.
- Never include secrets, tokens, API keys, or credentials in `principle`, `note`, or `source`.
- Do not edit historical signals, preferences, or log entries by hand — the `dream` pass is the only writer for transitions.
- Do not write into `Brain/.snapshots/` or `Brain/retired/` directly — those are managed by `dream` and `o2b brain reject` only.
- `o2b brain reject` requires `--reason <text>` from v0.10.1 onward. The reason is persisted on the retired file as `user_rejected_reason`. The next dream pass will mark any future signal on the same `(topic, scope)` as `signal-suppressed` and move it straight to `processed/` — do not re-record the same signal hoping it will re-grow into a preference. If you genuinely disagree with a past reject, raise it with the user; do not route around it via `brain_feedback`.

## Examples — good vs bad

These four pairs calibrate what makes a recorded signal useful versus
noise. The form of the entry matters as much as the timing — a vague
`principle` clogs the dream pass; a precise one trains it.

**Bad:** `principle: "Write good commits"`
**Good:** `principle: "Use imperative voice in commit subjects; describe what the commit does, not what was done"`
*Why:* the bad form is unenforceable — no future signal can reasonably mark an artifact as "applied" or "violated" against it. The good form names a checkable behaviour.

**Bad:** `principle: "Be careful with secrets"`
**Good:** `principle: "Do not commit .env, credentials, or API keys; route them through environment variables"`
*Why:* the bad form is a vibe. The good form gives the agent a concrete list of patterns to spot in a diff.

**Bad:** `topic: "stuff"`
**Good:** `topic: "no-internal-abbrev"`
*Why:* topic is the stable bucket future signals join. A generic slug collects unrelated rules; a precise one keeps the cluster meaningful and lets `brain_query --topic <slug>` return a focused slice.

**Bad:** `note: "fixed it"`
**Good:** `note: "expanded 'OSB' to 'Open Second Brain' on first use — README diff still carried the abbreviation, would have confused a new reader"`
*Why:* notes survive the artifact. Without the "why" line you cannot tell in three months whether a violation was a regression or a deliberate change.

## Fallback capture surfaces

When no agent is in the loop at the moment the rule is formed, the
user can write an `@osb` marker directly into any vault markdown
file — a Daily note, a project plan, a self-chat scratchpad. The
operator runs `o2b brain scan-inline` later to capture every marker
into `Brain/inbox/`. Two shapes are recognised:

```text
@osb feedback negative topic=mocking principle="don't mock DB in integration tests" scope=testing
```

````markdown
```osb
kind: feedback
signal: negative
topic: mocking
principle: don't mock DB in integration tests
scope: testing
```
````

This is a fallback path, not the default. When you (the agent) hear
a preference live, call `brain_feedback` directly — the inline
marker exists for situations where MCP is unavailable. After scan,
the source line becomes `@osb✓ [[sig-...]]` so a second run is
idempotent.

For session JSONLs (Claude / Codex / Hermes exports) the equivalent
operator command is `o2b brain import-session <path>` — it replays
both `@osb` markers in message text and live `brain_feedback`
tool_use calls. Useful for back-filling sessions where the agent
didn't make the call.
