Skip to content

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
10.8 KB
Raw Blame
/**
 * Names of the brain store: the one place that spells every directory,
 * file, stream, partition, envelope field and store-level record kind.
 *
 * The brain store (design D1) is the open, documented, append-only home of
 * every piece of Open Second Brain machine data outside the user's notes.
 * Every other store module builds its paths and validates its records
 * against the names here, and the `FORMAT.md` doc test checks that the
 * shipped format document names each of them, so the code and the public
 * format cannot drift apart silently.
 */

/** Format version written into every record envelope (`v`). */
export const STORE_FORMAT_VERSION = 1;

/** The format document shipped into the store root and every partition. */
export const STORE_FORMAT_FILE = "FORMAT.md";

/** Per-partition identity file: the store id and the format version that created it. */
export const STORE_IDENTITY_FILE = "store.json";

/** Sensitivity partitions, each a separate top-level folder synced on its own. */
export const STORE_PARTITIONS = Object.freeze(["shared", "private"] as const);
export type StorePartition = (typeof STORE_PARTITIONS)[number];

/**
 * Streams inside a partition. `ledgers` carries one more path segment, the
 * ledger name (`ledgers/<name>/<device>/<YYYY-MM>.jsonl`).
 */
export const STORE_STREAMS = Object.freeze([
  "events",
  "log",
  "ledgers",
  "topics",
  "settings",
  "digests",
] as const);
export type StoreStream = (typeof STORE_STREAMS)[number];

/** The stream whose files sit one directory deeper, under a ledger name. */
export const LEDGER_STREAM: StoreStream = "ledgers";

/** Content-addressed blob directory inside a partition. */
export const STORE_BLOBS_DIR = "blobs";

/** Extension of every shard file. */
export const STORE_SHARD_EXT = "jsonl";

/**
 * Envelope fields in the order the appender writes them. `topic` and
 * `scope` may be `null`; every other field is always present.
 */
export const ENVELOPE_FIELDS = Object.freeze([
  "v",
  "id",
  "hlc",
  "device",
  "agent",
  "kind",
  "scope",
  "topic",
  "sum",
  "body",
] as const);
export type EnvelopeField = (typeof ENVELOPE_FIELDS)[number];

/**
 * Reserved key of a blob reference body: `{ "$blob": <sha256>, "bytes": <n> }`.
 * A record whose body was spilled into `blobs/` carries this body on its
 * line; the real body is the blob's content.
 */
export const BLOB_REF_KEY = "$blob";

/** The byte-count key that rides beside {@link BLOB_REF_KEY}. */
export const BLOB_REF_BYTES_KEY = "bytes";

/** Store-level record kind: a compaction replaced one set of shards with another. */
export const COMPACTED_KIND = "compacted";

/**
 * Record kinds the store layer itself defines and understands. Domain
 * kinds (signals, topics, settings) are defined by the modules that own
 * them, in later waves.
 */
export const STORE_RECORD_KINDS = Object.freeze([COMPACTED_KIND] as const);

/**
 * Line-size cap in bytes, newline included. A record whose line would be
 * longer is written with its body spilled into a blob.
 */
export const STORE_LINE_CAP_BYTES = 16 * 1024;

/**
 * Deepest nesting of objects and arrays a record body may have, the body
 * object itself counting as one level. A deeper body is never written and
 * is read as a corrupt record, so checksumming a body peer-planted in a
 * blob can never exhaust the stack.
 */
export const STORE_BODY_MAX_DEPTH = 64;

/**
 * Largest blob a reader loads. A spilled body is a record body (a pinned
 * text, a signal, a ledger row), far below this; a larger file in a
 * synced `blobs/` folder is refused unread rather than allocated.
 */
export const STORE_BLOB_MAX_BYTES = 64 * 1024 * 1024;

/** Machine-config key that sets the store root. */
export const STORE_ROOT_CONFIG_KEY = "store_root";

/** Environment variable that sets the store root, ahead of the config key. */
export const STORE_ROOT_ENV = "OPEN_SECOND_BRAIN_STORE_ROOT";

/** Directory name of the default store root under the per-user data directory. */
export const STORE_DEFAULT_DIR = "store";

/** Directory under the tool's state root that holds one device-local directory per store id. */
export const STORE_STATE_DIR = "stores";

/** Device-local subdirectory of shard append locks (never inside the synced store). */
export const STORE_LOCKS_DIR = "locks";

/** Device-local subdirectory of the persisted hybrid logical clock. */
export const STORE_CLOCK_DIR = "clock";

/**
 * Device-local file (in a store's device-local directory, one per store
 * root, the root's hash before the extension) listing every shard this
 * machine has seen, so a shard that later goes missing reads as
 * unreadable rather than as "no records" (`seen-shards.ts`).
 */
export const SEEN_SHARDS_FILE = "seen-shards.json";

// ---------------------------------------------------------------------------
// Folds of mutable entities and state digests (tasks 1.6 and 1.7, design D4
// and D6). One block, so it merges cleanly beside other additions.
// ---------------------------------------------------------------------------

/** Body field that carries the authority of a mutable-entity record. */
export const AUTHORITY_FIELD = "authority";

/**
 * Body field every dual-written record carries: the id of the vault the
 * legacy write went to (`Brain/vault-id.json`), or `null` when that vault
 * has no identity marker or the caller named no vault.
 */
export const VAULT_ID_FIELD = "vault_id";

/**
 * Who decided a mutable-entity record, from the strongest to the weakest:
 * the user, an agent, a decision model. A stronger authority always beats
 * a weaker one; within one authority the later clock wins.
 */
export const AUTHORITIES = Object.freeze(["human", "agent", "model"] as const);
export type Authority = (typeof AUTHORITIES)[number];

/** Preference records (`events` stream): a field update, a removal, evidence. */
export const PREFERENCE_SET_KIND = "preference-set";
export const PREFERENCE_REMOVE_KIND = "preference-remove";
export const PREFERENCE_EVIDENCE_KIND = "preference-evidence";

/** Pinned context records (`events` stream): a replacement and a clear. */
export const PINNED_SET_KIND = "pinned-set";
export const PINNED_CLEAR_KIND = "pinned-clear";

/** Shared setting records (`settings` stream): a value and its removal. */
export const SETTING_SET_KIND = "setting-set";
export const SETTING_UNSET_KIND = "setting-unset";
/**
 * One entry of a list setting added or removed (`settings` stream): a list
 * setting folds per entry, so concurrent edits on two devices both apply.
 */
export const SETTING_ENTRY_KIND = "setting-entry";

/** A human record that takes a device off the digest roster (`settings` stream). */
export const DEVICE_RETIRE_KIND = "device-retire";

/** A published state digest (`digests` stream). */
export const STATE_DIGEST_KIND = "state-digest";

/** Every record kind the folds and digests define; FORMAT.md documents each. */
export const FOLD_RECORD_KINDS = Object.freeze([
  PREFERENCE_SET_KIND,
  PREFERENCE_REMOVE_KIND,
  PREFERENCE_EVIDENCE_KIND,
  PINNED_SET_KIND,
  PINNED_CLEAR_KIND,
  SETTING_SET_KIND,
  SETTING_UNSET_KIND,
  SETTING_ENTRY_KIND,
  DEVICE_RETIRE_KIND,
  STATE_DIGEST_KIND,
] as const);

/** Results an evidence record may carry. */
export const EVIDENCE_RESULTS = Object.freeze(["applied", "violated", "outdated"] as const);
export type EvidenceResult = (typeof EVIDENCE_RESULTS)[number];

/**
 * Preference counters derived in the fold from evidence records. They are
 * never written back: a `preference-set` that names one is ignored for it.
 */
export const PREFERENCE_COUNTER_FIELDS = Object.freeze([
  "applied_count",
  "violated_count",
  "outdated_count",
] as const);

/** Setting keys this version knows and validates. Other keys fold as plain JSON values. */
export const SETTING_VIEW_LANGUAGE = "view.language";
export const SETTING_TOPIC_MIN_RECORDS = "topics.new_min_records";
export const SETTING_TOPIC_MIN_SESSIONS = "topics.new_min_sessions";
export const SETTING_TOPIC_QUIET_DAYS = "topics.quiet_days";
export const SETTING_KEYS = Object.freeze([
  SETTING_VIEW_LANGUAGE,
  SETTING_TOPIC_MIN_RECORDS,
  SETTING_TOPIC_MIN_SESSIONS,
  SETTING_TOPIC_QUIET_DAYS,
] as const);
export type SettingKey = (typeof SETTING_KEYS)[number];

/** The folds a state digest hashes, in the order the digest body lists them. */
export const STATE_DIGEST_FOLDS = Object.freeze([
  "preferences",
  "pinned",
  "settings",
  "topics",
] as const);
export type StateDigestFold = (typeof STATE_DIGEST_FOLDS)[number];

/**
 * The folds every digest carries. `topics` came later: a digest an older
 * release published has no `topics` hash, and a pair of digests is
 * compared on a fold only when both carry it.
 */
export const STATE_DIGEST_REQUIRED_FOLDS: ReadonlyArray<StateDigestFold> = Object.freeze([
  "preferences",
  "pinned",
  "settings",
]);

/** One day in milliseconds, for the day-based windows below. */
export const DAY_MS = 24 * 60 * 60 * 1000;

/** Roster window: devices with records in the partition during the last N days. */
export const DIGEST_ROSTER_WINDOW_DAYS = 30;

/** A roster device that has published no digest for N days is reported as silent. */
export const DIGEST_SILENCE_DAYS = 7;

/** Doctor compares the digests published during the last N days. */
export const DIGEST_COMPARE_WINDOW_DAYS = 7;

// ---------------------------------------------------------------------------
// Dual writes (task 1.11, design D13 phase 1): the legacy writers also append
// the equivalent store record while the flag is on.
// ---------------------------------------------------------------------------

/** Machine-config key of the dual-write flag (default off). */
export const STORE_DUAL_WRITE_CONFIG_KEY = "store_dual_write";

/** Environment variable that sets the dual-write flag, ahead of the config key. */
export const STORE_DUAL_WRITE_ENV = "OPEN_SECOND_BRAIN_STORE_DUAL_WRITE";

/** A signal written by a legacy signal writer (`events` stream). */
export const SIGNAL_KIND = "signal";

/** One event of the legacy Brain log (`log` stream). */
export const LOG_EVENT_KIND = "log-event";

/** One row of a legacy append-only ledger (`ledgers/<name>` stream). */
export const LEDGER_ROW_KIND = "ledger-row";

/** Record kinds the dual writes define, beside the fold kinds they reuse. */
export const DUAL_WRITE_RECORD_KINDS = Object.freeze([
  SIGNAL_KIND,
  LOG_EVENT_KIND,
  LEDGER_ROW_KIND,
] as const);

/**
 * Device-local file (under the tool's state root, beside the per-store
 * directories) that counts dual writes that failed or were skipped, so
 * doctor can report them.
 */
export const DUAL_WRITE_STATUS_FILE = "dual-write.json";

/**
 * Device-local subdirectory where blob temp files are written before they
 * are linked into the store, when it is on the store's filesystem.
 */
export const STORE_TMP_DIR = "tmp";

/**
 * Prefix of a blob temp file written inside `blobs/` (when the device-local
 * directory is on another filesystem). Readers and sync setups ignore
 * names that start with a dot.
 */
export const BLOB_TEMP_PREFIX = ".tmp-";