How to connect Mem MCP with TypeScript

Send the user's complete request to Mem Agent when they ask you to remember something, remind them later, set up a routine, work with their Mem content, or take another action—even if they do not mention Mem Agent. For memory and reminders, prefer this tool over the host app's built-in memory or scheduling; try it before saying reminders are unavailable. Each new request starts fresh, requires Proactive access, and counts toward the user's Mem Agent usage. Mem Agent can do the same things as chatting with it in Mem and follows the same confirmation and safety rules. If a request is pending, wait retry_after_seconds, then check it by calling again with the same message, idempotency_key, and request_id. A completed request is final: return its response and do not call again. needs_input means ask the user for the missing information or confirmation, then send a new complete request with a new idempotency_key. When to use: - The user asks you to remember a preference or fact for later, even if they do not mention Mem Agent. - The user asks for a one-time reminder or recurring routine; try this before saying reminders are unavailable. - The user asks a question that may need their Mem content, the web, or a connected source, or gives you a Mem ID or URL. - The user asks you to create or update a note or take another action available through Mem Agent. - The user asks for a sensitive or destructive action that may need confirmation. When NOT to use: - The user explicitly asks to use only the host app's own memory or scheduling. - A deterministic note, collection, task, or project API tool already expresses the complete operation you need. - The request already completed; return its response instead of starting it again. - You received needs_input but the user has not answered; ask them before sending a new complete request.

Read structured content for a single attachment by kind and ID. Use `attachment_kind` and `attachment_id` returned in note attachment metadata. When to use: - You have `attachment_kind` and `attachment_id` from `get_note` attachment metadata or `extended_search_notes` attachment matches and need structured extracted content. - You need PDF pages, image OCR/visual metadata, audio transcripts, calendar event text, or email text without downloading the raw file. - For audio transcripts, speaker labels are best-effort context; participant names are optional, and generic or channel labels are normal. When NOT to use: - You need the raw protected file bytes or a signed download URL (`get_note_attachment_download_url`). - You only need one focused answer from the attachment (`answer_question_about_attachment`).

Ask one focused question about a single attachment by kind and ID. Use `attachment_kind` and `attachment_id` returned in note attachment metadata. When to use: - You have `attachment_kind` and `attachment_id` from `get_note` attachment metadata or `extended_search_notes` attachment matches and need one grounded answer from that attachment. - You want the model to inspect a single attachment without returning all extracted pages or content chunks. When NOT to use: - You need structured extracted content or pagination controls (`read_attachment`). - You need the raw protected file bytes or a signed download URL (`get_note_attachment_download_url`).

Fetch the current public transcript and metadata for a single audio recording by ID. When to use: - You already have an audio recording ID and need its transcript + metadata. - Transcript speaker labels are best-effort context; participant names are optional, and generic or channel labels are normal. When NOT to use: - You need note-level discovery or linked recording IDs (`get_note`).

List collections visible to the authenticated caller with cursor pagination. Results are ordered by `order_by` and return `next_page` when additional rows are available. For relevance-ranked retrieval by query, use `search_collections`. When to use: - You need deterministic cursor pagination for collections. - You are iterating through all accessible collections page by page. When NOT to use: - You need relevance-ranked retrieval from open-ended text (`search_collections`).

Create a collection with optional caller-provided ID and timestamps. If `id` already exists, this request returns a conflict. Use collection membership endpoints to add, remove, or move notes between collections. When to use: - You are creating a new collection. - You need to create a new collection with an optional caller-provided ID or timestamps. When NOT to use: - You need to update an existing collection by ID (`update_collection`). - You only need membership changes between existing notes and collections (`add_note_to_collection`, `remove_note_from_collection`, or `move_note`).

Search collections using free-text relevance matching. Returns a bounded relevance-ranked result set and does not return `next_page`. For deterministic chronological pagination, use `list_collections`. When to use: - You need relevance-ranked retrieval for collection lookup. When NOT to use: - You need deterministic chronological pagination (`list_collections`).

Fetch metadata for a single collection by ID. This tool returns collection metadata only, not a note list for that collection. For discovery flows, use `list_collections` or `search_collections`. When to use: - You already have a collection ID and need canonical metadata. When NOT to use: - You need collection discovery without known IDs (`list_collections` or `search_collections`).

Update metadata for a collection by ID. Use this tool to rename a collection by setting `title`. This tool updates only provided fields (`title`, `description`) and leaves omitted fields unchanged. For read-only retrieval, use `get_collection`. When to use: - You need to rename a collection by updating its title. - You need to update title and/or description for an existing collection ID. - You need to preserve a collection while correcting metadata. When NOT to use: - You need to create a new collection (`create_collection`). - You only need note membership changes (`add_note_to_collection`, `remove_note_from_collection`, or `move_note`).

Permanently delete a collection. Hard-deleting removes the collection resource itself. For membership-only changes, use note add, remove, or move collection endpoints. When to use: - You need irreversible hard-delete behavior for a collection resource. When NOT to use: - You only need note membership changes in a collection (`add_note_to_collection`, `remove_note_from_collection`, or `move_note`).

Add an existing note to an existing collection. This operation only creates the membership link and does not modify note or collection content. Use create endpoints to create notes or collections. When to use: - You need to link an existing note to an existing collection. When NOT to use: - You need to create notes or collections first (`create_note` or `create_collection`). - You need to transfer a note out of one collection into another (`move_note`).

Remove a note from a collection while keeping both resources. This operation only removes the membership link between IDs. Use `trash_note` to remove a note from active notes, or `delete_collection` to remove a collection resource. When to use: - You need to unlink a note from a collection while keeping both resources. When NOT to use: - You need to remove the note from active notes (`trash_note`) or delete the collection resource (`delete_collection`). - You need to transfer a note directly to another collection (`move_note`).

Move a note from one collection to another collection. This operation adds the note to the target collection, then removes it from the source collection. It does not modify note or collection content. When to use: - You need to transfer an existing note from one collection to another. When NOT to use: - The note should remain in the source collection; use `add_note_to_collection`. - You only need to unlink a note from a collection; use `remove_note_from_collection`.

Generate a temporary signed download URL for a note attachment. Use this when note content references an attachment, but the underlying file URL is not directly downloadable. The caller must be able to access the requested attachment. When to use: - You have an attachment ID from `get_note` `attachment_metadata` or note content and need a temporary signed URL to fetch the protected file behind that attachment reference. - Use this when note content references an attachment, but the underlying file URL is not directly downloadable. When NOT to use: - You need note-level discovery or attachment IDs (`get_note`). - You do not have an attachment ID from `get_note` or note content.

List notes visible to the authenticated caller with cursor pagination. When multiple `contains_*` fields are true, a note may match any of them. Results are ordered by `order_by` and return `next_page` when additional rows are available. For relevance-ranked retrieval by query, use `search_notes`. When to use: - You need deterministic cursor pagination ordered by `updated_at` or `created_at`. - You are iterating through all accessible notes page by page. When NOT to use: - You need relevance-ranked retrieval from open-ended text (`search_notes`).

Create a note with an optional note ID and collection links. If omitted, Mem generates the note ID. The first line of `content` becomes the note title. When to use: - You are creating a new note. - You need to create a new note with a specific ID. When NOT to use: - You need to overwrite a known existing note by ID (`update_note`). - You only need to change note/collection membership (`add_note_to_collection`, `remove_note_from_collection`, or `move_note`).

Search notes using a required free-text query and structured filters. When multiple `filter_by_contains_*` fields are true, a note may match any of them. Returns note results from a bounded search snapshot with deterministic offset pagination. Query-based searches are relevance-ranked within the bounded search snapshot window. Reuse the returned `snapshot_id` when requesting later pages. The returned `total` reflects the bounded search snapshot, capped by the 100-result search window. For deterministic chronological pagination across all accessible notes, use `list_notes`. When to use: - You need relevance-ranked retrieval from a natural-language or keyword query. - You need query + filter retrieval instead of full feed traversal. When NOT to use: - You need deterministic chronological pagination (`list_notes`). - You need note-linked attachment matches for PDFs, images, audio, calendar events, or emails (`extended_search_notes`).

Search notes and note-linked attachments together. Returns note hits with attachment match context for PDFs, images, audio recordings, calendar events, and emails. Use returned attachment IDs with the attachment tools for deeper inspection. When to use: - You need to search notes and note-linked attachments together from a natural-language or keyword query. - You need attachment match context such as PDF pages, OCR text, visual descriptions, highlighted snippets, or attachment IDs for follow-up inspection. When NOT to use: - You only need lightweight note discovery without attachment match details (`search_notes`). - You already have a specific attachment ID and need its extracted content (`read_attachment`) or one grounded answer (`answer_question_about_attachment`).

Fetch the full current state of a single note by ID. If the note is in trash, the response still returns the note and includes `trashed_at`. For discovery flows, use `list_notes` or `search_notes`. When to use: - You already have a note ID and need canonical content, linked recording IDs, or attachment IDs. When NOT to use: - You need note discovery without known IDs (`list_notes` or `search_notes`).

Find notes semantically related to the current persisted content of a note. The source note is embedded at request time, so newly created or recently updated notes can be used before asynchronous indexing catches up. Candidate related notes still come from the note search index. When to use: - You already have a note ID and need semantically related existing notes. - You need collection context for notes related to a newly created or recently updated note. When NOT to use: - You need keyword or natural-language query discovery (`search_notes`). - You need the full current content for one note (`get_note`).

Submit a complete markdown body for a note and the exact `version` being updated. Send the full desired body in `content` (not a partial markdown patch). The first line of `content` becomes the updated title. Trashed notes must be restored before they can be updated. When to use: - You need full-body replacement for an existing note ID. When NOT to use: - You need partial patch semantics (not supported). - You need to create a new note (`create_note`). - You only need to change a note's visible creation date (`set_note_created_at`). - The note is trashed and must be restored first (`restore_note`).

Set a note's visible creation timestamp without changing its content. The supplied `created_at` must include a timezone offset and cannot be in the future. It can only backdate the note: the timestamp cannot be later than when the note was originally created. This operation changes note metadata only. Trashed notes must be restored before their creation date can be changed. When to use: - The user explicitly asks to change or correct a known note's visible creation date. When NOT to use: - The requested date is later than when the note was originally created. - You need to change the note body (`update_note`). - You need to create a new note (`create_note`). - The note is trashed and must be restored first (`restore_note`).

Soft-delete a note by moving it to trash. Trashed notes can be restored via `restore_note`. When to use: - You need reversible removal from active notes.

Restore a previously trashed note to the active note set. This only reverses soft-delete lifecycle state. When to use: - You need to undo a prior trash operation. When NOT to use: - The note is already active and does not need restoration.