Markus

Overview • Architecture • Quick Start • Configuration • Structure • Tests

---

Overview

Markus es un asistente personal con memoria de grafo (GraphRAG) que entiende el contexto profundo, temporal y relacional de tu vida. A diferencia del RAG vectorial tradicional, Markus recuerda quién es quién, cómo te sentiste ante un problema similar hace meses, y las cadenas causales de tus emociones.

Habla con él como con un compañero de bienestar. Él decide autónomamente qué guardar en su grafo personal y cuándo aplicar herramientas basadas en evidencia clínica.

Incluye herramientas integradas de Terapia Cognitivo Conductual (TCC), Journaling y Coaching (Modelo GROW) para actuar como un compañero de bienestar conversacional.

Note

Markus no es un sustituto de terapia profesional. Si estás en crisis, contacta con una línea de ayuda.

---

Características

🧠 GraphRAG (Neo4j)	Extrae entidades (Personas, Emociones, Temas) y las vincula con relaciones causales (CAUSED, FELT, INVOLVES)
📈 Análisis emocional	Detecta patrones, desencadenantes y evolución del estado de ánimo a lo largo del tiempo
🩺 Herramientas clínicas	Reestructuración cognitiva (TCC), grounding 5-4-3-2-1, crisis intervention, gratitud, afirmaciones positivas
🎯 Coaching inteligente	Objetivos SMART, sesiones GROW, seguimiento semanal automatizado
🌐 Red de entidades visual	Interfaz gráfica interactiva (vis-network) para explorar conexiones entre eventos de tu vida
💬 Chat-first	Sin formularios. El LLM invoca herramientas autónomamente via function calling
🔒 Auto-contenido	Sin dependencias externas de SaaS. Todo corre localmente en Docker

---

Architecture

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Frontend    │     │    Backend        │     │    Neo4j 5       │
│  nginx       │────▶│   FastAPI         │────▶│   Graph DB       │
│  vis-network │     │   Server-Sent     │     │   + APOC         │
│  Vanilla JS  │     │   Events (SSE)    │     │                  │
└──────────────┘     └──────────────────┘     └─────────────────┘
                           │
                    ┌──────┴──────────┐
                    │   LLM Service    │
                    │   16 tools via   │
                    │  function calling│
                    │  (OpenAI-compat) │
                    └─────────────────┘

Data Flow

1. Chat: El usuario escribe en el chat → el frontend streamnea via SSE
2. LLM: FastAPI envía el mensaje + contexto narrativo del grafo → el LLM responde con streaming + tool calling
3. Tools: El LLM invoca save_memory autónomamente para persistir eventos, ejecuta ejercicios TCC, establece objetivos SMART, etc.
4. Graph: ExtractorService analiza cada entrada y crea entidades/relaciones en Neo4j
5. Context: NarrativeService construye contexto narrativo desde el grafo para conversaciones futuras

Tool System

Markus usa un sistema ligero de herramientas vía el decorador @tool:

@tool(name="save_memory", description="Guarda un recuerdo en el grafo", ...)
async def save_memory(content: str, title: str = None, mood: str = None):
    ...

16 herramientas registradas automáticamente por ToolRegistry, expuestas como funciones OpenAI al LLM.

---

Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.10+ (solo para desarrollo fuera del contenedor)

1. Setup

git clone https://github.com/tu-usuario/markus.git
cd markus

cp .env.example .env
# Edita .env con tu LLM_API_KEY

chmod +x scripts/setup.sh
./scripts/setup.sh

2. Services

URL	Service
http://localhost	Web App (Frontend)
http://localhost:8000/docs	API Docs (FastAPI Swagger)
http://localhost:7474	Neo4j Browser

---

Configuration

Environment Variables

Variable	Default	Description
LLM_API_KEY	—	API key del proveedor LLM (OpenAI-compatible)
LLM_API_BASE	https://opencode.ai/zen/v1	Base URL de la API LLM
LLM_MODEL	deepseek-v4-flash-free	Modelo a utilizar
NEO4J_PASSWORD	change_this_password	Contraseña de Neo4j
NEO4J_URI	bolt://neo4j:7687	URI de conexión Neo4j
NEO4J_USER	neo4j	Usuario de Neo4j

Production

Para desplegar detrás de HTTPS con Let's Encrypt:

# Configura tu dominio
cp .env.prod.example .env
# Edita DOMAIN, LLM_API_KEY, NEO4J_PASSWORD

./scripts/deploy.sh

---

Project Structure

markus/
├── backend/
│   ├── app/
│   │   ├── api/            # FastAPI routes (chat, diary, tools)
│   │   ├── mcps/           # Tool system (psychology, coaching, journaling)
│   │   ├── models/         # Pydantic models
│   │   └── services/       # Business logic (LLM, graph, narrative, extractor)
│   ├── tests/              # Unit tests (pytest)
│   └── pyproject.toml      # Ruff config
├── frontend/
│   ├── index.html          # SPA entry point
│   ├── app.js              # Client logic (chat, mind graph)
│   ├── style.css           # Warm editorial design
│   └── nginx.conf          # Static server config
├── scripts/
│   ├── setup.sh            # Local dev bootstrap
│   ├── deploy.sh           # Production deployment
│   └── backup.sh           # Neo4j dump + optional S3
├── docs/screenshots/       # Project screenshots
├── docker-compose.yml      # Dev compose (hot-reload)
├── docker-compose.prod.yml # Production compose
├── .env.example            # Env template
├── .pre-commit-config.yaml # Pre-commit hooks (ruff)
└── LICENSE                 # MIT

---

Tests

cd backend
pip install -r requirements.txt
pip install pytest

python -m pytest tests/ -v

12 tests unitarios que cubren: ToolRegistry, trim_context, Settings.

---

Built with 💜