Why this matters
If you retype “use PowerShell, don’t commit, don’t touch deploy/” every session, you will skip it on the session that matters. Project rules are how this shop teaches Grok the house once. Memory is a separate, experimental store for facts across sessions. They are not the same tool. Mixing them is how conventions rot and secrets leak.
Specialist rung. If you do not write software or run agents, you can stop after C4 and still have reached repo level.
This module is AGENTS.md first — durable, reviewable, in the repo. Then a short, honest pass at memory so you know what it is and how to leave it off.
Teach
Project rules are files Grok injects
Grok looks for instruction files and adds their contents at the start of the conversation. It follows them for work in that tree. You do not need to paste the style guide into every prompt.
Recognized filenames, checked in this order in each directory:
Agents.mdClaude.mdCLAUDE.mdCLAUDE.local.mdAGENT.mdAGENTS.md
Grok loads every matching name in a directory. On case-insensitive disks (Windows), Agents.md and AGENTS.md are the same file and count once. Claude-oriented names exist for compatibility. Prefer AGENTS.md in this pathway so the file means one thing.
Rules directories, also scanned:
<dir>/.grok/rules/*.md — always<dir>/.claude/rules/ and <dir>/.cursor/rules/ — when those compat flags are on- Home:
~/.grok/rules/ (always), plus ~/.claude/rules/ and ~/.cursor/rules/ when enabled
Home rules load first, then project files from the repo root down to the current working directory. Files in a rules directory load alphabetically. Deeper files appear later in context and win on conflict. A root AGENTS.md that says “styled-components” loses to src/components/AGENTS.md that says “CSS modules.”
Outside a git repo, Grok only loads the current directory. Inside a git repo, it walks root → cwd. When it later reads files outside that initial set, it notices instruction files there and loads them if they apply.
.gitignore hides a file from discovery. The usual personal-override pattern is to gitignore CLAUDE.local.md and keep private notes there. Custom names like AGENTS.local.md are not discovered at the top level. Inside .grok/rules/, every *.md loads regardless of name.
There is no character cap. Short still wins. A novel in AGENTS.md burns context and gets ignored in practice.
What belongs in AGENTS.md
Actionable instructions. Not a copy of the README.
Good:
- Language and style you will actually enforce
- Exact build/test commands
- Architecture boundaries (“do not import routes from services”)
- Commit/PR conventions if you want Grok to follow them
- Safety: “never commit
.env”; “do not run deploy scripts”
Bad:
- A tour of the company
- Pages of philosophy
- Secrets, tokens, hostnames that should not be in git
- “Be a senior engineer” with no observable rule
Subdirectory files scope to that tree. A monorepo can have a root file plus packages/frontend/AGENTS.md and packages/backend/AGENTS.md.
Global personal defaults go in ~/.grok/AGENTS.md (or ~/.grok/rules/). Commit repo rules. Do not commit machine-specific paths that are only true on your laptop unless the whole team shares them.
Session-only overlay, no file:
grok --rules "Always use TypeScript. Prefer functional components."
That text is wrapped and appended. --system-prompt-override replaces the default prompt entirely — do not use it unless you know you want that. For this lesson, --rules is the escape hatch when you do not want to commit a sentence.
Prove it loaded
grok inspect
Inspect lists each project instruction file it found, with path and a token estimate. If your AGENTS.md is missing from that list, Grok is not using it. Common causes: you launched from the wrong directory, the file is gitignored, or the name is not in the recognized list.
Then run a prompt that would go wrong without the rule (the exercise does this). A file that exists but does not change behavior is decoration.
The .grok/ directory can also hold project config, skills, plugins, agents, hooks, and lsp.json. Skills are C6. Do not fill .grok/ as a hobby today.
Memory is experimental and off
Without memory, each session starts cold except for AGENTS.md and what you type. Memory, when enabled, indexes notes and session summaries under ~/.grok/memory/ and can inject relevant bits on the first turn.
Default: disabled. Enable only on purpose:
grok --experimental-memory
$env:GROK_MEMORY="1"
grok
Or [memory] enabled = true in ~/.grok/config.toml. --no-memory always wins and turns it off.
In the TUI, /memory on and /memory off are session-scoped. They do not write config. /memory also opens a browser of global, workspace, and session files.
Useful commands, once it is on:
/remember always open PR links after pushing — you confirm a review panel before it writes- “remember …” / “forget …” in natural language
/flush — LLM summary of the session into the log (use before /compact if you care)/dream — consolidate fragments; also runs automatically under gates if enabled
Storage: ~/.grok/memory/MEMORY.md (global), plus a per-workspace directory keyed by origin remote (or path) and a short hash. Clones that share origin share workspace memory.
Priority if settings fight: --no-memory > --experimental-memory > GROK_MEMORY > config.toml > default off.
Memory is the wrong place for “never use tabs.” That is AGENTS.md. Memory is for durable facts you would otherwise re-explain (“staging is the eu-west cluster”). It is also a place people accidentally store tokens. Do not. Toggle it off for this pathway unless you are doing the optional memory step in the exercise.
Worked example
Scratch repo root. Create AGENTS.md:
# Practice repo rules
- This tree is a Grok Build practice desk, not a product.
- Do not commit unless the user names the files to stage and asks for a commit.
- Do not add dependencies or CI.
- Prefer a single new markdown file over a new folder of scaffolding.
- When the user asks for a practice-log entry, append to PRACTICE-LOG.md
using the existing heading template. Do not invent a second log format.
- Shell: on Windows prefer PowerShell syntax; do not emit bash-only
constructs (`export`, `&&` chains) unless the user is in Git Bash.
Save it. From the repo root:
grok inspect
Confirm AGENTS.md is listed. Then grok and send:
Add a practice-log entry for today. I tried plan mode and refused a
multi-file rewrite. Do not commit.
If PRACTICE-LOG.md does not exist, Grok should create it in the format the rule implied — or you create the skeleton first (C4) so the rule has something to append to. Read the diff. The point is: you did not restate “don’t commit” and “don’t add CI” in the prompt, and Grok still didn’t.
Then, optional: /memory on only if you enabled memory for the process, /remember this repo is the Pathway C scratch desk, confirm the panel, /memory to see the file. /memory off when you are done playing. Do not put a key in that note.
Your turn
Do c5-l01-e1 in Grok Build. You will write a real AGENTS.md, prove it with grok inspect, and run a prompt that only makes sense if the rule loaded. Memory is optional and off-by-default.
Common failure
Inspect does not list the file. You started Grok in a parent or child directory, or the file is gitignored, or you named it rules.md. Fix the path and the filename. Launch from the repo root.
The file is a manifesto. Cut it to commands and constraints. If a line cannot change Grok’s next tool call, delete it.
You put a secret in AGENTS.md and committed it. Rotate the secret. Remove the line. Rules are source.
You enabled memory globally and assumed it replaced AGENTS.md. Memory is search-and-inject, experimental, and easy to stale. Conventions stay in AGENTS.md.
Deeper file fights the root and you cannot tell why. grok inspect plus the walk order. The deeper file wins. That is a feature. Do not duplicate the whole root file in every package — only the conflicts.
What’s next
C6 is skills: a SKILL.md you invoke when a procedure is too specific for AGENTS.md and too long to retype. Rules are always on. Skills fire when the task matches. You will write one and run it.
