/brain-memory

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, `outdated` if the artifact shows the rule itself is obsolete (one `outdated` event retires the preference on the next dream pass). 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 ha