Namespaces resource

list()

def list(self) -> List[Dict[str, Any]]: ...

List every namespace owned by the calling org, newest first.

for ns in recall.namespaces.list():
    print(ns['id'], ns['name'], ns['mode'])

for ns in await recall.namespaces.list():
    print(ns['id'], ns['name'], ns['mode'])

create()

def create(self, req: Dict[str, Any]) -> Dict[str, Any]: ...

Create a new namespace and bootstrap its data plane (Postgres pool, embedding column, indexes). Returns the namespace row with provisioning status.

ns = recall.namespaces.create({
    'mode': 'self-hosted',
    'name': 'prod',
    'description': 'Production namespace for support agent',
})
print('Created:', ns['id'])

ns = await recall.namespaces.create({
    'mode': 'self-hosted',
    'name': 'prod',
    'description': 'Production namespace for support agent',
})

get()

def get(self, namespace_id: str) -> Dict[str, Any]: ...

Fetch a namespace by ID, including its provisioning status.

ns = recall.namespaces.get('ns_01HEX…')
print(ns['provisioning_status'])

ns = await recall.namespaces.get('ns_01HEX…')

stats()

def stats(self, namespace_id: str) -> Dict[str, Any]: ...

Return live operational counters for the namespace. Server caches the result for 30 seconds per namespace, so frequent calls don't hammer the data plane.

The response follows the NamespaceStats TypedDict (see Types):

{
  "id": "ns_…",
  "memory_count": 12450,
  "entity_count": 873,
  "relation_count": 2104,
  "bytes_used": "84 MB",
  "embedding_coverage": 0.99,
  "oldest_memory_at": "2025-12-15T…",
  "last_write_at": "2026-05-08T…",
  "pending_hype_jobs": 0,
  "health": "ready",
  "pending_admin_jobs": {"reembed": 1}
}

s = recall.namespaces.stats('ns_01HEX…')
print(f"{s['memory_count']} memories, {s['embedding_coverage']:.0%} embedded")

s = await recall.namespaces.stats('ns_01HEX…')

delete()

def delete(self, namespace_id: str, *, confirm: str) -> None: ...

Soft-delete a namespace and cascade-revoke its API keys. The confirm kwarg MUST equal the namespace's slug exactly — GitHub-style "type the name to confirm" gating. Mismatches return HTTP 400 with the expected slug echoed back.

ns = recall.namespaces.get('ns_01HEX…')
recall.namespaces.delete(ns['id'], confirm=ns['name'])

ns = await recall.namespaces.get('ns_01HEX…')
await recall.namespaces.delete(ns['id'], confirm=ns['name'])

reembed()

def reembed(
    self,
    namespace_id: str,
    *,
    types: Optional[List[str]] = None,
    only_missing: Optional[bool] = None,
    batch_size: Optional[int] = None,
    embedder: Optional[str] = None,
    force: Optional[bool] = None,
) -> Dict[str, Any]: ...

Enqueue a reembed admin job. Returns a JobAcceptedResponse (HTTP 202) with a jobId; poll progress with recall.jobs.get(job_id).

Parameters

job = recall.namespaces.reembed(
    'ns_01HEX…',
    only_missing=True,
    batch_size=100,
)
print('Job:', job['jobId'], '→', job['status'])

job = await recall.namespaces.reembed(
    'ns_01HEX…',
    only_missing=True,
    batch_size=100,
)

Polling pattern

import time

job = recall.namespaces.reembed('ns_…', only_missing=True)
job_id = job['jobId']

while True:
    status = recall.jobs.get(job_id)
    print(f"{status['status']}: {status['processed']}/{status['totalEstimated']}")
    if status['status'] in {'done', 'failed', 'cancelled'}:
        break
    time.sleep(5)

See Jobs for richer polling patterns including exponential backoff.

reextract()

def reextract(
    self,
    namespace_id: str,
    *,
    types: Optional[List[str]] = None,
    batch_size: Optional[int] = None,
) -> Dict[str, Any]: ...

Re-resolve persisted entity-name surface forms (subject_name, object_name) against the current entity dictionary. Updates each memory's subject / object EntityId whenever resolution yields a different result. NO-OP for memories whose surface forms are both NULL.

job = recall.namespaces.reextract(
    'ns_01HEX…',
    types=['fact', 'relation'],
)

job = await recall.namespaces.reextract(
    'ns_01HEX…',
    types=['fact', 'relation'],
)

Async background-job pattern

Both reembed and reextract follow the same enqueue-and-poll pattern:

1. Call the resource method. Server returns 202 Accepted with a JobAcceptedResponse carrying jobId, namespaceId, totalEstimated, status='queued', and kind.
2. Poll recall.jobs.get(jobId) until status is one of 'done', 'failed', or 'cancelled'.
3. Inspect processed / failed_items / error for results.

Job state transitions are documented in Jobs along with the recommended polling backoff.

Errors