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.1 KB
Raw Blame
/**
 * Vault-local artifact store for the MCP tool-result preview budget
 * (v0.18.0).
 *
 * When an MCP tool result exceeds its preview budget, the full
 * serialized payload is parked here so a text-only agent can pull it
 * back through `brain_artifact_get` instead of having it flood the
 * context window inline. Artifacts are ephemeral session scratch:
 *
 *   Brain/.artifacts/<run-id>/<artifact-id>.json
 *
 * Design notes:
 * - One store per MCP server process; the `runId` groups a process's
 *   outputs so they prune together.
 * - `artifactId` is a short SHA-256 of the persisted text - deterministic,
 *   dedupes identical payloads, depends on no clock or RNG.
 * - The text is run through `redactRawOutput` before it touches disk, so
 *   a tool that happened to surface a secret-shaped token never persists
 *   it. The returned `text`/`fullChars` reflect the redacted bytes so the
 *   caller's preview slice stays consistent with what was stored.
 * - Path construction funnels through `artifactPath` (→ `ensureInsideVault`),
 *   so a malformed `artifactId` from an MCP argument cannot traverse out.
 * - Pruning is best-effort and synchronous at construction time: no
 *   daemon, matching the "no hidden process" convention. The dot-directory
 *   is excluded from the vault walker exactly like `Brain/.snapshots`.
 */

import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
import { join } from "node:path";

import { artifactPath, artifactRunDir, brainArtifactsDir } from "../core/brain/paths.ts";
import { atomicWriteFileSync } from "../core/fs-atomic.ts";
import { redactRawOutput } from "../core/redactor.ts";

/** Length of the hex artifact id derived from the SHA-256 digest. */
const ARTIFACT_ID_HEX_LEN = 16;

export interface StoredArtifact {
  /** Content-hash id used to fetch the artifact back. */
  readonly artifactId: string;
  /** Run directory the artifact lives under. */
  readonly runId: string;
  /** Absolute path of the persisted file. */
  readonly path: string;
  /** Character count of the persisted (redacted) text. */
  readonly fullChars: number;
  /** The persisted (redacted) text, for the caller's preview slice. */
  readonly text: string;
}

export interface ArtifactStoreOptions {
  readonly vault: string;
  readonly runId: string;
}

export class ArtifactStore {
  private readonly vault: string;
  readonly runId: string;

  constructor(opts: ArtifactStoreOptions) {
    this.vault = opts.vault;
    this.runId = opts.runId;
  }

  /**
   * Persist `fullText` (after redaction) and return its metadata. Writing
   * the same content twice is idempotent: the content-hash id is stable
   * and the atomic write simply re-lands identical bytes.
   */
  put(fullText: string): StoredArtifact {
    // Scrub secrets but never truncate: the artifact IS the recoverable
    // full payload, so the receipt-oriented scan-window cap must not apply
    // here, or large results would be silently clipped on disk. The whole
    // payload is scanned, so also run the infra-topology pass — a bare
    // public IP or internal hostname in a stored tool result is the
    // likeliest topology leak and carries no key=value shape to catch it.
    const text = redactRawOutput(fullText, {
      maxInput: Number.POSITIVE_INFINITY,
      redactInfra: true,
    });
    const artifactId = createHash("sha256")
      .update(text, "utf8")
      .digest("hex")
      .slice(0, ARTIFACT_ID_HEX_LEN);
    const path = artifactPath(this.vault, this.runId, artifactId);
    mkdirSync(artifactRunDir(this.vault, this.runId), { recursive: true });
    atomicWriteFileSync(path, text);
    return { artifactId, runId: this.runId, path, fullChars: text.length, text };
  }

  /**
   * Read the full text for `artifactId` within this store's run. Returns
   * `null` when the id is well-formed but absent. Throws when the id is
   * malformed (path-traversal attempt) - the caller turns that into a
   * tool-level error envelope.
   */
  get(artifactId: string): string | null {
    const path = artifactPath(this.vault, this.runId, artifactId);
    if (!existsSync(path)) return null;
    return readFileSync(path, "utf8");
  }

  /**
   * Best-effort prune of run directories whose mtime is older than
   * `ttlMs`. Returns the count of directories removed. Never throws on a
   * single bad entry - pruning is a housekeeping convenience, not a
   * correctness requirement.
   */
  prune(ttlMs: number): number {
    const root = brainArtifactsDir(this.vault);
    if (!existsSync(root)) return 0;
    const cutoff = Date.now() - ttlMs;
    let removed = 0;
    let entries: string[];
    try {
      entries = readdirSync(root);
    } catch {
      return 0;
    }
    for (const entry of entries) {
      const dir = join(root, entry);
      try {
        const st = statSync(dir);
        if (!st.isDirectory()) continue;
        if (st.mtimeMs < cutoff) {
          rmSync(dir, { recursive: true, force: true });
          removed += 1;
        }
      } catch {
        // Entry vanished or is unreadable; skip it.
      }
    }
    return removed;
  }
}