mem_search

Signature

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

Runs full-text search (FTS5 with a LIKE fallback) scoped to user_id. Results are ranked by SearchScore — a combination of FTS rank, recency decay, and revision count.

warning

The score field returned here uses SearchScore and is not comparable to the score on memories[] from mem_session_start (which uses ContextScore). See Concepts: Scoring.

Parameters

Parámetro	Tipo	Requerido	Descripción
user_id	str	sí	Owner scope — only this user's observations are searched.
query	str	sí	Search string. Trimmed; must be non-empty. Short queries (< 3 chars) fall back to LIKE.
limit	int	no (default 10)	Maximum results. Must be >= 1. The HTTP layer enforces an additional upper bound of 100.
types	list[str] | None	no (default None)	Allowlist of observation types to include. Mutually exclusive with types_exclude — passing both raises ValueError.
types_exclude	list[str] | None	no (default None)	Denylist of observation types to skip. Mutually exclusive with types.

Returns

list[ObservationCompact] (frozen Pydantic models):

Sorted by score DESC. Each item has:

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

tip

Compact results omit full content for brevity (~100 tokens each). Hydrate the full record with mem_get_observation when you need it.

Raises

• ValueError — empty query (after trim), limit < 1, or both types and types_exclude provided.

Examples

Basic search

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

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

Filter by type

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

Exclude noisy types

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

See also

Concepts: Scoring

mem_get_observation