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
4.1 KB
Raw Blame
/**
 * Hermes Agent .jsonl adapter.
 *
 * First line is a meta block `{ "role": "session_meta", "tools":
 * [...], ... }`. Conversation turns:
 *
 *   - `{ "role": "user" | "assistant" | "tool",
 *        "content": string-or-empty,
 *        "tool_calls"?: [{ id, call_id, type: "function",
 *                          function: { name, arguments: "json-string" } }],
 *        "timestamp": "ISO" }`
 *
 * The `tool` role is skipped — it carries function-call results, not
 * agent-issued signals. `session_meta` is skipped too. User and
 * assistant rows are emitted; assistant rows with `tool_calls` get
 * the calls flattened into `SessionToolCall[]` with JSON-decoded
 * arguments.
 *
 * Hermes timestamps are stored without a `Z` suffix (e.g.
 * `2026-05-03T19:59:06.411024`). We accept them as-is — they parse
 * the same with `new Date()`.
 */

import { readLines } from "./read-lines.ts";
import { SESSION_TIMESTAMP_UNKNOWN } from "./types.ts";
import type { SessionAdapter, SessionToolCall, SessionTurn } from "./types.ts";

interface HermesToolCall {
  readonly id?: string;
  readonly call_id?: string;
  readonly type?: string;
  readonly function?: {
    readonly name?: string;
    readonly arguments?: string;
  };
}

function decodeArguments(raw: unknown): Record<string, unknown> {
  if (typeof raw === "string" && raw.length > 0) {
    try {
      const parsed = JSON.parse(raw);
      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
        return parsed as Record<string, unknown>;
      }
      return { _raw_arguments: raw };
    } catch {
      return { _raw_arguments: raw };
    }
  }
  if (raw !== undefined && raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
    return raw as Record<string, unknown>;
  }
  return {};
}

function buildTurn(obj: Record<string, unknown>, fallbackIndex: number): SessionTurn | null {
  const role = obj["role"];
  if (role !== "user" && role !== "assistant") return null;
  const turnId = `hermes-${fallbackIndex}`;
  const timestamp =
    typeof obj["timestamp"] === "string" && obj["timestamp"].length > 0
      ? (obj["timestamp"] as string)
      : SESSION_TIMESTAMP_UNKNOWN;

  const text =
    typeof obj["content"] === "string" && obj["content"].length > 0
      ? (obj["content"] as string)
      : undefined;

  const rawCalls = obj["tool_calls"];
  let toolCalls: SessionToolCall[] | undefined;
  if (Array.isArray(rawCalls)) {
    const collected: SessionToolCall[] = [];
    for (const raw of rawCalls) {
      if (raw === null || typeof raw !== "object") continue;
      const tc = raw as HermesToolCall;
      const fn = tc.function;
      if (!fn || typeof fn.name !== "string") continue;
      const id = tc.id ?? tc.call_id;
      collected.push({
        name: fn.name,
        input: decodeArguments(fn.arguments),
        ...(typeof id === "string" ? { id } : {}),
      });
    }
    if (collected.length > 0) toolCalls = collected;
  }

  return {
    turnId,
    timestamp,
    role,
    ...(text !== undefined ? { text } : {}),
    ...(toolCalls !== undefined ? { toolCalls } : {}),
  };
}

export const hermesAdapter: SessionAdapter = {
  id: "hermes",
  detect(firstLine: string): boolean {
    let obj: unknown;
    try {
      obj = JSON.parse(firstLine);
    } catch {
      return false;
    }
    if (obj === null || typeof obj !== "object") return false;
    const o = obj as Record<string, unknown>;
    if (o["role"] !== "session_meta") return false;
    // `tools` is the discriminator that separates Hermes from any
    // other "role: session_meta" shape (Claude / Codex meta lines
    // never set `tools` as a top-level array).
    return Array.isArray(o["tools"]);
  },
  async *iterate(path: string): AsyncIterable<SessionTurn> {
    let i = 0;
    for await (const line of readLines(path)) {
      i++;
      const trimmed = line.trim();
      if (trimmed === "") continue;
      let obj: unknown;
      try {
        obj = JSON.parse(trimmed);
      } catch {
        continue;
      }
      if (obj === null || typeof obj !== "object") continue;
      const turn = buildTurn(obj as Record<string, unknown>, i);
      if (turn) yield turn;
    }
  },
};