From 2df6c1b121bc94c707954c1552a79b20ae481ee7 Mon Sep 17 00:00:00 2001
From: JayadityaGit <jgedela@gitam.in>
Date: Tue, 7 Apr 2026 22:08:26 +0530
Subject: [PATCH] docs: add Gemini CLI setup guide and integration section

---
 README.md                    |  2 +
 examples/gemini_cli_setup.md | 95 ++++++++++++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 examples/gemini_cli_setup.md

diff --git a/README.md b/README.md
index 91b73b5..61c5121 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,8 @@ Now your AI has 19 tools available through MCP. Ask it anything:
 
 Claude calls `mempalace_search` automatically, gets verbatim results, and answers you. You never type `mempalace search` again. The AI handles it.
 
+MemPalace also works natively with **Gemini CLI** (which handles the server and save hooks automatically) — see the [Gemini CLI Integration Guide](examples/gemini_cli_setup.md).
+
 ### With local models (Llama, Mistral, or any offline LLM)
 
 Local models generally don't speak MCP yet. Two approaches:
diff --git a/examples/gemini_cli_setup.md b/examples/gemini_cli_setup.md
new file mode 100644
index 0000000..873ea86
--- /dev/null
+++ b/examples/gemini_cli_setup.md
@@ -0,0 +1,95 @@
+# Gemini CLI Integration Guide
+
+This guide explains how to set up MemPalace as a permanent memory for the [Gemini CLI](https://github.com/google/gemini-cli).
+
+## Prerequisites
+
+- Python 3.9+
+- Gemini CLI installed and configured
+
+## 1. Installation
+
+On many Linux systems, installing Python packages globally is restricted. We recommend using a local virtual environment within the MemPalace directory.
+
+```bash
+# Clone the repository (if you haven't already)
+git clone https://github.com/milla-jovovich/mempalace.git
+cd mempalace
+
+# Create a virtual environment
+python3 -m venv .venv
+
+# Install dependencies and MemPalace in editable mode
+.venv/bin/pip install -e .
+```
+
+## 2. Initialization
+
+Set up your "Palace" (the database) and configure your identity.
+
+```bash
+# Initialize the palace in the current directory
+.venv/bin/python3 -m mempalace init .
+```
+
+### Identity and Wings (Optional but Recommended)
+You can manually define who you are and what projects you work on by creating/editing these files in `~/.mempalace/`:
+
+- **`~/.mempalace/identity.txt`**: A plain text file describing your role and focus.
+- **`~/.mempalace/wing_config.json`**: A JSON file mapping projects and name variants to "Wings".
+
+## 3. Connect to Gemini CLI (MCP)
+
+Register MemPalace as an MCP server so Gemini CLI can use its tools.
+
+```bash
+gemini mcp add mempalace /absolute/path/to/mempalace/.venv/bin/python3 -m mempalace.mcp_server --scope user
+```
+*Note: Use the absolute path to ensure it works from any directory.*
+
+## 4. Enable Auto-Saving (Hooks)
+
+To ensure the AI saves memories automatically when conversation history becomes too long, add a `PreCompress` hook to your Gemini CLI settings.
+
+Edit your `~/.gemini/settings.json` and add the following:
+
+```json
+{
+  "hooks": {
+    "PreCompress": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/absolute/path/to/mempalace/hooks/mempal_precompact_hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Make sure the hook scripts are executable:
+```bash
+chmod +x hooks/*.sh
+```
+
+## 5. Usage
+
+Once connected, Gemini CLI will automatically:
+- Start the MemPalace server on launch.
+- Use `mempalace_search` to find relevant past discussions.
+- Use the `PreCompress` hook to save new memories before they are lost.
+
+### Manual Mining
+If you want the AI to learn from your existing code or docs immediately, run the "mine" command:
+```bash
+.venv/bin/python3 -m mempalace mine /path/to/your/project
+```
+
+### Verification
+In a Gemini CLI session, you can run:
+- `/mcp list`: Verify `mempalace` is `CONNECTED`.
+- `/hooks panel`: Verify the `PreCompress` hook is active.