README.md
Project Memory 🧠
CRM personal inteligente que procesa conversaciones de WhatsApp para construir conocimiento sobre tus contactos, expuesto vía Model Context Protocol (MCP).
✨ Características
- Procesamiento de Audio: Diarización (pyannote) + Transcripción (Groq Whisper)
- Identificación de Hablantes: Distingue tu voz de la del contacto
- Privacidad: Sanitización de PII con Microsoft Presidio (RUT, teléfonos, emails)
- Extracción Inteligente: Qwen 3 32B via Groq para extraer hechos, sentimientos, temas
- Búsqueda Semántica: pgvector para encontrar conversaciones por contexto
- MCP Server: Expone tools para usar con Claude Desktop
🏗️ Arquitectura
WhatsApp → WaHA → n8n → Redis → Worker Python → PostgreSQL
↓
Claude Desktop ← MCP Server
🚀 Quick Start
# 1. Clonar
git clone https://github.com/crtormo/project-memory.git
cd project-memory
# 2. Configurar
cp .env.example .env
# Editar .env con tus API keys
# 3. Levantar
docker-compose up -d
# 4. Vincular WhatsApp
# Abrir http://localhost:3000 y escanear QR
🔧 Configuración
Variables de Entorno
| Variable | Descripción |
|---|---|
HUGGINGFACE_TOKEN |
Token para pyannote (diarización) |
GROQ_API_KEY |
API key de Groq (Whisper + Qwen) |
GOOGLE_API_KEY |
API key de Google AI Studio (fallback) |
Servicios Docker
| Servicio | Puerto | Descripción |
|---|---|---|
| PostgreSQL | 5432 | Base de datos + pgvector |
| Redis | 6379 | Cola de mensajes |
| WaHA | 3000 | API WhatsApp |
| n8n | 5678 | Automatización |
🛠️ Herramientas MCP
| Tool | Descripción |
|---|---|
get_contact_summary |
Resumen completo de un contacto |
query_conversations |
Búsqueda semántica en historial |
add_reminder |
Crear recordatorio |
get_pending_reminders |
Ver recordatorios próximos |
list_contacts |
Listar todos los contactos |
Configurar Claude Desktop
Agregar a ~/.claude/config.json:
{
"mcpServers": {
"project-memory": {
"command": "docker",
"args": ["exec", "-i", "project-memory-mcp", "python", "-m", "src.mcp_server.server"]
}
}
}
📁 Estructura
project-memory/
├── src/
│ ├── core/ # AudioProcessor, PrivacyService, Intelligence
│ ├── database/ # Models, Repositories, Connection
│ ├── services/ # BatchProcessor, MessageQueue, Notifications
│ └── mcp_server/ # Servidor MCP con tools
├── scripts/ # CLI utilities
├── docker/ # Dockerfiles
└── n8n/ # Workflows
📊 Stack Tecnológico
- Python 3.11 + Poetry
- PostgreSQL 16 + pgvector
- Redis 7 para cola de mensajes
- pyannote.audio para diarización
- Groq API (Whisper + Qwen 3 32B)
- Microsoft Presidio para PII
- MCP SDK para Model Context Protocol
📝 Scripts CLI
# Verificar BD
python scripts/init_db.py
# Registrar tu voz
python scripts/enroll_voice.py
# Exportar datos
python scripts/export_data.py contacts --format csv
# Ver recordatorios
python scripts/check_reminders.py
🔒 Seguridad
- Las API keys nunca se commitean (están en
.env) - PII sanitizado antes de persistir
- Datos almacenados localmente (Home Lab)
📄 Licencia
MIT
Tools 5
get_contact_summaryProvides a complete summary of a specific contact.query_conversationsPerforms semantic search within the conversation history.add_reminderCreates a new reminder.get_pending_remindersRetrieves a list of upcoming reminders.list_contactsLists all contacts in the CRM.Environment Variables
HUGGINGFACE_TOKENrequiredToken for pyannote diarization serviceGROQ_API_KEYrequiredAPI key for Groq (Whisper and Qwen models)GOOGLE_API_KEYAPI key for Google AI Studio fallbackTry it
→Summarize my recent conversations with John to see what we discussed about the project.
→Search my WhatsApp history for any mentions of meeting times or deadlines.
→What are my pending reminders for this week?
→List all my contacts currently stored in the CRM.