Content
# Personal AI Cognitive Exobrain (MCP) 🧠
This is a personal cognitive exobrain server based on the **Model Context Protocol (MCP)**. It enables your large language models (such as Claude Desktop, Cursor, VS Code plugins, etc.) to have **long-term, structured, and emotionally coordinated real memory**.
## 🌟 Why Do We Need It? (Pain Points)
Current AI models have three fatal flaws when handling long-term memory:
1. **Context Forgetting (Memory Explosion)**: Large models cannot keep your lifelong chat records in memory, and traditional memory often leads to context length explosion.
2. **Lossy Compression of Information**: When you say "I want to buy two boxes of pure milk," current AI may store it as `Task: Buy Milk, Category: Life`, completely losing the semantic and emotional color of your speech.
3. **Lack of Emotional Perception**: Human memory is not equal - traumatic and ecstatic experiences are remembered for a long time, while mundane daily life is naturally forgotten. Traditional databases cannot simulate this **emotional weight**.
**Our Solution: Emotion-Aware Dual-Track Architecture**
* **Track 1: Emotion-Tagged Immutable Log**: Each original sentence is not only saved but also tagged with **Valence** and **Arousal** emotional coordinates. High-arousal memories (extreme joy or pain) automatically gain higher weight and naturally emerge like human memory.
* **Track 2: Projected Structural View**: Tasks, preferences, and goals extracted from Track 1 can be rebuilt at any time.
## 🛠 High Cohesion Semantic Tools for AI (MCP Tools)
This system exposes **6** function interfaces that are very friendly to large models:
| Tool | Function |
|---|---|
| `remember` | **Store everything** - user original words, AI observations, any text, **automatically analyze emotional coordinates** (Valence/Arousal) and topic domain |
| `add_task` | Capture task instructions, automatically record in Track 1 and map to Track 2 to-do tasks, support **task tree level** (`parent_task_id`), **priority** (`priority`), and **effort estimation** (`effort_estimate`) |
| `update_task` | Update task progress (completion/discarded), attach metadata tags, or do both |
| `recall` | **Hybrid search**: keyword matching + semantic vector search + **emotional weight sorting**. If the query is empty, automatically show the top 3 high-arousal memories with the highest weight |
| `suggest` | Query to-do tasks, and the backend algorithm automatically scores by priority, filters by free time, and returns accurate next action suggestions |
| `expose_schema` | **Advanced function**: expose database structure, facilitate Agent to write custom SQL. We **do not provide deletion tools** - if you need to delete, please write SQL yourself |
## 🔍 Core Highlights
### 1. Semantic Vector Search
`recall_past_mentions_of` implements a **three-layer hybrid search strategy**:
- **Pass 1**: Efficient SQLite `LIKE` exact keyword matching (zero delay)
- **Pass 2**: Semantic vector search based on `sentence-transformers`
- Use `paraphrase-multilingual-MiniLM-L12-v2` model (100MB, CPU can run, strong Chinese support)
- Preload model when the server starts (Eager Loading) to eliminate search cold start delay
- **Pass 3**: Emotional weight reordering
- Dynamic attenuation calculation based on **Ebbinghaus Forgetting Curve**
- High Arousal (arousal) memory gains additional benefits
- Search "dairy products" → recall "milk" record ✅
### 2. Emotional Coordinates and Memory Emergence
Each memory is marked on the **Russell Emotional Ring Model**:
- **Valence**: 0.0 (extremely negative) → 1.0 (extremely positive)
- **Arousal**: 0.0 (flat as water) → 1.0 (emotional intensity)
**Attenuation formula:**
```
Score = Importance × (Activation_Count^0.3) × Time_Decay × (Base + Arousal² × Boost)
```
- High-arousal memories decay slowly and are more likely to emerge in `recall()` (empty query) at the beginning of the conversation
- The more activated memories are, the harder they are to forget (repeatedly mentioned things are remembered more firmly)
## 🚀 Installation and Deployment
### Environmental Requirements
- Python 3.11+
- (Optional) `ANTHROPIC_API_KEY` environment variable - used for automatic emotional analysis. If not provided, the system will use default values (Valence=0.5, Arousal=0.3).
### Option A: Let Your AI Help You Install Automatically (The Most Cyberpunk Recommendation!)
If you are using an IDE with Agent capabilities (such as Cursor / Cline / Antigravity):
1. Clone this project to your local machine.
2. Directly send instructions to your AI: **"Please read the `INSTALL-MCP.md` in the directory and help me install this MCP service automatically."**
3. AI will automatically establish a virtual environment, find the configuration entry, and complete all injections!
### Option B: Manual Configuration for Geeks
1. **Get the code and initialize the environment:**
```bash
git clone <your repository address>
cd exobrain-mcp
python -m venv .venv
.\.venv\Scripts\activate # Windows users
source .venv/bin/activate # Mac/Linux users
pip install -r requirements.txt
```
> ⚠️ `requirements.txt` includes `sentence-transformers`, which will download about 100MB of semantic models during the first installation. Please ensure a stable network connection.
2. **Configure environment variables (optional but recommended):**
```bash
# Windows PowerShell
$env:ANTHROPIC_API_KEY="your-api-key"
# Windows CMD
set ANTHROPIC_API_KEY=your-api-key
# Linux/Mac
export ANTHROPIC_API_KEY="your-api-key"
```
3. **Configure your MCP host (such as Claude Desktop):**
Open the corresponding JSON configuration file (e.g., `claude_desktop_config.json`) and add an injection node under `mcpServers`:
```json
"mcpServers": {
"personal-memory": {
"command": "C:/absolute/path/.../exobrain-mcp/.venv/Scripts/python.exe",
"args": [
"C:/absolute/path/.../exobrain-mcp/server.py"
],
"env": {
"ANTHROPIC_API_KEY": "your-api-key"
}
}
}
```
> ⚠️ **Important**: `command` must point to the Python in the virtual environment (`.venv`), not the system global Python. Otherwise, `sentence-transformers` will not be loaded, and semantic search will silently degrade to pure keyword search.
4. **Restart and experience:**
Save the configuration and restart your client (e.g., restart Claude Desktop), and try saying in the dialog box: *"I really hate eating cilantro, remember this no matter what."* Then see how your cognitive exobrain works for you!
## 📂 Data Storage and Backup Strategy
### Experience: Code Openness vs. Data Privacy
This project is an **open-source project** (code open), but your memory data (`exobrain.db`) is **extremely private**.
**Problem scenario:**
> You want to fork this project to improve the code and contribute back to the community, but your database contains "yesterday's emotional issues discussed with AI," "tomorrow's to-do list," "your personal preferences"...
**Incorrect approach:**
- Submit the database to a public repository → privacy leak
- Hardcode the local path into the code → change machines and fail
**Correct approach:**
#### Scheme 1: Quick Start (Single Machine Use)
```bash
git clone https://github.com/HomuraTokido/exobrain-mcp.git
cd exobrain-mcp
# Run directly, database automatically created in the project directory
# .gitignore shields *.db, will not submit by mistake
```
**Suitable for:** Trial, insensitive data, single machine use
#### Scheme 2: Production Deployment (Code and Data Separation)
**Recommended for long-term use, multi-device synchronization, and data backup needs**
1. **Fork public repository** (for code contribution and improvement)
```bash
git clone https://github.com/<your account>/exobrain-mcp.git
```
2. **Create a private repository** (only for data backup)
```bash
# Create a new private repository on GitHub, e.g., my-exobrain-data
git clone https://github.com/<your account>/my-exobrain-data.git
```
3. **Configure data path**
Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
Edit `.env` file:
```env
MEMORY_DB_PATH=/path/to/my-exobrain-data/exobrain.db
```
Or set environment variables at startup:
```powershell
# Windows
$env:MEMORY_DB_PATH="C:\Users\<username>\Documents\my-exobrain-data\exobrain.db"
# Linux/Mac
export MEMORY_DB_PATH="/home/<username>/my-exobrain-data/exobrain.db"
```
4. **Start service**
```bash
python server.py
# Database now stored in private repository directory
```
**Architecture description:**
- `exobrain-mcp/` - public repository, store code, can pull upstream updates at any time
- `my-exobrain-data/` - private repository, store `exobrain.db` and configuration files
- `.env` - local configuration file (protected by `.gitignore`, will not be submitted)
**Backup strategy:**
```bash
# Regularly submit data changes
cd my-exobrain-data
git add exobrain.db
git commit -m "backup: $(date)"
git push origin main
```
## 🙏 Acknowledgments
This project referenced and integrated the excellent ideas of the following open-source projects during design and implementation:
- **[Ombre-Brain](https://github.com/P0lar1zzZ/Ombre-Brain)** by P0lar1zzZ (MIT License)
- Concept and application of emotional coordinates (Valence/Arousal)
- Memory attenuation algorithm based on Ebbinghaus Forgetting Curve
- High-arousal memory weight addition mechanism
The above concepts are adapted and applied to the `emotion_engine.py` module of this project, giving the memory system emotional perception and natural forgetting capabilities.
**From ordinary LLM to general artificial intelligence (AGI), the system needs a digital soul cache. I wish you and your AI cooperation pleasant!**
