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
9.3 KB
Raw Blame
/**
 * Whether the search index is store-aware, and where it then lives
 * (design D5, task 1.8).
 *
 * A store is "in use" when the resolved store root (environment, machine
 * config, then the per-user default; see `store/store-paths.ts`) holds at
 * least one partition carrying the store identity file. Nothing here
 * creates a store or writes into one: the probe only reads `store.json`.
 *
 * When a store is in use the index lives in the store's device-local state
 * directory, one file per vault:
 * `<device state>/index/<vault key>/brain.sqlite`. With no vault at all
 * (design D14 item 14) the index is keyed by the store id instead:
 * `<device state>/index/<store id>/brain.sqlite`; a vault key is 16 hex
 * characters and a store id a 26-character ULID, so the two never meet. When no store is in use
 * (every install before migration) the legacy vault location stays, and an
 * explicit `search_db_path` / `OPEN_SECOND_BRAIN_SEARCH_DB` override wins
 * in both cases (see `../paths.ts`).
 */

import { mkdirSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
import { join, resolve } from "node:path";

import { DERIVED_STORE_FILE } from "../../brain/path-constants.ts";
import { defaultConfigPath } from "../../config.ts";
import { sha256Hex } from "../../integrity/digest.ts";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { processDirsEnv, type PlatformDirsEnv } from "../../platform-dirs.ts";
import { STORE_PARTITIONS, type StorePartition } from "../../store/constants.ts";
import { lostHeldPartitions } from "../../store/held-ledger.ts";
import { readStoreId } from "../../store/store-open.ts";
import { isUlid } from "../../store/ulid.ts";
import {
  deviceStateDirFor,
  partitionDir,
  resolveStoreRoot,
  storesStateDir,
  StoreRootInsideVaultError,
} from "../../store/store-paths.ts";
import {
  STORE_INDEX_DIR,
  STORE_INDEX_ROOT_FILE,
  STORE_INDEX_VAULT_KEY_LENGTH,
} from "./constants.ts";

/** A store the index reads, as this machine holds it. */
export interface IndexedStore {
  readonly root: string;
  readonly storeId: string;
  /** Device-local state directory of the store (never synced). */
  readonly deviceStateDir: string;
  /** Partitions this machine holds, in {@link STORE_PARTITIONS} order. */
  readonly partitions: ReadonlyArray<StorePartition>;
}

/**
 * What a read-only look at a store root found: the store, no store (no
 * partition holds an identity file), or `unknown` when it could not tell
 * (an identity file is unreadable, the partitions disagree about the
 * store id, or a partition this machine has held lost its identity file:
 * a broken store is not indexed; the store's own open refuses it
 * by name).
 */
export type StoreProbe =
  | { readonly kind: "store"; readonly store: IndexedStore }
  | { readonly kind: "absent" }
  /** `root`: the store root probed, `null` when it could not be resolved. */
  | { readonly kind: "unknown"; readonly root: string | null };

/** Read-only probe of the store at `root`; see {@link StoreProbe}. */
export function probeStoreRoot(root: string, dirs: PlatformDirsEnv = processDirsEnv()): StoreProbe {
  const held: StorePartition[] = [];
  const ids = new Set<string>();
  for (const partition of STORE_PARTITIONS) {
    let id: string | null;
    try {
      id = readStoreId(partitionDir(root, partition));
    } catch {
      return { kind: "unknown", root };
    }
    if (id === null) continue;
    held.push(partition);
    ids.add(id);
  }
  // A partition this machine has held that lost its identity file: the
  // store's own open refuses it by name (`held-ledger.ts`).
  if (lostHeldPartitions(root, new Set(held)).length > 0) return { kind: "unknown", root };
  if (held.length === 0) return { kind: "absent" };
  if (ids.size !== 1) return { kind: "unknown", root };
  const storeId = [...ids][0]!;
  return {
    kind: "store",
    store: { root, storeId, deviceStateDir: deviceStateDirFor(storeId, dirs), partitions: held },
  };
}

/** The held store at `root`, or `null` when there is none or it cannot be read. */
export function probeIndexedStore(
  root: string,
  dirs: PlatformDirsEnv = processDirsEnv(),
): IndexedStore | null {
  const probe = probeStoreRoot(root, dirs);
  return probe.kind === "store" ? probe.store : null;
}

export interface ResolveIndexedStoreOptions {
  /** The vault indexed, or `null` for a machine with no vault. */
  readonly vault: string | null;
  /** Parsed machine config (`key: value`); empty when no file was read. */
  readonly config: Readonly<Record<string, string>>;
  /** Path of the machine config file; relative `store_root` values anchor to its directory. */
  readonly configPath?: string | null;
  readonly dirs?: PlatformDirsEnv;
}

/**
 * Which store the index of `vault` reads. A store root configured inside
 * the vault is not in use (`absent`): the store's own resolver refuses it
 * by name wherever a store is opened, and the index must not fail every
 * search over it. A root that cannot be resolved at all is `unknown`.
 */
export function resolveIndexedStoreProbe(opts: ResolveIndexedStoreOptions): StoreProbe {
  const dirs = opts.dirs ?? processDirsEnv();
  let root: string;
  try {
    root = resolveStoreRoot({
      ...dirs,
      config: opts.config,
      configPath: opts.configPath ?? defaultConfigPath(),
      vault: opts.vault,
    }).root;
  } catch (err) {
    return err instanceof StoreRootInsideVaultError
      ? { kind: "absent" }
      : { kind: "unknown", root: null };
  }
  return probeStoreRoot(root, dirs);
}

/** The store the index of `vault` reads, or `null` when none is in use or it cannot be read. */
export function resolveIndexedStore(opts: ResolveIndexedStoreOptions): IndexedStore | null {
  const probe = resolveIndexedStoreProbe(opts);
  return probe.kind === "store" ? probe.store : null;
}

/**
 * The directory name of a vault's index under a store: a short hash of the
 * vault's real path. The real path follows symlinks and, on macOS and
 * Windows, answers the on-disk spelling of each segment (drive letter
 * included), so one vault reached through a link or a different casing
 * keeps one index. A vault that does not exist yet hashes its resolved path.
 */
export function vaultIndexKey(vault: string): string {
  let real: string;
  try {
    real = realpathSync.native(vault);
  } catch {
    real = resolve(vault);
  }
  return sha256Hex(real).slice(0, STORE_INDEX_VAULT_KEY_LENGTH);
}

/**
 * The directory name of an index under a store: the vault's key, or the
 * store id when there is no vault.
 */
export function indexKeyFor(storeId: string, vault: string | null): string {
  return vault === null ? storeId : vaultIndexKey(vault);
}

/** The index file of `vault` (`null`: no vault) inside `store`'s device-local state. */
export function storeIndexPath(store: IndexedStore, vault: string | null): string {
  return join(
    store.deviceStateDir,
    STORE_INDEX_DIR,
    indexKeyFor(store.storeId, vault),
    DERIVED_STORE_FILE,
  );
}

/** The store root `deviceStateDir`'s store was last read at, or `null`. */
function rememberedRoot(deviceStateDir: string): string | null {
  try {
    return readFileSync(join(deviceStateDir, STORE_INDEX_DIR, STORE_INDEX_ROOT_FILE), "utf8");
  } catch {
    return null;
  }
}

/**
 * Note on this machine that `store` was read at its root, for
 * {@link lastStoreIndexPath}. Best effort: a failure only means a later
 * `unknown` probe uses the legacy location instead.
 */
export function rememberStoreRoot(store: IndexedStore): void {
  if (rememberedRoot(store.deviceStateDir) === store.root) return;
  try {
    const dir = join(store.deviceStateDir, STORE_INDEX_DIR);
    mkdirSync(dir, { recursive: true });
    atomicWriteFileSync(join(dir, STORE_INDEX_ROOT_FILE), store.root);
  } catch {
    // the next resolve tries again
  }
}

/**
 * The index of `vault` this machine last wrote under a store last read at
 * `root`, or `null` when it holds none: for a probe that answered
 * `unknown`. A store.json a sync tool is rewriting, or two partitions that
 * briefly disagree, tell nothing about where the index lives, and falling
 * back to the vault's legacy location would read and write a different
 * database (a stale one, or an empty one rebuilt in full) until the store
 * reads again. The store id is what names the index directory, so every
 * store directory of this machine whose store was last read at `root`
 * ({@link rememberStoreRoot}) is looked in, and the most recently written
 * index wins. A store retired or moved away from `root` is never picked.
 */
export function lastStoreIndexPath(
  vault: string | null,
  root: string | null,
  dirs: PlatformDirsEnv = processDirsEnv(),
): string | null {
  if (root === null) return null;
  let ids: string[];
  try {
    ids = readdirSync(storesStateDir(dirs)).filter((name) => isUlid(name));
  } catch {
    return null;
  }
  let best: { readonly path: string; readonly mtimeMs: number } | null = null;
  for (const id of ids) {
    const stateDir = deviceStateDirFor(id, dirs);
    if (rememberedRoot(stateDir) !== root) continue;
    const path = join(stateDir, STORE_INDEX_DIR, indexKeyFor(id, vault), DERIVED_STORE_FILE);
    let mtimeMs: number;
    try {
      const stat = statSync(path);
      if (!stat.isFile()) continue;
      mtimeMs = stat.mtimeMs;
    } catch {
      continue;
    }
    if (best === null || mtimeMs > best.mtimeMs) best = { path, mtimeMs };
  }
  return best?.path ?? null;
}