Grok CLI¶
Base path: ~/.grok (env override: GROK_HOME).
observed_version: grok-cli v0.1.219 (observed 2026-05-25).
Grok stores data under ~/.grok/sessions/ using URL-encoded project
paths as directory keys (e.g. %2Fhome%2Fd%2Fwork%2Fpython%2Fproj).
Each session is identified by a UUIDv7 (timestamp-sortable).
Stores¶
- Role:
prompt_history- Format:
jsonl- Coverage:
default_search- Adapter:
grok.prompt_history_jsonl.v1
- Role:
primary_chat- Format:
jsonl- Coverage:
default_search- Adapter:
grok.sessions_jsonl.v1
- Role:
supplementary_chat- Format:
sqlite- Coverage:
default_search- Adapter:
grok.session_search_sqlite.v1
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
-
- Role:
persistent_memory- Format:
md_frontmatter- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
opaque- Coverage:
catalog_only- Adapter:
-
grok.prompt_history¶
JSONL per-project user-prompt audit log. Keys: timestamp (ISO-8601 nanosecond), session_id (UUIDv7), prompt (text), is_bash (bool).
- Agent:
Grok
- Role:
prompt_history- Format:
jsonl- Coverage:
default_search- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/prompt_history.jsonl- Adapter:
grok.prompt_history_jsonl.v1- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
yes
grok.sessions¶
JSONL full session transcripts. type field discriminates system/user/assistant/tool_use/tool_result. content is text or content-blocks array. Includes tool calls and usage stats.
- Agent:
Grok
- Role:
primary_chat- Format:
jsonl- Coverage:
default_search- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/chat_history.jsonl- Adapter:
grok.sessions_jsonl.v1- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
yes
Full per-session transcript with tool calls; grok.prompt_history is the user-prompts-only audit log.
grok.session_search¶
SQLite with FTS5. Table session_docs: session_id, cwd, updated_at (unix seconds), title (generated), content (full-text index), content_hash. Schema version 3.
- Agent:
Grok
- Role:
supplementary_chat- Format:
sqlite- Coverage:
default_search- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/session_search.sqlite- Adapter:
grok.session_search_sqlite.v1- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
yes
Pre-indexed session titles and content for fast lookup. De-duplicate against grok.sessions by session_id.
grok.sessions.events¶
Per-session event stream with turn-level lifecycle events: turn_started, loop_started, phase_changed, tool_started, tool_finished. Schema version 1.0.
- Agent:
Grok
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/events.jsonl- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
no
grok.sessions.summary¶
Per-session summary: id, cwd, session_summary, created_at, updated_at, num_messages, current_model_id, git metadata, generated_title, agent_name.
- Agent:
Grok
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/sessions/<url_encoded_project>/<session_uuid>/summary.json- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
no
grok.memory¶
Persistent memory in Markdown; managed by Grok’s memory system.
- Agent:
Grok
- Role:
persistent_memory- Format:
md_frontmatter- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/memory/MEMORY.md- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
no
grok.logs¶
Structured application logs: ts, src, pid, lvl, msg, ctx. Debugging diagnostics, not chat content.
- Agent:
Grok
- Role:
app_state- Format:
jsonl- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/logs/unified.jsonl- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
no
grok.worktrees_db¶
SQLite database tracking git worktrees created by Grok.
- Agent:
Grok
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Path:
${GROK_HOME or ${HOME}/.grok}/worktrees.db- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
grok-cli v0.1.219 (observed 2026-05-25) (2026-05-25)
- Default search:
no
grok.config¶
Record schemas¶
grok.prompt_history¶
Per-project user-prompt audit log. One record per prompt, append-only.
{"timestamp": "2026-05-25T10:00:00.000000000Z",
"session_id": "019729a0-...", "prompt": "...", "is_bash": false}
Keys: timestamp (ISO-8601 nanosecond), session_id (UUIDv7),
prompt (user text), is_bash (bool — true for shell commands).
grok.sessions¶
Full session transcripts. The type field discriminates record
kinds: system, user, assistant, tool_use, tool_result.
content is either a plain string or a content-blocks array.
{"type": "user", "content": "explain the design",
"timestamp": "2026-05-25T10:00:01.000000000Z"}
grok.session_search¶
SQLite with FTS5. Table session_docs:
Column |
Type |
Description |
|---|---|---|
|
TEXT |
UUIDv7 primary key |
|
TEXT |
Working directory |
|
INTEGER |
Unix seconds |
|
TEXT |
Generated session title |
|
TEXT |
Full-text indexed body |
|
TEXT |
Content digest |
agentgrep converts updated_at to ISO-8601 for timestamp
consistency with other adapters.