# AI Knowledge Base Quick Start Guide

This guide provides a comprehensive walkthrough for setting up and using the local AI Knowledge Base
for the Neo.mjs repository.

## 1. Prerequisites

**AI Tooling on Windows:** The AI tooling for this project requires a Linux environment due to a third-party dependency (ChromaDB). If you are on Windows, you **MUST** use the Windows Subsystem for Linux (WSL). Please follow the [AI Tooling WSL Setup Guide](../learn/guides/ai/AiToolingWslSetup.md) before proceeding.

Before you begin, ensure you have the following:

1.  **Google Account**: You'll need one to access Google AI Studio for an API key, which is required to build the knowledge base. If you don't have one, you can create it at [accounts.google.com](https://accounts.google.com).
2.  **Node.js**: Version 20 or later. If you don't have it, you can install it from [nodejs.org](https://nodejs.org).
3.  **Project Setup**: Your setup depends on how you are working with Neo.mjs.

    **A) For contributions to the Neo.mjs framework itself:**

    To contribute directly to the framework, you should first fork the repository on GitHub, and then clone your personal fork.
    ```bash
    # In your browser, visit https://github.com/neomjs/neo and click the "Fork" button.
    # Then, clone your fork (replace YOUR_USERNAME):
    git clone https://github.com/YOUR_USERNAME/neo.git
    cd neo
    ```

    **B) For developing your own application in a Neo.mjs workspace:**

    If you are building your own application, you will have already created a workspace using `npx neo-app`.
    Simply navigate into your workspace directory.
    ```bash
    # Example:
    npx neo-app my-app
    cd my-app
    ```

## 2. What is an AI Agent?

For this workflow, an "AI agent" is a local AI assistant capable of executing shell commands and making architectural decisions.

**Current Support:** This guide covers the setup for two environments: the Google Gemini CLI and the Antigravity OS. The core infrastructure (MCP servers, knowledge base) is agent-agnostic, but their respective configuration files differ slightly.

## 3. Setup the AI Environment (Required)

This section covers the mandatory steps to set up the local AI environment.

### Step 3.1: Knowledge Base Setup (Automatic)

For most contributors, the Knowledge Base setup is fully automated. When you run `npm install` in the repository root, a `prepare` script automatically downloads the latest pre-built Knowledge Base artifact from the corresponding GitHub Release.

1.  **Install Dependencies**:
    ```bash
    npm install
    ```
    Watch for the `> neo.mjs@... prepare` step. It should say: `✅ Download complete` and `🎉 Knowledge Base is ready!`.

2.  **Verify**: Check if the `chroma-neo-knowledge-base` folder exists in your project root.

**Troubleshooting (Manual Setup):**
If the automatic download fails (e.g., due to network issues), you can trigger it manually:
```bash
npm run ai:download-kb
```

### Step 3.2: Obtain a Gemini API Key

The Knowledge Base artifact allows you to start quickly, but you still need a Gemini API Key to run the AI Agent (for chat/generation) and for incremental updates to the knowledge base.

1.  **Visit Google AI Studio**: Go to [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey).
2.  **Sign In**: Use your Google account credentials. Complete any two-factor authentication (2FA) if prompted.
3.  **Create API Key**: Click the "Create API key" button. The key will be generated instantly.
4.  **Copy and Secure the Key**: Click the copy icon next to the key. **Treat this key like a password and never commit it to version control.**

### Step 3.3: Configure Your Local Environment

1.  **Navigate to Repo Root**: Make sure you are in the root directory of your cloned `neo` repository.
2.  **Create `.env` file**: Create a new file named `.env`.
3.  **Add API Key**: Add the following line to the `.env` file, replacing `YOUR_API_KEY_HERE` with the key you just copied:
    ```
    GEMINI_API_KEY="YOUR_API_KEY_HERE"
    ```
    This file is already listed in `.gitignore` to prevent you from accidentally committing your key.

### Step 3.4: Understanding the Workflow

**Subsequent Sessions:**
- The MCP servers are automatically started by the Gemini CLI when you run `gemini`.
- The knowledge base is cached. Incremental updates (when you modify files) are fast and consume very little API quota.
- **You do not need to manually start servers** unless debugging.

**Critical Rate Limit Warning (Manual Rebuilds):**
The free tier of the Gemini API has a strict limit of **1,000 requests per day** for the embedding model.
*   **Do NOT** run `npm run ai:sync-kb` (full rebuild) unless absolutely necessary. A full rebuild requires ~153 requests and takes ~25 minutes due to rate-limiting delays.
*   The pre-built artifact saves you from this cost and delay.

### Step 3.5: Advanced Configuration (Optional)

You can tune the embedding process (e.g., for paid tier usage) by modifying `ai/mcp/server/knowledge-base/config.mjs` or by loading a custom config file.

*   **`batchSize`**: Number of documents per API request (Default: 50).
*   **`batchDelay`**: Wait time between batches in ms (Default: 10000).

Higher batch sizes or lower delays may trigger `429 Too Many Requests` errors on the free tier.

**Model Compatibility Warning:**
The pre-built Knowledge Base artifact is generated using **`gemini-embedding-001`**.
If you change the `embeddingModel` in the configuration (e.g., to a newer model), the existing database will be incompatible. You **MUST** run `npm run ai:sync-kb` to rebuild the database from scratch with the new model. Querying with a mismatched model will return irrelevant results.

## 4. Choosing Your Agent Environment

You can interact with the AI servers using either the Gemini CLI or the Antigravity OS.

### Option A: Gemini CLI

To install the Gemini CLI:
```bash
npm i -g @google/gemini-cli
```

## 5. Understanding the Configuration Files

The agent's behavior is controlled by several configuration files depending on your chosen environment:

### Core Configuration (Gemini CLI)
The repository provides a `.gemini/settings.json` file which automatically activates all 4 Neo MCP servers for the session.

### Core Configuration (Antigravity OS)
Antigravity requires a user-level configuration file located at `~/.gemini/antigravity/mcp_config.json`. You must create this file and configure it with your API keys and local paths. 

- **`<DEFAULT_PATH>`**: Your system's default `PATH` environment variable (e.g., on macOS this typically looks like `/usr/local/bin:/usr/local/sbin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin`).
- **`<YOUR_NODE_PATH>`**: The absolute path to your Node.js executable (e.g., `/usr/local/bin/node` or `~/.nvm/versions/node/v20.x.x/bin/node`).

Use the following structure:

```json
{
  "context": {
    "fileName": [
      "<YOUR_NEO_REPO_PATH>/.agent/ANTIGRAVITY_RULES.md",
      "<YOUR_NEO_REPO_PATH>/AGENTS.md",
      "~/.gemini/GEMINI.md"
    ]
  },
  "mcpServers": {
    "neo-mjs-knowledge-base": {
      "command": "<YOUR_NODE_PATH>",
      "args": [
        "<YOUR_NEO_REPO_PATH>/ai/mcp/server/knowledge-base/mcp-server.mjs"
      ],
      "env": {
        "GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
        "PATH": "<YOUR_NEO_REPO_PATH>/node_modules/.bin:<DEFAULT_PATH>"
      }
    },
    "neo-mjs-memory-core": {
      "command": "<YOUR_NODE_PATH>",
      "args": [
        "<YOUR_NEO_REPO_PATH>/ai/mcp/server/memory-core/mcp-server.mjs"
      ],
      "env": {
        "GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
        "PATH": "<YOUR_NEO_REPO_PATH>/node_modules/.bin:<DEFAULT_PATH>"
      }
    },
    "neo-mjs-github-workflow": {
      "command": "<YOUR_NODE_PATH>",
      "args": [
        "<YOUR_NEO_REPO_PATH>/ai/mcp/server/github-workflow/mcp-server.mjs"
      ],
      "env": {
        "GH_TOKEN": "<YOUR_GH_TOKEN>",
        "PATH": "<YOUR_NEO_REPO_PATH>/node_modules/.bin:<DEFAULT_PATH>"
      }
    },
    "neo-mjs-neural-link": {
      "command": "<YOUR_NODE_PATH>",
      "args": [
        "<YOUR_NEO_REPO_PATH>/ai/mcp/server/neural-link/mcp-server.mjs",
        "--cwd",
        "<YOUR_NEO_REPO_PATH>"
      ],
      "env": {
        "PATH": "<YOUR_NEO_REPO_PATH>/node_modules/.bin:<DEFAULT_PATH>"
      }
    }
  }
}
```

### Agent Guidelines (Repository root)
- **`AGENTS_STARTUP.md`**: Step-by-step session initialization instructions
- **`AGENTS.md`**: Per-turn operational mandates (automatically loaded via settings.json)

### Developer Guide (Repository root)
- **`WORKING_WITH_AGENTS.md`**: Your playbook for working effectively with AI agents

**Important:** Before starting your first session, read [WORKING_WITH_AGENTS.md]() to understand how to guide the agent effectively.

## 6. Your First Agent Session

1. **Start the agent** from the repository root:
   * **For Gemini CLI:** Run `gemini` in your terminal.
   * **For Antigravity:** Follow the Antigravity launch procedure.

2. **Follow the initialization instructions in AGENTS_STARTUP.md**:

   The agent **will not** automatically initialize itself on startup. You must explicitly instruct it to do so:

   > "Read and follow all instructions in @AGENTS_STARTUP.md"

   The agent will then:
    - Read the AGENTS_STARTUP.md file
    - Load core Neo.mjs files (Neo.mjs, Base.mjs, CodebaseOverview.md)
    - Check the Memory Core status
    - Confirm it's ready for work

   **Important:** This initialization step is required at the start of every new session. Without it, the agent will not
   have proper context about the codebase structure and operational guidelines.

3. **Give your actual prompt**, for example:
   > "Explain the Neo.mjs two-tier reactivity model with a code example."

   The agent will now autonomously:
    - Query the knowledge base for "reactivity"
    - Read relevant source files
    - Synthesize an accurate answer from the codebase

This is the key difference: you delegate *research* to the agent, making it a true partner that can autonomously navigate
and understand your codebase.

## 7. Common Troubleshooting

### MCP Server Issues
- **Empty query results**: The knowledge base may still be embedding - wait for completion
- **ChromaDB errors on Windows**: Verify you're running in WSL (see Prerequisites)

### API Key Issues
- **Authentication errors**: Regenerate your key at Google AI Studio
- **Rate limit errors**: You've exceeded the free tier quota - wait or upgrade
- **"Invalid API key" errors**: Check `.env` file has correct format: `GEMINI_API_KEY="your-key-here"`

### Agent Behavior Issues
- **Agent doesn't initialize**: Check that `AGENTS_STARTUP.md` exists
- **Agent doesn't save memories**: Memory Core may not be running. Ask the agent to perform a healthcheck on the `neo.mjs-memory-core` MCP server. If it's unhealthy, you can ask the agent to start the database or use other memory-core tools.
- **Agent makes incorrect assumptions**: It may be hallucinating - remind it to query the knowledge base

### Installation Issues
- **`gemini` command not found**: Add npm global binaries to PATH
  ```bash
  npm bin -g
  # Add the output directory to your PATH
  ```
