mem_session_start

Signature

mem.mem_session_start(user_id: str) -> SessionStartResponse

Starts a new session or reuses an existing non-expired one for user_id. Either way, you get back the active session_id, recent past-session summaries, and the most relevant prior memories (scored with ContextScore).

note

Session reuse: if the user already has an active session within the configured session_timeout_hours window, this call returns it (is_new=False). The reused session's last_activity_at is touched so the timeout resets from this handshake.

Parameters

Parámetro	Tipo	Requerido	Descripción
user_id	str	sí	Identifier of the user whose session to start or reuse. Stable across sessions.

Returns

SessionStartResponse (frozen Pydantic model):

• session_id (str) — active session identifier.
  • is_new (bool) — True if a fresh session was opened, False if an existing one was reused.
  • sessions_context (list[SessionSummaryCompact]) — up to 5 recent past-session summaries.
  • memories (list[ObservationCompact]) — up to 10 recent observations per recent session, ranked by ContextScore.

warning

The score field on memories[] is computed with ContextScore and is not comparable to the score on results from mem_search (which uses SearchScore). Different formulas, different scales — see Concepts: Scoring.

Examples

First call (new session)

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

print(response.session_id)        # e.g. "9f3c..."
print(response.is_new)            # True
print(len(response.memories))     # 0 on a fresh database

Subsequent call (reuse)

# Within session_timeout_hours, the same session is returned
response = mem.mem_session_start(user_id="alice")
print(response.is_new)            # False — reused
print(len(response.memories))     # prior observations show up here

Hydrate UI from context

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

for past in response.sessions_context:
    print(f"[{past.date}] {past.summary[:80]}")

for memory in response.memories:
    print(f"  - ({memory.type}) {memory.title}  score={memory.score:.2f}")

See also

Concepts: Sessions

mem_session_end