Gemini Rust Suite 🦀

This project provides a suite of Rust crates for interacting with Google Gemini models, enabling advanced features like tool usage via the Model Context Protocol (MCP), persistent semantic memory, and a powerful command-line interface (CLI) for Linux terminals.

✨ Table of Contents

Architecture
Features
Prerequisites
Installation (CLI)
Manual Installation
Configuration
CLI Configuration (config.toml)
MCP Server Configuration (mcp_servers.json)
API Key Precedence
System Prompt Precedence
CLI Usage
Interaction Modes
Chat History
Memory Features
MCP Integration & Function Calling
Development

🏗️ Architecture

The Gemini Rust Suite is a modular project composed of several crates within a Cargo workspace:

gemini-core: Provides the foundational components:
Asynchronous GeminiClient for interacting with the Google Gemini API (generateContent endpoint).
Type-safe Rust structs mirroring the Gemini API request/response formats (content parts, function calls, generation config).
Core configuration loading (GeminiConfig from TOML) and error handling (GeminiError).
Shared JSON-RPC types (Request, Response, ServerCapabilities, Tool) used by MCP.

gemini-ipc: Centralizes Inter-Process Communication definitions:
Defines standardized Rust structs/enums for messages passed between different daemons/clients (e.g., gemini-cli, mcp-hostd, HAPPE, IDA).
Ensures consistent communication protocols (relies on serde for serialization).

gemini-mcp: Implements the host side of the Model Context Protocol (MCP):
McpHost manages discovering, launching (via stdio, SSE, WebSocket), and communicating with MCP servers (external tools/services).
Handles JSON-RPC communication for tool execution (mcp/tool/execute) and resource retrieval.
Translates between Gemini function calling and MCP tool execution.
Includes the mcp-hostd binary, a standalone MCP host daemon (uses gemini-ipc for client communication).
Provides the source for built-in MCP servers (filesystem, command, memory_store).

gemini-memory: Implements a persistent, semantic memory store:
Uses LanceDB as a vector database.
Stores memories (key-value pairs with metadata) and their vector embeddings.
Performs semantic search to find relevant memories based on query meaning.
Relies on an McpHostInterface (typically provided by gemini-mcp) to call an external embedding/embed tool for generating vectors.
Provides enhance_prompt functionality to add relevant memory context to LLM prompts.

gemini-cli: The primary user-facing application:
A command-line interface (gemini-cli-bin) built using the other crates.
Supports single-shot prompts, interactive chat, and task loops.
Integrates MCP for tool usage and Memory for context awareness and history.
Manages user configuration, chat history, and session state.
Can connect to the mcp-hostd daemon (via gemini-ipc) or run an embedded McpHost.
Can also run the built-in MCP servers directly via flags (--filesystem-mcp, etc.).

(New) HAPPE: Host Application Environment daemon:
Intended as the primary execution environment, replacing direct CLI usage for more complex scenarios.
Manages interactions between users/clients, the main LLM, IDA, and MCP servers.
Uses gemini-ipc to communicate with IDA.
Handles LLM calls and LLM-initiated MCP tool execution.

(New) IDA: Internal Dialogue App daemon:
Manages persistent memory and other background cognitive tasks.
Communicates with HAPPE via gemini-ipc.
Interacts with the Memory MCP Server (via gemini-mcp client logic) for retrieval and storage.

🚀 Features

This suite provides a comprehensive set of features through its components:

Core API Access: Robust, async communication with the Gemini API.
Tool Usage (MCP): Extend Gemini's capabilities by connecting it to external tools and services via the Model Context Protocol.
Persistent Memory: Equip Gemini with long-term memory using a semantic vector database (LanceDB), enabling context retrieval across sessions.
Automatic Prompt Enhancement: Automatically inject relevant memories into prompts.
Auto-Memory Storage: Automatically capture key information from conversations into the memory store.
Interactive CLI: User-friendly command-line interface (gemini) with multiple interaction modes.
Chat History: Maintain conversation history across CLI commands (requires shell wrapper function).
Configuration: Manage API keys, system prompts, models, and feature flags via config files and environment variables.
Formatted Output: CLI renders markdown and syntax highlighting.
Built-in Tools: Includes ready-to-use MCP servers for filesystem operations, command execution, and memory storage/embedding.

✅ Prerequisites

Rust Toolchain: Install from https://rustup.rs/ 🛠️
Gemini API Key: Obtain from Google AI Studio 🔑
Supported Shell (for CLI wrapper): Bash or Zsh recommended for the seamless gemini command experience 🐚
(Optional) External MCP Servers: If you want to connect to tools beyond the built-in ones.

📦 Installation (CLI)

The primary way to use the suite is through the gemini-cli application. The easiest installation method uses the provided script:

```bash