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
import { createHash } from "node:crypto";
export type ClaudeMemoryParseResult =
| {
readonly kind: "feedback";
readonly name: string;
readonly description: string;
readonly body: string;
readonly bodySha256: string;
}
| {
readonly kind: "skip";
readonly skipReason: string;
};
// Accept both LF and CRLF line endings around the frontmatter fence —
// memory files written from Windows clients carry `\r\n`, and a pure
// `\n` regex would mis-classify them as malformed.
const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
/**
* Minimal two-level YAML parser for Claude MEMORY.md frontmatter.
*
* Handles:
* - `key: scalar value` at the top level
* - `key:` with an indented block of ` subkey: scalar` one level deep
* - blank lines and `# comments` are ignored
*
* Returns a plain object whose nested blocks are plain objects. Does not
* use an external YAML library — consistent with the project's design
* principle of keeping the core dependency-free.
*/
function parseFrontmatterBlock(text: string): Record<string, unknown> {
const out: Record<string, unknown> = {};
const lines = text.split("\n");
let i = 0;
while (i < lines.length) {
const raw = lines[i]!;
i++;
const trimmed = raw.trim();
if (!trimmed || trimmed.startsWith("#")) continue;
const colon = trimmed.indexOf(":");
if (colon === -1) continue;
const key = trimmed.slice(0, colon).trim();
const rest = trimmed.slice(colon + 1).trim();
if (rest === "" || rest === null) {
// Possible block header — collect indented children.
const child: Record<string, string> = {};
const indent = detectIndent(lines, i);
if (indent > 0) {
while (i < lines.length) {
const innerRaw = lines[i]!;
const innerTrimmed = innerRaw.trim();
if (!innerTrimmed || innerTrimmed.startsWith("#")) {
i++;
continue;
}
// Stop if this line is at top-level indentation (indent 0) or
// has less indentation than the detected block indent.
const lineIndent = innerRaw.length - innerRaw.trimStart().length;
if (lineIndent < indent) break;
i++;
const innerColon = innerTrimmed.indexOf(":");
if (innerColon === -1) continue;
const innerKey = innerTrimmed.slice(0, innerColon).trim();
const innerVal = innerTrimmed.slice(innerColon + 1).trim();
child[innerKey] = stripYamlQuotes(innerVal);
}
}
out[key] = child;
} else {
out[key] = stripYamlQuotes(rest);
}
}
return out;
}
function detectIndent(lines: string[], from: number): number {
for (let j = from; j < lines.length; j++) {
const raw = lines[j]!;
const trimmed = raw.trim();
if (!trimmed || trimmed.startsWith("#")) continue;
const spaces = raw.length - raw.trimStart().length;
return spaces;
}
return 0;
}
function stripYamlQuotes(val: string): string {
if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
return val.slice(1, -1);
}
return val;
}
export function parseClaudeMemoryFile(text: string): ClaudeMemoryParseResult {
const m = text.match(FM_RE);
if (!m) {
return { kind: "skip", skipReason: "missing or malformed frontmatter" };
}
// Unit F: the `catch` that stood here returned a
// "frontmatter is not valid YAML" skip. `parseFrontmatterBlock` is a
// line scanner with no `throw` anywhere in it or in the two pure string
// helpers it calls, so that arm was unreachable and the skip reason it
// named could never be produced - a diagnostic that reads as coverage
// and provides none. Unsupported grammar is dropped line-by-line by
// that scanner, exactly as in `parseFrontmatterText`, and the shapes it
// cannot express fall out of the `type` / `name` / `description` checks
// below with a skip reason that is actually reachable.
const fm = parseFrontmatterBlock(m[1]!);
const name = typeof fm["name"] === "string" ? fm["name"].trim() : "";
const description = typeof fm["description"] === "string" ? fm["description"].trim() : "";
// Claude Code Memory uses two frontmatter shapes for the `type` field:
// older entries put it at the top level (`type: feedback`), newer ones
// nest it under `metadata: { type: feedback }`. Accept either — the
// semantics are identical and 12 of 17 real memory files this code
// has seen use the older shape.
const meta = (fm["metadata"] as Record<string, unknown> | undefined) ?? {};
const nestedType = typeof meta["type"] === "string" ? meta["type"] : "";
const topLevelType = typeof fm["type"] === "string" ? fm["type"] : "";
const type = nestedType || topLevelType;
if (type !== "feedback") {
return { kind: "skip", skipReason: `type=${type || "<missing>"}; only feedback maps to Brain` };
}
if (!name || !description) {
return { kind: "skip", skipReason: "feedback entry missing required name/description" };
}
const body = m[2]!.trim();
const bodySha256 = createHash("sha256").update(body).digest("hex");
return { kind: "feedback", name, description, body, bodySha256 };
}