Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
Variant 1: Boundary interceptor with a namespaced _meta error envelope
- Approach: Add one registry module (frozen
MCP_ERROR_CODESobject, members list, guard, census test) and teach the two existing choke points to read a structuralreadonly code: stringoff any thrown error:toolErrorin server.ts attaches_meta["open-second-brain/error"] = {code, surface}next to the unchanged text body, and the MCPError builder copies the code intodata.codewhere a wrapping site (skill-tools rewrap,searchErrorToMcp) currently drops it. Throws without a code get the single registeredunclassifiedcode, andwithProgressRefusalis changed to merge_metainstead of replacing it. Rerank liveness joins the same release as a newRETRIEVAL_DEGRADATIONmemberrerank_skippedwhose detail is an identifier reason (provider_sunset,provider_unreachable,provider_error), fed by a rerank sunset survey that reuses the generic classifier fromembeddings/sunset.ts, adoctor/rerank-sunset-check.tsregistered in the exit census, and a cache-write bypass when that degradation is present. - Trade-offs:
- Pro: two change points cover all ~28 coded classes and every surface at once; no per-tool rewiring.
- Pro: text bodies and existing
data.codespellings stay byte-identical;_metapasses strict SDK result validation, mirroring the existing progress key. - Pro: the census test forces each listed code to a live producer and surfaces casing drift as data, without rewriting it.
- Pro: rerank skip stays inside the closed-vocabulary convention and flows into
search --explainfor free. - Con: mixed snake/kebab/UPPER casing is inherited onto the wire as-is; a normalization pass would be a second release.
- Con: structural duck-typing can pick up unrelated
codefields (NodeENOENTstrings); needs the guard to whitelist registry members and route the rest tounclassified. - Con: the
_metamerge in progress.ts is a behavior change that needs its own test.
- Complexity: medium
- Risk: low
Variant 2: Shared CodedError base class, codes normalized at the source
- Approach: Introduce an abstract
BrainErrorbase in core carryingcode,surface, andretryable, migrate the ~28 existing coded classes to extend it, and add newWorkspaceErrorandWriteSessionErrorclasses with their own enumerated vocabularies for the currently prose-only paths. The server detects errors byinstanceofand emits bothdata.code(channel A) and the_metaenvelope (channel B); awirealias table keeps already-emitted spellings while new codes use one canonical casing. Rerank becomes a typedRerankOutcomereturned by post-rank, consumed by the trail as a degradation member, by doctor, and by the cache layer to skip caching degraded results. - Trade-offs:
- Pro: strongest typing and one place to answer "what codes exist";
retryablelets clients branch on retry versus fallback without a second table. - Pro: workspace and write-session refusals gain real codes instead of
unclassified. - Pro: the typed
RerankOutcomecleanly separates "did not run" from "ran and failed" for the explain and doctor surfaces. - Con: touches 28 classes across core; large diff with real chances of altering a message string or a pinned
toBetext. - Con:
instanceofis brittle across module duplication and the Hermes plugin boundary; structural detection would still be needed as a fallback. - Con: two vocabularies (canonical plus wire aliases) is a second convention the constraints warn against.
- Con: converting write-session prose refusals to typed errors risks moving them between channels and changing wire shape for clients.
- Pro: strongest typing and one place to answer "what codes exist";
- Complexity: large
- Risk: medium
Variant 3: Per-surface mapping tables extending the search precedent
- Approach: Keep the server untouched and replicate the
searchErrorToMcppattern per tool module:skillErrorToMcp,workspaceErrorToMcp,writeSessionErrorToMcp, each with a sibling*_ERROR_CODESfrozen vocabulary and each producing anMCPErrorwithdata.code. Unmapped throws stay on the prose-only channel B path. Rerank liveness is reported as its ownrerank: {ran, skipped_reason}block in the retrieval trail rather than a degradation member, with a doctor section that reads the provider registry and a static rerank sunset table. - Trade-offs:
- Pro: smallest server-side change; each mapping is explicit and locally reviewable, exactly like the existing search module.
- Pro: no duck-typing, no
_metamerge change in progress.ts. - Con: N mapping sites drift independently; a new tool module ships uncoded unless someone remembers the mapper, which is the gap that produced today's state.
- Con: moving skill and workspace errors from a
isErrortool result to a JSON-RPC error changes the wire shape clients already see, even though message text is unchanged. - Con: a separate
reranktrail block diverges from the closedRETRIEVAL_DEGRADATIONconvention and does not surface in existing degradation-driven output paths. - Con: still leaves the cached-degraded-rerank problem unless handled separately.
- Complexity: medium
- Risk: medium
Recommended: Variant 1
Rationale: It satisfies every hard constraint directly: text bodies stay byte-identical, no error payload touches structuredContent, existing data.code spellings are preserved, and the registry census enforces a live producer per code. Two interception points plus the existing namespaced _meta precedent deliver cross-surface coverage without the 28-class migration of Variant 2 or the drift-prone per-module mappers and wire-shape change of Variant 3, and the rerank work lands inside the closed-vocabulary and sunset-survey conventions the repository already uses.