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
/**
* What a caller is told when the vault is frozen, and where the refusal
* is recorded (who-wrote-what, Task C, Override 2).
*
* The freeze itself lives in `assertVaultIdentityForWrite`, below the
* Brain log module in the import graph. That guard therefore cannot
* append the event that says a write was refused - the edge back would
* close a cycle paid for by every consumer in the tree. So the record is
* made at the one seam that already knows both the refusal and who
* caused it: the MCP tool-dispatch boundary, which sees the thrown
* `VaultFrozenError`, the tool name, and the resolved agent identity.
*
* That is the right place for a second reason as well. The event is the
* AGENT-facing audit trail, and the agent side is the side a fleet
* freeze exists to hold: an operator lifting a freeze wants to know what
* kept trying to write while it was on.
*
* ## The refusal is structured, not prose
*
* A caller that can only regex a sentence cannot act on it. The `data`
* payload carries the four facts an agent needs - when the freeze was
* set, by whom, why, and the one command that lifts it - in the same
* shape `./reach-refusal.ts` uses for the boundary it guards.
*
* ## Recording never fails the refusal
*
* The write was already refused; the event is the record of it. A log
* append that throws must not turn a clean refusal into an internal
* error, so the append is best-effort and its failure is reported to the
* caller as an `audit_reason` on the same payload rather than swallowed.
* The refusal itself is the load-bearing answer.
*/
import { appendLogEvent } from "../core/brain/log.ts";
import { BRAIN_LOG_EVENT_KIND } from "../core/brain/types.ts";
import { isoSecond } from "../core/brain/time.ts";
import { VaultFrozenError } from "../core/brain/freeze-marker.ts";
import { MigrationInProgressError } from "../core/migration-gate.ts";
import { INVALID_PARAMS, MCPError } from "./protocol.ts";
/** The refusal token, named in the message and carried in `data`. */
export const VAULT_FROZEN_REFUSAL = "vault_frozen";
/** The structured payload attached to the refusal, for machine callers. */
export interface VaultFrozenData {
readonly code: typeof VAULT_FROZEN_REFUSAL;
readonly tool: string;
readonly frozen_at: string;
readonly by: string;
readonly reason: string;
readonly next_command: string;
/** Why the refusal reached no `write-refused` event, when it did not. */
readonly audit_reason?: string;
}
/**
* Record one `write-refused` event, and report why when it could not be
* recorded.
*
* Returns `null` on success and the reason on failure; see the module
* docblock for why a failure here is reported rather than raised.
*/
function recordRefusal(
vault: string,
tool: string,
agent: string,
err: VaultFrozenError,
): string | null {
try {
appendLogEvent(vault, {
timestamp: isoSecond(new Date()),
eventType: BRAIN_LOG_EVENT_KIND.writeRefused,
body: {
tool,
agent,
reason: err.reason,
frozen_at: err.frozen_at,
},
});
return null;
} catch (exc) {
return exc instanceof Error ? exc.message : String(exc);
}
}
/**
* Re-raise a typed write refusal ahead of any generic error mapping: a
* frozen vault, or a store migration running on this machine.
*
* The tool handlers wrap an unrecognised throw in an `INTERNAL_ERROR`
* MCPError, which is right for an I/O fault and wrong for these: each is a
* state an operator started, and a caller told "internal error" learns
* neither that nor the command that ends it. A converter calls this first
* so the typed refusal reaches the dispatch seam, which is where it
* becomes the structured refusal. Only the freeze is also recorded as a
* `write-refused` event (see {@link migrationInProgressRefusal}).
*
* A no-op for every other error, so a call site pays two `instanceof`.
*/
export function rethrowVaultFrozen(err: unknown): void {
if (err instanceof VaultFrozenError || err instanceof MigrationInProgressError) throw err;
}
/** The refusal token of a write refused by a running store migration. */
export const MIGRATION_IN_PROGRESS_REFUSAL = "migration_in_progress";
/** The structured payload of that refusal, the shape {@link VaultFrozenData} has. */
export interface MigrationInProgressData {
readonly code: typeof MIGRATION_IN_PROGRESS_REFUSAL;
readonly tool: string;
readonly run_id: string;
readonly since: string;
readonly next_command: string;
}
/**
* Turn a {@link MigrationInProgressError} into the refusal a caller
* receives: the same structured shape as a frozen vault's. Nothing is
* appended to the Brain log, which the migration is moving into the store
* at that moment; the gate itself is the record.
*/
export function migrationInProgressRefusal(tool: string, err: MigrationInProgressError): MCPError {
// The error's own message already names the resume command; it is in
// `next_command` for a caller that acts on the data.
const message = `${tool}: refused (${MIGRATION_IN_PROGRESS_REFUSAL}). ${err.message}.`;
const data: MigrationInProgressData = Object.freeze({
code: MIGRATION_IN_PROGRESS_REFUSAL,
tool,
run_id: err.gate.run_id,
since: err.gate.since,
next_command: err.next_command,
});
return new MCPError(INVALID_PARAMS, message, data);
}
/**
* Turn a {@link VaultFrozenError} into the refusal a caller receives,
* recording it on the way through.
*
* The caller's identity is passed as a THUNK because resolving it can
* itself throw on an unreadable config, and a broken config must not
* replace the freeze refusal with a different error - the freeze is what
* actually stopped the write. An unresolvable identity is recorded under
* {@link UNRESOLVED_AGENT}, which is a named absence rather than a guess.
*/
export function vaultFrozenRefusal(
vault: string,
tool: string,
err: VaultFrozenError,
resolveAgent: () => string,
): MCPError {
let agent: string;
try {
agent = resolveAgent();
} catch {
agent = UNRESOLVED_AGENT;
}
const auditReason = recordRefusal(vault, tool, agent, err);
const message =
`${tool}: refused (${VAULT_FROZEN_REFUSAL}). ${err.notice.detail}. ` +
"Every content write in this vault is refused until the freeze is lifted; " +
"this refusal was recorded in the Brain log.";
const data: VaultFrozenData = Object.freeze({
code: VAULT_FROZEN_REFUSAL,
tool,
frozen_at: err.frozen_at,
by: err.by,
reason: err.reason,
next_command: err.next_command,
...(auditReason !== null ? { audit_reason: auditReason } : {}),
});
return new MCPError(INVALID_PARAMS, message, data);
}
/**
* Recorded as the caller when the server's own identity resolution
* fails. A token, not a plausible name: an agent field that reads like a
* real identity but was invented is worse than one that says it is
* missing.
*/
export const UNRESOLVED_AGENT = "unresolved";