# Grok Build memory across sessions: settings and limitations
> How to enable memory, where notes are stored, and how /flush, /remember, /dream, and /memory work. Settings priority, checking, and deleting entries.
Source: https://ailoot.ai/blog/en/grok-build-memory/
Canonical: https://ailoot.ai/blog/en/grok-build-memory/
Language: en
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-111
Revision: sha256-058cbf55cdc33fa0f7c16560f0278c655bb30ab080928a42a575ad62e9431c73
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](https://ailoot.ai/docs/).
## What does memory provide in Grok Build?
Key takeaway
Without memory, a new Grok Build session receives no information from previous sessions: neither conventions you explained nor decisions you made, unless they are recorded in a repository instruction file. With memory enabled, the agent searches saved notes and automatically adds relevant ones to the context of a new session. Notes are stored as ordinary Markdown files that you can read and edit.
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?
Key takeaway
For a single run, set the `GROK_MEMORY=1` environment variable. To keep it enabled, add an `[memory]` section with `enabled = true` to `~/.grok/config.toml`. To have saved notes added at the start of work, start a new session with `/new` after enabling memory.
**Once, for a single run:**
```bash
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`:
```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?
Key takeaway
Notes are stored in `~/.grok/memory/` as Markdown files: a global `MEMORY.md` for all projects, a separate `MEMORY.md` for each project, and session logs. The automatic session-end summary is written without a model call, detailed notes are created with `/flush` and `/remember`, and `/dream` groups disparate entries by topic.
The `~/.grok/memory/` directory structure:
| Location | Scope | Contents |
|----|----|----|
| `~/.grok/memory/MEMORY.md` | Global | Facts and preferences for all your projects |
| `~/.grok/memory/` + project directory with hash + `/MEMORY.md` | Project | Conventions and context for a specific repository |
| `~/.grok/memory/` + project directory with hash + `/sessions/` | Sessions | Summaries and logs of individual sessions |
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?
Key takeaway
On the first turn of a session, Grok Build searches memory for entries related to the project and adds them to the context automatically—you do not need to remind it. The search runs again after automatic context compaction. Older session entries are marked for freshness checks.
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?
Key takeaway
The `/memory` command opens an overview of all memory files with previews. You can edit the files in any text editor—the changes will be picked up during the next search. The request “forget ...” works without a guarantee; to reliably remove a specific entry, edit the file.
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:
| Key | Action |
|----|----|
| `↑`/`↓` or `j`/`k` | Move through the list |
| `/` | Filter the list |
| `y` | Copy the path to the selected file |
| `x` | Delete the selected note (press again to confirm) |
| `t` | Enable or disable memory |
| `Esc` | Close the window |
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?
Key takeaway
You write an instruction file such as CLAUDE.md or AGENTS.md and put it in the repository—it is shared with the team through Git. The Grok Build agent maintains memory notes and stores them in `~/.grok/memory/`, outside the repository: they are personal and are not shared through Git.
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](https://ailoot.ai/blog/en/agents-md-claude-md-one-instruction-file/). 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](https://ailoot.ai/blog/en/claude-memory-claude-md-auto-memory/). For a comparison of the tools themselves, see [Grok Build or Claude Code](https://ailoot.ai/blog/en/grok-build-vs-claude-code/).
## Limitations and checking that memory works
Key takeaway
The feature is experimental: commands and settings may change. To have notes added on the first turn after enabling memory, start a new session with `/new`. Some entries are created by the model, so review the notes periodically and ask it not to remember secrets.
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.
### Sources
- Grok Build, official “Cross-Session Memory” guide (user guide, chapter 13):
- Grok Build, xAI repository on GitHub:
[Open Ailoot](https://ailoot.ai/).
## Questions about Grok Build memory across sessions: settings and limitations
### Why are saved notes not appearing after I enabled memory?
Saved notes are added on the first turn of a new session. Start a new session after enabling memory and check the reported state with grok inspect; a process started with GROK_MEMORY=0 cannot enable it through the session toggle.
### Does turning memory off delete its files?
No. Disabling memory removes access to its tools but leaves the Markdown notes on disk. Inspect or edit the stored notes separately if you need to remove an entry.
## Ailoot · The company and its project portfolio
Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control.
The company and its project portfolio: millions of customers; monthly sales in the billions.
Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.