Memory

The memory port, SQLite and callable backends, Mem0/Zep/Graphiti adapters and the memory tools. Concepts: Memory.

Memory: the MemoryPort, SQLite, callable, Mem0, Zep and Graphiti backends, and memory tools.

ScopeFrom = Callable[[ToolContext], MemoryScope | None] module-attribute

CallableMemory

Bases: GuardedMemory

Wraps host functions (sync or async) as a MemoryPort.

add and search are required; get, delete and export are optional and raise ToolUsageError when missing. Whatever they return still passes the scope, expiry and filter checks, so a backend bug cannot leak another scope's records.

Raises:

Type	Description
ToolUsageError	a given function is not callable.

GraphitiMemory

Bases: GuardedMemory

Graphiti behind the memory port: episodes in a hashed group per user; search returns facts.

Raises:

Type	Description
ConfigError	graphiti is None (pass your connected Graphiti instance).

GuardedMemory

Bases: ABC

The base of every backend: checks inputs, drops out-of-scope or expired output.

add(records, *, ctx=None) async

Store records (ids, created_at and retention expires_at filled in); the stored.

Raises:

Type	Description
ToolUsageError	bad records, or an id that is already stored.
IntegrationError	the backend failed (the cause is chained).

add_sync(records, *, timeout=None, **kw)

add from sync code.

delete(ids=None, *, scope=None, ctx=None) async

Delete ids, every record in scope, or ids only within scope; the count.

Raises:

Type	Description
ToolUsageError	neither ids nor scope, or a bad one.
IntegrationError	the backend failed.

delete_sync(ids=None, *, timeout=None, **kw)

delete from sync code.

export(scope, *, ctx=None) async

Every live record in scope, oldest first (for a privacy request).

Raises:

Type	Description
ToolUsageError	bad scope.
IntegrationError	the backend failed.

export_sync(scope, *, timeout=None, **kw)

export from sync code.

get(id, *, scope=None, ctx=None) async

The live record id, or None; with scope, None unless the record is in it.

Raises:

Type	Description
ToolUsageError	bad id or scope.
IntegrationError	the backend failed.

get_sync(id, *, timeout=None, **kw)

get from sync code.

purge() async

Delete expired records now; how many. Backends without storage of their own: 0.

purge_sync(*, timeout=None)

purge from sync code.

search(query, *, scope, k=5, filters=None, ctx=None) async

Up to k live records in scope that match query and filters, best first.

An empty query returns the newest records.

Raises:

Type	Description
ToolUsageError	bad query, scope, k or filters.
IntegrationError	the backend failed.

search_sync(query, *, timeout=None, **kw)

search from sync code.

Mem0Memory

Bases: GuardedMemory

Mem0 2.x behind the memory port: user, session (run_id) and agent scopes.

Raises:

Type	Description
MissingDependency	no client and mem0ai is not installed (on first use).

client property

The Mem0 client, built on first use when none was given.

MemoryHit

Bases: BaseModel

A search result: the record and its score (higher is better, backend-specific).

MemoryPort

Bases: Protocol

Stores and finds texts per scope; every backend here also has *_sync twins.

MemoryRecord

Bases: BaseModel

One remembered text in its scope; id and created_at are filled in on add.

live(now, retention_days)

False once expired, or older than retention_days.

MemoryScope

Bases: BaseModel

Whose memory: a user, a session (chat thread) and an agent; at least one is set.

A query scope covers a record when the user ids are equal (both may be empty), and the session and agent ids are equal wherever the query sets them. So a user's scope sees all their sessions, and never another user's records.

covers(other)

True when a record in other belongs to this (query) scope.

SQLiteMemory

Bases: GuardedMemory

Memory in one SQLite file: keyword search, optional vectors, deletes that leave no text.

Raises:

Type	Description
ConfigError	a bad path, timeout, retention_days or embedder (here); on first use, a file without WAL, another schema or foreign tables with our names.

purge() async

Delete expired records and those past retention_days now; how many.

ZepMemory

Bases: GuardedMemory

Zep behind the memory port: records are text episodes in a Zep user of our own (hashed id).

Raises:

Type	Description
MissingDependency	no client and zep-cloud is not installed (on first use).

client property

The Zep client, built on first use when none was given (it reads ZEP_API_KEY).

memory_tools(memory, *, scope_from=None, confirm_writes=False, forget=True, across_sessions=True, k=5)

remember, recall and forget tools whose scope is scope_from(ctx), never an argument.

Raises:

Type	Description
ConfigError	memory is not a memory backend, scope_from is not callable, or a bad k.

scope_from_context(ctx)

The signed-in caller's scope (ctx.user_id, else the host's principal), or None.

thread_scope(ctx)

Opt-in memory for anonymous chats: the thread only; safe only with unguessable ids.

user_scope(ctx)

The caller's user-only scope (for backends that partition by user), or None.