Grok Build memory across sessions: settings and limitations

Grok Build, xAI’s terminal agent, has cross-session memory: it can remember project conventions, decisions, and successful debugging steps, then add them to the context of a new session without reminders. The feature is off by default and experimental—it can be enabled with a single setting.

This description is based on the official guide in the xai-org/grok-build repository as of September 20, 2026. The mechanics are described based on the documentation, not personal testing.

Practical information about working with Ailoot is available in the documentation.

What does memory provide in Grok Build?#

For example, in one session you explained to the agent that the project uses two-space indentation, database migrations are run with a separate command, and a specific module handles payments. In a new session, you have to provide this information again.

With memory enabled, Grok Build can:

• recall project conventions you explained earlier;
• use debugging steps that have already worked;
• carry architectural decisions into later sessions;
• avoid asking again about things that have already been answered.

The feature is experimental and off by default. Until you enable it, the agent’s behavior does not change.

How do you enable memory?#

Once, for a single run:

GROK_MEMORY=1 grok

The variable applies only to this run. The command export GROK_MEMORY=1 keeps it in the current shell and enables memory for all subsequent grok runs from that shell—until the terminal session ends or you run export GROK_MEMORY=0.

Permanently, through the config. Add this to ~/.grok/config.toml:

[memory]
enabled = true

Inside a session, without restarting: open /memory and press t.

This toggle applies only to the current session and is not written to the config. It can be used to enable or disable memory. Disabling it removes access to memory tools, but does not delete the files from disk; enabling it again reopens the storage. The toggle cannot override a forced process-wide memory disable via GROK_MEMORY=0: /memory remains unavailable for the entire session.

If settings are specified in multiple places, they have the following priority:

• GROK_MEMORY=0 forcibly disables memory for the entire process and has the highest priority.
• An explicit enabled = false in the config disables memory, even if a managed remote setting enables it.
• Memory can be enabled with GROK_MEMORY=1, enabled = true in the config, or a managed remote setting.
• If nothing is specified, memory is off.

Notes are added on the first turn of a session. If you enabled memory in the middle of your work and want the agent to start using saved project information, run /new. You can check whether memory is enabled in the output of grok inspect.

What does Grok Build record, and where?#

The ~/.grok/memory/ directory structure:

A short hash of the repository identifier is added to the project directory name. The origin remote in “organization/repository” form is used for identification, or the directory path if there is no Git repository. Thus, clones and worktrees (separate working copies of Git branches) of the same repository share one project memory: what the agent remembers in one copy is available in another.

Entries are created in four ways:

1. Automatic session-end summary. When a session ends, Grok Build saves a short service summary to the daily log: the message count, up to five first substantive exchanges, and the date and time. The summary is built from metadata without a model call or delay. Very short sessions are skipped: if there are fewer than three substantive exchanges or less than 50 bytes of your text, no entry is created. The summary does not include tools used, file paths, or commands. Automatic summaries can be disabled with the session.save_on_end = false setting.
2. /flush—a detailed note on request. With this command, the model summarizes the most important points from the current session: decisions, patterns, debugging steps, and API findings. The summary is written to a dated log and indexed for future sessions. The documentation recommends running /flush before context compaction, at the end of a successful debugging session, and after discovering important patterns.
3. /remember—an explicit request to remember something. Type /remember always open PR links after sending or tell the agent, “remember that...” A review panel opens before the entry is written: the note is saved only after you confirm, and Memory saved to ~/.grok/memory/MEMORY.md appears in the feed. Project information goes into the project MEMORY.md; information shared across all projects goes into the global one.
4. /dream—consolidation. The command groups scattered logs and notes by topic and removes duplicates to make search more accurate. As with /flush, consolidation is performed by the model—it reads accumulated entries and rewrites them into topics, so you should periodically review the result with /memory. There is also an automatic mode: by default, Grok Build checks the conditions at startup and once an hour, and starts consolidation when at least 24 hours have passed and at least 5 sessions have accumulated. The thresholds can be configured in the [memory.dream] section of the config.

Notes are searched through a SQLite index: by default, it uses full-text FTS5, and if an embedding model is configured, semantic vector search is added.

How does memory get into a new session?#

The initial injection uses a selection threshold of min_score = 0.9, which you can change in the [memory.initial_injection] section. After automatic context compaction, the agent searches memory again to restore information that may have been removed from the context along with older exchanges.

You can also ask the agent directly, “What do you remember?” It will group the answer by source: global preferences, project knowledge, and session history.

Session entries have freshness markers. The older a session log entry is, the more strongly it is marked, “Check that this is still current before relying on it.” The global and project MEMORY.md files do not receive such markers: their contents are intended for long-term use, so you need to monitor their accuracy yourself.

How do you view, edit, and delete notes?#

The /memory command in a session opens a window with all memory files, grouped by scope: global, project, and sessions (in reverse chronological order). The list of files is on the left, and a read-only preview of the selected file is on the right.

Useful keys in the overview:

The window can delete individual notes and session files; it cannot delete the generated MEMORY.md indexes (global and project).

The second method is to edit files directly. They are in ~/.grok/memory/ and can be opened with any editor. Changes in the directory are tracked: created and modified files are reindexed, and deleted files are removed from the index during the next search.

The request “forget about snake_case” works without a guarantee: the model searches for and removes matching entries, but it may miss some. To ensure deletion, open the file (you can conveniently copy its path with y in /memory) and remove the entry manually. You can clear memory entirely from the command line: grok memory clear for project memory, grok memory clear --global for global memory, and grok memory clear --all for both.

How is memory different from a repository instruction file?#

A repository instruction is shared with everyone working on the project, and is visible in the code and change history. Memory grows over the course of sessions, is stored on your machine, and is not published by itself.

Memory does not replace an instruction file. General project rules needed by the whole team and any agent still make sense in the repository. We have a separate guide to using one instruction file for Claude Code, Codex, and Cursor: AGENTS.md and CLAUDE.md together. Memory preserves personal context: your preferences, what has already been tried, and what decision was reached.

Claude uses a similar distinction: we explain how memory differs from CLAUDE.md in the article Claude memory and CLAUDE.md. For a comparison of the tools themselves, see Grok Build or Claude Code.

Limitations and checking that memory works#

Keep the following limitations in mind:

• Experimental status. Commands, thresholds, and behavior may change in future versions; check the repository’s memory guide if something does not work as expected.
• Initial injection in a new session. After enabling memory, start work with /new so saved notes are added on the first turn.
• The model decides what matters. The model creates the /flush summary and chooses what goes into the note. Every week or two, open /memory and review what has accumulated; delete anything unnecessary.
• Do not ask it to remember secrets. Keys, tokens, and passwords do not belong in long-lived notes: the files in ~/.grok/memory/ are stored in plain text. If something sensitive is recorded, remove it by editing the file.
• Project memory is shared across repository copies. If the agent remembers something in one clone that is outdated for another, account for the shared directory when cleaning up.

If memory does not work:

1. Check the grok inspect output to confirm that memory is enabled.
2. Check that GROK_MEMORY=0 or the config is not disabling it.
3. For diagnostics, run RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok and check the lines about memory in /tmp/grok.log.

Brief summary#

Grok Build memory is enabled with GROK_MEMORY=1 or [memory] enabled = true in ~/.grok/config.toml. To have notes added the first time after enabling it, start a new session with /new. The agent writes notes to ~/.grok/memory/: session summaries without a model call, detailed summaries with /flush, explicit entries with /remember after your confirmation, and organized topics with /dream. View and clean up notes through /memory and direct file edits. The feature is experimental, so check thresholds and commands against the official guide and review notes periodically.

Open Ailoot.