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.
- 📄 Oroi: una red semántica para agentes conversacionales (castellano)
- 📄 Oroi: a semantic network for conversational agents (English)
- 🔗 DOI: 10.5281/zenodo.21208930
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 syncCredenciales: 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).
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ónLa 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.
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.
| Pieza | Soporte hoy |
|---|---|
| Extracción (LLM rápido) | Azure OpenAI, u OpenAI-compatible (OpenAI directo, Ollama, vLLM...) |
| Embeddings | Azure OpenAI, u OpenAI-compatible con un modelo de embeddings en el endpoint |
| Conversador | Claude (API o sesión local de Claude Code), Azure, u OpenAI-compatible |
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.
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 + costesCó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.
Igor Laburu · Gako AI · oroi@gako.ai