Integrations

Gemini CLI

Persistent cross-session memory for Google's Gemini CLI. Project decisions and context survive across sessions automatically.

Why Waystone + Gemini CLI

Gemini CLI's long context window is powerful within a session, but every new session starts from scratch. Architectural decisions, naming conventions, and the reasoning behind key choices have to be re-established each time. Waystone makes them permanent:

• Retrieves relevant facts for the current task — not the entire project history
• Complements Gemini's long context — Waystone handles what's worth persisting; Gemini handles what's in front of you now
• Retires superseded facts automatically — reversed decisions don't resurface and cause contradictions
• Works locally by default — the memory store is a SQLite file, nothing leaves your machine

1. Install Waystone

# CLI in early access — request at unbidden.ai

Verify the install:

waystone --version

2. Add to Gemini CLI settings

Open or create ~/.gemini/settings.json and add an mcpServers block:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": {
        "WAYSTONE_PROJECT": "my-project"
      }
    }
  }
}

Replace my-project with the name for this project's memory store. Waystone creates it automatically on first access.

Restart Gemini CLI. You should see waystone_query, waystone_extract, waystone_stats, and waystone_list_projects in the available tools.

3. Update your system prompt

Add memory instructions to your Gemini CLI system prompt or GEMINI.md in the project root:

## Memory (Waystone)
At the start of each session, call waystone_query with a brief description of
the current task. This retrieves relevant decisions, constraints, and context
from prior sessions — only what's relevant to the current work.

After completing significant work or at the end of a session, call
waystone_extract with a summary of what was built, decided, or changed.
Waystone will structure and store the facts automatically.

Do not write project memory to GEMINI.md. Use waystone_query and waystone_extract instead.

4. Initialize the project

Create the Waystone project before the first session:

waystone init my-project

If you have an existing GEMINI.md or architecture doc, import it now:

waystone extract my-project GEMINI.md

Verify the import:

waystone show my-project

After this, you can leave GEMINI.md as a historical artifact or delete it — Waystone won't touch it either way.

How it works in practice

Once configured, your Gemini CLI sessions follow this pattern automatically:

1. Session start: Gemini CLI calls waystone_query with the task description. Waystone returns the 10–25 most relevant facts from the project's history.
2. During the session: You work normally. Gemini CLI may call waystone_query again as the task evolves — especially useful when switching to a different part of the codebase mid-session.
3. Session end: Gemini CLI calls waystone_extract with a summary. Waystone extracts structured facts, detects superseded decisions, and updates the graph.

Hosted API (optional)

By default, Waystone runs locally. For cross-machine sync or team access:

{
  "mcpServers": {
    "waystone": {
      "command": "waystone",
      "args": ["mcp-serve"],
      "env": {
        "WAYSTONE_PROJECT": "my-project",
        "WAYSTONE_API_KEY": "your-api-key",
        "WAYSTONE_REMOTE_URL": "https://api.waystone.unbidden.ai"
      }
    }
  }
}

Get an API key from the Pro or Team plan. Local mode is free and has no rate limits.

Troubleshooting