Skip to main content
Prerequisite: Install the engram binary first via Homebrew or binary download.
engram setup gemini-cli
This command does three things:
  1. Registers mcpServers.engram in ~/.gemini/settings.json (Windows: %APPDATA%\gemini\settings.json)
  2. Writes ~/.gemini/system.md with the Engram Memory Protocol
  3. Ensures ~/.gemini/.env contains GEMINI_SYSTEM_MD=1 so Gemini loads the system prompt
1

Install engram binary

brew install gentleman-programming/tap/engram
2

Run setup command

engram setup gemini-cli
Output:
✓ Registered MCP server in ~/.gemini/settings.json
✓ Wrote Memory Protocol to ~/.gemini/system.md
✓ Added GEMINI_SYSTEM_MD=1 to ~/.gemini/.env
3

Verify installation

gemini "list memory tools"
The agent should list mem_save, mem_search, etc.

​
What Gets Configured

​
MCP Server Registration

Adds to ~/.gemini/settings.json: 
{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

​
Memory Protocol System Prompt

Writes the full Memory Protocol to ~/.gemini/system.md: 
## Engram Persistent Memory — Protocol

You have access to Engram, a persistent memory system that survives across sessions and compactions.

### WHEN TO SAVE (mandatory — not optional)

Call `mem_save` IMMEDIATELY after any of these:
- Bug fix completed
- Architecture or design decision made
- Non-obvious discovery about the codebase
- Configuration change or environment setup
- Pattern established (naming, structure, convention)
- User preference or constraint learned

...

​
Environment Variable

Adds to ~/.gemini/.env: 
GEMINI_SYSTEM_MD=1
This tells Gemini CLI to load system.md on every session start.

​
Manual Setup (Alternative)

If you prefer to configure manually:

​
Add MCP Server

Edit ~/.gemini/settings.json (Windows: %APPDATA%\gemini\settings.json): 
{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}
Or via CLI: 
gemini mcp add engram engram mcp

​
Add Memory Protocol

Copy the Memory Protocol from DOCS.md to ~/.gemini/system.md.

​
Enable System Prompt

Add to ~/.gemini/.env: 
GEMINI_SYSTEM_MD=1

​
Compaction Recovery

The Memory Protocol in system.md includes compaction recovery instructions: 
### AFTER COMPACTION

If you see a message about compaction or context reset:
1. IMMEDIATELY call `mem_session_summary` with the compacted summary
2. Then call `mem_context` to recover additional context
3. Only THEN continue working
This ensures the agent persists work before compaction and recovers state after.

​
Platform-Specific Notes

​
Windows

engram setup gemini-cli writes to:
  • MCP config: %APPDATA%\gemini\settings.json
  • System prompt: %APPDATA%\gemini\system.md
  • Environment: %APPDATA%\gemini\.env

​
macOS / Linux

engram setup gemini-cli writes to:
  • MCP config: ~/.gemini/settings.json
  • System prompt: ~/.gemini/system.md
  • Environment: ~/.gemini/.env

​
Memory Protocol Behavior

With the Memory Protocol in system.md, the agent:
  • Saves proactively after bugfixes, decisions, discoveries, patterns
  • Searches reactively when you say “remember” or “what did we do”
  • Searches proactively when starting work that might overlap past sessions
  • Closes sessions with mem_session_summary before saying “done”
  • Recovers state after compaction with mem_context
No manual prompting needed — the protocol is always active.

​
Troubleshooting

​
MCP tools not available

Check MCP server registration: 
# macOS/Linux
cat ~/.gemini/settings.json | grep engram

# Windows
type %APPDATA%\gemini\settings.json | findstr engram

​
Agent doesn’t use memory

Check that system.md exists and GEMINI_SYSTEM_MD=1 is set: 
# macOS/Linux
ls ~/.gemini/system.md
cat ~/.gemini/.env | grep GEMINI_SYSTEM_MD

# Windows
dir %APPDATA%\gemini\system.md
type %APPDATA%\gemini\.env | findstr GEMINI_SYSTEM_MD

​
Server not running

Manually start the server: 
engram serve
Gemini CLI will connect via stdio, but the HTTP API is useful for debugging.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us