mem0ai--mem0/docs/api-reference/organizations-projects.mdx

---
title: Organizations & Projects
icon: "building"
description: "Manage multi-tenant applications with organization and project APIs"
---

## Overview

Organizations and projects provide multi-tenant support, access control, and team collaboration capabilities for Mem0 Platform. Use these APIs to build applications that support multiple teams, customers, or isolated environments.

<Info>
Organizations and projects are **optional** features. You can use Mem0 without them for single-user or simple multi-user applications.
</Info>

## Key Capabilities

- **Multi-org/project Support**: Organization and project are resolved automatically from your API key via `/v1/ping/`: no org or project params are accepted by `MemoryClient.__init__`. Use a project-specific API key to target a particular project.
- **Member Management**: Control access to data through organization and project membership
- **Access Control**: Only members can access memories and data within their organization/project scope
- **Team Isolation**: Maintain data separation between different teams and projects for secure collaboration

---

## Using Organizations & Projects

### Initialize with Org/Project Context

Example with the mem0 Python package:

<Tabs>
  <Tab title="Python">

```python
from mem0 import MemoryClient
client = MemoryClient(api_key="your-api-key")
```

  </Tab>

  <Tab title="Node.js">

```javascript
import { MemoryClient } from "mem0ai";
const client = new MemoryClient({ apiKey: "your-api-key" });
```

  </Tab>
</Tabs>

---

## Project Management

The Mem0 client provides comprehensive project management through the `client.project` interface:

### Get Project Details

Retrieve information about the current project:

```python
# Get all project details
project_info = client.project.get()

# Get specific fields only
project_info = client.project.get(fields=["name", "description", "custom_categories"])
```

### Create a New Project

Create a new project within your organization:

```python
# Create a project with name and description
new_project = client.project.create(
    name="My New Project",
    description="A project for managing customer support memories"
)
```

### Update Project Settings

Modify project configuration including custom instructions, categories, language preferences, retrieval criteria, and memory decay:

```python
# Update project with custom categories
client.project.update(
    custom_categories=[
        {"customer_preferences": "Customer likes, dislikes, and preferences"},
        {"support_history": "Previous support interactions and resolutions"}
    ]
)

# Update project with custom instructions
client.project.update(
    custom_instructions="..."
)

# Use the input language for memory storage and retrieval
client.project.update(multilingual=True)

# Set retrieval criteria to control which memories are surfaced in search
client.project.update(
    retrieval_criteria=[
        {"name": "relevance", "description": "How directly relevant this memory is to the current topic or user query", "weight": 3},
        {"name": "access_frequency", "description": "How often this memory has been accessed or surfaced recently", "weight": 1}
    ]
)

# Enable Memory Decay (boosts recently-accessed memories at search time)
client.project.update(decay=True)

# Update multiple settings at once
client.project.update(
    custom_instructions="...",
    custom_categories=[
        {"personal_info": "User personal information and preferences"},
        {"work_context": "Professional context and work-related information"}
    ],
    multilingual=True
)
```

#### Set Retrieval Criteria

`retrieval_criteria` is a per-project list of dictionaries (`List[Dict]`) that shapes how memories are ranked and filtered during search. Each dictionary has three fields: `name` (identifier), `description` (interpreted by the LLM to score each memory), and `weight` (relative influence on the final score). Use this to focus retrieval on intent-aligned or signal-specific memories:

```python
client.project.update(
    retrieval_criteria=[
        {
            "name": "joy",
            "description": "Measure the intensity of positive emotions such as happiness, excitement, or amusement expressed in the memory. A higher score reflects greater joy.",
            "weight": 3
        },
        {
            "name": "curiosity",
            "description": "Assess the extent to which the memory reflects inquisitiveness or interest in exploring new information. A higher score reflects stronger curiosity.",
            "weight": 2
        },
        {
            "name": "access_frequency",
            "description": "How often this memory has been accessed or surfaced recently.",
            "weight": 1
        }
    ]
)
```

Pass an empty list to clear all criteria and restore default retrieval behaviour.

#### Toggle Memory Decay

`decay` is a per-project boolean that turns on [Memory Decay](/platform/features/memory-decay): a search-time ranking bias that reinforces recently-accessed memories and gently dampens stale ones. The flag is `false` by default; set it via the same project-update endpoint:

```bash cURL
curl -X PATCH https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/ \
  -H "Authorization: Token $MEM0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decay": true}'
```

The current state is returned on every project read (and supports `?fields=decay` for a minimal response). Toggling has no effect on stored memories, only on how v3 search ranks them.

### Delete Project

<Warning>
This action will remove all memories, messages, and other related data in the project. **This operation is irreversible.**
</Warning>

Remove a project and all its associated data:

```python
# Delete the current project (irreversible)
result = client.project.delete()
```

---

## Member Management

Manage project members and their access levels:

```python
# Get all project members
members = client.project.get_members()

# Add a new member as a reader
client.project.add_member(
    email="colleague@company.com",
    role="READER"  # or "OWNER"
)

# Update a member's role
client.project.update_member(
    email="colleague@company.com",
    role="OWNER"
)

# Remove a member from the project
client.project.remove_member(email="colleague@company.com")
```

### Member Roles

| Role | Permissions |
|------|-------------|
| **READER** | Can view and search memories, but cannot modify project settings or manage members |
| **OWNER** | Full access including project modification, member management, and all reader permissions |

---

## Async Support

All project methods are available in async mode:

```python
from mem0 import AsyncMemoryClient

async def manage_project():
    client = AsyncMemoryClient(api_key="your-api-key")

    # All methods support async/await
    project_info = await client.project.get()
    await client.project.update(multilingual=True)
    members = await client.project.get_members()

# To call the async function properly
import asyncio
asyncio.run(manage_project())
```

---

## API Reference

For complete API specifications and additional endpoints, see:

<CardGroup cols={2}>
  <Card title="Organizations APIs" icon="building" href="/api-reference/organization/create-org">
    Create, get, and manage organizations
  </Card>

  <Card title="Project APIs" icon="folder" href="/api-reference/project/create-project">
    Full project CRUD and member management endpoints
  </Card>
</CardGroup>