Kagami - Psychological Profiling Messenger Bot

Kagami (鏡) is a psychological profiling and behavior analysis bot that integrates directly into Facebook Messenger. Built with Python and the Gemini 2.5 Flash Lite LLM (via OpenRouter), it monitors individual or group chats and provides deep, data-driven psychological profiles when summoned.

Features

• Automated Mention Detection: Seamlessly listens to Facebook Messenger threads and detects when it is tagged (e.g., @Kagami, psycho).
• Contextual Awareness: Automatically fetches and parses the last 150 messages from the thread when summoned, retaining deep conversational context.
• Identity Resolution: Maps internal Facebook user IDs to display names so the LLM knows exactly who is speaking.
• Psychological Profiling: Leverages the prompt constraints in persona.txt to provide a cold, structured, and analytical side-profile of the chat members' cognitive styles, social labels, and defense mechanisms. Includes a humorous conclusion.
• Background Processing: Employs Python threading to ensure the Messenger listening event loop is never blocked by LLM API calls.

Prerequisites

• Python 3.9+
• A valid Facebook account (to serve as the Bot's identity)
• An OpenRouter API Key for Gemini

Installation

1. Clone this repository:

   git clone <your-repo-url>
   cd <your-repo-directory>

2. Create and activate a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate

3. Install the required dependencies:

   pip install -r requirements.txt

4. Set your OpenRouter API key. Create a .env file in the root directory:

   OPENROUTER_API_KEY=your_openrouter_api_key_here

Authentication Setup (Getting Cookies)

Facebook blocks automated login scripts. To authenticate Kagami, you must manually extract your session cookies.

1. Log in to Facebook: Open your preferred desktop web browser and log in to Facebook.com.
2. Open Developer Tools: Press F12.
3. Navigate to Storage/Application:
   • Chrome/Edge: Click on the Application tab.
   • Firefox: Click on the Storage tab.
4. Locate the Cookies list: Expand the Cookies section and click on https://www.facebook.com.
5. Find c_user & xs: Look at the table. Copy the values for both the c_user and xs cookies.
6. Create fb_cookies.json: In the root directory of this project, create fb_cookies.json:

   {
     "c_user": "YOUR_C_USER_VALUE_HERE",
     "xs": "YOUR_XS_VALUE_HERE"
   }

Persona Customization

You can fully customize how Kagami behaves by editing persona.txt. By default, it is instructed to be cold, analytical, and objective, analyzing cognitive boundaries and social patterns.

Usage

Once dependencies are installed and cookies are set, simply start the bot:

python3 psycho.py

1. Add the bot's Facebook account to a group chat.
2. Let the chat naturally evolve.
3. Tag the bot (just typing Kagami depending on your fallback identifiers in psycho.py).
4. Kagami will fetch the recent chat history, send it to Gemini, and reply back to the chat with the psychological analysis.

Core Dependencies

• fbchat: An embedded, modified version for modern Facebook API interactions.
• python-dotenv: Environment variable management.
• openai: The AsyncOpenAI library to interact with OpenRouter.
• requests & beautifulsoup4: Required by the embedded fbchat.

Disclaimer

This is an unofficial, community-driven project and is not affiliated with, endorsed by, or sponsored by Meta/Facebook. Automated interaction with Facebook may sometimes trigger security checkpoints or temporary account suspensions. Use responsibly.