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
/**
* Pi adapter — skill symlink, no MCP.
*
* Pi (pi.dev / pi-mono) intentionally chose "CLI-tool + README + skill"
* over MCP. For OSB this means: drop the `brain-memory` skill into
* Pi's `~/.pi/skills/` directory as a symlink and let the agent
* invoke `o2b brain *` CLI commands from there.
*
* Plugin-source resolution order:
* 1. `opts.piSkillSource` (tests)
* 2. `OSB_PLUGIN_ROOT` env var + `/skills/brain-memory`
* 3. `import.meta.url` based — walks up to repo root
*
* Target-side resolution order:
* 1. `opts.piSkillDir` → `<piSkillDir>/brain-memory`
* 2. `PI_HOME` env var → `<PI_HOME>/skills/brain-memory`
* 3. `~/.pi/skills/brain-memory`
*/
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import {
existsSync,
lstatSync,
mkdirSync,
readlinkSync,
rmSync,
symlinkSync,
type Stats,
} from "node:fs";
import {
InstallError,
type ApplyOpts,
type ApplyResult,
type DetectResult,
type InstallAdapter,
type InstallEnv,
type InstallPlan,
type ManifestEntry,
type McpPayload,
type UninstallResult,
type VerifyResult,
type SessionPathsResult,
} from "../types.ts";
import { sessionPathsFor } from "../session-paths.ts";
import { recordEntry, readManifest, removeEntry } from "../manifest.ts";
import { defaultRegistry } from "../registry.ts";
const TARGET = "pi";
const LABEL = "Pi (pi.dev)";
function repoRoot(): string {
return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
}
function resolveSourcePath(opts: ApplyOpts): string {
if (opts.piSkillSource) return opts.piSkillSource;
const envRoot = process.env["OSB_PLUGIN_ROOT"];
if (envRoot) return join(envRoot, "skills", "brain-memory");
return join(repoRoot(), "skills", "brain-memory");
}
function resolveTargetPath(env: InstallEnv, opts: ApplyOpts | { piSkillDir?: string }): string {
if ("piSkillDir" in opts && opts.piSkillDir) {
return join(opts.piSkillDir, "brain-memory");
}
const piHome = env.env["PI_HOME"];
const base = piHome && piHome.length > 0 ? piHome : join(env.home, ".pi");
return join(base, "skills", "brain-memory");
}
function targetPathFromEnvOnly(env: InstallEnv): string {
const piHome = env.env["PI_HOME"];
const base = piHome && piHome.length > 0 ? piHome : join(env.home, ".pi");
return join(base, "skills", "brain-memory");
}
function lstatOrNull(p: string): Stats | null {
try {
return lstatSync(p) as Stats;
} catch {
return null;
}
}
function ensureParent(target: string): void {
const parent = dirname(target);
if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
}
export const piAdapter: InstallAdapter = {
target: TARGET,
label: LABEL,
detect(env: InstallEnv): DetectResult {
const path = targetPathFromEnvOnly(env);
const stat = lstatOrNull(path);
if (stat === null) {
return { target: TARGET, status: "not-installed", configPath: path, notes: [] };
}
if (!stat.isSymbolicLink()) {
return {
target: TARGET,
status: "drift",
configPath: path,
notes: ["path exists but is not a symlink"],
};
}
return { target: TARGET, status: "installed", configPath: path, notes: [] };
},
plan(_payload: McpPayload, env: InstallEnv): InstallPlan {
const target = targetPathFromEnvOnly(env);
return {
target: TARGET,
steps: [
{
kind: "symlink",
path: target,
preview: `symlink ${target} → <plugin>/skills/brain-memory`,
},
],
postNotes: ["Pi reads skills from its own skills directory; no MCP registration needed."],
};
},
apply(_plan: InstallPlan, _payload: McpPayload, env: InstallEnv, opts: ApplyOpts): ApplyResult {
const target = resolveTargetPath(env, opts);
const source = resolveSourcePath(opts);
if (!existsSync(source)) {
throw new InstallError(
`pi: skill source not found at ${source}; cannot create symlink`,
TARGET,
"config-missing",
"verify the plugin checkout is intact",
);
}
const stat = lstatOrNull(target);
if (stat) {
if (stat.isSymbolicLink()) {
// Resolve the link target relative to the symlink's directory so
// `current === source` holds for both absolute and relative link
// targets (e.g. `../../skills/brain-memory`).
const current = resolve(dirname(target), readlinkSync(target));
const canonicalSource = resolve(source);
if (current === canonicalSource) {
const manifest = buildManifest(env, target);
if (!opts.dryRun) recordEntry(env.vault, manifest);
return { target: TARGET, manifest, steps_executed: 0 };
}
if (!opts.dryRun) rmSync(target, { force: true });
} else {
if (!opts.force) {
throw new InstallError(
`pi: target ${target} exists and is not a symlink; refusing to clobber`,
TARGET,
"user-modified-block",
"re-run with --force to overwrite, or move the existing directory aside",
);
}
if (!opts.dryRun) rmSync(target, { recursive: true, force: true });
}
}
if (!opts.dryRun) {
ensureParent(target);
symlinkSync(source, target);
}
const manifest = buildManifest(env, target);
if (!opts.dryRun) recordEntry(env.vault, manifest);
return { target: TARGET, manifest, steps_executed: opts.dryRun ? 0 : 1 };
},
uninstall(env: InstallEnv, opts: ApplyOpts & { fromSnippet?: boolean }): UninstallResult {
const stored = readManifest(env.vault).installs[TARGET];
const skipped: Array<readonly [string, string]> = [];
const removed_paths: string[] = [];
const targets = stored?.owned_paths ?? [];
if (targets.length === 0 && !opts.fromSnippet) {
throw new InstallError(
"pi: no install manifest entry found",
TARGET,
"manifest-missing",
"o2b uninstall --target pi --apply --force-from-snippet",
);
}
const list = targets.length > 0 ? targets : [targetPathFromEnvOnly(env)];
for (const t of list) {
const stat = lstatOrNull(t);
if (!stat) {
skipped.push([t, "not present"]);
continue;
}
if (!stat.isSymbolicLink()) {
skipped.push([t, "not a symlink — refusing to remove"]);
continue;
}
if (!opts.dryRun) rmSync(t, { force: true });
removed_paths.push(t);
}
if (!opts.dryRun) removeEntry(env.vault, TARGET);
return { target: TARGET, removed_keys: [], removed_paths, skipped };
},
verify(env: InstallEnv): VerifyResult {
const stored = readManifest(env.vault).installs[TARGET];
if (!stored) {
return {
target: TARGET,
status: "not-installed",
details: ["no install manifest entry"],
fix_hint: null,
};
}
const path = stored.owned_paths?.[0] ?? targetPathFromEnvOnly(env);
const stat = lstatOrNull(path);
if (!stat || !stat.isSymbolicLink()) {
return {
target: TARGET,
status: "drift",
details: [stat ? `${path} is not a symlink` : `${path} not present`],
fix_hint: "o2b install --target pi --apply",
};
}
const linkTarget = readlinkSync(path);
const resolvedTarget = resolve(dirname(path), linkTarget);
if (!existsSync(resolvedTarget)) {
return {
target: TARGET,
status: "drift",
details: [`${path} → ${linkTarget} (target missing)`],
fix_hint: "o2b install --target pi --apply",
};
}
return {
target: TARGET,
status: "ok",
details: [`${path} → ${linkTarget}`],
fix_hint: null,
};
},
/**
* Where this runtime keeps session logs, from the one declaration.
* `Pi is installed as a skill symlink and keeps no transcript store, so the declaration is empty and the answer is null.`
*/
sessionPaths(env: InstallEnv): SessionPathsResult | null {
return sessionPathsFor(TARGET, env);
},
};
function buildManifest(env: InstallEnv, target: string): ManifestEntry {
return {
target: TARGET,
applied_at: env.now.toISOString(),
operation: "symlink",
config_path: null,
owned_paths: [target],
};
}
defaultRegistry.register(piAdapter);