User management

Helpers for resolving, looking up, and creating users. These live under cognee.modules.users.methods and are async, so await them.

from cognee.modules.users.methods import (
    get_default_user,
    get_user,
    get_user_by_email,
    get_user_id_by_email,
    create_user,
)

Methods

get_default_user()

user = await get_default_user()

Returns the default user, creating it on first call if it does not exist yet. This is the same user Cognee resolves when you call remember(), recall(), etc. without passing user=. The default email comes from DEFAULT_USER_EMAIL (falls back to default_user@example.com); the password used at creation comes from DEFAULT_USER_PASSWORD (falls back to default_password). The auto-created default user is a superuser. See the Users concept page for the environment variables.

get_user()

user = await get_user(user_id)

Look up a user by UUID. Raises EntityNotFoundError if no user matches.

Parameter	Type	Default	Notes
`user_id`	`UUID`	required	The user’s UUID.

get_user_by_email()

user = await get_user_by_email("alice@example.com")

Look up a user by email. Returns the User object, or None if no user has that email — use this for existence checks (see below).

Parameter	Type	Default	Notes
`user_email`	`str`	required	Email to look up.

get_user_id_by_email()

user_id = await get_user_id_by_email("alice@example.com")

Returns just the user’s UUID for a given email, or None if no such user exists. Lighter than get_user_by_email() when you only need the id.

Parameter	Type	Default	Notes
`user_email`	`str`	required	Email to look up.

create_user()

user = await create_user(
    email="alice@example.com",
    password="s3cret",
)

Creates a new user. Raises fastapi_users.exceptions.UserAlreadyExists if a user with that email already exists.

Parameter	Type	Default	Notes
`email`	`str`	required	The new user’s email (unique).
`password`	`str`	required	Plaintext password; stored hashed.
`is_superuser`	`bool`	`False`	Grants administrative privileges: manage other users/tenants/roles and access all datasets.
`is_active`	`bool`	`True`	Whether the account is active. Inactive users cannot authenticate.
`is_verified`	`bool`	`False`	Whether the email is treated as verified.
`auto_login`	`bool`	`False`	When `True`, refreshes the user record after creation so it is ready for an immediate login flow.
`parent_user_id`	`Optional[UUID]`	`None`	UUID of a parent user. Pass this when creating agent or service users so the parent automatically inherits permissions on any datasets those users create. Leave `None` for regular human users.

There is no global “list all users” helper. To enumerate the users in a tenant, use get_users_in_tenant(tenant_id, user) from cognee.modules.users.tenants.methods; the requesting user must have user-management permission on that tenant. It returns a list of dicts with id, email, and roles.

Examples

Check if a user exists before creating

get_user_by_email() (and get_user_id_by_email()) return None when no user matches, so you can check existence without a try/except:

from cognee.modules.users.methods import get_user_by_email, create_user

email = "alice@example.com"

user = await get_user_by_email(email)
if user is None:
    user = await create_user(email=email, password="s3cret")
    print("created", user.id)
else:
    print("already exists", user.id)

If you prefer to attempt creation directly, catch UserAlreadyExists:

from fastapi_users.exceptions import UserAlreadyExists
from cognee.modules.users.methods import create_user, get_user_by_email

try:
    user = await create_user(email=email, password="s3cret")
except UserAlreadyExists:
    user = await get_user_by_email(email)

Get the default user and pass it to operations

import cognee
from cognee.modules.users.methods import get_default_user

user = await get_default_user()

await cognee.add("Cognee turns data into memory.", user=user)
await cognee.cognify(user=user)
results = await cognee.search("What does Cognee do?", user=user)

Most top-level operations resolve the default user automatically when user= is omitted, so calling get_default_user() explicitly is only needed when you want the User object itself.

Create an agent user owned by a parent

Pass parent_user_id so the parent user inherits permissions on datasets the agent creates:

from cognee.modules.users.methods import get_default_user, create_user

owner = await get_default_user()

agent = await create_user(
    email="agent@example.com",
    password="s3cret",
    parent_user_id=owner.id,
)

See Users for how parent/child permission inheritance works.

​User management

​Methods

​get_default_user()

​get_user()

​get_user_by_email()

​get_user_id_by_email()

​create_user()

​Examples

User management

Methods

get_default_user()

get_user()

get_user_by_email()

get_user_id_by_email()

create_user()

Examples