ai_ex_girlfriend

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #go #rust #deep-learning #macos #windows #vue #pytorch #mcp #openai #open-source

ai_ex_girlfriend

(★ 12)

ai前女友，根据微信历史聊天记录，尽可能还原记忆以及真实说话口癖风格，达到逼真效果，真真假假假假真真，是真是假已无所谓，感情这东西，糊涂过吧

ai_ex_girlfriend Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 💘 AI Virtual Girlfriend (Context-Aware AI Girlfriend)
[中文readme文档](README_zh.md)                            [回复逻辑实现](LOGIC_EXPLAIN.md)
> A project for an AI virtual companion with **long-term memory**, **emotional state machine**, and **personality imitation capabilities**, using **WeChat chat history** as the source for the virtual girlfriend's memory, speech habits, and tone.
> She not only remembers topics you discussed long ago but also gets happy or angry based on your attitude, rejecting mechanical AI responses. This project is **not for commercial use or modification**, for learning purposes only. Violators will be subject to legal action.
> The embedding model and LLM model can be chosen freely. I used OpenAI: text-embedding-3-large and Gemini 3.

---

![Chat Screenshot 2](https://raw.githubusercontent.com/waterfall132/ai_ex_girlfriend/main/微信图片_20260124221432.png)
![Chat Screenshot](https://raw.githubusercontent.com/waterfall132/ai_ex_girlfriend/main/微信截图_20260124214939.png)

## 📂 1. Project File Deep Dive (Beginners Must Read)

In this project, each file acts as an organ of the body. Here are the detailed explanations:

### 🧠 Core Brain

*   **`main_agent.py` (Chief Commander)**:
    *   This is the AI's **cerebral cortex**. It's responsible for receiving your messages, deciding which memory to access, judging the current mood (happy or angry), assembling the Prompt, and finally directing the LLM to speak.
    *   **Core functions**: Emotion calculation, user profile update (`user_info`), response generation.

*   **`app.py` (Mouth and Ears)**:
    *   This is a web server (based on Flask). It's responsible for serving the web interface (frontend) to your browser, receiving the messages you type on the webpage, passing them to the brain, and sending the brain's reply back to the webpage.

*   **`config.py` (ID Card & Keys)**:
    *   The place to store configuration information. Includes API Keys (your account passwords), model selection, database dimension settings, etc. **Do not share this file with strangers**.

### 💾 Memory System (Hippocampus)

*   **`memory_core.py` (Deep Subconscious)**:
    *   **The most awesome file**. It's responsible for reading `ex_gf.csv` (chat history), converting thousands of records into vectors (mathematical numbers), and storing them in the vector database.
    *   When you ask "Where are you?", it can instantly find similar scenes you've discussed before, allowing the AI to imitate the tone from that time.

*   **`conversation_history.py` (Short-term Memory)**:
    *   Responsible for remembering the **last 20 messages** of the conversation to ensure chat coherence (e.g., if you said "eat" last time and "so full" next, it knows you're full from eating). Also responsible for asynchronously saving new conversations to the hard drive.

*   **`conversation.py` (Connector)**:
    *   An adapter utility. It acts like a translator, helping the database understand our Embedding service.

*   **`conversation_2.py` (Old Brain)**:
    *   *Deprecated/Backup*. This is the previous generation's keyword matching logic. The current project primarily runs on `memory_core.py`. This file is for reference or backup only.

### 🔧 Tools & Drivers

*   **`llm.py`**: A tool responsible for communicating with remote large language models (e.g., DeepSeek, GPT).
*   **`embedding.py`**: A tool responsible for converting text into vectors (Embeddings). It handles complex issues like network retries and timeouts.
*   **`requirements.txt`**: The shopping list. It enumerates all the Python libraries required to run this project.

### 📁 Data Files

*   **`ex_gf.csv`**: **Raw Material**. Your exported WeChat chat history.
*   **`save/` Directory**:
    *   `me.txt`: Facts about you that the AI remembers (dynamically updated).
    *   `mood.txt`: The AI's current mood score.
    *   `memory_advanced/`: Database storing long-term tone memories (files for the machine).
    *   `chat_history/`: Database storing all historical conversations.
    *   `log/`: A running diary for humans to read.

---

## 🛠️ 2. Quick Start Guide

### Step 1: Environment Setup

1.  Ensure you have **Python 3.8** or a later version installed.
2.  Open a terminal (CMD or PowerShell) and navigate to the project folder.
3.  Install the required libraries (buying items from the shopping list):
    ```bash
    pip install -r requirements.txt
    ```

### Step 2: Configure Accounts (`config.py`)

Open `config.py` and fill in your API information:

```python
class Config:
    # 你的大模型 API 地址和 Key
    LLM_API_URL = "https://twohornedcarp.com/v1" 
    LLM_API_KEY = "sk-你的Key"
    
    # 你的向量模型配置 (必须与 Embedding API 对应)
    EMBEDDING_API_KEY = "sk-你的Key"
    EMBEDDING_DIMENSION = 1024  # 注意：必须确认你的模型维度是 1024 还是 4096！
```

### Step 3: Inject Memory (Required only for the first time)

**This step is to give the AI the "soul" of the "ex-girlfriend" (her tone and past memories).**

1.  Prepare your chat history CSV file. Ensure it contains the columns `StrContent` (content) and `IsSender` (who sent it, 1 is you, 0 is her).
2.  Open `memory_core.py`.
3.  Find the `main` function at the bottom and **uncomment this line of code**:
    ```python
    # await memory_system.ingest_excel(excel_path)  <-- Remove the preceding # symbol
    ```
4.  Run this file to perform memory injection:
    ```bash
    python memory_core.py
    ```
    *Wait for the progress bar to complete and see the "🎉 Memory injection complete" message.*
5.  **Important**: After injection is complete, remember to **re-comment that line of code** (add `#` back), otherwise it will repeat the injection the next time you run it.

### Step 4: Launch the Virtual Girlfriend

Run the main program:

```bash
python app.py
```

After seeing `Running on http://127.0.0.1:5000`, open your browser and visit this address to start chatting!

---

## ❓ 3. Frequently Asked Questions (Lifesaver for Beginners)

**Q1: What should I do if I get the error `Dimension 1024 does not match collection dimensionality 768`?**

*   **Reason**: You upgraded to a more advanced phone case (1024-dimensional), but are still using the old phone (768-dimensional database).
*   **Solution**:
    1.  Close the program.
    2.  Delete the `chat_history` and `memory_advanced` folders inside the `save/` directory.
    3.  Restart the program; it will automatically create new ones.

**Q2: I want to reset her memory, make her forget who I am?**

*   **Solution**: Delete the `save/me.txt` file and the `save/chat_history` folder.

**Q3: She's too aggressive/too clingy, how to adjust?**

*   **Solution**: Open `save/mood.txt`.
    *   Change it to `10`: She will become a fierce dragon, extremely irritable.
    *   Change it to `90`: She will become a sweet girl, super clingy.
    *   Or, simply comfort/scold her in the chat, and her mood will change automatically.

**Q4: Error `Event loop is closed`?**

*   **Reason**: The program didn't exit properly, or there's a background task conflict.
*   **Solution**: Ensure you are using the latest version of `conversation_history.py` (the one that uses `threading`).

---

## 🌟 Core Feature Explanation

1.  **Emotional State Machine**:
    She doesn't have a fixed personality. If your replies are perfunctory, her mood value drops, and her responses become shorter and colder. If you comfort her, her mood value rises, and her responses become sweeter and longer.

2.  **RAG Tone Imitation**:
    When you say "What are you doing?", she won't reply with a generic "I'm daydreaming." Instead, she will search your chat history from years ago for her past reply to "What are you doing?" (e.g., "None of your business"), achieving astonishing realism.

3.  **Incremental Memory**:
    If you say "I'm going to Beijing next week," she will quietly note it down in her little notebook (`me.txt`). Next week, when you ask "Where am I going?", she can answer correctly.

---

Wishing you a pleasant time with your AI companion! If you encounter code errors, please check your API Key balance or network connection.

ai_ex_girlfriend

ai_ex_girlfriend Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ai_ex_girlfriend

ai_ex_girlfriend Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README