Skip to content
Palimem Docsspec v1.7.0

Use Palimem with Gemini CLI

Connect Palimem to the Gemini CLI using ai-memory connect gemini. The helper merges a memory-service entry into ~/.gemini/settings.json (or a project .gemini/settings.json).

Prerequisites

Section titled “Prerequisites”
  • Gemini CLI installed
  • Node.js 18+
  • Either @palimem/mcp on npm (no clone) or a local clone of palimem/palimem with cd app && npm install
Section titled “Recommended install”

From your project directory (user-level config):

Terminal window
npx -y @palimem/mcp@latest ai-memory connect gemini \
  --project-root "$(pwd)" \
  --launcher npx \
  --data-dir .ai-memory/data

--launcher npx writes MCP config with npx -y @palimem/mcp — no local clone required.

Project-level config:

Terminal window
npx -y @palimem/mcp@latest ai-memory connect gemini \
  --project-root "$(pwd)" \
  --project-config .gemini/settings.json \
  --launcher npx \
  --data-dir .ai-memory/data

Default target: ~/.gemini/settings.json. Set GEMINI_HOME to override the config directory.

Config block

Section titled “Config block”

With --launcher npx (recommended), the connect helper writes:

{
  "mcpServers": {
    "memory-service": {
      "command": "npx",
      "args": ["-y", "@palimem/mcp"],
      "env": {
        "MEMORY_SERVICE_DATA_DIR": "/absolute/path/to/.ai-memory/data"
      }
    }
  }
}

From a cloned repo, the committed sample at examples/gemini-cli/.gemini/settings.json.sample uses a local Node path:

{
  "mcpServers": {
    "memory-service": {
      "command": "node",
      "args": ["/absolute/path/to/repo/app/scripts/memory-service-mcp.js"],
      "env": {
        "MEMORY_SERVICE_DATA_DIR": "/absolute/path/to/repo/.ai-memory/data"
      }
    }
  }
}

Use absolute paths. The ai-memory connect gemini CLI resolves them automatically.

Verification

Section titled “Verification”

Restart Gemini CLI after writing settings. Invoke memory_status via MCP.

Smoke test (non-interactive):

Terminal window
bash examples/gemini-cli/demo/gemini-smoke.sh

The smoke starts the MCP server via stdio and verifies memory_status responds with all eleven tools.

Agent prompt

Section titled “Agent prompt”
Set up Palimem as governed local memory for this Gemini CLI session.


- Project: Palimem (spec v1.7.0)
- Run: npx -y @palimem/mcp@latest ai-memory connect gemini --project-root "$(pwd)" --launcher npx --data-dir .ai-memory/data
- Verify: tools/list (11 tools), then memory_status — expect ok and index_status current


Use local data directory .ai-memory/data. Do not enable cloud services.

CLI options

Section titled “CLI options”
Flag Purpose
--launcher MODE MCP server launcher in written config: node (default, local clone) or npx (no clone)
--config PATH User settings.json (default: ~/.gemini/settings.json)
--project-config PATH Also write project .gemini/settings.json
--project-root PATH Repo root for resolving script paths
--data-dir PATH MEMORY_SERVICE_DATA_DIR (default: .ai-memory/data)
--replace Overwrite existing memory-service entry
--dry-run Print merged JSON without writing

Troubleshooting

Section titled “Troubleshooting”

MCP server not listed

Restart Gemini CLI after writing settings.json.

ENOENT on memory-service-mcp.js

Run cd app && npm install.

Existing entry refused

Re-run with --replace:

Terminal window
node app/scripts/ai-memory.js connect gemini \
  --project-root "$(pwd)" --data-dir .ai-memory/data --replace

Wrong config directory

Set GEMINI_HOME to point at the directory containing settings.json.

Seed memory (optional)

Section titled “Seed memory (optional)”
Terminal window
python3 app/import_markdown.py \
  --data-dir .ai-memory/data \
  examples/markdown/USER.md.sample \
  examples/markdown/MEMORY.md.sample

Next steps

Section titled “Next steps”