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.
Grok Build native integration - config.toml MCP, native hooks, session import, hook-payload compat
Status: implemented (superseded MCP/hooks delivery; see Correction below) Author: claude-dev-agent (via feature-release-playbook) Audience: implementation Kanban: t_0eda929d (epic) with children t_fc98eef2, t_23cd40bc, t_b69deebd, t_8fdd6077, t_f7111278
Correction (2026-06-12) - the bundled-plugin approach did NOT work; superseded
The original design (below) shipped MCP and hooks as a bundled grok plugin under
~/.grok/plugins/open-second-brain/. Validated against live grok 0.2.45 (session debug
log), that does NOT deliver working tools/hooks in a real session:
- The plugin's
.mcp.jsonused a bareo2bcommand. grok spawns MCP servers with a restricted PATH that excludes~/.local/bin, soo2bfails with ENOENT and zero tools load. (The earlier "verified, 71 tools" was a false positive:grok mcp doctorruns with the interactive shell PATH, masking the session-spawn failure.) - Plugin-provided hooks are not discovered in a session (
hooks: discovery complete total_hooks=0); the plugin.mcp.jsonis also lower priority thanconfig.toml.
The shipped, working design (implemented; proven in a real session: 71 + 5 MCP tools registered, 10 hooks discovered and dispatched):
- MCP ->
~/.grok/config.toml[mcp_servers.open-second-brain]/[mcp_servers.open-second-brain-writer](grok's primary, highest-priority source), with an ABSOLUTE commandbun run <repo>/src/cli/main.ts mcp …(bun =process.execPath, repo and vault resolved at install).src/core/install/grok-config.tsis a minimal, dependency-free TOML editor that ensures/removes only these two tables, preserving all other config. - Hooks ->
~/.grok/hooks/open-second-brain.json(grok's native, always-trusted hooks dir), absolutebun run <repo>/hooks/<name>.tscommands.src/core/install/grok-asset.tsrenders both artifacts. - The bundled plugin (
plugins/grok/,grok-plugin-asset.ts) is removed. The session-import adapter (sessions/grok.ts) and the hook-payload compat (hooks/lib/*) are unchanged - they were correct independent of the delivery mechanism.
The sections below are the original (superseded) plugin design, kept for the audit trail.
Problem statement
Open Second Brain integrates deeply with Claude Code, OpenAI Codex, and opencode (MCP
registration, lifecycle hooks, session import) but has no Grok Build (grok, xAI) support.
Grok auto-reads Claude Code and Cursor config, so a user who already runs the Claude Code
integration gets partial pickup, but pure-grok users get nothing, grok sessions are never
imported into the Brain, our hook scripts misparse grok's stdin payload, and there is no
first-class, marketplace-publishable grok unit. This ships a native grok integration matching
the depth of the existing runtimes.
Scope
- A bundled grok plugin (
plugins/grok/open-second-brain/):plugin.jsonmanifest,.mcp.jsonwith the two canonical Open Second Brain MCP servers,hooks/hooks.jsonwith three lifecycle hooks (SessionStart active-context inject, PostToolUse post-write logging nudge, SessionEnd session capture). The plugin is the marketplace-publishable unit. - A
grokinstall target (o2b install --target grok --apply) that installs the plugin under~/.grok/plugins/open-second-brain/(auto-trusted), ensures it is enabled, records it in the install manifest, reports drift onverify, and reverses onuninstall. - A
groksession adapter that imports~/.grok/sessions/<cwd>/<id>/updates.jsonl(ACP stream) with lineage fromsummary.jsonparent_session_id, wired throughimportSessionPath. - Hook-payload compatibility: the shared hook stdin parser learns grok's camelCase payload so
the hooks run under grok (whether via native
~/.grok/hooks/or grok's Claude-compat scan). - Docs:
install/grok.md,install.mdtable,README.mdruntime list,docs/how-it-works.mdintegration section,CHANGELOG.md.
Out of scope
- Writing
~/.claude.json/~/.claude/settings.jsonfor pure-grok users (Variant 3, rejected: impersonates a foreign vendor's namespace). - A general TOML serialization layer for the MCP payload (Variant 1, rejected). MCP lives in the
plugin's
.mcp.json(standard JSON), so the canonicalMcpServerEntryis reused verbatim and no TOML touches the MCP payload. grok mcp addshelling andgrok plugin installshelling for the install path: rejected to keep the adapter offline-unit-testable and free of a hard runtime dependency on the grok binary. (grokIS used in QA smoke tests, just not as an apply-time dependency.)- LSP server registration (
.lsp.json),commands/,agents/plugin components: not needed. - PreCompact extraction parity: handled by session capture; revisit if a gap shows in the field.
Chosen approach
Variant 2 from variants.md (consultant-recommended, accepted without override).
The bundled plugin is the single first-class artifact, mirroring the opencode bundled plugin.
src/core/install/grok-plugin-asset.ts resolves the bundled plugin tree and a version stamp
(mirroring opencode-plugin-asset.ts). The plugin directory holds:
plugin.json- nameopen-second-brain, version mirrored frompackage.jsonvia the version-sync script, description, metadata. Passesgrok plugin validate..mcp.json- MCP standard format{ "mcpServers": { ... } }. STATIC and vault-agnostic, mirroring the repo's existing Claude plugin file./.mcp.json:command${CLAUDE_PLUGIN_ROOT}/scripts/o2b, args["mcp"]and["mcp", "--scope", "writer"]. Grok populates${CLAUDE_PLUGIN_ROOT}via its documented alias ofGROK_PLUGIN_ROOT, ando2b mcpresolves the vault from the persisted config (no--vaultarg, no install-time generation). This is the plugin-scoped MCP form already proven by the Claude integration, NOT thebuildPayload(--vault <path>) form the file-config adapters use; the two forms are intentionally different and the grok plugin reuses the plugin-scoped one.hooks/hooks.json- mirrors the repo's existing Claude plugin./hooks/hooks.json(sameo2b-hook active-inject | post-write-reminder | session-capturecommands, same$CLAUDE_PLUGIN_ROOT-then-PATH fallback), with grok-specific adjustments:- Lifecycle events (
SessionStart,SessionEnd,UserPromptSubmit,Stop) carry NOmatcher- grok rejects a matcher on those events. Tool events (PostToolUse) keep theirs. PostToolUsematcher lists both the Claude-style names (Write|Edit|MultiEdit|apply_patch) and grok's aliasedsearch_replace, since grok maps Claude tool names to its own.- Session capture is wired on
SessionEnd(grok's terminal lifecycle event). - The commands bake in no vault path, so one bundle serves every vault and the content is deterministic for drift detection.
- Lifecycle events (
The grok install adapter (src/core/install/adapters/grok.ts) does NOT use the JSON-MCP
factory for MCP (MCP ships inside the plugin, not in a grok config file). Its plan/apply/verify/
uninstall manage the plugin tree:
apply: copy the bundled plugin tree into~/.grok/plugins/open-second-brain/(creating dirs), record every written path under the manifestowned_paths, and refresh an outdated copy.GROK_HOMEoverrides the base dir; honor it. NOconfig.tomltouch is needed: verified against live grok 0.2.45 that a user-scope plugin under~/.grok/plugins/<name>/is auto-enabled and auto-trusted (grok inspectshowsenabled: truewith its MCP servers and hooks active,grok mcp doctorstarts the server and discovers its tools), with config.toml carrying only[cli]. The docs' "plugins disabled by default" applies to marketplace and project-scope plugins, not user-scope ones. This drops the planned TOML enable helper entirely.verify: flag a missing, edited, or non-file (stray directory) plugin file as drift, with ao2b install --target grok --applyfix hint.uninstall: remove exactly theowned_pathsand the now-empty plugin directory, leaving unrelated grok config untouched.
The grok session adapter (src/core/brain/sessions/grok.ts) detects on the ACP updates.jsonl
structure, yields SessionTurn-shaped turns, and resolves lineage from a sibling summary.json
parent_session_id. A newer/unknown ACP shape fails with a versioned PARSE error.
Hook-payload compat (hooks/lib/stdin.ts + detect.ts): a single declarative field-mapping
normalizes grok's {hookEventName, sessionId, cwd, workspaceRoot, toolName, toolInput} into the
internal shape the Claude/Codex paths use; runtime detection recognizes grok via GROK_* env and
payload shape. Where grok omits a Claude field (transcript_path), the type stays optional and
the code branches explicitly rather than faking a default.
Design decisions
- Plugin is the MCP vehicle, not config.toml.
.mcp.jsonis standard JSON - zero TOML, and (per the verified enable finding below) zeroconfig.tomltouch at all. - Reuse the Claude plugin artifacts; the whole plugin tree is static and vault-agnostic. The
grok
.mcp.jsonandhooks/hooks.jsonmirror the repo's existing./.mcp.jsonand./hooks/hooks.json. Grok setsCLAUDE_PLUGIN_ROOTas an alias forGROK_PLUGIN_ROOTand reads the Claude-shape hook JSON, so those artifacts work under grok almost verbatim. NobuildPayload, no install-time generation, no vault path baked into the bundle. A unit test asserts the grok artifacts stay in sync with their Claude-plugin sources (the only allowed divergences are the documented grok adjustments: lifecycle-event matchers removed,SessionEndcapture), so the two never drift. - File-copy install, no
config.tomltouch, nogrok plugin install --trustshell. Verified on live grok: dropping the tree into~/.grok/plugins/<name>/is sufficient (auto-enabled and auto-trusted). The adapter stays offline-unit-testable and free of an apply-time grok-binary dependency, and the planned TOML enable helper proved unnecessary and was dropped. - Hook env vars over payload fields where grok provides both.
GROK_SESSION_ID/GROK_WORKSPACE_ROOT/CLAUDE_PROJECT_DIRare stable; the parser prefers them and falls back to payload fields, matching how the Claude layer already reads env first. - Capture via SessionEnd hook, import via adapter. The hook only triggers capture; the
adapter owns parsing
updates.jsonl. Same separation the opencode spool used, but grok's own session store is the source of truth (no spool file to own), so the adapter reads grok's files directly. - Matcher lists both tool-name spellings. grok maps Claude names to its own, but listing both
Edit|Write|MultiEditandsearch_replacemakes the hook robust whether grok applies the alias before or after matcher evaluation; verified in QA.
File changes
New:
plugins/grok/open-second-brain/plugin.json,.mcp.json,hooks/hooks.json- the bundled plugin tree (hooks use inlineo2b-hookcommands; nohooks/bin/scripts needed).src/core/install/grok-plugin-asset.ts- renders the grok artifacts from the Claude sources + exposes the committed bytes for the adapter.src/core/install/adapters/grok.ts- the install adapter (plugin-tree lifecycle).src/core/brain/sessions/grok.ts- the ACP session adapter.tests/core/install/adapters/grok.test.ts,tests/core/brain.sessions.grok.test.ts,tests/plugins/grok-plugin.test.ts,tests/hooks/grok-stdin.test.ts- per-unit tests.tests/fixtures/sessions/grok-minimal.jsonl(realupdates.jsonlcaptured from live grok),tests/fixtures/install/grok/fixtures.install/grok.md- install guide.
Modified:
src/core/install/registry.ts(or adapter self-register) - registergrok.src/core/install/adapters/types.tsif a target-id union exists - addgrok.src/core/brain/sessions/registry.ts(SESSION_ADAPTERS) +types.ts(SessionAdapterId) - addgrok.hooks/lib/stdin.ts,hooks/lib/detect.ts- grok payload normalization + runtime detection.- The version-sync script's manifest list, if
plugin.jsonversion must mirrorpackage.json. README.md,install.md,docs/how-it-works.md,CHANGELOG.md.
Risks and open questions
- Enable semantics: RESOLVED in Phase 2 against live grok 0.2.45. A user-scope plugin under
~/.grok/plugins/<name>/is auto-enabled and auto-trusted with noconfig.tomlentry (grok inspectreportsenabled: true, MCP + hooks active;grok mcp doctorhandshakes and discovers 71 tools). The planned[plugins] enabledTOML helper was therefore dropped. updates.jsonlACP event schema: typed from grok's ACP docs but must be pinned to a real captured session; theformat/version gate surfaces a shape mismatch as a versioned error, not silent corruption.- Whether grok applies matcher tool-name aliasing before or after matcher evaluation: the matcher lists both spellings to be safe; QA confirms which fires.
plugin.jsonversion mirroring: RESOLVED.plugins/grok/open-second-brain/plugin.jsonwas added toscripts/sync-version.tsJSON_TARGETS (and the CLAUDE.md mirrored-manifest list), so CI gates it againstpackage.json.