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
/**
* Pure decision core for the opt-in strict PreToolUse read-block hook
* (retrieval-quality-and-context-delivery, D2 / t_36b0fd8d).
*
* Intent: nudge an agent to query the brain search surface before it re-reads
* raw vault files. With the strict flag on and no "recently oriented" stamp,
* the FIRST raw vault-file read of a session is denied once (with a redirect
* to the search surface), after which the hook downgrades to a soft nudge for
* the rest of the session. Any brain query/search refreshes the orientation
* stamp, which suppresses the block entirely.
*
* Two hard rules from the spec are encoded here:
* 1. "Raw vault-file read" detection is STRUCTURAL: it turns on the tool
* call's file path resolving inside the configured vault root. The tool
* name is used only as an exact read-vs-mutate discriminator (an exact
* allowlist, never a loose/substring match), so a Write/Edit inside the
* vault is never blocked and a Read outside the vault is never blocked.
* 2. Every failure path fails OPEN. A harness the plugin layer does not
* relay (anything that is not Claude Code or the opencode lane, whose
* plugin marks its synthetic payloads with the host marker) never
* receives a hard block (`deny`); the hook wrapper additionally maps
* unreadable state, malformed stamps, and a missing vault to `allow`.
* Fail-open here means "allow the action and record the reason", an
* explicit decision - never a swallowed error.
*
* The core is I/O-free: the caller resolves the runtime, the stamps, and the
* vault root, so this stays deterministic and unit-testable.
*/
import { resolve, sep } from "node:path";
/** Redirect shown when the first raw vault read is denied. */
export const ORIENT_DENY_MESSAGE =
"Strict orientation is on: query the brain search surface (brain_search / brain_query, or `o2b search`) before reading raw vault files. This first raw read is blocked once - run a brain search to orient, then retry the read.";
/** Soft reminder shown on subsequent raw reads after the one-time block. */
export const ORIENT_NUDGE_MESSAGE =
"Reminder: prefer the brain search surface (brain_search / brain_query) over raw vault reads - a brain query orients you and suppresses this reminder.";
/**
* Exact set of tool names that read a single file. Membership (not a loose
* substring test) is what distinguishes a raw READ from a mutate; the
* load-bearing structural signal is still the in-vault path below.
*/
const READ_TOOL_NAMES: ReadonlySet<string> = new Set(["Read"]);
/** Keys under which a tool's file-path argument may appear. */
const FILE_PATH_KEYS: ReadonlyArray<string> = ["file_path", "path"];
/**
* Tool-name suffixes that count as querying the brain search surface. Anchored
* on either string start or a `__` separator so a runtime-injected MCP prefix
* (`mcp__plugin_<plugin>_<server>__brain_search`) still matches. EXACT-suffix
* membership, not a loose substring test.
*/
const BRAIN_SEARCH_NAME_SUFFIX =
/(?:^|__)(brain_search|brain_query|second_brain_query|brain_search_expand|brain_search_by_source|brain_context_pack)$/;
/**
* The harnesses that receive the hard block: Claude Code, and opencode -
* whose plugin relays this same decision core through synthetic payloads
* marked `hook_host: opencode` (the lane's declared deny parity). Every
* other harness, and every payload that names no known harness, fails
* open.
*/
const HARD_BLOCK_RUNTIMES: ReadonlySet<string> = new Set(["claudecode", "opencode"]);
/**
* True when `name` is one of the brain search/query tools (or a
* runtime-decorated form thereof): querying the brain search surface is exactly
* the orientation the read block wants to encourage, so it refreshes the stamp.
*/
export function isBrainSearchToolName(name: string): boolean {
return BRAIN_SEARCH_NAME_SUFFIX.test(name);
}
export interface OrientInput {
/**
* Detected hook runtime label (e.g. from the hook layer's runtime detector).
* Only the relayed harnesses - `"claudecode"` and `"opencode"` - receive a
* hard block; any other value fails open.
*/
readonly runtime: string;
readonly toolName: string;
readonly toolInput: unknown;
/** Absolute configured vault root; a read resolving inside it is "raw". */
readonly vaultRoot: string;
/** True when the `osb.oriented.recent` stamp is live. */
readonly isOriented: boolean;
/** True when the `osb.oriented.blocked` stamp is live (block already fired). */
readonly alreadyBlocked: boolean;
}
export type OrientDecision =
| { readonly kind: "allow" }
| { readonly kind: "refresh_orientation" }
| { readonly kind: "deny"; readonly reason: string }
| { readonly kind: "nudge"; readonly reason: string };
/** Extract a file-path argument from a tool input object, if present. */
function extractFilePath(toolInput: unknown): string | null {
if (toolInput === null || typeof toolInput !== "object" || Array.isArray(toolInput)) {
return null;
}
const record = toolInput as Record<string, unknown>;
for (const key of FILE_PATH_KEYS) {
const value = record[key];
if (typeof value === "string" && value.length > 0) return value;
}
return null;
}
/**
* True when this tool call is a raw read of a file inside the vault root.
* Structural: an exact read-tool name AND a file path that resolves to the
* vault root or below it. A resolved path equal to the root, or prefixed by
* `root + sep`, is inside; a sibling directory sharing a name prefix is not.
*/
function isRawVaultRead(input: OrientInput): boolean {
if (!READ_TOOL_NAMES.has(input.toolName)) return false;
const raw = extractFilePath(input.toolInput);
if (raw === null) return false;
const resolved = resolve(raw);
const root = resolve(input.vaultRoot);
return resolved === root || resolved.startsWith(root + sep);
}
/**
* Decide what to do for one PreToolUse call. Orientation refresh takes
* priority; then non-raw-read calls and oriented sessions allow; then the
* one-time deny / soft-nudge ladder applies only to a relayed harness
* (Claude Code, or the opencode lane) - every other harness fails open.
*/
export function decideOrient(input: OrientInput): OrientDecision {
if (isBrainSearchToolName(input.toolName)) {
return Object.freeze({ kind: "refresh_orientation" });
}
if (!isRawVaultRead(input)) return Object.freeze({ kind: "allow" });
if (input.isOriented) return Object.freeze({ kind: "allow" });
// Harnesses the plugin layer does not relay stay nudge-only / fail-open:
// never a hard block.
if (!HARD_BLOCK_RUNTIMES.has(input.runtime)) return Object.freeze({ kind: "allow" });
if (!input.alreadyBlocked) {
return Object.freeze({ kind: "deny", reason: ORIENT_DENY_MESSAGE });
}
return Object.freeze({ kind: "nudge", reason: ORIENT_NUDGE_MESSAGE });
}