Skip to content

vt-c-openbrain-capture

Proactively capture factually-relevant knowledge (external-stakeholder facts, decisions + rationale, durable domain/process knowledge) to Open Brain during a session, sanitized and deduplicated. Judgment-driven, opt-in per project. Auto-stores clearly-relevant facts; asks before turn-end when relevance is unclear.

Plugin: core-standards
Category: Other
Command: /vt-c-openbrain-capture

openbrain-capture Skill

Purpose: Make Claude proactively store the core facts of a session in Open Brain — so Open Brain becomes a reliable single research surface — while never leaking credentials or PII and never duplicating what is already stored or what the session journal owns.

When to Use

Once a project has opted in, consider a capture when any of these triggers fire (the triggers are prose here, not a frontmatter key — that key is not recognized and would be silently ignored):

  • A new external-stakeholder fact appears (partner/customer, from email/meeting/transcript).
  • A decision is made together with its rationale.
  • Durable domain/process knowledge, a number, or a convention is established.
  • Before ending a turn that produced information of unclear relevance.

This is the always-on judgment layer above SPEC-089's fixed-point capture. SPEC-089 captures at ~17 specific workflow points; this skill captures whenever relevant information appears anywhere in a session. Both write to the same store via capture_thought, so search_thoughts dedup sees everything (Decision 2).

Opt-in per project. This skill is dormant until a project opts in — see How to enable. There is no always-on global rule; §10a in the managed CLAUDE.defaults.md stays the only global sanitization guarantee (Decision 1).

Execution

Once a project has opted in, evaluate — at each turn that produced or received information, and again before ending the turn — whether anything crossed the capture bar below.

Step 1 — Classify the content type first (Decision 5, EC-4)

Route each candidate to exactly one owner. Do not double-record.

Content Owner Why
Session narrative, in-context reasoning, "what I did / why I did it here" /vt-c-session-journal Project-scoped, ephemeral session record.
Durable external-stakeholder facts, domain/process knowledge, cross-session research Open Brain (this skill) Cross-session research surface.
A decision that also carries reusable domain value beyond this session Both — but only with an explicit added-value reason Cross-posting is opt-in, never the default.

If the session journal already owns it, stop — do not also capture here.

Step 2 — Apply the relevance heuristic (FR-3, NFR-3)

Capture (high signal): - External-stakeholder facts — partner/customer positions, commitments, constraints, dates ("Partner ACME renews Q3 at 12% uplift"). - Decisions with their rationale ("chose tiered pricing because …"). - Durable domain/process knowledge, conventions, key numbers, thresholds.

Skip (noise — NFR-3 keeps the store high-signal): - Chit-chat, acknowledgements, restated questions. - Procedural how-to steps and command invocations. - Anything already captured (see Step 4 dedup). - Trivia. When in doubt about triviality, skip. When in doubt about relevance, ask (Step 3).

Step 3 — Two-tier decision: auto vs ask (Decision 3, US-1 / US-2 / FR-2)

  • Auto-store only clearly relevant facts / decisions+rationale / durable domain knowledge.
  • Ask before ending the turn when relevance is genuinely ambiguous — prompt, in the user's language, e.g. "Soll ich das in OpenBrain ablegen?" — via AskUserQuestion. Never silently drop an ambiguous-but-possibly-important fact; never force-store trivia.
  • Never auto-store trivia — it dilutes the store's signal (NFR-3) and trains the user to distrust and ignore captures.

This tier rule is checkable (SC-2): a high-confidence fact is stored; an ambiguous one does trigger the prompt.

Step 4 — Deduplicate before storing (Decision 8, FR-6, EC-2)

Two-layer dedup — an exact key for the same fact re-seen this session, then a semantic search for near-duplicates already in the store:

  1. Exact (key): compute the normalized dedup key printf '%s' "<project-slug> <fact gist>" | ~/.claude/skills/vt-c-openbrain-capture/scripts/sanitize-capture.sh --key and keep a per-session set of keys already captured. If this key is already in the set → suppress the store (exact re-capture, EC-2). The key is deterministic, so the same fact always collapses to the same value.
  2. Semantic: otherwise run search_thoughts on the project slug + fact gist. If a close match already exists → suppress the store; optionally note the existing entry to the user.
  3. Otherwise continue to Step 5, and add this key to the session set once stored.

Step 5 — Data-minimization: facts-only, source-linked, NO verbatim (Decision 6)

This is the gate a regex cannot enforce, so it lives here, not in the sanitizer:

  • Store a distilled core fact, not the raw email/file/transcript. Never paste verbatim external content (whole emails, whole files, long quotes).
  • Attach a source reference (which email / meeting / file / decision), not the source's body.
  • If the fact itself is confidential enough that even distilled it should not leave the repo, omit it — the sanitizer does not screen the fact payload; opt-in scope + this gate do.

Step 6 — Sanitize, then capture (NFR-2, US-3, Principle I: sanitize before every capture)

Every capture MUST be piped through the sanitizer before it reaches capture_thought:

CLEANED="$(printf '%s' "$FACT_WITH_TAGS" | \
  ~/.claude/skills/vt-c-openbrain-capture/scripts/sanitize-capture.sh)"
# optional build-time self-audit that nothing sensitive survived:
# printf '%s' "$FACT_WITH_TAGS" | .../sanitize-capture.sh --check

Then store $CLEANED via capture_thought (Open Brain MCP). The sanitizer strips the four mechanical §10a classes: credentials, username-bearing absolute paths, env-var values, and connection strings / internal hostnames.

Capture format (Decision 6 / 7) — a distilled fact string carrying inline attribution:

<distilled core fact>. Project: <project-slug>. Source: <email|meeting|decision|domain>.

Example (after sanitization):

Partner ACME renews Q3 at 12% uplift; chose tiered pricing to protect margin.
Project: visimatch. Source: meeting.

The Project: and Source: tags are free-text and semantic-searchable via search_thoughts (they are not a structured filter field — an accepted consequence of the Decision-2 single-store choice).

Edge Cases

  • EC-1 — Open Brain MCP unavailable in the session: skip capture silently. Never fail the turn because the tool is absent.
  • EC-3 — item is entirely sensitive and cannot be safely distilled: omit it entirely rather than storing a partially-scrubbed version.
  • EC-4 — overlaps a session-journal entry: Step 1 routing decides the single owner; dedup (Step 4) suppresses a genuine duplicate.

Boundaries & honest residuals

  • The sanitizer is advisory on this path, not mechanically forced. NFR-1 forbids a deterministic hook (capture is a judgment task), so Step 6's pipe is mandated here but not enforced by machinery. Principle I ("sanitize before every capture") is satisfied on the skill path; the residual is bounded by opt-in scope (Decision 1) and facts-only (Decision 6).
  • The sanitizer cannot screen the distilled fact itself. "Partner X won't renew over pricing" is confidential yet passes every regex. That residual is carried by opt-in scope + Step 5, not by sanitize-capture.sh. Do not overclaim the sanitizer closes it.
  • Dedup is best-effort. search_thoughts is semantic; a heavily reworded fact can slip the match and store a near-duplicate. Re-running the same fact (EC-2) is the reliable dedup path.

How to enable

This skill ships dormant. A project opts in by dropping the provided rule into its project rules directory:

  1. Copy assets/openbrain-capture.rule.md into the project's .claude/rules/ directory.
  2. That rule invokes this skill for the project's sessions; remove the file to opt back out.
  3. Security-conscious repos stay off by default — enabling is a deliberate, auditable act.

See assets/openbrain-capture.rule.md for the drop-in template and enable/disable steps.

Success Criteria

  • bash plugins/core-standards/tests/test-openbrain-sanitization.sh — seeded-secret gate (NFR-2 / SC-3): proves no credential / PII / absolute-user-path survives sanitization while a wanted fact (and business metrics) do, the --check self-audit has teeth, sanitize stays at parity with secret-scanner.sh, and the dedup key is deterministic.