@webdevtoday/grok-cli/docs/memory-system.md

A sophisticated CLI tool for interacting with xAI Grok 4, featuring conversation history, file reference, custom commands, memory system, and genetic development workflows

# Memory System

## Overview

The Grok CLI memory system provides persistent context management through GROK.md files, enabling automatic injection of project knowledge into AI conversations.

## Core Features

- **Automatic GROK.md Discovery** - Finds memory files in current and parent directories
- **Hierarchical Memory Loading** - User → Project → Local context layers
- **Import System** - Reference other files with `@import` directives
- **Memory Injection** - Automatic context enhancement for conversations
- **Search Capabilities** - Find information across all memory files
- **Live Management** - Add, edit, and reload memory during sessions

## File Structure

### GROK.md Locations

1. **Project Memory**: `./GROK.md` (current directory)
2. **Local Memory**: `../GROK.md`, `../../GROK.md` (up to `maxDepth`)
3. **User Memory**: `~/.grok-cli/GROK.md` (global user context)

### Memory File Format

```markdown
# Grok CLI Memory

## Project Overview
Describe your project goals and architecture.

## Key Files
- `src/` - Main source code
- `tests/` - Test files

@import "./docs/architecture.md"

## Development Workflow
Build: npm run build
Test: npm test

## Important Notes
Add any important context for AI conversations.
```

## Commands

### Basic Operations

```bash
# Show memory status
/memory status

# Load memory files
/memory load

# Reload all memory
/memory reload

# Create new GROK.md
/memory create

# Create memory file at custom path
/memory create /path/to/GROK.md
```

### Content Management

```bash
# Add content to memory
/memory add "Important: Always use TypeScript strict mode"

# Search memory content
/memory search "API key"
/memory search "database"

# Show memory files
/memory show              # All files
/memory show project      # Project files only
/memory show user         # User files only
/memory show local        # Local files only

# Clear loaded memory
/memory clear
```

### Quick Memory Addition

```bash
# Use # commands for quick memory addition
#Remember: Database connection uses environment variables
#TODO: Implement rate limiting for API calls
```

## Configuration

### Memory Settings

Location: `~/.grok/config.json` or `.grok/settings.json`

```json
{
  "memory": {
    "autoLoad": true,                    // Auto-load memory on startup
    "maxDepth": 5,                      // Max parent directory depth
    "excludePatterns": [                // Files/dirs to exclude
      "node_modules/**",
      ".git/**",
      "*.log",
      "dist/**"
    ]
  }
}
```

### Auto-loading Behavior

When `autoLoad` is `true`:
- Memory files are loaded automatically on CLI startup
- Memory content is injected into AI conversations
- Changes to GROK.md files require manual reload

When `autoLoad` is `false`:
- Memory must be loaded manually with `/memory load`
- No automatic context injection
- More control over when memory is used

## Import System

### @import Directives

```markdown
# Import specific files
@import "./docs/api.md"
@import "../shared/conventions.md"
@import "~/templates/project-template.md"

# Multiple imports
@import "./docs/architecture.md"
@import "./docs/deployment.md"
```

### Markdown Link References

```markdown
# Automatic file references
See [API Documentation](./docs/api.md)
Check [Database Schema](../database/schema.sql)
```

## Memory Injection

### Automatic Context Enhancement

When memory auto-load is enabled, AI conversations are enhanced:

```
Original message: "How do I set up the database?"

Enhanced message:
Context from memory:

# Project Context
## Database Setup
Uses PostgreSQL with connection pooling...
[full memory content]

---

User message: How do I set up the database?
```

### Manual Context Control

```bash
# Disable auto-load for selective memory use
/memory clear          # Clear current memory
/memory show project   # Review project context
/memory load          # Load when needed
```

## Advanced Features

### Memory Statistics

```bash
/memory status
```

Output:
```
🧠 Memory Status:

Total files: 4
User files: 1
Project files: 1  
Local files: 2
Total size: 15.2 KB
```

### Memory Search

```bash
/memory search "API"
```

Output:
```
🔍 Search Results for "API" (2 files):

 1. ./GROK.md (project)
    Line 23: API endpoints are documented in docs/api.md

 2. ./docs/api.md (local)  
    Line 1: # API Documentation
    Line 15: Authentication uses API keys
```

### Memory Types

- **User**: Global context for all projects (`~/.grok-cli/GROK.md`)
- **Project**: Main project memory (`./GROK.md`)
- **Local**: Additional context files in project hierarchy

## Best Practices

### Content Organization

1. **Project Overview**: High-level goals and architecture
2. **Key Files**: Important file locations and purposes  
3. **Development Workflow**: Build, test, and deployment processes
4. **Important Notes**: Critical information for AI conversations
5. **Custom Commands**: Project-specific workflows
6. **Architecture Decisions**: Technical choices and rationales

### Memory Management

1. **Keep It Relevant**: Only include information useful for AI conversations
2. **Regular Updates**: Update memory when project changes
3. **Use Imports**: Reference detailed docs instead of duplicating
4. **Search Before Adding**: Check if information already exists
5. **Clear Structure**: Use consistent markdown formatting

### Performance Tips

1. **Exclude Large Files**: Use `excludePatterns` for build outputs
2. **Reasonable Depth**: Limit `maxDepth` to avoid excessive file loading
3. **Selective Loading**: Disable auto-load for large projects
4. **Regular Cleanup**: Remove outdated memory content

## Integration

### Hook System Integration

Memory loading integrates with the hook system:

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "memory.*",
      "hooks": [{
        "type": "command", 
        "command": "echo 'Memory operation starting'"
      }]
    }]
  }
}
```

### File Reference System

Memory works with file references:

```bash
# Reference GROK.md files
@GROK.md              # Current directory
@../GROK.md           # Parent directory  
@~/.grok-cli/GROK.md  # User memory
```

### Conversation History

Memory content is included in conversation transcripts when injected.

## Troubleshooting

### Common Issues

1. **Memory Not Loading**:
   ```bash
   /memory status        # Check if files found
   /memory reload       # Force reload
   ```

2. **Import Errors**:
   - Check file paths in `@import` directives
   - Verify files exist and are readable
   - Check exclude patterns

3. **Large Memory Size**:
   - Review included files with `/memory show`
   - Add exclusion patterns for large files
   - Use selective imports instead of full file inclusion

4. **Context Not Injecting**:
   - Verify `autoLoad: true` in configuration
   - Check if memory files loaded with `/memory status`
   - Ensure GROK.md files have content

### Debug Commands

```bash
# Detailed memory information
/memory show

# Search for specific content
/memory search "problematic content"

# Reload and check logs
/memory reload

# Clear and reload
/memory clear
/memory load
```

## Examples

### Basic Project Memory

```markdown
# My Web App

## Overview
React + Node.js e-commerce application

## Key Files  
- `src/client/` - React frontend
- `src/server/` - Express.js backend
- `database/` - PostgreSQL schemas

## Environment
- Development: `npm run dev`
- Production: `npm run build && npm start`
- Testing: `npm test`

## Important Notes
- Uses Stripe for payments
- Redis for session storage
- Deployed on AWS with Docker
```

### Advanced Project with Imports

```markdown
# Enterprise Application

## Overview
@import "./docs/overview.md"

## Architecture
@import "./docs/architecture.md"

## API Documentation
See [API Docs](./docs/api.md) for endpoints.

## Deployment
@import "./docs/deployment.md"

## Recent Decisions
- Migrated to TypeScript for better type safety
- Adopted microservices architecture
- Implemented event-driven messaging
```

### User-Level Memory

`~/.grok-cli/GROK.md`:
```markdown
# Personal Development Preferences

## Code Style
- Always use TypeScript with strict mode
- Prefer functional programming patterns
- Use ESLint with Prettier

## Common Patterns
- Database: Prefer PostgreSQL with Prisma ORM
- Testing: Jest for unit tests, Cypress for E2E
- Deployment: Docker containers on AWS

## Frequent Commands
- Start: `npm run dev`
- Test: `npm test -- --watch`
- Build: `npm run build`
```

## See Also

- [Configuration System](./configuration.md)
- [File Reference System](./file-reference-system.md)
- [Hook System](./hooks-system.md)
- [Command System](./command-system.md)