1 files changed, 29 insertions, 5 deletions
diff --git a/docs/core/index.md b/docs/core/index.md
index 0a3b9d9e..da7e8c3c 100644
--- a/docs/core/index.md
+++ b/docs/core/index.md
@@ -1,6 +1,11 @@
 # Gemini CLI Core
 
-This section delves into the core component of the Gemini CLI (`packages/core`). The core acts as the backend engine, handling communication with the Gemini API, managing tools, and processing requests from the CLI client.
+The Gemini CLI Core (`packages/core`) acts as the backend engine for the Gemini CLI, handling communication with the Gemini API, managing tools, and processing requests from the CLI client. For a general overview of the Gemini CLI, see the [main documentation page](../index.md).
+
+## Navigating this Section
+
+- **[Core Configuration](../cli/configuration.md):** Details on how to configure the core component, including environment variables and specific settings.
+- **[Core Tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core.
 
 ## Role of the Core
 
@@ -44,9 +49,28 @@ The core plays a vital role in security:
 - **API Key Management:** It handles the `GEMINI_API_KEY` and ensures it is used securely when communicating with the Gemini API.
 - **Tool Execution:** When tools interact with the local system (e.g., `execute_bash_command`), the core (and its underlying tool implementations) must do so with appropriate caution, often involving sandboxing mechanisms to prevent unintended side effects.
 
-## Navigating this Section
+## Chat History Compression
 
-- **[Core Configuration](./configuration.md):** Details on how to configure the core component, including environment variables and specific settings.
-- **[Core Tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core.
+To ensure that long conversations don't exceed the token limits of the Gemini model, the CLI includes a chat history compression feature.
+
+When a conversation approaches the token limit for the configured model, the CLI will automatically compress the conversation history before sending it to the model. This compression is designed to be lossless in terms of the information conveyed, but it reduces the overall number of tokens used.
+
+You can find the token limits for each model in the [Google AI documentation](https://ai.google.dev/gemini-api/docs/models).
+
+## Model Fallback
+
+The Gemini CLI includes a model fallback mechanism to ensure that you can continue to use the CLI even if the default "pro" model is rate-limited.
+
+If you are using the default "pro" model and the CLI detects that you are being rate-limited, it will automatically switch to the "flash" model for the current session. This allows you to continue working without interruption.
+
+## File Discovery Service
+
+The file discovery service is responsible for finding files in the project that are relevant to the current context. It is used by the `@` command and other tools that need to access files.
+
+## Memory Discovery Service
+
+The memory discovery service is responsible for finding and loading the `GEMINI.md` files that provide context to the model. It searches for these files in a hierarchical manner, starting from the current working directory and moving up to the project root and the user's home directory. It also searches in subdirectories.
+
+This allows you to have global, project-level, and component-level context files, which are all combined to provide the model with the most relevant information.
 
-Understanding the core's role and architecture is key to comprehending the full capabilities and operational flow of the Gemini CLI.
+You can use the `/memory show` command to see the combined content of all loaded `GEMINI.md` files, and the `/memory refresh` command to reload them.