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.
Stable error codes at the MCP boundary - variants (audit trail)
Consultant: Claude Code (claude -p, primary), prompt in cli-output/prompt.md, raw output in cli-output/claude.md. It returned three parseable variants and exited 0, so the Codex fallback was not run.
Variants, verbatim
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.
Orchestrator decision
Variant 1 is taken, as the consultant recommended. It is the only variant that keeps text bodies byte-identical, keeps every error payload out of structuredContent, and covers every tool through the two seams in server.ts instead of relying on each module remembering a mapper (the failure mode that produced today's state, which Variant 3 repeats). Variant 2 was rejected because migrating about 28 core classes to a new base risks altering pinned message strings and adds a canonical-plus-alias second convention; Variant 3 was rejected because it leaves every unmapped throw prose-only, moves skill and workspace errors between channels, and puts rerank liveness outside the closed RETRIEVAL_DEGRADATION vocabulary.
Five parts of Variant 1 are overridden, with reasons recorded in design.md ("Orchestrator overrides of the consultant's Variant 1"):
- An unclassified error maps to the existing explicit member
internal_errorand is logged by error name; nounclassifiedboundary code is added, because that would be a blank code by another name. - Classification is by
instanceofover a closed table (with a boundedcausewalk), not by structurally reading any.code, which would leak NodeENOENTand similar unregistered tokens. - Rerank gets two kebab-case members,
rerank-provider-unavailable(withdetail.categoryfrom a closedRERANK_FAILURE_CATEGORY) andrerank-model-sunset, instead of one snake-casererank_skipped: the vocabulary is kebab throughout and names the cause in the code. - The
_metapayload is{ schema, code }with nosurfacemember. - The rerank code is documented as appearing in
--jsonand MCPbrain_search, not insearch --explain(premise correction indesign.md).
Orchestrator decisions taken before the consultant ran, and honoured by the chosen variant: channel B code in _meta["open-second-brain/error"] with the text unchanged; channel A error.data.code with the default derived at the single builder; withProgressRefusal merges _meta; one closed registry importing the core vocabularies unchanged; a sunset survey with entries only where a source was read; a config-only doctor check registered where the census tests demand; a rerank endpoint failure not written to the query cache; the missing hybrid-deadline-exceeded row added to docs/cli-reference.md; HTTP 429, the OpenClaw envelope and missing-key-as-degradation out of scope.