> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Context

> Create and update context items (mgmt.context).

### ContextResource

```python
class ContextResource(http: HttpClient, config: ModusConfig)
```

Bases: `object`

Full knowledge base access for modus.management.ModusManagement.

mgmt.context.items.list() → Page\[ContextItem] mgmt.context.items.get(uid) → ContextItem mgmt.context.items.update(uid, …) → ContextItem mgmt.context.items.delete(uid) → ContextItemDeletion mgmt.context.create\_note(title, content) → CreatedContextItem mgmt.context.update\_note(uid, title=…, body=…) → ContextItem mgmt.context.create\_saved\_query(name, query, …) → CreatedContextItem mgmt.context.update\_saved\_query(uid, name=…, …) → ContextItem mgmt.context.create\_link(url, …) → CreatedContextItem mgmt.context.update\_link(uid, title=…, url=…) → ContextItem

#### create\_note()

```python
create_note(title: str, content: str) → CreatedContextItem
```

Add a free-form text note to the Modus knowledge base.

* Parameters:

  * **title** – Display title for the note.

  * **content** – Markdown body text.

* Returns:

  Created item with its new `uid`.

#### update\_note()

```python
update_note(uid: str, *, title: str, body: str, existing: ContextItemDto | None = None, description: str | None = None, user_feedback: UserFeedback | str | None = None, topics: List[str] | None = None) → ContextItemDto
```

Update a note’s title and markdown body.

Preserves server-owned fields (`noteId`, `s3Key`, …) on the existing `content` blob. Pass `existing` to skip a GET when you already have the item from a list call.

#### create\_saved\_query()

```python
create_saved_query(name: str, query: str | None = None, *, connection_id: str, description: str | None = None, path: List[str] | None = None) → CreatedContextItem
```

Save a SQL query to the Modus knowledge base.

* Parameters:

  * **name** – Display name for the saved query.

  * **query** – SQL text (optional at create if you set it later).

  * **connection\_id** – Data connection the query runs against.

  * **description** – Optional human-readable description.

  * **path** – Optional hierarchical path segments for organisation.

* Returns:

  Created item with its new `uid`.

#### update\_saved\_query()

```python
update_saved_query(uid: str, *, name: str, query: str, connection_id: str | None = None, path: List[str] | None = None, existing: ContextItemDto | None = None, description: str | None = None, user_feedback: UserFeedback | str | None = None, topics: List[str] | None = None) → ContextItemDto
```

Update a saved query’s name, SQL, and optional connection metadata.

#### create\_link()

```python
create_link(url: str, *, title: str | None = None, is_crawl: bool | None = None, page_limit: int | None = None) → CreatedContextItem
```

Add a URL to the Modus knowledge base.

* Parameters:

  * **url** – Link target URL.

  * **title** – Optional display title.

  * **is\_crawl** – When `True`, fetch and index page content.

  * **page\_limit** – Maximum pages to crawl when `is_crawl` is `True`.

* Returns:

  Created item with its new `uid`.

#### update\_link()

```python
update_link(uid: str, *, title: str | None = None, url: str | None = None, existing: ContextItemDto | None = None, description: str | None = None, user_feedback: UserFeedback | str | None = None, topics: List[str] | None = None) → ContextItemDto
```

Update link metadata on an existing item.

Merges `title` and/or `url` into the stored `content` blob. Does not re-fetch or re-crawl the URL.

### AsyncContextResource

```python
class AsyncContextResource(http: AsyncHttpClient, config: ModusConfig)
```

Bases: `object`

#### create\_note()

```python
async create_note(title: str, content: str) → CreatedContextItem
```

Add a free-form text note to the Modus knowledge base.

#### update\_note()

```python
async update_note(uid: str, *, title: str, body: str, existing: ContextItemDto | None = None, description: str | None = None, user_feedback: UserFeedback | str | None = None, topics: List[str] | None = None) → ContextItemDto
```

Update a note’s title and markdown body.

#### create\_saved\_query()

```python
async create_saved_query(name: str, query: str | None = None, *, connection_id: str, description: str | None = None, path: List[str] | None = None) → CreatedContextItem
```

Save a SQL query to the Modus knowledge base. See the sync `create_saved_query` for argument details.

#### update\_saved\_query()

```python
async update_saved_query(uid: str, *, name: str, query: str, connection_id: str | None = None, path: List[str] | None = None, existing: ContextItemDto | None = None, description: str | None = None, user_feedback: UserFeedback | str | None = None, topics: List[str] | None = None) → ContextItemDto
```

Update a saved query’s name, SQL, and optional connection metadata.

#### create\_link()

```python
async create_link(url: str, *, title: str | None = None, is_crawl: bool | None = None, page_limit: int | None = None) → CreatedContextItem
```

Add a URL to the Modus knowledge base. See the sync `create_link` for argument details.

#### update\_link()

```python
async update_link(uid: str, *, title: str | None = None, url: str | None = None, existing: ContextItemDto | None = None, description: str | None = None, user_feedback: UserFeedback | str | None = None, topics: List[str] | None = None) → ContextItemDto
```

Update link metadata on an existing item.

### ContextItemsResource

```python
class ContextItemsResource(http: HttpClient, config: ModusConfig)
```

Bases: `object`

#### list()

```python
list(*, page_size: int = 25, page_token: str | None = None, context_type: str | None = None) → Page[ContextItemDto]
```

List context items in the knowledge base.

* Parameters:

  * **page\_size** – Items per page (default 25).

  * **page\_token** – Opaque token from a previous page’s `next_page_token`.

  * **context\_type** – Filter by type, e.g. `"note"`, `"link"`, `"saved_query"`.

* Returns:

  Page of context items.

#### get()

```python
get(uid: str) → ContextItemDto
```

Retrieve a context item by its UID.

* Parameters:

  **uid** – The item’s UUID.

* Returns:

  The context item.

* Raises:

  [**NotFoundError**](<> "modus._exceptions.NotFoundError") – if no item with this UID exists.

#### update()

```python
update(uid: str, *, content: Any | None = None, context_type: str | None = None, description: str | None = None, user_feedback: UserFeedback | str | None = None, topics: List[str] | None = None, update_mask: str | None = None) → ContextItemDto
```

Update a context item.

* Parameters:

  * **uid** – UUID of the context item to update.

  * **content** – Replacement type-specific content, if changing it.

  * **context\_type** – The item’s type (e.g. `"note"`). Required when `content` is supplied.

  * **description** – New description, if changing it.

  * **user\_feedback** – Feedback verdict — `"positive"`, `"neutral"`, or `"negative"`.

  * **topics** – Replacement topic tags. Pass `[]` to clear all tags.

  * **update\_mask** – Comma-separated field names to clear. Name a field here and leave its argument unset to set it to null on the server; fields not named in the mask are left untouched.

Only the fields you pass are changed; omitted fields are left as-is.

#### delete()

```python
delete(uid: str) → DeleteContextItemResponseDto
```

Delete a context item from the knowledge base.

* Parameters:

  **uid** – The item’s UUID.

* Returns:

  Deletion confirmation with the removed item’s UID.

### CustomContextItemsResource

```python
class CustomContextItemsResource(http: HttpClient, config: ModusConfig)
```

Bases: `object`

#### list()

```python
list(*, page_size: int = 25, page_token: str | None = None, search_query: str | None = None, topics: List[str] | None = None) → Page[ContextItemDto]
```

List custom context items in the organization.

* Parameters:

  * **page\_size** – Maximum items per page.

  * **page\_token** – Cursor from a previous page.

  * **search\_query** – Optional free-text filter.

  * **topics** – Optional topic filters.

* Returns:

  A page of custom context items.

#### get()

```python
get(uid: str) → ContextItemDto
```

Fetch one custom context item by uid.

* Parameters:

  **uid** – Custom context item identifier.

* Returns:

  The matching custom context item.

#### create()

```python
create(**payload: Any) → Dict[str, Any]
```

Create a custom context item for an internal system or custom database.

#### batch\_create()

```python
batch_create(items: List[Dict[str, Any]]) → List[Dict[str, Any]]
```

Create or update a batch of custom context items by stable hierarchy.

#### update()

```python
update(uid: str, **payload: Any) → Dict[str, Any]
```

Update mutable fields on a custom context item.

* Parameters:

  * **uid** – Custom context item identifier.

  * **\*\*payload** – Fields to update, such as description or topics.

* Returns:

  The update acknowledgement payload.

#### delete()

```python
delete(uid: str) → DeleteContextItemResponseDto
```

Delete a custom context item.

* Parameters:

  **uid** – Custom context item identifier.

* Returns:

  Deletion metadata for the removed item.