mem_search

Firma

mem.mem_search(
    user_id: str,
    query: str,
    *,
    limit: int = 10,
    types: list[str] | None = None,
    types_exclude: list[str] | None = None,
) -> list[ObservationCompact]

Corre búsqueda full-text (FTS5 con fallback a LIKE) scoped a user_id. Los resultados se rankean con SearchScore — combinación de FTS rank, decay por recencia y revision count.

aviso

El campo score que devolvés acá usa SearchScore y no es comparable con el score de memories[] de mem_session_start (que usa ContextScore). Ver Conceptos: Scoring.

Parámetros

Parámetro	Tipo	Requerido	Descripción
user_id	str	sí	Scope del dueño — solo se buscan las observaciones de este user.
query	str	sí	String de búsqueda. Trimmeado; no puede ser vacío. Queries cortas (< 3 chars) van por el fallback de LIKE.
limit	int	no (default 10)	Resultados máximos. Tiene que ser >= 1. La capa HTTP impone un upper bound adicional de 100.
types	list[str] | None	no (default None)	Allowlist de tipos de observación a incluir. Mutuamente exclusivo con types_exclude — pasar ambos levanta ValueError.
types_exclude	list[str] | None	no (default None)	Denylist de tipos de observación a saltear. Mutuamente exclusivo con types.

Returns

list[ObservationCompact] (modelos Pydantic frozen):

Ordenados por score DESC. Cada item tiene:

• id (int)
• type (str)
• title (str)
• topic_key (str | None)
• score (float) — SearchScore.value
• snippet (str) — preview truncado del content
• updated_at (str, ISO-8601 UTC)

tip

Los resultados compact omiten el content completo por brevedad (~100 tokens cada uno). Hidratá el record completo con mem_get_observation cuando lo necesités.

Levanta

• ValueError — query vacía (post-trim), limit < 1, o types y types_exclude ambos provistos.

Ejemplos

Búsqueda básica

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

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

Filtrar por tipo

decisions = mem.mem_search(
    user_id="alice",
    query="database",
    types=["decision"],
)

Excluir tipos ruidosos

non_summaries = mem.mem_search(
    user_id="alice",
    query="auth",
    types_exclude=["summary"],
)

Ver también

Conceptos: Scoring

mem_get_observation