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
/**
* Per-user base directories for the files this tool owns, per platform.
*
* One place answers "where does Open Second Brain keep its config, data,
* state and cache, and where does `o2b install-cli` put its launchers", so
* the config resolver, the session spools and the install surfaces cannot
* disagree about a path. Not everything reads it yet: the codegraph resync
* recipe (`cli/partner-codegraph-cron.ts`) emits a bash script that expands
* `${XDG_STATE_HOME:-$HOME/.local/state}` itself, at cron time on a POSIX
* host, where it agrees with the POSIX layout below by construction. The
* cache root and the data root have no production caller yet; the state
* root's first is the decision-model tuning mark (`eval/mark.ts`).
*
* POSIX (Linux, macOS, the BSDs): the XDG Base Directory layout, with the
* `XDG_*_HOME` variables honoured and `$HOME/.config`, `$HOME/.local/share`,
* `$HOME/.local/state`, `$HOME/.cache` as the defaults. macOS keeps the XDG
* layout rather than `~/Library` because every existing install already
* lives there.
*
* Windows: the `XDG_*_HOME` variables still win when set (an operator who
* sets one has said where the files go), otherwise every root is
* `%LOCALAPPDATA%` - the per-machine, non-roaming application-data root.
* Local rather than Roaming because what lives here is machine-bound: the
* vault path, the agent name (which carries the host), the search index
* cursor, the session spools. A roaming profile carrying `vault:
* D:\Vault` or `agent_name: claude-devbox-agent` to another machine would be
* wrong there. Hermes Agent makes the same choice (`%LOCALAPPDATA%\hermes`).
* Launchers go to `%USERPROFILE%\.local\bin`, the directory the native
* Claude Code and uv installers already put on the user's PATH.
*
* Every function takes an injected {@link PlatformDirsEnv} so tests can
* exercise any platform from any host; the zero-argument forms read the
* running process.
*/
import { homedir } from "node:os";
import { join, posix, win32 } from "node:path";
/** Injected view of the environment the resolvers read. */
export interface PlatformDirsEnv {
/** `process.platform` value. */
readonly platform: string;
/** `homedir()` value. */
readonly home: string;
readonly env: Readonly<Record<string, string | undefined>>;
}
/** The directory name this tool uses under every base directory. */
export const APP_DIR_NAME = "open-second-brain";
/** The running process as a {@link PlatformDirsEnv}. */
export function processDirsEnv(): PlatformDirsEnv {
return { platform: process.platform, home: homedir(), env: process.env };
}
/** True on native Windows (not WSL, which reports `linux`). */
export function isWindows(source: Pick<PlatformDirsEnv, "platform"> = process): boolean {
return source.platform === "win32";
}
function nonEmpty(value: string | undefined): string | null {
return value !== undefined && value.length > 0 ? value : null;
}
/**
* `%LOCALAPPDATA%`, or `%USERPROFILE%\AppData\Local` when a stripped
* environment (a service, a scheduled task with a minimal block) lacks it.
*/
export function windowsLocalAppData(source: PlatformDirsEnv): string {
return nonEmpty(source.env["LOCALAPPDATA"]) ?? win32.join(source.home, "AppData", "Local");
}
/**
* `%APPDATA%` (Roaming), or `%USERPROFILE%\AppData\Roaming` when unset.
* Not used for this tool's own files; exposed for the hosts that keep
* their state there (Cursor, VS Code).
*/
export function windowsRoamingAppData(source: PlatformDirsEnv): string {
return nonEmpty(source.env["APPDATA"]) ?? win32.join(source.home, "AppData", "Roaming");
}
type BaseKind = "config" | "data" | "state" | "cache";
const XDG_VARIABLE: Readonly<Record<BaseKind, string>> = Object.freeze({
config: "XDG_CONFIG_HOME",
data: "XDG_DATA_HOME",
state: "XDG_STATE_HOME",
cache: "XDG_CACHE_HOME",
});
const POSIX_DEFAULT: Readonly<Record<BaseKind, ReadonlyArray<string>>> = Object.freeze({
config: [".config"],
data: [".local", "share"],
state: [".local", "state"],
cache: [".cache"],
});
function baseDir(kind: BaseKind, source: PlatformDirsEnv): string {
const xdg = nonEmpty(source.env[XDG_VARIABLE[kind]]);
if (xdg) return xdg;
if (isWindows(source)) return windowsLocalAppData(source);
// A POSIX layout keeps POSIX separators even when resolved on a Windows
// host (an injected source), so callers joining onto it stay consistent.
return posix.join(source.home, ...POSIX_DEFAULT[kind]);
}
/**
* Base directory for user configuration: `$XDG_CONFIG_HOME`, else
* `%LOCALAPPDATA%` on Windows, else `$HOME/.config`. Callers append
* {@link APP_DIR_NAME} (or another tool's directory) themselves.
*/
export function configBaseDir(source: PlatformDirsEnv = processDirsEnv()): string {
return baseDir("config", source);
}
/** Base directory for user data (`$XDG_DATA_HOME` / `%LOCALAPPDATA%` / `~/.local/share`). */
export function dataBaseDir(source: PlatformDirsEnv = processDirsEnv()): string {
return baseDir("data", source);
}
/** Base directory for user state (`$XDG_STATE_HOME` / `%LOCALAPPDATA%` / `~/.local/state`). */
export function stateBaseDir(source: PlatformDirsEnv = processDirsEnv()): string {
return baseDir("state", source);
}
/** Base directory for user cache (`$XDG_CACHE_HOME` / `%LOCALAPPDATA%` / `~/.cache`). */
export function cacheBaseDir(source: PlatformDirsEnv = processDirsEnv()): string {
return baseDir("cache", source);
}
/**
* This tool's own root under the state base directory:
* `<stateBaseDir>/open-second-brain`. Machine-side state lives here -
* files the tool itself consumes and that must never sync with the
* vault. The decision-model tuning marks (`eval/mark.ts`) are the first
* production caller.
*/
export function stateRootDir(source: PlatformDirsEnv = processDirsEnv()): string {
return join(baseDir("state", source), APP_DIR_NAME);
}
/**
* Machine-side state directory for the decision-model feature: the
* tuning marks the config resolver consults sit under it, keyed by
* threshold profile and use. Outside every vault by construction.
*/
export function decisionModelStateDir(source: PlatformDirsEnv = processDirsEnv()): string {
return join(stateRootDir(source), "decision-model");
}
/**
* Directory `o2b install-cli` publishes launchers into: `~/.local/bin` on
* every platform (`%USERPROFILE%\.local\bin` on Windows).
*/
export function userBinDir(source: PlatformDirsEnv = processDirsEnv()): string {
return join(source.home, ".local", "bin");
}
/**
* The same directories written for humans, with the variables unexpanded:
* what documentation and ownership listings print so the text is right on
* the platform that reads it.
*/
export function describeBaseDir(kind: BaseKind, platform: string = process.platform): string {
const xdg = XDG_VARIABLE[kind];
if (platform === "win32") return `%${xdg}% if set, else %LOCALAPPDATA%`;
return `\${${xdg}:-~/${POSIX_DEFAULT[kind].join("/")}}`;
}
/**
* The stand-in vault path of a machine with no vault (task 2.10): a path
* below the state root that is never created. Code that takes a vault
* string is handed it so every store-only branch runs; a resolver of
* machine state treats it as no vault at all.
*/
export function noVaultRoot(): string {
return join(stateRootDir(processDirsEnv()), "no-vault");
}