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
5.2 KB
Raw Blame
/**
 * Walk the vault, yielding `.md` files that should be indexed.
 *
 * Anchored in docs/plans/2026-05-16-brain-search-design.md §6 edge cases
 * (symlinks, ignore list).
 *
 * v0.10.9: scope decisions are delegated to `src/core/vault-scope` so
 * the search indexer and `scan-inline` share one policy. `parseIgnore`
 * (CSV string ➝ set) was removed in this version;
 * `ResolvedSearchConfig.scopeRules` is already classified at
 * config-resolution time.
 *
 * v1.46.0: the same delegation now carries the positive
 * `vault.include_paths` allowlist. Files are gated with `matchScope`
 * and directories with `mayDescend`, which are different questions - a
 * directory that holds no included file may still be the only route to
 * a declared root.
 */

import { readdirSync, statSync, realpathSync, type Dirent, type Stats } from "node:fs";
import { join, relative, sep } from "node:path";

import { canonicalNotePath } from "../path-safety.ts";
import { admitToIndex } from "../vault-scope/index-admission.ts";
import { matchScope, mayDescend } from "../vault-scope/index.ts";
import type { ResolvedSearchConfig } from "./types.ts";

export interface WalkedFile {
  /** Absolute path on disk. */
  readonly absPath: string;
  /** Vault-relative POSIX path. */
  readonly relPath: string;
  readonly stat: Stats;
}

function isInsideVault(absTarget: string, vaultReal: string): boolean {
  try {
    const r = realpathSync(absTarget);
    return r === vaultReal || r.startsWith(vaultReal + sep);
  } catch {
    return false;
  }
}

/**
 * Synchronous generator yielding every `.md` file under `config.vault`
 * (respecting `config.scopeRules`). The caller drives the iteration so
 * the indexer can pipeline reads + writes without buffering the whole
 * tree.
 */
export function* walkVault(config: ResolvedSearchConfig): Generator<WalkedFile> {
  // No vault (design D14): there are no notes to walk; the index holds the
  // brain store's records only.
  const vault = config.vault;
  if (vault === null) return;
  const vaultReal = (() => {
    try {
      return realpathSync(vault);
    } catch {
      return vault;
    }
  })();
  // Track real (canonical) paths of visited directories so a symlink
  // pointing back at an ancestor (or sibling) cannot send the walker
  // into an infinite loop. `isInsideVault` covers escape outside the
  // vault but is not acyclic on its own.
  const seenDirs = new Set<string>([vaultReal]);
  const rules = config.scopeRules;

  function* walk(dir: string): Generator<WalkedFile> {
    let entries: Dirent[];
    try {
      entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" }) as Dirent[];
    } catch {
      return;
    }
    // Sort by name so two identical vaults produce the same traversal
    // order across filesystems and platforms — important for the
    // deterministic-indexing contract and for stable Syncthing peers.
    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
    for (const entry of entries) {
      const absPath = join(dir, entry.name);
      const relPathRaw = relative(vaultReal, absPath);
      if (relPathRaw === "" || relPathRaw.startsWith("..")) continue;
      // Canonical note identity (POSIX + NFC). `absPath` stays in the
      // on-disk form for I/O (APFS lookup is normalisation-insensitive),
      // but the vault-relative key that identifies the note - matched
      // against the stored index path and against ignore rules - must be
      // one value across a macOS (NFD) / Linux (NFC) Syncthing peer set.
      const relPath = canonicalNotePath(relPathRaw);

      const isLinkHint = entry.isSymbolicLink();

      let stat: Stats;
      try {
        stat = statSync(absPath);
      } catch {
        continue;
      }

      if (stat.isDirectory()) {
        // Descent, not membership: an allowlist root may live below a
        // directory that holds no included file of its own.
        if (!mayDescend(relPath, rules)) continue;
        // Index-admission predicate (seam 2): skip descending into an
        // excluded lane directory (e.g. the exact-state lane) entirely.
        if (!admitToIndex(relPath).admit) continue;
        let dirReal: string;
        try {
          dirReal = realpathSync(absPath);
        } catch {
          continue;
        }
        if (dirReal !== vaultReal && !dirReal.startsWith(vaultReal + sep)) continue;
        if (seenDirs.has(dirReal)) continue;
        seenDirs.add(dirReal);
        yield* walk(absPath);
        continue;
      }

      if (!stat.isFile()) continue;
      if (!entry.name.toLowerCase().endsWith(".md")) continue;
      if (isLinkHint && !isInsideVault(absPath, vaultReal)) continue;
      // File-level rule too: a `path/to/file.md` entry in
      // `vault.ignore_paths` excludes that exact file, and a declared
      // `vault.include_paths` admits only what it names.
      if (!matchScope(relPath, rules).inScope) continue;
      // Index-admission predicate (seam 2): the exact-state lane and any
      // other lane-owned artifact never enters the index. Defaults to
      // admit, so all existing non-lane content is yielded unchanged.
      if (!admitToIndex(relPath).admit) continue;

      yield { absPath, relPath, stat };
    }
  }

  yield* walk(vaultReal);
}