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
/**
* Host memory-write bridge core (t_5e06b572).
*
* Persists a Hermes built-in memory-tool write into the vault as a durable
* `host_memory_write` continuity record, so the vault becomes the backing
* store for native host memory instead of relying on the agent to call
* `brain_*` explicitly.
*
* VERIFIED HOST CONTRACT (Hermes c253b0738 β do not re-derive from memory):
* - `MemoryProvider.on_memory_write(action, target, content, metadata=None)`
* (agent/memory_provider.py); the manager dispatches it once per write.
* - Providers NEVER receive a batch: the builtin tool accepts an
* `operations[]` array but Hermes DECOMPOSES it host-side and calls the
* hook once per op (agent/tool_executor.py, agent/agent_runtime_helpers.py).
* - Only `action β {add, replace}` are bridged; `remove` is filtered out
* host-side and never reaches a provider.
* - `target β {memory, user}` ("memory" = agent notes, "user" = profile facts).
* - The hook returns nothing; the manager swallows exceptions. Explicit
* rejection here is for the in-process callers and tests, not the host.
*
* This kernel is deterministic and provider-agnostic: it never calls an LLM
* and parses no natural language β it maps already-structured fields. The
* `operations` batch helper exists so the (host-decomposed) single writes and
* any future multi-record caller share one validated, atomic substrate
* (`appendContinuityRecords`), not because the host ever sends a batch.
*/
import { appendContinuityRecord, appendContinuityRecords } from "./continuity/store.ts";
import type { AppendContinuityRecordInput, ContinuityRecord } from "./continuity/types.ts";
export const HOST_MEMORY_WRITE_KIND = "host_memory_write" as const;
/** Actions Hermes bridges to providers. `remove` is filtered out host-side. */
const BRIDGED_ACTIONS = Object.freeze(new Set(["add", "replace"]));
/** Targets the builtin memory tool writes to. */
const KNOWN_TARGETS = Object.freeze(new Set(["memory", "user"]));
export type HostMemoryWriteErrorCode = "invalid_action" | "invalid_target" | "empty_content";
/**
* A malformed/unsupported host payload. Carries a machine-readable `code`
* and the offending batch `index` (when raised from the batch path) so the
* MCP layer can surface a structured rejection instead of a vague failure.
*/
export class HostMemoryWriteError extends Error {
readonly code: HostMemoryWriteErrorCode;
readonly index?: number;
constructor(code: HostMemoryWriteErrorCode, message: string, index?: number) {
super(message);
this.name = "HostMemoryWriteError";
this.code = code;
if (index !== undefined) this.index = index;
}
}
export interface HostMemoryWriteInput {
/** Verified host action; only `add`/`replace` are accepted. */
readonly action: string;
/** Verified host target; only `memory`/`user` are accepted. */
readonly target: string;
/** The memory entry content. */
readonly content: string;
/** Optional structured provenance from the host (write_origin, session_id, β¦). */
readonly metadata?: Readonly<Record<string, unknown>>;
/** ISO timestamp override; defaults to now. Records are sharded by month. */
readonly createdAt?: string;
}
/**
* Validate one host write and project it to a continuity append input.
* Throws {@link HostMemoryWriteError} on a malformed/unsupported payload
* BEFORE any disk mutation, so callers can rely on all-or-nothing semantics.
*/
function toAppendInput(input: HostMemoryWriteInput, index?: number): AppendContinuityRecordInput {
const action = typeof input.action === "string" ? input.action.trim() : "";
if (!BRIDGED_ACTIONS.has(action)) {
throw new HostMemoryWriteError(
"invalid_action",
`action must be 'add' or 'replace' (got '${input.action}'); 'remove' is not bridged by the host`,
index,
);
}
const target = typeof input.target === "string" ? input.target.trim() : "";
if (!KNOWN_TARGETS.has(target)) {
throw new HostMemoryWriteError(
"invalid_target",
`target must be 'memory' or 'user' (got '${input.target}')`,
index,
);
}
if (typeof input.content !== "string" || input.content.trim().length === 0) {
throw new HostMemoryWriteError("empty_content", "content must be a non-empty string", index);
}
const metadata =
input.metadata && typeof input.metadata === "object" && !Array.isArray(input.metadata)
? input.metadata
: undefined;
return {
kind: HOST_MEMORY_WRITE_KIND,
createdAt: input.createdAt ?? new Date().toISOString(),
payload: {
action,
target,
content: input.content,
...(metadata && Object.keys(metadata).length > 0 ? { metadata } : {}),
},
};
}
/**
* Persist a single host memory write as a `host_memory_write` continuity
* record. Throws on a malformed payload, writing nothing.
*/
export function recordHostMemoryWrite(
vault: string,
input: HostMemoryWriteInput,
): ContinuityRecord {
return appendContinuityRecord(vault, toAppendInput(input));
}
/**
* Persist a batch of host memory writes atomically through the shared
* continuity batch substrate. EVERY input is validated first; one malformed
* entry aborts the whole batch with zero writes (the on-disk log is left
* unchanged). Single-month batches are fully atomic β see
* {@link appendContinuityRecords} for the cross-shard boundary.
*/
export function recordHostMemoryWrites(
vault: string,
inputs: ReadonlyArray<HostMemoryWriteInput>,
): ReadonlyArray<ContinuityRecord> {
if (!Array.isArray(inputs) || inputs.length === 0) {
throw new HostMemoryWriteError("empty_content", "operations must be a non-empty array");
}
const appendInputs = inputs.map((input, index) => toAppendInput(input, index));
return appendContinuityRecords(vault, appendInputs);
}