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
/**
* Grok Build session adapter.
*
* Grok persists each session under
* `${GROK_HOME:-~/.grok}/sessions/<url-encoded-cwd>/<session-id>/updates.jsonl`
* as a newline-delimited ACP session-update stream. Every line is
*
* {"timestamp": <unix-seconds>, "method": "session/update",
* "params": {"sessionId": "...", "update": {"sessionUpdate": "<kind>", ...}}}
*
* (shapes captured from live grok 0.2.45). The kinds this adapter maps:
* - `user_message_chunk` / `agent_message_chunk`: `update.content.text` is a
* fragment of a streamed message. Consecutive chunks of the same role are
* coalesced into one turn so a message - and any `@osb` marker inside it -
* is never split across turns.
* - `tool_call`: `update.title` is the tool name (e.g.
* `open-second-brain__brain_note`), `update.rawInput` the input,
* `update.toolCallId` the id. (`tool_call_update` carries only progress /
* output for the same id, so it is skipped.)
* Other kinds (`available_commands_update`, `agent_thought_chunk`,
* `tool_call_update`, `plan`, ...) are skipped: the ACP stream is an evolving
* protocol, so an unrecognized update kind is ignored rather than failing the
* import. The structural gate is the first line - it must be a grok
* `session/update`, or the import throws PARSE.
*/
import { basename, dirname } from "node:path";
import { readLines } from "./read-lines.ts";
import { SESSION_TIMESTAMP_UNKNOWN, SessionImportError } from "./types.ts";
import type { SessionAdapter, SessionTurn } from "./types.ts";
interface GrokUpdate {
readonly sessionId: string | null;
readonly kind: string;
readonly raw: Record<string, unknown>;
/** ISO-8601 derived from the line's unix-seconds `timestamp`. */
readonly timestamp: string;
}
function asRecord(value: unknown): Record<string, unknown> | null {
if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
return value as Record<string, unknown>;
}
function isoFrom(ts: unknown): string {
if (typeof ts === "number" && Number.isFinite(ts)) {
return new Date(ts * 1000).toISOString();
}
return SESSION_TIMESTAMP_UNKNOWN;
}
/** Parse one line into its `session/update` payload, or null if it is not one. */
function parseUpdateLine(line: string): GrokUpdate | null {
let obj: unknown;
try {
obj = JSON.parse(line);
} catch {
return null;
}
const o = asRecord(obj);
if (!o || o["method"] !== "session/update") return null;
const params = asRecord(o["params"]);
if (!params) return null;
const update = asRecord(params["update"]);
if (!update || typeof update["sessionUpdate"] !== "string") return null;
return {
sessionId: typeof params["sessionId"] === "string" ? params["sessionId"] : null,
kind: update["sessionUpdate"],
raw: update,
timestamp: isoFrom(o["timestamp"]),
};
}
function chunkText(update: Record<string, unknown>): string {
const content = asRecord(update["content"]);
return content && typeof content["text"] === "string" ? content["text"] : "";
}
/**
* Grok namespaces MCP tools as `<server>__<tool>` (e.g.
* `open-second-brain__brain_feedback`); built-in tools (`search_replace`,
* `run_terminal_command`) carry no `__`. Strip the namespace to the bare tool
* name so the import's exact-match replay (`name === "brain_feedback"`) fires,
* matching what every other adapter yields. Built-in names pass through.
*/
function bareToolName(title: string): string {
const sep = title.lastIndexOf("__");
return sep === -1 ? title : title.slice(sep + 2);
}
function notAGrokStream(): SessionImportError {
return new SessionImportError(
"PARSE",
"grok session: first line is not an ACP session/update; not a grok updates.jsonl stream",
);
}
const ROLE_BY_KIND: Readonly<Record<string, "user" | "assistant">> = {
user_message_chunk: "user",
agent_message_chunk: "assistant",
};
export const grokAdapter: SessionAdapter = {
id: "grok",
detect(firstLine: string): boolean {
return parseUpdateLine(firstLine) !== null;
},
async *iterate(path: string): AsyncIterable<SessionTurn> {
// The structural gate is the first non-empty line. Streaming cannot
// rewind, so that line is gated as it arrives and then processed by the
// same loop body as every other line.
let sessionId = "";
let gated = false;
let seq = 0;
const nextId = (): string => `${sessionId}:${seq++}`;
// Buffered coalescing of consecutive same-role message chunks.
let buf: { role: "user" | "assistant"; parts: string[]; timestamp: string } | null = null;
const flush = (): SessionTurn | null => {
if (buf === null) return null;
const turn: SessionTurn = {
turnId: nextId(),
timestamp: buf.timestamp,
role: buf.role,
text: buf.parts.join(""),
};
buf = null;
return turn;
};
for await (const rawLine of readLines(path)) {
const trimmed = rawLine.trim();
if (trimmed === "") continue;
const parsed = parseUpdateLine(trimmed);
if (!gated) {
gated = true;
if (parsed === null) throw notAGrokStream();
sessionId = parsed.sessionId ?? basename(dirname(path));
}
if (parsed === null) continue;
const timestamp = parsed.timestamp;
const role = ROLE_BY_KIND[parsed.kind];
if (role !== undefined) {
const text = chunkText(parsed.raw);
if (buf !== null && buf.role === role) {
buf.parts.push(text);
} else {
const pending = flush();
if (pending !== null) yield pending;
buf = { role, parts: [text], timestamp };
}
continue;
}
// Any non-message update is a turn boundary: flush the buffered message.
const pending = flush();
if (pending !== null) yield pending;
if (parsed.kind === "tool_call") {
const title = parsed.raw["title"];
if (typeof title === "string" && title.length > 0) {
const input = asRecord(parsed.raw["rawInput"]) ?? {};
const id = parsed.raw["toolCallId"];
yield {
turnId: nextId(),
timestamp,
role: "assistant",
toolCalls: [
{ name: bareToolName(title), input, ...(typeof id === "string" ? { id } : {}) },
],
};
}
}
// Every other kind (available_commands_update, agent_thought_chunk,
// tool_call_update, plan, ...) is intentionally skipped.
}
// A file that is empty or entirely blank never reached the gate.
if (!gated) throw notAGrokStream();
const tail = flush();
if (tail !== null) yield tail;
},
};