realMemory

Una capa de memoria persistente para agentes LLM con aprendizaje continuo: una memoria "hipocampal" local que escribe sin reindexar, olvida mediante dinámicas de trazas y consolida episodios en semántica durante el "sueño".

Estado: v0.4 — almacén SQLite único compartido por todos los procesos, ámbitos de memoria global/proyecto, búsqueda híbrida FTS5, umbrales calibrados sobre texto real.

La idea en pocas palabras

El LLM permanece congelado ("córtex"). realMemory es un módulo mutable separado ("hipocampo"):

• Escrituras con compuerta de novedad: un hecho conocido se potencia, uno relacionado se enlaza, uno nuevo asigna una traza nueva. Las reformulaciones nunca se acumulan.

• Memoria compartida + por proyecto: cada traza lleva un ámbito (global o un nombre de proyecto); la operación recall ve el proyecto actual más global y nunca mezcla contextos.

• Olvido por dinámica de trazas: la retención de cada traza decae exponencialmente, los refuerzos prolongan su vida, los episodios suficientemente reforzados ascienden a trazas semánticas (decaimiento lento). La curva de olvido es una propiedad de la sinapsis, no una tarea cron.

• Un grafo asociativo gratis: todo lo que se recupera junto queda vinculado por plasticidad (una regla similar a STDP) — el recorrido multi-salto surge de estadísticas de uso, no de la extracción de entidades del LLM.

• Recuperación híbrida: la búsqueda por tokens exactos (FTS5) complementa los embeddings — los IDs de error, los nombres de paquetes y los códigos se encuentran incluso cuando la similitud coseno es baja.

• Sueño: la consolidación fuera de línea confirma las trazas de elegibilidad, decae/poda los enlaces débiles y promueve estados. Todo el estado vive en una única base de datos SQLite: un servidor MCP y los hooks se ejecutan concurrentemente sin perder datos.

Related MCP server: Cortex

Inicio rápido

pip install -e ".[dev]"
pytest                # full core test suite
python -m realmemory.eval.bench_recall --facts 1500 --queries 200   # synthetic
python -m realmemory.eval.bench_real                                # real-text (fastembed)

from realmemory import Hippocampus, MemoryConfig

hippo = Hippocampus.open("./rm_data", config=MemoryConfig.dev())
hippo.remember("The project uses PostgreSQL 16 with alembic migrations",
               scope="myproject")            # a project-scoped fact
hippo.remember("The user prefers concise answers") # global by default

packet = hippo.recall("which database does the project use?", scope="myproject")
for item in packet.items:
    print(f"[{item.confidence:.2f}] ({item.source}) {item.text}")
if packet.abstained:
    print("no trustworthy memories")     # abstention instead of hallucination

hippo.consolidate()   # "sleep": commit traces, decay weak links

Embedder local

Por defecto, el núcleo usa un HashingEmbedder determinista (sin modelos). El embedder semántico local de producción es fastembed (ONNX Runtime, CPU):

pip install 'realmemory[local]'

• Modelo: paraphrase-multilingual-MiniLM-L12-v2, dim=384, ruso+inglés.

• Caché del modelo: ~/.cache/realmemory/fastembed (~240 MB), se descarga una vez.

• Carga medida: ~580 MB de RAM del proceso; ~65–75 ms por texto en CPU; una recuperación completa ≈ 77 ms. Invisible para el agente.

• La asimetría se maneja: los hechos se codifican con embed(), las consultas con embed_query().

• Los umbrales de la compuerta se calibran según la anisotropía del modelo: el perfil de umbrales vive en FastEmbedProvider.recommended_thresholds, se aplica al iniciar el servidor y se deriva del benchmark de texto real (ver más abajo).

Integración con ZCode / Claude Code (MCP)

Registra un servidor stdio de ámbito de usuario en la configuración de tu cliente:

"realmemory": {
  "type": "stdio",
  "command": "/path/to/venv/Scripts/python.exe",
  "args": ["-m", "realmemory.api.mcp_server",
           "--path", "/path/to/rm_data",
           "--embedder", "local"]
}

Herramientas del agente (nombradas como acciones cognitivas): recall(query,k,project) · memorize(text,kind,related_ids,project) · reflect(memory_ids,reward) · revise(old_id,new_text) · introspect() · dream_log().

Memoria compartida + por proyecto: cada traza se etiqueta con un ámbito — global (preferencias, identidad) o un nombre de proyecto. El proyecto se detecta automáticamente (REALMEMORY_PROJECT → ZCODE_PROJECT_DIR → directorio actual que contiene .git); también se puede pasar explícitamente mediante el argumento project o --project. recall busca en el proyecto actual + global; otros proyectos nunca se filtran.

El aislamiento total de espacios de nombres entre cerebros separados está disponible mediante Hippocampus.open(path, namespace=...) / --namespace.

La base de datos almacena un marcador de embedder (db_meta) y se niega a abrirse con uno diferente — los vectores antiguos y nuevos no son comparables por coseno.

Automatización: hacer que los agentes realmente la usen

Tres mecanismos, instalados por defecto:

1. Skill / instrucciones que describen cuándo usar recall / memorize / reflect, y se cargan en el contexto de cada sesión.

2. Hook SessionStart → python -m realmemory.hook_cli brief — inyecta un breve estado de memoria: hechos semánticos y trazas episódicas duraderas del proyecto actual + global, presupuesto de ~600 caracteres.

3. Hook Stop → python -m realmemory.hook_cli sleep — consolidación después de cada respuesta; limitado por el estado de la base de datos (se omite cuando nada ha cambiado desde el último sueño). Tarda ~0.3 s, no carga el modelo de embedder.

Los hooks y el servidor MCP se ejecutan de forma segura al mismo tiempo: todo el estado está en SQLite, los "sueños" concurrentes se serializan mediante una transacción.

Operaciones

• Copias de seguridad: antes de cada "sueño", la base de datos se copia a <store>/backups/ (API de copia de seguridad sqlite consistente), se conservan las últimas 10 copias (backups_keep; 0 las desactiva). Cualquier migración de esquema realiza primero una copia de seguridad automática.

• Versión del esquema registrada en db_meta.schema_version.

• Los fallos de los hooks no son silenciosos: un hook que falla imprime en el stderr de la sesión y deja un evento hook_error en el diario, visible en el informe.

• Disciplina de aprendizaje: el informe muestra reflect/recall — por debajo de ~0.1 el agente rara vez califica las memorias recuperadas y el decaimiento/promoción funcionan a ciegas.

• El enrutamiento de proyectos se verifica con una llamada — introspect muestra el proyecto detectado actualmente.

Observabilidad ("cómo se comporta la memoria con el tiempo")

Cada evento se añade al diario dentro de la base de datos: escrituras, recuperaciones (latencia, abstención, confianza), retroalimentación, consolidaciones con métricas completas. Informe completo en cualquier momento:

python -m realmemory.report --path ./rm_data [--json report.json]

Muestra: crecimiento de la memoria por tipo/ámbito/estado, historial de decisiones de la compuerta de novedad, proporción de abstención y latencia de recuperación p50/p95, qué se ha reforzado, qué episodios se desvanecen, dinámicas de retención a lo largo de los sueños, fallos de hooks.

Resultados de la fase 0 (ejecuciones reales)

Benchmark sintético (bench_recall, embedder hashing, dim=2048):

Benchmark de texto real (bench_real, fastembed MiniLM dim=384, 103 hechos RU/EN, 89 consultas — paráfrasis, tokens exactos, ruido):

Lección del benchmark sintético: obtuvo 1.000 mientras que los umbrales por defecto sobre texto real fusionaban casi todo en unos pocos blobs — la calibración ahora se deriva de las distribuciones del benchmark y vive en el perfil del embedder. El mismo benchmark de texto real incluye una línea base ingenua de escaneo completo por coseno: el pipeline gana claramente en tokens exactos (1.000 vs 0.800), está a la par en paráfrasis y, por ahora, se abstiene de forma menos agresiva que un umbral puro — ver docs/ARCHITECTURE.md §7.2.

Barrido de escala (10k–50k trazas) con hallazgos honestos sobre una caída brusca de la calidad de recuperación en 30k con datos sintéticos: §7.3.

Detalles y el resultado negativo de Hamming-SDM en docs/ARCHITECTURE.md §3 y §7.

Pruebas: 122 superadas.

Arquitectura

En resumen: L1 — SDRVotingIndex, votación de punteros sobre un índice invertido de unidades SDR (capacidad + candidatos), L2 — una red de ensamblaje sobre las mismas unidades (asociaciones, completado, multi-salto), rematada con un rerank exacto por embeddings, una compuerta de novedad, políticas de decaimiento y un consolidador fuera de línea ("sueño").

Las interfaces de los módulos están fijadas en docs/CONTRACTS.md; antecedentes de investigación y fuentes en docs/RESEARCH.md.

Estructura del proyecto

src/realmemory/
├── encoding/     # embedders, SDR encoding
├── core/         # L1 SDRVotingIndex, L2 AssemblyNetwork, plasticity
├── policies/     # novelty gate, trace decay/promotion
├── store/        # SQLite storage (traces, edges, eligibility, events)
├── api/          # MCP server
└── eval/         # benchmarks

Licencia

MIT