curated-thoughts-ops
Use when Curated Thoughts looks broken — sidecar unreachable, vault errors, tier mismatches, or failed MCP tool calls.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 2
- Forks
- 1
01 前言 Front Matter
- name
- curated-thoughts-ops
- description
- Use when Curated Thoughts looks broken — sidecar unreachable, vault errors, tier mismatches, or failed MCP tool calls.
03 SKILL.md 正文
Curated Thoughts Operations
Diagnose and report problems with a Curated Thoughts (CT) integration — for maintainers and power users. Scope is diagnosis and safe routing, never repair by out-of-band writes.
First move: run the doctor
Run the plugin's doctor (node lib/scripts/ct_doctor.js check) before
guessing. It reports PASS / WARN / FAIL per check, each with a fix hint:
- Sidecar binary —
curated-thoughts-mcpon PATH, or in this platform's install location (macOS app bundle, Linux/usr/bin, Windows Programs dir). FAIL here invalidates everything downstream. - Sidecar identity — the binary is an installed sidecar, not a build
output from a source checkout (
target/,tools/). A same-named dev build shadowing the installed one gives two servers on one brain. - Sidecar reachable —
tools/listover MCP; prints the tool count, which is what determines the capability tier. WARN at 8 tools means the write path is dormant (curated_add_wisdomabsent) — an older sidecar, not breakage. - Brain directory — the directory holding
brain.dbandconfig.json, resolved exactly as Curated Thoughts resolves it:CURATED_BRAIN_DIR, defaulting to~/.brain. - Vault — the documents tree named by
vault_pathinside config.json. This is a different thing from the brain directory, and it is machine-specific: a brain imported from another machine almost always has avault_paththat does not exist here. - Embedding backend — the configured embedding host responds. WARN/FAIL degrades semantic search but the sidecar may still answer.
- Harness registration — the
mcp["curated-thoughts"]entry and the loader file~/.config/opencode/plugins/curated-thoughts.jspointing at a readable payload, plus the three skill directories under~/.config/opencode/skills/, so the tools and skills actually load. - Import pre-flight — reads the engine version and censuses every
llm_wiki_entries.source_ref. See below; this is the check that protects an imported graph. - Version compat — best-effort sidecar version against
shared/compat.yaml. Undiscoverable on most platforms, which is fine and reported as PASS; it only warns when a discoverable version disagrees with the live tool count (the signature of a stale sidecar process).
Exit code 0 = all PASS, 1 = any FAIL, 2 = WARNs but no FAIL.
Import pre-flight: when a brain arrives from another machine
Curated Thoughts is memory-in-a-box, so a brain is meant to travel. Two things can destroy an imported graph before an agent reads a word of it, and the pre-flight check reports both.
The engine rewrites source_ref. core-llm-wiki's setup() runs an
unconditional back-rewrite. findRowsForSourceRefMigration() selects a row if
any of five predicates holds — TRIM(source_ref) != source_ref,
INSTR '/', INSTR '\', INSTR CHAR(0), or the GLOB
'*[^-A-Za-z0-9._ ]*' — then strips it through normalizeSourceRef. Every
JSON blob qualifies, destroying the proposal_id needed for retraction and the
evidence array behind provenance display. It fires on every app launch, over
the shared brain.db. The current engine pin, 7.1.0, still mangles.
Note the GLOB is not the whole selector: space is inside the keep-set, so a
whitespace-padded ref clears the GLOB and is still caught by TRIM.
Detection is a positive token-shape test (§2.5.1): a non-NULL row is
damaged iff its source_ref does not match ^librarian-[0-9a-f]{32}$. The
evidence… prefixes
drive recovery (§2.5.4), never detection.
The census is scoped to source_type = 'librarian_inferred', and this matters:
a legitimate document-sourced ref can itself reach the 255-char cap (long vault
paths normalize to exactly 255), so an unscoped shape test would report a
healthy brain as damaged. NULL refs are legitimate engine-era data, counted
separately as null_ref_count.
Verdicts:
- mangled → FAIL. Evidence already destroyed. Do not trust this graph's provenance. The V18 repair migration re-derives it (outbox-first, then proposal lookup) and exports before mutating.
- at_risk → FAIL. Rows still hold JSON or whitespace-padded refs; intact right now, destroyed at the next app launch. Do not open this brain with the desktop app until Curated Thoughts carries the PR #188 fix.
- token with no
librarian_evidencetable → FAIL. The entries travelled, their provenance did not — a broken import contract. - token rows missing individual evidence rows → WARN. §2.3 treats these as still-grounded and never auto-purges them, so nothing is being deleted; provenance display and retraction just cannot resolve them.
- token with evidence → PASS.
unanchored=1rows are expected under §2.4 Phase 1 write-with-flag, not damage.
Export whole brains, not table subsets. §2.5.5 defines a supported export
as brain-complete — entries, evidence, chunks and proposals. A partial export
made legitimately-anchored facts look like orphans, so the repair migration now
asserts a complete chunk schema before any orphan deletion and skips it loudly
if the assertion fails. shared/compat.yaml lists what must travel.
Registration in OpenCode
The sidecar is registered as mcp["curated-thoughts"] in the global
~/.config/opencode/opencode.json[c] with --mcp arguments, and the plugin
loads from the loader file
~/.config/opencode/plugins/curated-thoughts.js, which points at the payload
directory under ${XDG_DATA_HOME:-~/.local/share}/curated-thoughts/opencode/.
All three pieces matter: without the mcp entry there are no tools, without
the loader file the health snapshot never loads, and without the skill
directories under ~/.config/opencode/skills/ the skills never appear.
scripts/install.sh prints the proposed merge by default and only writes it
under CT_INSTALL_EDIT=1 — it merges the mcp entry only if absent, never
overwrites an existing entry, and never touches the plugin config array.
If both a plugin-installed copy and a loose
~/.config/opencode/skills/curated-thoughts* skill exist, remove the loose
copy to avoid skill collisions (the installer warns; it never deletes user
files). Verify with node lib/scripts/ct_doctor.js check: check 7 reports
UNKNOWN when an entry is simply absent from the global config (OpenCode also
merges project and managed config the doctor cannot see) and FAILs only on
local, unambiguous problems such as a loader pointing at a missing payload.
Safe routing when things fail
- Report, don't improvise. Capture the exact tool error, the doctor check that failed, and the tool count. Sidecar errors mean route around: use non-CT sources for this session and surface the error to the user.
- Never write out-of-band. Fixing a vault problem by hand-editing files or opening the database directly corrupts indexing and embeddings. The sidecar is the only writer, always.
- Tier mismatch ≠ failure. A WARN on tool count just means the sidecar
version predates the write path; read tools still work. Check
shared/compat.yamlfor the expected surface at that version. - Fail open. A down sidecar must not block a session; state it plainly and continue without CT memory.
04 同仓库更多 Skills
curated-thoughts-usage
Host-contract fixture skill (curated-thoughts-usage); verifies OpenCode discovers skills from ~/.config/opencode/skills.
curated-thoughts-sidecar
Host-contract fixture skill (curated-thoughts-sidecar); verifies OpenCode discovers skills from ~/.config/opencode/skills.
curated-thoughts-ops
Host-contract fixture skill (curated-thoughts-ops); verifies OpenCode discovers skills from ~/.config/opencode/skills.
curated-thoughts-usage
Use when a harness session needs Curated Thoughts memory — search, recall, or wisdom writes via the CT MCP sidecar.
curated-thoughts-sidecar
Use when managing the Curated Thoughts MCP sidecar — respawns, staleness, upgrades, or same-named binary confusion.
curated-thoughts-usage
Use when a harness session needs Curated Thoughts memory — search, recall, or wisdom writes via the CT MCP sidecar.