Skip to main content

​
Gemini CLI Setup

Give Gemini CLI persistent memory across sessions.
Gemini CLI starts every session from scratch. Claude-mem changes that by capturing observations, decisions, and patterns — then injecting relevant context into each new session.
How it works: Claude-mem installs lifecycle hooks into Gemini CLI that capture tool usage, agent responses, and session events. A local worker service extracts semantic observations and injects relevant history at session start.

​
Prerequisites

  • Gemini CLI installed and configured
  • Node.js 18+
  • The ~/.gemini directory must exist (created by Gemini CLI on first run)

​
Installation

​
Step 1: Install claude-mem

npx claude-mem install
The installer will:
  1. Auto-detect Gemini CLI (checks for ~/.gemini directory)
  2. Prompt you to select Gemini CLI from the IDE picker
  3. Install 8 lifecycle hooks into ~/.gemini/settings.json
  4. Inject context configuration into ~/.gemini/GEMINI.md
  5. Start the worker service

​
Step 2: Configure an AI provider

Claude-mem needs an AI provider to extract observations from your sessions. Choose one:
The simplest option — use Gemini’s own API for observation extraction:
  1. Get a free API key from Google AI Studio
  2. Add it to your settings:
mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_API_KEY"
}
EOF
Free tier: 1,500 requests/day with gemini-2.5-flash-lite. Enable billing on Google Cloud for 4,000 RPM without charges.

​
Step 3: Verify installation

# Check worker is running
npx claude-mem status

# Check hooks are installed — look for claude-mem entries
cat ~/.gemini/settings.json | grep claude-mem
Open http://localhost:37777 to see the memory viewer.

​
Step 4: Start using Gemini CLI

Launch Gemini CLI normally. Claude-mem works in the background: 
gemini
On session start, you’ll see claude-mem context injected with your recent observations and project history.

​
What gets captured

Claude-mem registers 8 of Gemini CLI’s 11 lifecycle hooks:
HookPurpose
SessionStartInjects memory context into the session
SessionEndMarks session complete, triggers summary
PreCompressCaptures session summary before compression
NotificationRecords system events (permissions, etc.)
BeforeAgentCaptures user prompts
AfterAgentRecords full agent responses
BeforeToolLogs tool invocations before execution
AfterToolCaptures tool results after execution
Three model-level hooks (BeforeModel, AfterModel, BeforeToolSelection) are intentionally skipped — they fire per-LLM-call and are too noisy for memory capture.

​
Troubleshooting

​
Hooks not firing

  1. Verify hooks exist in settings: 
    cat ~/.gemini/settings.json
    You should see entries like "SessionStart", "AfterTool", etc. with claude-mem commands.
  2. Restart Gemini CLI after installation.
  3. Re-run the installer: 
    npx claude-mem install

​
Worker not running

# Check status
npx claude-mem status

# View logs
npx claude-mem logs

# Restart worker
npx claude-mem restart

​
No context appearing at session start

  1. Ensure the worker is running (check http://localhost:37777)
  2. You need at least one previous session with observations for context to appear
  3. Check your AI provider is configured in ~/.claude-mem/settings.json

​
Raw escape codes in output

If you see characters like [31m or [0m in the session context, your claude-mem version may need updating: 
npx claude-mem install
This was fixed in v10.6.3+ — the Gemini CLI adapter now strips ANSI color codes automatically.

​
Uninstalling

npx claude-mem uninstall
This removes hooks from ~/.gemini/settings.json and cleans up ~/.gemini/GEMINI.md.

​
Next Steps