Quickstart

Esta guía muestra el flujo Python embebido: instalá la librería, creá un store, guardá una observación (con strip de contenido privado), buscala, y cerrá la sesión con un summary.

1. Instalar

iLAB Memory es un único paquete Python. El core no tiene dependencias externas en runtime más allá de Pydantic y la stdlib (SQLite viene con Python).

pip install ilab-memory

2. Crear un memory store

ILabMemory.from_path es la factory para el store backed por SQLite. Apuntalo a un path en disco (o :memory: para tests).

from ilab_memory import ILabMemory

mem = ILabMemory.from_path("./memory.db")

tip

ILabMemory es context manager — usá with ILabMemory.from_path(...) as mem: si querés que el store cierre limpio al final del script.

3. Iniciar una sesión para un usuario

Las sesiones son por usuario y se reutilizan si siguen activas (timeout por defecto: configurable en Config). La response trae el session_id, si es nueva, y el contexto de memoria previo.

response = mem.mem_session_start(user_id="alice")

print(response.session_id)        # ej. 1
print(response.is_new)            # True en la primera llamada para este user
print(len(response.memories))     # observaciones previas, scored con ContextScore

4. Guardar una observación

mem_save requiere user_id, content, type y title. Pasá topic_key cuando el mismo tema pueda actualizarse entre turnos — los saves siguientes con la misma key hacen upsert in-place en lugar de duplicar.

Cualquier cosa dentro de <private>...</private> se elimina antes de hashear o persistir el contenido. Los secretos nunca llegan a disco.

result = mem.mem_save(
    user_id="alice",
    type="preference",
    title="Saludo preferido",
    content="Alice prefiere que la saluden como 'Ali'. <private>API key: sk-xxx</private>",
    topic_key="user/alice/greeting",
)

print(result.id)        # id de la observación
print(result.outcome)   # 'created' | 'updated' | 'deduped'

5. Buscar memoria

mem_search corre búsqueda full-text (FTS5) limitada al usuario y devuelve observaciones compactas rankeadas por SearchScore (combina rank de FTS, recency y revision).

results = mem.mem_search(
    user_id="alice",
    query="saludo",
    limit=5,
)

for obs in results:
    print(obs.id, obs.score, obs.title)

nota

Los resultados vuelven como ObservationCompact (payload chico, ~100 tokens). Usá mem_get_observation para hidratar el contenido completo cuando lo necesites.

6. Obtener la observación completa

Los resultados compactos no traen el content por brevedad. Hidratá el registro completo por id cuando lo necesites para inspeccionar o renderizar. Fijate que el bloque <private> desapareció — solo queda [REDACTED].

obs = mem.mem_get_observation(user_id="alice", observation_id=result.id)

print(obs.content)
# → "Alice prefiere que la saluden como 'Ali'. [REDACTED]"

7. Cerrar la sesión con un summary

Cuando termina la conversación, escribí un summary humano para que la próxima sesión arranque sabiendo dónde quedó esta.

closed = mem.mem_session_end(
    user_id="alice",
    summary="Capturé el saludo preferido de Alice y confirmé que el agente usará 'Ali'.",
)

print(closed.id, closed.completed_at)

tip

¿Querés el mismo flujo por red? iLAB Memory trae un servidor HTTP REST (FastAPI) y un servidor MCP stdio — ambos exponen exactamente las mismas operaciones y serializan los mismos modelos Pydantic. Mirá la API Reference cuando aterrice Fase 4.

¿Qué sigue?

Concepts

Sessions, observations, topic_keys, scoring, privacy y los Braess points detrás del diseño.

Cookbook

Recetas end-to-end — embeber iLAB Memory en un chat FastAPI, un asistente Tauri, un agente autónomo.

API Reference

Schemas Pydantic completos, la fachada ILabMemory, el spec OpenAPI HTTP y la lista de tools MCP.