# Instrucciones para el agente: Graphiti: memoria de agentes con grafos temporales

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

- Dificultad: avanzado
- Proyecto: https://github.com/getzep/graphiti (licencia Apache-2.0)
- Guía completa: https://lab.wisd.ai/hub/graphiti-temporal-agent-memory

---

## Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

---

## Pasos de configuración

### Paso 1: prepara Python y Neo4j

Comprueba Python ≥3.10 y pip en un entorno aislado. El README del ejemplo aún dice 3.9: usa el mínimo del paquete. Instala Neo4j Desktop, crea e inicia una base local Neo4j 5.26 y conserva su usuario y contraseña. El paquete Python no instala el servicio.

```sh
pip install graphiti-core
```

Carga `OPENAI_API_KEY`, `NEO4J_URI`, `NEO4J_USER` y `NEO4J_PASSWORD` en el entorno privado de la terminal. La URI local del [ejemplo oficial](https://github.com/getzep/graphiti/blob/main/examples/quickstart/README.md) es `bolt://localhost:7687`. Usa una base vacía de prueba. Las llamadas al modelo y a embeddings (representaciones numéricas para buscar por significado) tienen coste.

### Paso 2: obtiene el ejemplo y prepara su inicialización

Con Git disponible:

```sh
git clone https://github.com/getzep/graphiti.git
cd graphiti/examples/quickstart
```

El archivo es [quickstart_neo4j.py](https://github.com/getzep/graphiti/blob/main/examples/quickstart/quickstart_neo4j.py). Antes de ejecutarlo, añade dentro de `try:`, antes de incorporar episodios:

```python
        await graphiti.build_indices_and_constraints()
```

El README exige inicializar índices y restricciones, pero el archivo consultado omite esa llamada. La adaptación usa el [método del código oficial](https://github.com/getzep/graphiti/blob/main/graphiti_core/graphiti.py). El script utiliza `python-dotenv`, incluido entre las dependencias de `graphiti-core`.

### Paso 3: ejecuta y contrasta un cambio temporal

Primero ejecuta el ejemplo sin cambiar sus episodios:

```sh
python quickstart_neo4j.py
```

Debe incorporar episodios e imprimir resultados sobre la fiscal general de California, incluidos hechos y fechas. Para evaluar cambios temporales, usa otra base de prueba vacía: conserva la estructura de los episodios pero sustituye su contenido por dos hechos sobre la misma entidad, por ejemplo «Ana trabaja en Alfa» y después «Ana ahora trabaja en Beta y ya no en Alfa». Asigna a cada episodio un campo `reference_time` con fechas UTC distintas usando `datetime(2026, 1, 1, tzinfo=timezone.utc)` y `datetime(2026, 2, 1, tzinfo=timezone.utc)`. Cambia el argumento `reference_time=datetime.now(timezone.utc)` por `reference_time=episode['reference_time']` y las consultas por «¿Dónde trabaja Ana?». Ejecuta el mismo archivo.

## Comprobación

Comprueba `Added episode` y los hechos extraídos, no solo la conexión. En la prueba temporal, inspecciona `valid_at` e `invalid_at`: la relación con Alfa debería quedar invalidada y la de Beta vigente. La extracción depende del modelo: si no refleja el cambio, revisa los episodios y relaciones antes de dar la capacidad por comprobada.

## Si algo falla

Comprueba servicio, URI, base de datos y credenciales antes de cambiar de backend. Los ejemplos de FalkorDB o Neptune tienen requisitos distintos. Este procedimiento se ha contrastado con documentación y código; no se ha ejecutado aquí.