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
/**
* Tiered frontmatter field protection (write-time-integrity-governance).
*
* Four tiers, EverOS-inspired, mapped onto Open Second Brain's
* existing conventions:
*
* - `identity` - framework-owned join keys (`kind`, `id`,
* `entity_id`, an entity's `category`). A hand-edit here corrupts
* the joins the index and registry depend on.
* - `system` - framework-written bookkeeping: timestamps,
* counters, lifecycle status. The `_`-prefixed preference fields
* already follow this convention informally; the tier model makes
* it explicit.
* - `business` - domain fields agents write through verbs.
* - `user` - freely editable; everything undeclared.
*
* Resolution order: schema-pack `frontmatter_tiers` override >
* built-in framework defaults > `user`. Unknown kinds resolve every
* field to `user`, so a human's own vault is never constrained.
*
* The guard never write-denies humans: framework writers merge
* through `mergeFrontmatterTiered` (preserve user fields they do not
* own, refuse to change identity values), and the drift check
* (`o2b brain tiers check`) detects hand-edits against the indexed
* baseline and stages repair - it does not fight the editor.
*/
import { Database } from "bun:sqlite";
import { existsSync } from "node:fs";
import { FRONTMATTER_TIERS, type FrontmatterTier, type SchemaPack } from "./schema-pack.ts";
import { closeDatabase } from "../sqlite-close.ts";
export { FRONTMATTER_TIERS };
export type { FrontmatterTier };
/** Thrown when a merge would change an identity join key. */
export class FrontmatterTierConflictError extends Error {
readonly field: string;
readonly existingValue: unknown;
readonly incomingValue: unknown;
constructor(field: string, existingValue: unknown, incomingValue: unknown) {
super(
`identity field "${field}" cannot change in a framework write: ` +
`${JSON.stringify(existingValue)} -> ${JSON.stringify(incomingValue)} ` +
`(pass acceptIdentity for an explicit migration)`,
);
this.name = "FrontmatterTierConflictError";
this.field = field;
this.existingValue = existingValue;
this.incomingValue = incomingValue;
}
}
/**
* Built-in tier defaults for framework-owned kinds, grounded in the
* fields the writers actually emit (preference.ts, entities/registry,
* signal.ts, dead-ends.ts). Fields not listed here fall through to
* the `_`-prefix system rule, then to `user`.
*/
export const DEFAULT_TIER_MAP: Readonly<Record<string, Readonly<Record<string, FrontmatterTier>>>> =
Object.freeze({
"brain-preference": Object.freeze<Record<string, FrontmatterTier>>({
kind: "identity",
id: "identity",
created_at: "system",
unconfirmed_until: "system",
topic: "business",
principle: "business",
scope: "business",
tags: "business",
aliases: "business",
supersedes: "business",
// Legacy unprefixed Group C names (pre-§24). System tier so a
// tier-merging rewrite drops them instead of preserving a stale
// copy beside the `_`-prefixed field the writer emits today.
status: "system",
confirmed_at: "system",
evidenced_by: "system",
applied_count: "system",
violated_count: "system",
last_evidence_at: "system",
confidence: "system",
confidence_value: "system",
}),
"brain-retired": Object.freeze<Record<string, FrontmatterTier>>({
kind: "identity",
id: "identity",
created_at: "system",
retired_at: "system",
}),
// Derived cluster notes (link-recall-intelligence, t_4ba927ec):
// fully framework-owned and regenerated every run, so every field
// is system except the identity pair.
"brain-cluster": Object.freeze<Record<string, FrontmatterTier>>({
kind: "identity",
cluster: "identity",
generated_at: "system",
size: "system",
density: "system",
members: "system",
}),
"brain-signal": Object.freeze<Record<string, FrontmatterTier>>({
kind: "identity",
id: "identity",
created_at: "system",
agent: "system",
topic: "business",
signal: "business",
scope: "business",
}),
"brain-entity": Object.freeze<Record<string, FrontmatterTier>>({
kind: "identity",
entity_id: "identity",
category: "identity",
created_at: "system",
updated_at: "system",
status: "system",
source_agent: "system",
name: "business",
aliases: "business",
confidence: "business",
}),
"brain-dead-end": Object.freeze<Record<string, FrontmatterTier>>({
kind: "identity",
id: "identity",
created_at: "system",
agent: "system",
}),
});
/**
* Resolve one field's tier: pack override > built-in default >
* `_`-prefix system rule (framework kinds only) > `user`.
*/
export function resolveFieldTier(pack: SchemaPack, kind: string, field: string): FrontmatterTier {
const packKind = pack.frontmatter_tiers[kind];
const override = packKind?.[field];
if (override !== undefined) return override;
const isFrameworkKind = DEFAULT_TIER_MAP[kind] !== undefined || packKind !== undefined;
if (!isFrameworkKind) return "user";
const builtin = DEFAULT_TIER_MAP[kind]?.[field];
if (builtin !== undefined) return builtin;
if (field.startsWith("_")) return "system";
return "user";
}
/**
* Every field of a kind with a declared non-`user` tier (pack
* overrides merged over built-ins). The drift check walks this map;
* `user`-tier overrides are omitted because they need no protection.
*/
export function tieredFieldsForKind(
pack: SchemaPack,
kind: string,
): Record<string, FrontmatterTier> {
const out: Record<string, FrontmatterTier> = {};
for (const [field, tier] of Object.entries(DEFAULT_TIER_MAP[kind] ?? {})) out[field] = tier;
for (const [field, tier] of Object.entries(pack.frontmatter_tiers[kind] ?? {})) {
if (tier === "user") delete out[field];
else out[field] = tier;
}
return out;
}
export interface MergeFrontmatterTieredOptions {
/** The file's framework kind (the writer knows what it writes). */
readonly kind: string;
readonly pack: SchemaPack;
/**
* Allow an identity value to change - explicit migrations only
* (rename, re-id). Never set this on a routine update write.
*/
readonly acceptIdentity?: boolean;
}
/**
* Tier-respecting frontmatter merge for framework writers. Incoming
* (framework) values win field-by-field; existing-only fields are
* preserved when their tier is `user` - a field a human added by hand
* survives every framework rewrite - and DROPPED otherwise: a
* framework-owned field the writer no longer emits is a deliberate
* migration (e.g. legacy unprefixed names), not user data. A changed
* identity value throws unless `acceptIdentity` marks an explicit
* migration. Unknown kinds have no non-`user` fields, so the merge
* degrades to a plain spread.
*/
export function mergeFrontmatterTiered<V>(
existing: Readonly<Record<string, V>>,
incoming: Readonly<Record<string, V>>,
opts: MergeFrontmatterTieredOptions,
): Record<string, V> {
if (opts.acceptIdentity !== true) {
for (const [field, incomingValue] of Object.entries(incoming)) {
if (resolveFieldTier(opts.pack, opts.kind, field) !== "identity") continue;
if (!(field in existing)) continue;
const existingValue = existing[field];
if (!sameScalar(existingValue, incomingValue)) {
throw new FrontmatterTierConflictError(field, existingValue, incomingValue);
}
}
}
const merged: Record<string, V> = {};
for (const [field, value] of Object.entries(existing)) {
if (field in incoming) continue;
if (resolveFieldTier(opts.pack, opts.kind, field) === "user") merged[field] = value;
}
return Object.assign(merged, incoming);
}
function sameScalar(left: unknown, right: unknown): boolean {
if (Array.isArray(left) && Array.isArray(right)) {
return left.length === right.length && left.every((v, i) => sameScalar(v, right[i]));
}
return left === right;
}
/**
* Count the staged tier-drift findings straight from the index
* database (doctor surface). Read-only, fail-soft: a missing index
* file, a pre-v6 schema, or any read error counts as zero.
*
* With `readable`, only the rows on pages the caller may read count, so
* a drifted page it cannot read moves the count no more than an absent
* one does.
*/
export function readTierDriftCount(dbPath: string, readable?: (rel: string) => boolean): number {
if (!existsSync(dbPath)) return 0;
let db: Database | null = null;
try {
db = new Database(dbPath, { readonly: true });
if (readable !== undefined) {
return db
.query<{ path: string }, []>(
"SELECT d.path FROM tier_drift t JOIN documents d ON d.id = t.document_id",
)
.all()
.filter((row) => readable(row.path)).length;
}
return db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM tier_drift").get()?.n ?? 0;
} catch {
return 0;
} finally {
closeDatabase(db);
}
}