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
/**
* The schema pack of a store-only machine (design D14 item 3, task 2.11):
* the `schema:` block of `_brain.yaml` lives in the shared settings
* records `brain.schema.<field>`, each holding the field's list exactly as
* the migration imported it (one entry per rendered list line). A machine
* with no vault reads the same records.
*
* - {@link storeSchemaConfigText} renders those records back into the
* config text the pack parser (`./schema-pack.ts`) reads, so every
* reader of the pack works unchanged on a store-only machine.
* - {@link writeSchemaPackToStore} writes a pack the mutation lane
* already validated as one store operation through the shared settings
* writer (`./policy/settings-write.ts`): one `setting-entry` record per
* entry the pack adds or drops (task 3.12, design D19 item 1), never the
* whole list, so an entry another device adds or removes meanwhile is
* kept by the per-entry fold (`../store/fold-setting-lists.ts`).
* Nothing under the vault's `Brain/` is written.
* - {@link schemaDecidingRecords} names the records that decide the pack
* in force, which an apply's audit row attests, each bound to its
* content ({@link schemaRecordAttestation}).
* - {@link readStoreSchemaRecords} returns the field lists, their text and
* their deciding records from one read, for a caller that must hold all
* three to one snapshot (an apply, the integrity read).
*/
import { canonicalJson, sha256Hex } from "../integrity/digest.ts";
import type { StoreRecord } from "../store/envelope.ts";
import { settingEntrySlot } from "../store/fold-setting-lists.ts";
import type { RegisterState } from "../store/fold.ts";
import { foldSettings, type SettingsFold } from "../store/fold-settings.ts";
import { configuredStore } from "../store/read/store-entities.ts";
import { readStreamRecords } from "../store/read/stream-read.ts";
import { brainSettingKey } from "./policy/settings-keys.ts";
import {
writeSharedSettingEntries,
type SettingAuthority,
type SharedSettingEntryChange,
} from "./policy/settings-write.ts";
import { SCHEMA_VOCAB_CATEGORIES } from "./schema-vocab.ts";
/** The settings block the pack lives in. */
const SCHEMA_BLOCK = "schema";
/** What a store-only machine names as the place its schema pack lives. */
export const STORE_SCHEMA_PACK_SOURCE = `store:shared/settings/${brainSettingKey(SCHEMA_BLOCK)}`;
/** The shared settings fold the pack is read from (empty without `shared`). */
function schemaFold(configPath?: string): SettingsFold {
const store = configuredStore(configPath);
if (store === null || !store.partitions.has("shared")) return foldSettings([]);
return foldSettings(readStreamRecords(store.root, "shared", { stream: "settings" }).records);
}
const SCHEMA_PREFIX = `${brainSettingKey(SCHEMA_BLOCK)}.`;
/**
* The fields of the `schema:` block the pack parser reads
* (`parseSchemaPack` in `./schema-pack.ts`). A record under
* `brain.schema.` for any other name changes no pack, so it is neither
* rendered into the pack's text nor attested.
*/
export const SCHEMA_PACK_FIELDS: ReadonlySet<string> = new Set([
...SCHEMA_VOCAB_CATEGORIES,
"aliases",
"prefixes",
"link_types",
"extractable",
"expert_routing",
"labels",
"link_constraints",
"attributes",
"frontmatter_tiers",
]);
/** One record that decides the pack in force. */
export interface SchemaDecidingRecord {
readonly id: string;
/** What an audit row names to attest this record: {@link schemaRecordAttestation}. */
readonly attestation: string;
}
/**
* What an audit row names to attest one record: `<id>:<digest>`, the
* digest the sha256 of the record's canonical JSON (envelope and body).
* The id alone is not enough: a record's checksum covers its body, never
* its id, so another version under an attested id (a different body with
* a matching checksum) would pass as attested. A row attests the one
* version it saw.
*/
export function schemaRecordAttestation(record: StoreRecord): string {
return `${record.id}:${sha256Hex(canonicalJson(record))}`;
}
/**
* The schema records of the store as one read of the shared settings
* stream (task 3.12, design D19 item 1): the field lists in force, the
* config text they render to, and the records deciding them. An apply and
* the integrity read take all three from this one fold, so a record that
* syncs in meanwhile can neither change the pack without being among its
* deciding records nor reach the entries a repair removes.
*/
export interface StoreSchemaRecords {
/** The `brain.schema.<field>` values in force, by field. */
readonly fields: Readonly<Record<string, ReadonlyArray<string>>>;
/** {@link storeSchemaConfigText} of those fields. */
readonly text: string | null;
/** {@link schemaDecidingRecords} of the same fold. */
readonly deciding: ReadonlyArray<SchemaDecidingRecord>;
/**
* The id of the record deciding each entry of {@link fields}, by field
* and entry: what a repair of that entry checks the slot against when
* it writes (`writeSharedSettingEntries`).
*/
readonly decidedBy: Readonly<Record<string, Readonly<Record<string, string>>>>;
}
/** Read the store's schema records once: see {@link StoreSchemaRecords}. */
export function readStoreSchemaRecords(configPath?: string): StoreSchemaRecords {
const fold = schemaFold(configPath);
const fields = fieldsOf(fold);
return {
fields,
text: configTextOf(fields),
deciding: decidingOf(fold),
decidedBy: decidedByOf(fold, fields),
};
}
function decidedByOf(
fold: SettingsFold,
fields: Readonly<Record<string, ReadonlyArray<string>>>,
): Record<string, Record<string, string>> {
const out: Record<string, Record<string, string>> = {};
for (const [field, entries] of Object.entries(fields)) {
const key = `${SCHEMA_PREFIX}${field}`;
const slots = fold.lists.get(key);
const whole = fold.settings.get(key)!.winner.record.id;
out[field] = Object.fromEntries(
entries.map((entry) => [
entry,
slots?.get(settingEntrySlot(key, entry))?.winner.record.id ?? whole,
]),
);
}
return out;
}
/**
* The records that decide the pack in force, sorted by id: for a field
* folded per entry each entry's deciding record (removals included, so a
* removal nobody audited is seen), else the field's winning record. An
* apply's audit row names them (`decided`), so a pack merged from applies
* on two devices is still attested (`./schema-integrity.ts`).
*/
export function schemaDecidingRecords(configPath?: string): SchemaDecidingRecord[] {
return decidingOf(schemaFold(configPath));
}
function decidingOf(fold: SettingsFold): SchemaDecidingRecord[] {
const records = new Map<string, StoreRecord>();
const add = (record: StoreRecord) => records.set(record.id, record);
for (const [key, state] of fold.settings) {
if (!isPackField(key, state)) continue;
const slots = fold.lists.get(key);
if (slots === undefined) add(state.winner.record);
else for (const slot of slots.values()) add(slot.winner.record);
}
return [...records.keys()]
.toSorted()
.map((id) => ({ id, attestation: schemaRecordAttestation(records.get(id)!) }));
}
/** The `brain.schema.<field>` values in force, by field. */
export function storeSchemaFields(configPath?: string): Record<string, ReadonlyArray<string>> {
return fieldsOf(schemaFold(configPath));
}
function fieldsOf(fold: SettingsFold): Record<string, ReadonlyArray<string>> {
const out: Record<string, ReadonlyArray<string>> = {};
for (const [key, state] of fold.settings) {
if (!isPackField(key, state) || state.removed) continue;
out[key.slice(SCHEMA_PREFIX.length)] = (state.value as unknown[]).map(String);
}
return out;
}
/**
* Whether the settings key `key` is a field of the pack: a name under
* `brain.schema.` the pack parser reads ({@link SCHEMA_PACK_FIELDS}),
* holding a list or removed (a removal decides the field too). The pack
* reader and the attestation use this one filter, so a record the pack
* never reads cannot change what is attested.
*/
function isPackField(key: string, state: RegisterState<unknown>): boolean {
if (!key.startsWith(SCHEMA_PREFIX)) return false;
if (!SCHEMA_PACK_FIELDS.has(key.slice(SCHEMA_PREFIX.length))) return false;
return state.removed || Array.isArray(state.value);
}
/**
* The config text of the store's schema pack, or `null` when no schema
* field is set (the pack is then the built-in vocabulary alone).
*/
export function storeSchemaConfigText(configPath?: string): string | null {
return configTextOf(storeSchemaFields(configPath));
}
function configTextOf(fields: Readonly<Record<string, ReadonlyArray<string>>>): string | null {
const names = Object.keys(fields).toSorted();
if (names.length === 0) return null;
const lines = ["schema_version: 1", `${SCHEMA_BLOCK}:`];
for (const name of names) {
const entries = fields[name]!;
if (entries.length === 0) continue;
lines.push(` ${name}:`);
for (const entry of entries) lines.push(` - ${entry}`);
}
return `${lines.join("\n")}\n`;
}
/**
* The `schema:` block text of a rendered pack, as per-field lists of the
* entries exactly as rendered (` - <entry>`). Split line by line, the
* inverse of {@link storeSchemaConfigText}, so an entry the general YAML
* parser would read otherwise (a `: ` or ` #` inside it, quotes) round-
* trips byte for byte to the pack's own line parser.
*/
function fieldsOfSchemaBlock(schemaBlock: string): Record<string, ReadonlyArray<string>> {
const out: Record<string, string[]> = {};
let field: string | null = null;
for (const line of schemaBlock.replace(/\r\n?/g, "\n").split("\n")) {
const header = /^ {2}([A-Za-z0-9_]+):\s*$/.exec(line);
if (header !== null) {
field = header[1]!;
continue;
}
const entry = /^ {4}- (.*)$/.exec(line);
if (entry !== null && field !== null) (out[field] ??= []).push(entry[1]!);
}
return out;
}
export interface SchemaPackStoreWrite {
readonly vault: string | null;
readonly configPath?: string;
readonly authority: SettingAuthority;
readonly agent: string;
}
/**
* Write the pack whose rendered `schema:` block is `schemaBlock` over the
* pack in force, rendered as `currentBlock`: a `setting-entry` record
* adding each entry the new pack has and the one in force lacks, and one
* removing each entry it drops (a keyed entry whose value changed is
* replaced by its new entry alone). Entries are compared by slot, the
* normalised form the pack parser reads, so a stored entry in another
* spelling of the same token is no change. An entry the records still
* hold but the pack in force dropped on read (a reference to an undeclared
* token, `dropDanglingReferences` in `./schema-pack.ts`) is removed too,
* as a repair: skipped where this authority may not remove it, since every
* reader drops it anyway. `stored` holds the field lists `currentBlock` was
* read from ({@link readStoreSchemaRecords}): the same read, so a repair
* removes only an entry the pack in force dropped, never one that synced
* in after the pack was read; and a repair is skipped when another record
* decides the entry's slot by the time it is written (`decidedBy`), so a
* replacement another device wrote meanwhile is kept. Returns the ids of
* the records written.
*/
export function writeSchemaPackToStore(
ctx: SchemaPackStoreWrite,
schemaBlock: string,
currentBlock: string,
stored: Pick<StoreSchemaRecords, "fields" | "decidedBy">,
): string[] {
const next = fieldsOfSchemaBlock(schemaBlock);
const current = fieldsOfSchemaBlock(currentBlock);
const names = [
...new Set([...Object.keys(stored.fields), ...Object.keys(current), ...Object.keys(next)]),
].toSorted();
const changes: SharedSettingEntryChange[] = [];
for (const field of names) {
const name = `${SCHEMA_BLOCK}.${field}`;
const key = `${SCHEMA_PREFIX}${field}`;
const slot = (entry: string) => settingEntrySlot(key, entry);
const before = current[field] ?? [];
const after = next[field] ?? [];
const kept = new Set(after.map(slot));
const shown = new Set(before.map(slot));
for (const entry of after) {
if (!before.includes(entry)) changes.push({ name, entry, present: true });
}
for (const entry of before) {
if (!kept.has(slot(entry))) changes.push({ name, entry, present: false });
}
for (const entry of stored.fields[field] ?? []) {
const s = slot(entry);
if (!shown.has(s) && !kept.has(s)) {
// An entry with no deciding record named is never repaired.
const decidedBy = stored.decidedBy[field]?.[entry] ?? "";
changes.push({ name, entry, present: false, repair: { decidedBy } });
}
}
}
return writeSharedSettingEntries(
{
vault: ctx.vault,
authority: ctx.authority,
agent: ctx.agent,
...(ctx.configPath !== undefined ? { configPath: ctx.configPath } : {}),
},
changes,
);
}