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
6.2 KB
Raw Blame
/**
 * May the caller of one request read a vault page at this path?
 *
 * A tool that reads a page's bytes on the caller's behalf and answers
 * something derived from them - whether a span occurs in it, which
 * capture scope it backs - must answer at the caller's reach, or the
 * derived answer discloses what the page itself would not. This module
 * binds the two existing per-path rules to one request, and adds no rule
 * of its own:
 *
 *   - visibility: `isPathReadableAtReach` at the reach the transport
 *     minted (`contextReach`, fail closed when none was minted);
 *   - ownership: `isPathOwnerVisible` under the server-resolved identity,
 *     only when `integrity.owner_scope_delivery` is `fail` (the same gate
 *     `gatedOwnerScopeView` reads).
 *
 * The predicate is a plain vault-relative path test rather than an
 * `ArtifactRefView`, because the reference view reads a path without a
 * `.md` extension as a Brain artifact id, and a source path may name any
 * vault file.
 */

import { join, resolve } from "node:path";

import { isOwnerVisible, pageOwner } from "../../core/graph/agent-scope.ts";
import { remoteDenyVisibilityTokens } from "../../core/graph/privacy-markers.ts";
import { TRANSPORT_REACH, type TransportReach } from "../../core/graph/transport-reach.ts";
import { isRemotelyReadable } from "../../core/graph/visibility.ts";
import {
  lanePagesInStore,
  laneVaultRoot,
  readLanePage,
  type LanePage,
} from "../../core/store/lane-pages.ts";
import { BRAIN_ROOT_REL } from "../../core/brain/path-constants.ts";
import { pathIsInside } from "../../core/path-safety.ts";
import { resolveOwnerScopeDelivery } from "../../core/brain/preferences-collect.ts";
import {
  isPathOwnerVisible,
  isPathReadableAtReach,
  type FrontmatterCache,
} from "../../core/search/result-filters.ts";
import { contextReach, type ServerContext, contextVault } from "../tool-contract.ts";

/** A vault-relative path test bound to one request's reach and owner. */
export type ReadablePredicate = (rel: string) => boolean;

/** Every path readable: the answer for a local reach with the ownership gate off. */
const READ_EVERYTHING: ReadablePredicate = () => true;

/**
 * The predicate for one request. Local reach with the ownership gate off
 * answers `true` without touching the filesystem.
 */
export function readableAtContextReach(ctx: ServerContext): ReadablePredicate {
  return readableAtContextReachOrUndefined(ctx) ?? READ_EVERYTHING;
}

/**
 * The predicate for one request, or `undefined` when it would withhold
 * nothing (local reach with the ownership gate off), so a reader that
 * skips work for an absent filter can be handed no filter at all.
 */
export function readableAtContextReachOrUndefined(
  ctx: ServerContext,
): ReadablePredicate | undefined {
  const reach = contextReach(ctx);
  const vault = contextVault(ctx);
  // A server with no vault is store-only: its record-lane pages are store
  // records, measured by the same frontmatter rules below; local reach
  // with the gate off withholds nothing.
  if (vault === null) return vaultlessReadable(ctx, reach);
  const scope = resolveOwnerScopeDelivery(vault, ctx.agentName).enforcedScope;
  if (reach === TRANSPORT_REACH.local && scope === null) return undefined;
  const root = resolve(ctx.vault);
  const cache: FrontmatterCache = new Map();
  const inVault: ReadablePredicate = (rel) =>
    // A path that leaves the vault names no page the caller could be
    // shown, and is answered before anything is read.
    pathIsInside(resolve(root, rel), root) &&
    isPathReadableAtReach(ctx.vault, rel, reach, cache) &&
    (scope === null || isPathOwnerVisible(ctx.vault, rel, scope, cache));
  if (!lanePagesInStore(vault)) return inVault;
  // A store-only machine: a record-lane page under `Brain/` is a store
  // record, measured from its fields; any other path (a memory page, a
  // vault note) is judged by the vault rules. Containment is answered
  // first, so a traversing path reads nothing.
  const lanes = storeLaneReadable(reach, scope);
  return (rel) => {
    const path = resolve(root, rel);
    if (!pathIsInside(path, root)) return false;
    const page = underBrain(root, path) ? readLanePage(vault, join(vault, rel)) : null;
    return page !== null ? lanes(page) : inVault(rel);
  };
}

/** Whether `path` (already inside `root`) is under `root`'s `Brain/` folder. */
function underBrain(root: string, path: string): boolean {
  return pathIsInside(path, join(root, BRAIN_ROOT_REL));
}

/**
 * The predicate of a server with no vault: a record-lane page is a lane
 * record (`storeLaneReadable`), a memory page (a preference or a signal)
 * is its store record, judged by `isPathReadableAtReach` and the owner
 * rule over the fields the record carries; local reach with the gate off
 * withholds nothing.
 */
function vaultlessReadable(
  ctx: ServerContext,
  reach: TransportReach,
): ReadablePredicate | undefined {
  const scope = resolveOwnerScopeDelivery(null, ctx.agentName).enforcedScope;
  if (reach === TRANSPORT_REACH.local && scope === null) return undefined;
  const root = laneVaultRoot(null);
  const lanes = storeLaneReadable(reach, scope);
  const cache: FrontmatterCache = new Map();
  return (rel) => {
    // A path that leaves the stand-in root names no record, and is
    // answered before anything is read.
    const path = resolve(root, rel);
    if (!pathIsInside(path, root)) return false;
    const page = underBrain(root, path) ? readLanePage(root, join(root, rel)) : null;
    if (page !== null) return lanes(page);
    return (
      isPathReadableAtReach(null, rel, reach, cache) &&
      (scope === null || isPathOwnerVisible(null, rel, scope, cache))
    );
  };
}

/**
 * The rule over a record-lane page kept as a store record: the same
 * `visibility:` and owner rules the vault check applies to a page's
 * frontmatter, read from the record's fields. Only called once the request
 * withholds something (remote reach, or the ownership gate on).
 */
function storeLaneReadable(
  reach: TransportReach,
  scope: string | null,
): (page: LanePage) => boolean {
  return (page) =>
    isRemotelyReadable(remoteDenyVisibilityTokens(page.frontmatter), reach) &&
    (scope === null || isOwnerVisible(pageOwner(page.frontmatter), scope));
}