Grok Bot & Grok Build Shared Memory
Cross-Bot Shared Agent Memory

TL;DR

Give Grok Bot & Grok Build Shared Memory across every session. The Memwyre plugin auto-injects past project context when you start a session and auto-captures decisions when you exit — no manual AGENTS.md management needed.

The Problem: Grok Build Forgets Everything

Every time you close a Grok Build session, the context window resets. Your debugging breakthroughs, architecture decisions, database schema notes, and style conventions — all gone. You spend the first 5 minutes of every session re-explaining your project.

xAI provides AGENTS.md and auto-memory as built-in solutions, but they require manual maintenance, are limited to flat Markdown files, and don't share context across tools. If you use Grok Build and Claude Code and Cursor, each tool maintains its own isolated silo.

The Complete Guide to AGENTS.md: Hierarchy, Syntax & Best Practices

AGENTS.md (and cross-agent standard AGENTS.md) is the foundational instruction file for xAI's Grok Build CLI. Whenever you initiate a session, Grok reads this file and injects its contents into the root system prompt. Mastering AGENTS.md is the single most effective way to eliminate repetitive prompting for static project rules.

Directory Hierarchy & Rule Precedence

Grok Build searches for instruction files across a deterministic directory hierarchy. Understanding this resolution order prevents conflicting instructions:

• Global Configuration (~/.grok/AGENTS.md): Applies across every repository and terminal session on your computer. Use this exclusively for developer-specific habits, such as preferred shell shortcuts, default terminal flags, or global Git commit author styles.
• Project Root (.grok/AGENTS.md): Placed at the root of your Git repository. This file is shared among your team and defines project-level architecture, build commands, testing frameworks, and linting rules.
• Subdirectory Scopes (./apps/web/AGENTS.md): In monorepos, you can place localized files within package directories. When Grok runs commands inside that directory, it merges the package-level rules with the root rules.

Production AGENTS.md Master Template

The most effective AGENTS.md files are concise, imperative, and structured with clear Markdown headers. Avoid narrative paragraphs; use bullet points and exact shell syntax:

# Project: E-Commerce Microservices Platform

## Tech Stack & Package Manager
- Runtime: Node.js 20 LTS with pnpm (NEVER use npm or yarn)
- Framework: Next.js 15 (App Router only, Server Actions for mutations)
- Database: PostgreSQL 16 with Drizzle ORM
- Styling: Tailwind CSS v4 with Shadcn UI

## Core Build & Test Commands
- Dev Server: `pnpm run dev` (runs on http://localhost:3000)
- Typecheck: `pnpm run type-check` (TypeScript strict mode)
- Test Suite: `pnpm test` (Vitest unit tests)
- Integration Tests: `pnpm test:e2e` (Playwright)
- Database Migration: `pnpm drizzle-kit push`

## Architectural Invariants
- Never use standard API route handlers (`/api/...`) for form submissions; always use Server Actions with `zod` validation.
- All database queries must run through repository modules in `lib/db/repositories/`.
- Zero `any` policy in TypeScript. Use unknown + narrowing or generic constraints.

## Git & Workflow Rules
- Commits must adhere to Conventional Commits format: `feat(auth): add OAuth provider`.
- Never commit directly to `main`. Create feature branches (`feat/`, `fix/`).

What NEVER to Put in AGENTS.md (Context Inflation Anti-Pattern)

Because AGENTS.md is injected verbatim into every single turn of your conversation, bloating it directly degrades performance:

• Do NOT include raw database schemas: Dumping 500 lines of SQL or Prisma models into AGENTS.md consumes 3,000+ tokens on every interaction. Grok can read schema files on demand via its file tools when needed.
• Do NOT include ephemeral debugging fixes: Notes like "Fixed Redis port mismatch on line 88" become obsolete in days and clutter Grok's reasoning window.
• Do NOT paste conversation logs or changelogs: Historical changelogs belong in Git history, not in the active LLM context.

xAI Prompt Caching vs. Persistent Memory

Many developers confuse xAI's Prompt Caching with long-term memory. While both optimize context, they serve fundamentally different functions:

In short: Prompt caching saves tokens within a rapid typing loop. But as soon as you step away, switch git branches, or close your terminal, the cache can be evicted at any time — xAI provides no guaranteed TTL. Persistent memory stores lessons forever and injects them only when semantically relevant.

How Grok Build Memory Works: Deconstructing Native Limits

To understand why Grok Build developers frequently experience memory loss, we analyzed how Grok Build manages persistent context buffers. Grok Build provides three native mechanisms for managing context:

1. AGENTS.md (Static Rules)

AGENTS.md is a Markdown file placed at your project root or in ~/.grok/AGENTS.md. On startup, Grok loads this file verbatim into its context window. It is ideal for permanent guidelines (e.g., "Always use pnpm", "Follow TypeScript strict mode"), but it requires 100% manual updating and does not learn dynamically from your terminal sessions.

2. Native Memory Engine (Hybrid Search)

xAI's Grok Build includes a native memory engine that writes session observations to ~/.grok/memory/ using hybrid vector search. While more capable than flat files, it suffers from three architectural constraints:

• Local-Only Storage: Native memory is stored entirely on your local machine at ~/.grok/memory/. There is no built-in mechanism to synchronize context across multiple computers, share with teammates, or access from other IDEs.
• No Cross-Tool Sync: Native memory is locked to the Grok Build CLI. If you also use Cursor, VS Code, or Claude Code, each tool maintains entirely separate context silos.
• Basic Embedding Search: Native memory uses single-stage embedding search (1024 dimensions) without cross-encoder re-ranking or entity graph relationships. This means it lacks the precision of two-stage retrieval and cannot reason about entity dependencies (e.g., how a schema change affects downstream API routes).

3. Automated Compaction (Idle Consolidation)

Grok Build and modern coding agents incorporate automated context compaction during idle periods to summarize conversational histories. However, these local summaries remain machine-locked: it cannot synchronize observations to your laptop, your teammates, or your other editors (Cursor, VS Code, or Claude Code).

Grok Build CLI Commands: Managing Working Context

During active development, Grok Build accumulates terminal output, file reads, and tool execution traces. xAI provides several built-in slash commands in the CLI to inspect and control working context:

The Team Silo Problem: Why Local Memory Fails Collaborative Engineering

By default, Grok Build stores memory observations in ~/.grok/memory/. Because this directory lives on your personal workstation, it is completely invisible to your teammates.

This creates severe organizational context fragmentation across development teams:

• Redundant Problem Solving: When Senior Engineer Sarah spends 45 minutes debugging an esoteric Docker networking issue on macOS and Grok notes the fix, Junior Engineer Alex encounters the exact same failure the next day and spends another 45 minutes rediscovering the solution from scratch.
• Git Merge Conflicts from Shared Files: Teams that try to solve this by committing dynamic notes to AGENTS.md in Git quickly suffer from branch collision. Every developer's branch modifies AGENTS.md, generating messy merge conflicts on pull requests.
• Cross-Editor Disconnect: Even on a single developer's laptop, if you alternate between Grok Build in your terminal, Cursor for IDE coding, and VS Code or Claude Code, none of them know what the other two discovered.

Four Approaches to Grok Build Memory

There is no single "right" approach — each method suits a different workflow. If you've researched this space, you've likely seen grok-mem (93K+ GitHub stars) alongside xAI's built-in options. Here is an honest breakdown of all four approaches.

These approaches are complementary, not mutually exclusive. Many production teams use AGENTS.md for permanent guidelines and an external memory layer for dynamic session memory.

Approach 1: Pure Native (AGENTS.md + Auto Memory)

xAI's built-in combination requires no external tools or API keys. You write static guidelines into AGENTS.md, and Grok Build automatically records observations to its local memory store.

• Best for: Solo developers working on single repositories who don't mind manually curating Markdown files.
• Trade-off: Works well for single-machine solo development, but has no cross-tool or cross-machine synchronization.

Approach 2: Local Open-Source (claude-mem for Grok by thedotmack)

claude-mem is a widely adopted open-source project (93K+ GitHub stars, created by thedotmack) that provides persistent memory for Grok Bot and Claude Code. It installs via npm and manages context using SQLite and ChromaDB:

# Install grok-mem CLI
npx grok-mem install

Under the hood, claude-mem hooks into Grok's execution stream to summarize observations and store vector embeddings in ChromaDB.

• Strengths: Completely local-first, zero cloud reliance, open-source codebase.
• Limitations: Single-machine lock-in. To share context across multiple computers or team members, developers must configure custom SSH sync scripts over SSH tunnels. Its local-only architecture means sharing context across machines or team members requires custom SSH sync scripts.

Approach 3: Generic MCP Memory Servers

The Model Context Protocol (MCP) allows Grok Build to connect to external servers exposing memory tools (e.g., save_memory and search_memory):

# Add a custom MCP server to Grok Build
grok mcp add memory-server -- node /path/to/server.js

• Strengths: Standardized protocol supported across Grok Build, Cursor, and VS Code.
• Limitations: Predictive tool invocation. The LLM must actively decide when to query or update memory during conversation turns. This consumes reasoning tokens on every turn and frequently fails when the model doesn't realize relevant memory exists.

Approach 4: Dedicated Unified Context Engine (Memwyre)

Memwyre approaches memory deterministically rather than predictively. Instead of forcing the LLM to remember to make tool calls, Memwyre intercepts Grok Build's native lifecycle hooks (SessionStart and Stop). Context is injected before prompt typing begins and extracted when the terminal closes, synchronized across Grok Build, Cursor AI, and VS Code (MCP).

How the Memwyre Grok Build Plugin Works

The plugin hooks into Grok Build's native lifecycle events — two hooks, zero configuration after install. It reads your project directory name and handles context retrieval and capture automatically.

① SessionStart — Context Injection

When you open a Grok Build session, the plugin fires before the first prompt. It reads your working directory, queries the Memwyre retrieval engine for past memories matching that project, and injects them directly into Grok's system prompt.

<memwyre-context>
## Past Memories for my-project
- Database uses PostgreSQL 15 with pgvector
- Auth flow: JWT + refresh tokens in httpOnly cookies
- Fixed: race condition in worker queue (use Redis lock)
</memwyre-context>

② Stop — Session Capture

When you exit Grok Build (or the session ends), the plugin reads the full JSONL session transcript, sends it to Memwyre's background worker, and extracts structured memories — architecture decisions, debugging solutions, code patterns, and configuration choices.

Troubleshooting & Edge Cases

No extraction model is perfect. Here's how to handle the edge cases:

• Misclassified memory: If the extraction model captures something irrelevant or incorrect, you can view, edit, or delete any individual memory from the Memwyre dashboard or via the API (DELETE /api/v1/memories/:id). Every memory is individually addressable.
• Stale facts: Decided to switch from PostgreSQL to CockroachDB? The Ebbinghaus logarithmic recency decay model automatically deprioritizes older, superseded facts. The most recent observation wins in retrieval ranking — you don't need to manually clean up outdated context.
• Deduplication: If consecutive sessions produce near-identical observations (e.g., "project uses Tailwind" captured in sessions #4, #5, and #6), the extraction model deduplicates them during ingestion. Your vault stays lean.
• Project exclusion: Don't want to capture sessions for a specific repo? Unset the MEMWYRE_API_KEY environment variable for that terminal session, or configure project-level exclusions in your Memwyre dashboard settings.

Install in 60 Seconds

Choose between standard CLI plugin installation or manual hooks configuration:

{
  "description": "Memwyre: Persistent autonomous memory",
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/node_modules/@memwyre/grok-memwyre/dist/inject-memory.cjs\"", "timeout": 30 }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/node_modules/@memwyre/grok-memwyre/dist/capture-session.cjs\"", "timeout": 30 }] }]
  }
}

What Grok Remembers With Memwyre

• 🧠 Architecture Decisions: Database choices, API patterns, deployment configs, and framework decisions from past sessions.
• 🐛 Debugging Solutions: Race conditions fixed, environment variable gotchas, and edge cases you already solved once.
• 🔗 Entity Relationships: Connections between database tables, files, services, and APIs — enabling multi-hop reasoning.
• ✂️ Dynamic Pruning: Filters out duplicate CLI logs, compiler errors, and noise — keeping memory lean and token costs low.

Monorepo & Package Boundary Scoping

In multi-package monorepos (Turborepo, Nx, pnpm workspaces), native AGENTS.md files often create context collision: Grok Build running in a backend service directory pulls in frontend styling rules, polluting the prompt and wasting context. Memwyre applies path-aware AST bounding to ensure strict context isolation.

Benchmark: Why Retrieval Quality Matters

Generic memory plugins dump raw vectors into Grok's context window. That approach fails on the queries that actually matter in a codebase — temporal reasoning ("when did we switch from REST to GraphQL?"), multi-hop connections ("which services depend on the auth token format we changed last week?"), and adversarial edge cases ("we never discussed Redis" → the system should abstain, not hallucinate).

We evaluated Memwyre's retrieval engine against a flat vector RAG baseline on the LoCoMo-10 benchmark (Snap Research, ACL 2024) — 1,540 questions across 10 long conversations spanning ~90,000 tokens across 300+ turns:

The improvement comes from three architectural choices: dynamic context pruning during ingestion (strips conversational filler), two-stage cross-encoder re-ranking (high-recall vector fetch → precision cross-encoder scoring), and Ebbinghaus logarithmic recency decay (automatically deprioritizes stale observations).

View the full LoCoMo-10 benchmark results →Read our Vector DB vs. Agent Memory deep dive →

Real-World Workflow: Large Codebase Refactoring

To understand the depth of this integration, consider a common scenario: migrating a large React SPA to Next.js App Router.

In a standard Grok Build setup, you might tackle routing on Monday, API endpoints on Tuesday, and state management on Wednesday. By Wednesday, Grok has forgotten that you decided to use Server Actions for mutations instead of traditional API routes. It will start generating standard REST calls, requiring you to manually correct it and burn through tokens.

With the Memwyre Plugin, Monday's architectural decision ("we are exclusively using Server Actions for Next.js mutations") is extracted during the session stop hook. When you open Grok on Wednesday, that context is automatically injected. Grok inherently knows the project's boundaries, saving you countless prompt-correction cycles and significantly reducing your token usage by preventing hallucinated code paths.

Token Costs, Noise, & Security

Sending large conversational contexts directly impacts both billing and privacy. The plugin employs several strategies to mitigate this:

Algorithmic Noise Filtration

Not every CLI error needs to be remembered. Memwyre's backend uses a specialized extraction model that differentiates between ephemeral noise (e.g., a typo in a git commit command) and structural knowledge (e.g., adding a new enum to a Prisma schema). Only the structural knowledge is saved to your vector vault, keeping your persistent memory highly relevant and dense.

Predictable Token Usage

By summarizing and deduplicating past sessions, the plugin injects a concise <memwyre-context> block that rarely exceeds 1,500 tokens. Compared to manually pasting in megabytes of old transcript logs, this targeted injection saves xAI API costs while providing superior context.

Zero-Retention & Self-Hosting

Your code is yours. The Memwyre extraction engine uses zero-retention policies—meaning your transcripts are processed in memory and immediately discarded. For enterprise environments with strict compliance requirements, the entire Memwyre backend can be self-hosted behind your firewall, ensuring your proprietary source code never leaves your VPC.

License & Requirements

• License: Apache-2.0 — no copyleft obligations. You can use, modify, and deploy Memwyre in proprietary environments without open-sourcing your changes. This matters for teams: claude-mem's AGPL-3.0 license requires that any modifications served over a network be made open-source, which creates real compliance friction in enterprise environments.
• System requirements: Node.js 18+ (for the plugin runtime). Works on macOS, Linux, and Windows. No local database required — unlike claude-mem (SQLite + ChromaDB dependency), Memwyre stores data in a managed cloud vault.
• Self-hosting: For teams that need full data sovereignty, the entire Memwyre backend is available for self-hosted Docker deployment. See the GitHub repo for instructions.

Why Not Just Use GROK.md?

AGENTS.md is genuinely useful — and you should keep using it. It's the right place for static project rules like "use TypeScript strict mode" or "prefer Tailwind over inline styles."

But it has real limitations:

• Manual maintenance — you have to remember to update it.
• Flat storage — everything goes into one Markdown file. No semantic search or entity relationships.
• Tool-locked — GROK.md only works in Grok Build. Your Cursor and VS Code sessions can't access it.

FAQ