brain-memory

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:

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:

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

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