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.
TypeScript
/**
* Snake_case wire serializers shared by the CLI (`o2b search`) and MCP
* (`brain_search`) surfaces, so the two output contracts cannot drift
* field-by-field the way independently hand-written copies do.
*/
import type { StampMismatch } from "../integrity/stamp.ts";
import type {
ChunkWindowCensus,
EmbedderRecordCensus,
IndexStatusSnapshot,
PendingVectorCensus,
SearchCard,
VisibilityHonestyFinding,
} from "./types.ts";
/**
* Wire shape for a stamp comparison. `recorded` is what the index
* wrote, `runtime` what this build would write; a `recorded` of `null`
* is a field the index never stamped. Shared by `o2b search check`,
* `o2b search status --json` and the MCP `search.*` status block, so
* one drift cannot be described three ways.
*/
export function serializeStampMismatches(
mismatches: ReadonlyArray<StampMismatch>,
): Array<Record<string, unknown>> {
return mismatches.map((m) => ({
field: m.field,
recorded: m.expected,
runtime: m.actual,
}));
}
/** Layer-1 card projection - identical shape on both the CLI and MCP surfaces. */
export function serializeSearchCard(c: SearchCard): Record<string, unknown> {
return {
path: c.path,
title: c.title,
score: c.score,
snippet: c.snippet,
pointer: c.pointer,
reasons: c.reasons,
document_id: c.documentId,
chunk_id: c.chunkId,
...(c.origin !== undefined ? { origin: c.origin } : {}),
// Exact-duplicate merge (task D): the `path:Lstart-Lend` pointers the
// surviving card was folded from. Absent, never null, when nothing
// was merged - the card carries the key only in that case.
...(c.duplicatePointers !== undefined ? { duplicate_pointers: c.duplicatePointers } : {}),
};
}
/**
* Wire shape of the pending-vector census (nothing-writes-silently,
* unit A). Emitted in EVERY state, which is what separates it from the
* drift fields on the same report: those say nothing when there is
* nothing to say, while a census whose count could not be taken has
* something to say precisely then. The unrecorded arm carries no
* `pending` key at all, so a consumer cannot read a default zero out of
* a state that measured nothing.
*/
export function serializePendingVectorCensus(census: PendingVectorCensus): Record<string, unknown> {
if (census.verdict === "unrecorded") {
return { verdict: census.verdict, reason: census.reason };
}
return { verdict: census.verdict, pending: census.pending, chunks: census.chunks };
}
/**
* Wire shape of the record-vs-data embedder audit
* (nothing-writes-silently, unit G). Emitted in every state on the same
* terms as the pending-vector census beside it, and the `unrecorded`
* arm carries no numbers at all - there is no dimension to report when
* nothing was compared.
*
* `reconciliation` keeps the shared vocabulary's own field names, so a
* consumer reading this audit and one reading the import census read
* the same three words for the same three quantities.
*/
export function serializeEmbedderRecordCensus(
census: EmbedderRecordCensus,
): Record<string, unknown> {
if (census.verdict === "unrecorded") {
return { verdict: census.verdict, reason: census.reason };
}
return {
verdict: census.verdict,
outcome: census.outcome,
recorded_dimension: census.recordedDimension,
stored_dimensions: census.storedDimensions,
vec_declared_width: census.vecDeclaredWidth,
reconciliation: {
attempted: census.reconciliation.attempted,
found: census.reconciliation.found,
missing: census.reconciliation.missing,
},
};
}
/**
* Wire shape of the visibility honesty finding (nothing-writes-silently,
* unit H, form B). Present only when the caller already established
* there is something to report - `search check` omits the key entirely
* rather than serializing a zero-count finding, the same convention
* `embeddingAbi` uses for a matching store.
*/
export function serializeVisibilityHonestyFinding(
finding: VisibilityHonestyFinding,
): Record<string, unknown> {
return {
excluded_surface_count: finding.excludedSurfaceCount,
total_surface_count: finding.totalSurfaceCount,
reserved_document_count: finding.reservedDocumentCount,
unmeasured_document_count: finding.unmeasuredDocumentCount,
};
}
/**
* Wire shape of an oversize-chunk census verdict, shared by the index
* run's report and the status snapshot so the two cannot describe one
* verdict with different field names.
*
* No `next_command` here: whether a surface names an exit beside a
* verdict is that surface's decision, and the index run spreads its own
* on top. Baking one in would put a command on the status field the
* ruling deliberately keeps out of the warning channel.
*/
export function serializeChunkWindowCensus(census: ChunkWindowCensus): Record<string, unknown> {
if (census.verdict === "window-undeclared") {
return {
verdict: census.verdict,
model: census.model,
chunks_measured: census.chunksMeasured,
};
}
if (census.verdict === "estimate-undecided") {
// No `chunks_over_window` here on the same terms the undeclared
// verdict carries no window: nothing was proved over it.
return {
verdict: census.verdict,
model: census.model,
window_tokens: census.windowTokens,
chunks_undecided: census.chunksUndecided,
chunks_measured: census.chunksMeasured,
};
}
return {
verdict: census.verdict,
model: census.model,
window_tokens: census.windowTokens,
chunks_over_window: census.chunksOverWindow,
// Absent, never zero - an index the estimate decided in full emits
// the record it emitted before the undecided band existed.
...(census.chunksUndecided === undefined ? {} : { chunks_undecided: census.chunksUndecided }),
chunks_measured: census.chunksMeasured,
};
}
/**
* Full snake_case index-status mapping. The CLI surfaces every field; the
* MCP block (token-budget conscious) picks a subset of the returned object
* rather than re-declaring the mapping.
*/
export function serializeIndexStatus(s: IndexStatusSnapshot): Record<string, unknown> {
return {
index_path: s.indexPath,
exists: s.exists,
schema_version: s.schemaVersion,
documents: s.documents,
chunks: s.chunks,
embeddings: s.embeddings,
stale_embeddings: s.staleEmbeddings,
embedding_model: s.embeddingModel,
embedding_dimension: s.embeddingDimension,
embedding_signature: s.embeddingSignature,
estimated_refresh_cost_usd: s.estimatedRefreshCostUsd,
refresh_price_source: s.refreshPriceSource,
vec_extension: s.vecExtension,
semantic_enabled: s.semanticEnabled,
embedding_key_present: s.embeddingKeyPresent,
last_indexed_at: s.lastIndexedAt,
last_full_index_at: s.lastFullIndexAt,
// Emitted only on drift, so a matching store's JSON is byte-identical
// to the pre-gate output (context-integrity-gates, Unit E).
...(s.embeddingAbi.length > 0
? { embedding_abi: serializeStampMismatches(s.embeddingAbi) }
: {}),
// Emitted only when the oversize-chunk census could NOT run, on the
// same terms and for the same reason: a status over a model with a
// declared window is byte-identical to the pre-census output. The
// two verdicts the census reaches by measuring - overflow, and the
// band its estimate cannot decide - are not here; both are warnings,
// because both name a command.
...(s.chunkWindowUndeclared === undefined
? {}
: { chunk_window_undeclared: serializeChunkWindowCensus(s.chunkWindowUndeclared) }),
// The same terms as the census field above: present only when the
// index actually holds chunks under the active key, so a status with
// nothing held serializes the bytes it emitted before this existed.
...(s.heldChunks === undefined
? {}
: {
held_chunks: {
total: s.heldChunks.total,
items: s.heldChunks.items.map((item) => ({
path: item.path,
chunk_index: item.chunkIndex,
estimated_tokens: item.estimatedTokens,
window_tokens: item.windowTokens,
reason: item.reason,
})),
},
}),
warnings: s.warnings,
};
}