Oroi

Oroi (euskera: raíz de oroitu, «recordar») — una red semántica para agentes conversacionales. Memoria para una conversación infinita.

Oroi es una memoria asociativa para chatbots y agentes LLM que almacena la conversación como una red semántica con dinámica de activación inspirada en la memoria humana: lo mencionado se activa, la activación se propaga a lo asociado, todo decae con los turnos, las asociaciones que se repiten se refuerzan y un proceso en segundo plano consolida lo importante — como la memoria humana consolida durante el sueño.

La hipótesis: la recuperación sensible a la activación supera a la recuperación por similitud vectorial pura (RAG) en conversaciones largas con referencias recurrentes y deriva temática. En una evaluación de 224 escenarios, Oroi supera al RAG híbrido 0,75 frente a 0,55 en recall de recuperación (gana en 43 escenarios y no pierde en ninguno; p<10⁻⁴), con la ventaja concentrada en los casos que confunden a la búsqueda por similitud: distractores, datos que cambian y cadenas de tres asociaciones.

Oroi is an associative memory for LLM agents: a semantic network with activation dynamics inspired by human memory. Spanish-first project; English preprint available below.

El preprint

• 📄 Oroi: una red semántica para agentes conversacionales (castellano)
• 📄 Oroi: a semantic network for conversational agents (English)
• 🔗 DOI: 10.5281/zenodo.21208930

Instalación

Requiere Python ≥ 3.12 con soporte de extensiones SQLite (los intérpretes de uv, Homebrew, conda y las distribuciones Linux lo traen; el instalador de python.org para macOS, no).

# como librería, dentro de tu proyecto (venv, uv, poetry...):
pip install oroi

# como herramienta de línea de comandos, global:
uvx oroi            # o: pipx install oroi

# desde el repositorio, para desarrollo:
git clone https://github.com/igorlaburu/oroi && cd oroi && uv sync

Credenciales: copia .env.example a .env (en tu carpeta de trabajo o en ~/.oroi/.env para tenerlas globales) y rellena tus claves — Azure OpenAI, o cualquier endpoint OpenAI-compatible como Ollama para correr 100 % en local. Tu memoria vive por defecto en ~/.oroi/mind.db (cámbiala con --db en cualquier comando).

Uso en diez líneas

from oroi import Mind
from oroi.extraction.extractor import TurnExtractor
from oroi.providers.azure import AzureEmbedder, AzureLLM
from oroi.providers.settings import ProviderSettings

settings = ProviderSettings()                      # lee .env
llm = AzureLLM(settings)
mind = Mind("memoria.db", AzureEmbedder(settings), TurnExtractor(llm), judge=llm)

mind.perceive("mi oficina está en Madrid")         # codificar un turno
print(mind.recall("¿dónde trabajo?"))              # recuperar: reconocimiento + evocación

La memoria persiste en memoria.db: reabrir es continuar, no empezar de cero. Mind.sleep() consolida (fusión de duplicados, promoción de asociaciones repetidas, poda); en el REPL y el servidor ocurre solo al quedar inactiva la conversación.

La línea de comandos

uv run oroi-chat                        # REPL conversacional con memoria (proveedor por .env)
uv run oroi viz --db memoria.db         # la película de la memoria, en HTML autocontenido
uv run oroi serve --db memoria.db       # visor en vivo + chat contra la mente real
uv run oroi replay --db memoria.db      # reconstruye la película desde los episodios
uv run oroi consolidate --db memoria.db # consolidación bajo demanda

¿Sin conversación propia todavía? uv run python examples/demo_conversation.py graba una conversación cotidiana de demostración en examples/demo.db.

Proveedores

Para correr 100 % en local con Ollama: MEMORY_PROVIDER=openai, OPENAI_BASE_URL=http://localhost:11434/v1, OPENAI_FAST_MODEL=qwen3.6:latest (o tu modelo), y un modelo de embeddings servido (p. ej. nomic-embed-text, con OPENAI_EMBEDDING_DIM=768).

El núcleo no depende de ningún proveedor: oroi/providers/base.py define los Protocols (Embedder, Extractor, Chat) y todo se inyecta por constructor — cualquier otro proveedor es implementar dos o tres métodos.

Evaluación

El protocolo del preprint es reproducible: evaluation/ contiene el corpus sintético (224 escenarios, 7 fenómenos), las condiciones de contraste (RAG híbrido, RAG sobre hechos, re-ranker) y las dos métricas (Recall@contexto y Answer@judge).

uv run python -m evaluation.run        # tabla por fenómeno + test de McNemar + costes

Estado y licencia

Código bajo Apache-2.0; el nombre «Oroi» queda fuera de la concesión de licencia. Proyecto de investigación en desarrollo activo: la API puede cambiar. Próximas piezas declaradas en el preprint: reelaboración de recuerdos y validación sobre benchmark externo.

Contacto

Igor Laburu · Gako AI · oroi@gako.ai