MemorySync

https://docs.memorysync.io
Admin
MemorySync provides persistent, user-scoped context and long-term memory for AI applications,...
Tokens:336,185
Snippets:2,985
Trust Score:4.3
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Complete async quickstart with AsyncMemorySyncClient

Source: https://docs.memorysync.io/sdks/python/async

Use this example to get started with the async client. It requires the MEMORYSYNC_API_KEY and MEMORYSYNC_PROJECT_ID environment variables, and uses an async with context manager for cleanup. The example adds a memory, queries for relevant memories, and prints the results.

```python
import asyncio
import os
from memorysync import AsyncMemorySyncClient

async def main() -> None:
    async with AsyncMemorySyncClient(
        api_key=os.environ["MEMORYSYNC_API_KEY"],
        base_url="https://api.memorysync.io",
        project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
        end_user_id="usr_7f3a9c2e",
    ) as client:
        await client.add("The user prefers weekly progress summaries.")
        response = await client.query("How often should I send updates?", k=3)
        for memory in response.memories:
            print(memory.id, memory.text)

asyncio.run(main())
```

--------------------------------

### memorysync mcp list and install examples

Source: https://docs.memorysync.io/cli

Examples of listing detected clients and installing MCP configuration for all detected clients.

```bash
memorysync mcp list
memorysync mcp install
```

--------------------------------

### Install MemorySync MCP server

Source: https://docs.memorysync.io/mcp/overview

Run this command to install the MemorySync MCP server and then restart your client. This is the quickest way to get started.

```bash
npx -y memorysync-mcp-install
```

--------------------------------

### Install MemorySync CLI

Source: https://docs.memorysync.io/getting-started/agent-signup

Install the CLI globally using npm to begin the agent setup process.

```bash
npm install -g memorysync-cli
```

--------------------------------

### memorysync get example

Source: https://docs.memorysync.io/cli

Fetches the memory with id m_60632 for user alice.

```bash
memorysync get m_60632 --user alice
```

--------------------------------

### Complete runnable example

Source: https://docs.memorysync.io/guides/livekit

A complete Python script for a LiveKit agent with MemorySyncMemory. It loads environment variables, defines an Assistant class that saves user turns to memory, and sets up an AgentSession with VAD, STT, LLM, and TTS. The memory is attached to the session to capture both roles. The entrypoint connects to the room, starts the agent, and generates a greeting. Run with `cli.run_app`.

```python
import os
from dotenv import load_dotenv
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import openai, silero
from livekit_memorysync import MemorySyncMemory

load_dotenv()

class Assistant(Agent):
    def __init__(self, memory: MemorySyncMemory) -> None:
        super().__init__(instructions=(
            "You are a warm, concise voice assistant. "
            "Use anything you remember about the caller naturally."
        ))
        self._memory = memory

    async def on_user_turn_completed(self, turn_ctx, new_message):
        await self._memory.on_user_turn(turn_ctx, new_message)

async def entrypoint(ctx: JobContext):
    await ctx.connect()

    memory = MemorySyncMemory(
        user_id="caller-42",        # your stable end-user id (see Identity)
        thread_id=ctx.room.name,    # scope the transcript to this room
    )

    session = AgentSession(
        vad=silero.VAD.load(),
        stt=openai.STT(),
        llm=openai.LLM(model="your-model"),
        tts=openai.TTS(voice="ash"),
    )
    memory.attach(session)          # capture both roles as items finalize

    await session.start(agent=Assistant(memory), room=ctx.room)
    await session.generate_reply(instructions="Greet the caller briefly.")

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

--------------------------------

### Install to Custom Profile

Source: https://docs.memorysync.io/guides/hermes-agent

Use the --target flag to install the provider into a non-standard profile directory.

```bash
npx -y memorysync-hermes install --target /path/to/profile/plugins/memorysync
```

--------------------------------

### Install livekit-memorysync

Source: https://docs.memorysync.io/guides/livekit

Installs the livekit-memorysync package.

```bash
pip install livekit-memorysync
```

--------------------------------

### Install MemorySync Provider

Source: https://docs.memorysync.io/guides/hermes-agent

Commands to install the provider and verify its status within the Hermes environment.

```bash
npx -y memorysync-hermes install
```

```bash
hermes memory setup
```

```bash
hermes memory status
```

--------------------------------

### Python SDK Example

Source: https://docs.memorysync.io/api/api-keys/test

Python SDK example for testing an API key using the ControlPlaneClient.

```APIDOC
## POST /org/api-keys/{key_id}/test

### Description
Inspect the current status and metadata of one organization API key without rotating or revealing its secret.

### Method
POST

### Endpoint
/org/api-keys/{key_id}/test

### Parameters
#### Path Parameters
- **key_id** (integer) - Required - API-key record ID. This is not the raw secret.

#### Request Body
None. Do not send a JSON body.

### Request Example
No request body.

### Response
#### Success Response (200)
- **key_id** (integer) - The API key record ID.
- **valid** (boolean) - True only when the key is active and not expired.
- **status** (string) - Status of the key (e.g., "active").
- **environment** (string) - Environment of the key (e.g., "production").
- **rate_limit_tier** (string) - Rate limit tier (e.g., "pro").
- **scopes** (array of strings) - Scopes associated with the key (e.g., ["memories:read"]).
- **project_id** (string) - Project ID associated with the key.
- **last_used_at** (string) - Timestamp of last use.
- **expires_at** (string or null) - Expiration timestamp or null.
- **expired** (boolean) - Whether the key is expired.
- **server_time** (string) - Server time.

#### Response Example
{
  "key_id": 41,
  "valid": true,
  "status": "active",
  "environment": "production",
  "rate_limit_tier": "pro",
  "scopes": ["memories:read"],
  "project_id": "project_abc123",
  "last_used_at": "2026-07-31T10:00:00Z",
  "expires_at": null,
  "expired": false,
  "server_time": "2026-08-01T12:00:00Z"
}

### Authentication
Bearer access token for an active organization member.

### Permission / Scope
`api_keys.view` capability and `admin:read` scope.

### Resource Scope
The key must belong to the caller's organization and selected project context.

### Error Handling
- 400 / 422: Correct the request - fix invalid path, query, or body fields.
- 401 / 403: Access denied - refresh authentication or verify required permission and scope.
- 404: Unavailable in scope - treat as unavailable without revealing existence.
- 429 / 5xx: Keep action recoverable - use retry metadata when present.
```

--------------------------------

### Install MemorySync and OpenAI packages

Source: https://docs.memorysync.io/guides/respan

Install the MemorySync OpenTelemetry instrumentation and the OpenAI client via pip.

```bash
pip install opentelemetry-instrumentation-memorysync openai
```

--------------------------------

### memorysync config show and use-profile examples

Source: https://docs.memorysync.io/cli

Examples of showing the active config and switching to the 'staging' profile.

```bash
memorysync config show
memorysync config use-profile staging
```

--------------------------------

### Interactive Setup Wizard

Source: https://docs.memorysync.io/guides/hermes-agent

Run the interactive wizard to configure the MemorySync provider.

```bash
hermes memory setup        # choose "memorysync", paste the key
```

--------------------------------

### Get Webhook Event Types response.json

Source: https://docs.memorysync.io/api/webhooks/manage

Example JSON response from the Get Webhook Event Types endpoint. Use this response as the canonical subscription choices.

```json
{"event_types":["memory.created","memory.updated","memory.deleted"],"categories":{"memory":["memory.created","memory.updated","memory.deleted"]}}
```

--------------------------------

### Sample 200 response for GET /memory/ontology

Source: https://docs.memorysync.io/api/memory/ontology

Example JSON response returned by the GET /memory/ontology endpoint. It lists built-in and custom content and relation types, and shows max_custom_types is 32.

```json
{"content_types":["preference","fact","behavior","intent","temporal","relationship","skill","event","other"],"relation_types":["similar","derived_from","continuation","contradiction","summary_of","detail_of","caused_by","references","supports","extends"],"builtin_content_types":["preference","fact","behavior","intent","temporal","relationship","skill","event","other"],"builtin_relation_types":["similar","derived_from","continuation","contradiction","summary_of","detail_of","caused_by","references","supports","extends"],"custom_content_types":[],"custom_relation_types":[],"max_custom_types":32}
```

--------------------------------

### memorysync init: usage examples

Source: https://docs.memorysync.io/cli

Various init invocations: default, with API key, agent mode, email claim, and email with code. Agent keys expire in 7 days unless claimed.

```bash
memorysync init
memorysync init --api-key ms_live_xxx --user alice --force
memorysync init --agent --agent-caller claude-code
memorysync init --email you@example.com
memorysync init --email you@example.com --code K7MP-3XQR
```

--------------------------------

### Install opencode-memorysync plugin

Source: https://docs.memorysync.io/guides/opencode

Adds the opencode-memorysync plugin to the global or project OpenCode configuration. OpenCode installs the plugin on next start, providing hooks, slash commands, and the MCP server.

```json
{ "plugin": ["opencode-memorysync"] }
```

--------------------------------

### memorysync add: usage examples

Source: https://docs.memorysync.io/cli

Examples of adding memories with text, stdin, and file input. Consumes plan quota add_requests.

```bash
memorysync add "Prefers TypeScript over JavaScript" --user alice
echo "Ships on Fridays" | memorysync add --user alice
memorysync add --file note.txt --user alice --wait
```

--------------------------------

### memorysync init: command syntax

Source: https://docs.memorysync.io/cli

Shows the full init command syntax with optional flags for API key, agent, email, user, project, and force. The key is stored in the OS keychain or an encrypted file, never in plain text.

```bash
memorysync init [--api-key <key> | --agent | --email <address>] [--user <id>] [--project <id>] [--force]
```

--------------------------------

### GET /api/v2/integrations/providers/notion

Source: https://docs.memorysync.io/integrations/notion

Reads the Notion provider record to check availability and capabilities before offering setup.

```APIDOC
## GET /api/v2/integrations/providers/{provider_id}

### Description
Reads the provider record for Notion to check availability and capabilities.

### Method
GET

### Endpoint
/api/v2/integrations/providers/{provider_id}

### Parameters
#### Path Parameters
- **provider_id** (string) - Required - The provider identifier (e.g., "notion").

### Authentication
- **X-API-Key** (string) - Required - API key for authentication.
- **Scope**: `integrations:read`

### Request Example
No request body required.

### Response
#### Success Response (200)
- **is_available** (boolean) - Indicates if the provider is available.
- **capabilities** (object) - Capabilities of the provider.

#### Response Example
{
  "is_available": true,
  "capabilities": {}
}
```

--------------------------------

### GET /api/v2/integrations/providers/{provider_id}

Source: https://docs.memorysync.io/integrations/onedrive

Reads the OneDrive provider record to check availability and capabilities before setup.

```APIDOC
## GET /api/v2/integrations/providers/{provider_id}

### Description
Reads the provider record for OneDrive to check availability and capabilities before setup.

### Method
GET

### Endpoint
/api/v2/integrations/providers/{provider_id}

### Parameters
#### Path Parameters
- **provider_id** (string) - Required - The provider identifier, e.g., `onedrive`.

### Request Example
```
GET /api/v2/integrations/providers/onedrive
```

### Response
#### Success Response (200)
- **is_available** (boolean) - Indicates whether the provider is available.
- **capabilities** (object) - Provider capabilities.

#### Response Example
```json
{
  "is_available": true,
  "capabilities": {}
}
```
```

--------------------------------

### memorysync init (interactive)

Source: https://docs.memorysync.io/cli

Run `memorysync init` to start interactive authentication. It asks for an API key, verifies it against the API before saving, and records a default user and project.

```bash
memorysync init
```

--------------------------------

### memorysync import examples

Source: https://docs.memorysync.io/cli

Imports memories.jsonl for user alice with dry-run, with resume, and with resume plus async and wait.

```bash
memorysync import memories.jsonl --user alice --dry-run
memorysync import memories.jsonl --user alice --resume
memorysync import memories.jsonl --user alice --resume --async --wait
```

--------------------------------

### Get Webhook Health response.json

Source: https://docs.memorysync.io/api/webhooks/manage

Example JSON response from the Get Webhook Health endpoint. Contains operational summaries such as active webhooks, delivery counts, success rate, and dead letter count.

```json
{"active_webhooks":1,"total_webhooks":1,"total_deliveries_24h":240,"success_rate_7d":99.5,"failing_endpoints":0,"pending_retries":0,"dead_letter_count":0}
```

--------------------------------

### Install MemorySync via npx

Source: https://docs.memorysync.io/guides/devin

Recommended one-command installation that writes the current Devin path and legacy Windsurf file.

```bash
# Writes the current Devin path (and the legacy Windsurf file when present):
npx memorysync-mcp-install --client devin-desktop
```

--------------------------------

### JSON: Example response for list organizations

Source: https://docs.memorysync.io/api/orgs/list

Shows the response shape of the GET /organizations endpoint. The result is an array of memberships, each with user_id, organization_id, and role.

```json
[{"user_id":42,"organization_id":7,"role":"owner"},{"user_id":42,"organization_id":12,"role":"developer"}]
```

--------------------------------

### GET /api/v2/integrations/connections/{connection_id}/slack/available-channels

Source: https://docs.memorysync.io/integrations/slack

Retrieves the list of Slack channels visible to the connected Slack installation, annotated with metadata for a picker UI. This endpoint takes no parameters and performs no ingestion.

```APIDOC
## GET /api/v2/integrations/connections/{connection_id}/slack/available-channels

### Description
Reads the channels the Slack installation can see, annotated for a picker, so a user chooses from reality rather than typing a channel name that may not exist or may not be visible to the bot. It takes no parameters and performs no ingestion.

### Method
GET

### Endpoint
/api/v2/integrations/connections/{connection_id}/slack/available-channels

### Parameters
#### Path Parameters
- **connection_id** (string) - Required - The ID of the Slack connection.

### Response
#### Success Response (200)
- **total** (number) - Total number of channels returned.
- **channels** (array) - List of channels.
  - **id** (string) - The Slack channel id.
  - **name** (string) - The Slack channel name.
  - **channel_type** (string) - What kind of channel it is.
  - **is_private** (boolean) - Whether the channel is private.
  - **is_external_shared** (boolean) - Whether the channel is externally shared.
  - **is_member** (boolean) - Whether the bot is in the channel.
  - **is_archived** (boolean) - Whether Slack has archived the channel.
  - **num_members** (number) - Number of members in the channel. May be absent.
  - **topic** (string) - Channel topic. May be absent.
  - **purpose** (string) - Channel purpose. May be absent.
  - **approved** (boolean) - Whether the channel is already selected on this connection.
  - **selectable** (boolean) - Whether the channel can be approved at all.
  - **reason** (string) - Why the channel is not selectable, when it is not.

#### Response Example
{
  "total": 2,
  "channels": [
    {
      "id": "C123456",
      "name": "general",
      "channel_type": "public",
      "is_private": false,
      "is_external_shared": false,
      "is_member": true,
      "is_archived": false,
      "num_members": 10,
      "topic": "Company updates",
      "purpose": "General discussions",
      "approved": true,
      "selectable": true,
      "reason": null
    }
  ]
}
```

--------------------------------

### Generate shell completions for bash, zsh, fish, and PowerShell

Source: https://docs.memorysync.io/cli

Install shell completions for bash, zsh, fish, or PowerShell. Start a new shell afterwards for the completions to take effect.

```bash
# bash
memorysync completion bash > /etc/bash_completion.d/memorysync

# zsh
memorysync completion zsh > "${fpath[1]}/_memorysync"

# fish
memorysync completion fish > ~/.config/fish/completions/memorysync.fish

# PowerShell — add to your profile
memorysync completion powershell | Out-String | Invoke-Expression
```

--------------------------------

### Python example: add and query

Source: https://docs.memorysync.io/advanced/overview

A working example of adding a memory with tags and source, then querying with filters and iterating over results. Use this to see the basic write/read flow in Python.

```python
write = ms.add("The user prefers concise answers.", tags=["preference"], source="chat")
result = ms.query("How should answers be formatted?", k=5, filters={"tags": ["preference"]})

for memory in result.memories:
    print(memory.id, memory.score, memory.text)
```

--------------------------------

### Current User Response JSON

Source: https://docs.memorysync.io/api/auth

Example response body for the GET /auth/me endpoint. Contains the user ID, role, organization, and session ID. OAuth identities may include additional fields.

```json
{"user_id":"usr_42","role":"developer","org":7,"sid":302}
```

--------------------------------

### Install full MemorySync plugin

Source: https://docs.memorysync.io/guides/codex

Install the recommended full plugin suite including hooks, skills, and MCP. Requires Node.js 18+ and manual approval of hooks via the /hooks command.

```bash
# Hooks + skills + MCP:
codex plugin marketplace add memorysyncio/memorysync-plugins
codex plugin add memorysync@memorysync

# Trust the hooks once (Codex reviews non-managed hooks):
#   run /hooks inside codex and approve the memorysync entries
```

--------------------------------

### Search with --json and pipe to jq

Source: https://docs.memorysync.io/cli

Use --json before the command name to get a single JSON envelope on stdout. The response always has a data array, so .data[] works for every command. This example pipes the output to jq to extract the text of each result.

```bash
memorysync --json search "preferences" --user alice | jq '.data[].text'
```

--------------------------------

### Python: Make a first request with MemorySyncClient

Source: https://docs.memorysync.io/api/overview

Initializes the MemorySyncClient with API key, base URL, project ID, and end-user ID, then adds a memory entry with tags. Requires the MEMORYSYNC_API_KEY and MEMORYSYNC_PROJECT_ID environment variables. Prints the returned result object.

```python
import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="usr_7f3a9c2e",
)

result = client.add(
    "The user prefers concise answers.",
    tags=["preference"],
)
print(result)
```

--------------------------------

### List recent import jobs with Python (GET /imports)

Source: https://docs.memorysync.io/api/memory/bulk-import

Lists recent imports, newest first, scoped to the tenant. Accepts status, limit, and offset parameters. The example uses a limit of 5 and iterates over the 'jobs' list to print job id, status, and created timestamp.

```python
import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="usr_7f3a9c2e",
)

for job in client.list_imports(limit=5)["jobs"]:
    print(job["id"], job["status"], job["created"])
```

--------------------------------

### Manual Configuration

Source: https://docs.memorysync.io/guides/hermes-agent

Manually set the provider and configure the API key and settings file.

```bash
hermes config set memory.provider memorysync
echo "MEMORYSYNC_API_KEY=ms_..." >> ~/.hermes/.env
```

```json
{
  "user_id": "alice",
  "base_url": "",
  "memory_mode": "hybrid",
  "top_k": 8,
  "prefetch_enabled": true,
  "api_timeout": 5.0
}
```

--------------------------------

### Install MemorySync plugin

Source: https://docs.memorysync.io/guides/agent-built-integrations

Install the MemorySync plugin from the marketplace, which includes the skill and docs MCP server together. The docs MCP server requires no authentication and serves documentation, not memories.

```bash
/plugin marketplace add memorysyncio/memorysync-plugins
/plugin install building-with-memorysync@memorysync
```

--------------------------------

### Install ag2-memorysync

Source: https://docs.memorysync.io/guides/ag2

Install the ag2-memorysync package from PyPI. Requires Python 3.10+ and the classic ConversableAgent framework (pip install autogen).

```bash
pip install ag2-memorysync
```
Tokens:
Raw