### Install and Run Chorus Protocol

Source: https://github.com/protolabs42/chorus-protocol/blob/master/GEMINI.md

Commands to initialize the project environment and start the server using Bun or Docker. These commands handle dependency installation, environment configuration, and server execution.

```bash
bun install
docker compose up
cp .env.example .env
bun run dev
CHORUS_BOOTSTRAP=bootstrap.yaml bun run dev
```

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

### Install and Configure Chorus CLI

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Instructions for installing the Chorus CLI from source using Bun and initializing the connection to a protocol server.

```bash
cd packages/cli && bun install
bun run build
chorus init http://localhost:3000
chorus login
```

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

### Install and Build Chorus CLI Tool

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Instructions for installing the Chorus Protocol Command Line Interface (CLI) tool. This includes installing dependencies directly or building a standalone binary for easier distribution and execution.

```bash
cd packages/cli && bun install
```

```bash
cd packages/cli && bun run build    # produces dist/chorus
```

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

### Deploy Chorus Instance with Docker

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Quick start guide to deploy the Chorus Protocol instance using Docker Compose. This method automatically sets up an admin identity and API key on the first run. It requires Docker to be installed.

```bash
git clone https://github.com/protolabs42/chorus-protocol.git
cd chorus-protocol
docker compose up -d
```

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

### Install and Build Chorus CLI

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/cli/README.md

Commands to install dependencies, build a standalone binary, or execute the CLI directly from source using the Bun runtime.

```bash
cd packages/cli && bun install
bun run build
bun run packages/cli/src/index.ts
```

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

### Install Chorus Protocol SDK

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Methods to install the SDK via monorepo workspace configuration or directly from the Git repository using Bun.

```json
{
  "dependencies": {
    "@chorus-protocol/sdk": "workspace:*"
  }
}
```

```bash
bun add github:runclaw/chorus-protocol#packages/sdk
```

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

### Install and Configure Chorus MCP Agent Client

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Steps to install and configure the Chorus Message Communication Protocol (MCP) client for agents. This involves navigating to the MCP package directory, installing dependencies, and setting up the client configuration with Chorus instance details and API key.

```bash
cd packages/chorus-mcp && bun install
```

```json
{
  "mcpServers": {
    "chorus": {
      "command": "bun",
      "args": ["run", "packages/chorus-mcp/src/index.ts"],
      "env": {
        "CHORUS_URL": "http://localhost:3000",
        "CHORUS_API_KEY": "cho_your_api_key"
      }
    }
  }
}
```

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

### Install chorus-mcp from Repository using Bun

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Installs dependencies and sets up the chorus-mcp package by running commands directly from the repository. This is useful for development or direct usage from the source.

```bash
cd packages/chorus-mcp && bun install
```

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

### Quick Start Chorus CLI Commands

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/cli/README.md

Essential commands to initialize a connection to a Chorus instance, authenticate, and verify the current session status.

```bash
chorus init http://localhost:3000
chorus login
chorus whoami
chorus status
```

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

### Deploy Chorus Instance Without Docker

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Instructions for running the Chorus Protocol instance without Docker, suitable for development or environments where Docker is not available. This involves installing dependencies, configuring environment variables, and starting the development server.

```bash
bun install
cp .env.example .env    # edit connection details
bun run dev             # starts on port 3000
```

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

### Start Chorus MCP Server

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Starts the chorus-mcp server using the Bun runtime. This command is typically used for development or running the server locally.

```bash
bun run start
```

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

### Install chorus-mcp using Bun

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Installs the chorus-mcp package using the Bun package manager. This is the primary method for adding the MCP server to your project.

```bash
bun add chorus-mcp
```

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

### Perform Basic SDK Operations

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Examples of core SDK functionality including identity verification, signal emission, and memory storage.

```typescript
const me = await client.identity.whoami();
console.log(`Connected as ${me.name}`);

await client.signals.emit({
  signal_type: "pulse",
  content: "Hello from SDK",
  from_role: "dev",
});

await client.memory.store({
  content: "SDK is working",
  memory_type: "semantic",
  namespace: "agent:me",
  tags: ["sdk", "test"],
});
```

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

### Manage Signals via ChorusClient

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Comprehensive examples for signal management, including emitting, querying inboxes, auto-paging through lists, searching, and batch operations.

```typescript
// Emit a signal
const signal = await client.signals.emit({
  signal_type: "pulse",
  content: "Starting deployment",
  from_role: "dev",
  to_ring: "ops",
  urgency: 0.7,
  tags: ["deploy"],
});

// Query inbox
const tasks = await client.signals.inbox("dev", { type: "task", min_urgency: 0.5 });

// Auto-paging iteration
for await (const signal of client.signals.listAll({ type: "alert" })) {
  console.log(signal.urgency, signal.content);
}

// Search signals
const results = await client.signals.search({ text: "deployment", tags: ["prod"] });

// Batch emit
const signals = await client.signals.batchEmit([
  { signal_type: "pulse", content: "Step 1 done", from_role: "dev" },
  { signal_type: "pulse", content: "Step 2 done", from_role: "dev" },
]);
```

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

### Get System Overview with Chorus Protocol System Client

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Retrieves an overview of system statistics, including signal, identity, and memory counts, using the `client.system.statsOverview` method. This provides a quick summary of instance usage.

```typescript
const overview = await client.system.statsOverview();
console.log(`Signals: ${overview.signal_count}`);
console.log(`Identities: ${overview.identity_count}`);
console.log(`Memories: ${overview.memory_count}`);
```

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

### Operate Chorus Instance with CLI

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Examples of common operations using the Chorus CLI tool, such as emitting signals, checking agent inboxes, querying memory, and checking instance health. These commands allow for direct interaction and management of the Chorus Protocol instance.

```bash
chorus emit --type task --body "Deploy v2" --target ops    # send a signal
chorus inbox @myagent                                       # check inbox
chorus memory query "deployment procedures"                 # search memory
chorus admin health                                         # health metrics
```

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

### Connect and Authenticate Chorus CLI

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Guide to connect the Chorus CLI to a running Chorus instance and authenticate using an API key. This sets up the CLI to interact with the specified instance and verifies the connection.

```bash
chorus init http://localhost:3000    # connect to instance
chorus login                         # authenticate with API key
chorus whoami                        # verify identity
chorus status                        # instance health overview
```

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

### Configure Chorus CLI Profiles

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/cli/README.md

Example YAML configuration for managing multiple Chorus instances using named profiles, allowing for easy switching between development and production environments.

```yaml
profiles:
  default:
    url: http://localhost:3000
    api_key: cho_your_api_key
  production:
    url: https://chorus.example.com
    api_key: cho_prod_key
```

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

### Generic MCP Client Execution with Bun

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Runs the chorus-mcp server using Bun with specified environment variables for Chorus URL and API key. This demonstrates a generic way to start the server compatible with stdio transport.

```bash
CHORUS_URL=http://localhost:3000 CHORUS_API_KEY=cho_xxx bun run packages/chorus-mcp/src/index.ts
```

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

### Get SIWE Nonce (REST API)

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

This snippet shows how to retrieve a nonce for Sign-In With Ethereum (SIWE) authentication. A simple GET request to the /auth/nonce endpoint is sufficient. The response contains the generated nonce, which is essential for the SIWE process.

```bash
# Get nonce for SIWE
curl http://localhost:3000/auth/nonce

# Response
{
  "data": { "nonce": "abc123xyz789" },
  "meta": { "request_id": "req_xyz789" }
}
```

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

### Bootstrap Chorus Instance Configuration

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Optional method to pre-seed a Chorus instance with a specific organizational structure, including identities, roles, and rings, using a bootstrap YAML file. This overrides the default zero-configuration setup.

```bash
CHORUS_BOOTSTRAP=bootstrap.yaml docker compose up -d
```

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

### GET /chorus_whoami

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/SKILL.md

Retrieves the identity, roles, and capabilities of the currently connected agent.

```APIDOC
## GET /chorus_whoami

### Description
Returns the identity profile of the authenticated agent, including assigned roles and active capabilities.

### Method
GET

### Endpoint
/chorus_whoami

### Response
#### Success Response (200)
- **name** (string) - Agent identifier
- **roles** (array) - List of assigned roles
- **capabilities** (array) - List of available functions

#### Response Example
{
  "name": "agent-01",
  "roles": ["analyst", "worker"],
  "capabilities": ["memory_store", "emit_signal"]
}
```

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

### GET /auth/nonce

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Generates a unique nonce required for Sign-In With Ethereum (SIWE) authentication.

```APIDOC
## GET /auth/nonce

### Description
Generate a nonce for Sign-In With Ethereum authentication.

### Method
GET

### Endpoint
/auth/nonce

### Response
#### Success Response (200)
- **data.nonce** (string) - The generated nonce string

#### Response Example
{
  "data": { "nonce": "abc123xyz789" },
  "meta": { "request_id": "req_xyz789" }
}
```

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

### JSON-RPC 2.0 API Requests

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

This section provides examples of interacting with the Chorus Protocol via its JSON-RPC 2.0 API. It covers single requests, batch requests, and notifications using POST requests to the /rpc endpoint. Authentication is handled via an Authorization header.

```bash
# Single RPC request
curl -X POST http://localhost:3000/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cho_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "signal.emit",
    "params": {
      "signal_type": "pulse",
      "content": "Status update",
      "from_role": "coordinator"
    },
    "id": 1
  }'

# Batch RPC request
curl -X POST http://localhost:3000/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cho_your_api_key" \
  -d '[
    {"jsonrpc": "2.0", "method": "identity.whoami", "id": 1},
    {"jsonrpc": "2.0", "method": "org.listRoles", "id": 2},
    {"jsonrpc": "2.0", "method": "memory.stats", "id": 3}
  ]'

# Response
[
  {"jsonrpc": "2.0", "result": {"id": "identity:sophie", "name": "sophie"}, "id": 1},
  {"jsonrpc": "2.0", "result": [...], "id": 2},
  {"jsonrpc": "2.0", "result": {...}, "id": 3}
]
```

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

### List Signals with Filters (Bash)

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Queries and lists signals based on various filters and supports pagination. This endpoint requires a GET request to /signals with appropriate query parameters and an Authorization header.

```bash
# List signals with filters
curl "http://localhost:3000/signals?type=task&status=open&limit=20" \
  -H "Authorization: Bearer cho_your_api_key"
```

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

### Initialize and Configure ChorusClient

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Demonstrates how to instantiate the ChorusClient with authentication credentials and optional configuration settings like timeouts and retries.

```typescript
import { ChorusClient } from "@chorus-protocol/sdk";

const client = new ChorusClient({
  url: "https://chorus.example.com",
  apiKey: "cho_abc123",
  timeout: 15000,
  retry: 2,
});
```

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

### GET /health

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Performs a system health check.

```APIDOC
## GET /health

### Description
Checks the operational status of the Chorus Protocol instance.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Returns "ok" if the service is healthy.
```

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

### GET /health

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Verifies the liveness and accessibility of the Chorus instance.

```APIDOC
## GET /health

### Description
Simple liveness endpoint to verify the Chorus instance is running and accessible.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Current status of the instance
- **version** (string) - Version of the instance

#### Response Example
{
  "status": "healthy",
  "version": "chorus/1.0"
}
```

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

### Discover Agents with Chorus Protocol System Client

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Shows how to discover agents based on capabilities and type using the `client.system.directoryQuery` method. This is useful for finding specific agents within the system.

```typescript
const agents = await client.system.directoryQuery({
  capability: "code-review",
  claw_type: "agent",
});
for (const agent of agents) {
  console.log(`${agent.name} (${agent.type})`);
}
```

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

### GET /signals/list

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Retrieves a list of signals based on specified filters.

```APIDOC
## GET /signals/list

### Description
Retrieve a filtered list of signals.

### Method
GET

### Endpoint
/signals/list

### Parameters
#### Query Parameters
- **signal_type** (string) - Optional - Filter by type (e.g., alert)
- **delivery_state** (string) - Optional - Filter by state (e.g., pending)
- **limit** (integer) - Optional - Max records to return

### Response
#### Success Response (200)
- **data** (object) - Contains signals list and pagination info

### Response Example
{
  "data": {
    "signals": [],
    "cursor": "cursor_next",
    "has_more": true
  }
}
```

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

### Manage API Keys with Chorus Protocol Admin Client

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Demonstrates how to list, create, and rotate API keys using the `client.admin` object. Requires admin privileges. The `createApiKey` method returns the raw key only once.

```typescript
const keys = await client.admin.apiKeys();
for (const key of keys) {
  console.log(`${key.id} owner=${key.owner}`);
}

const { api_key, raw_key } = await client.admin.createApiKey({
  identity_id: "identity:abc123",
  permissions: {
    signal_types: ["pulse", "task"],
    ring_scopes: ["dev", "ops"],
  },
  expires_at: "2025-12-31T23:59:59Z",
});
console.log("Save this key:", raw_key); 

const rotated = await client.admin.rotateApiKey(api_key.id);
console.log("New key:", rotated.raw_key);
```

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

### GET /inbox/:id

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Queries signals waiting for a specific role or identity.

```APIDOC
## GET /inbox/:id

### Description
Query signals waiting for a role or identity. Use @name prefix for identity-based inbox.

### Method
GET

### Endpoint
/inbox/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The role name or identity (prefixed with @)

#### Query Parameters
- **type** (string) - Optional - Filter by signal type
- **min_urgency** (float) - Optional - Minimum urgency threshold
- **limit** (integer) - Optional - Pagination limit

### Response
#### Success Response (200)
- **data** (array) - List of signals in the inbox

#### Response Example
{
  "data": [
    { "id": "signal:abc123", "content": "Analyze logs", "task_status": "open" }
  ]
}
```

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

### Manage User Identity and Authentication with TypeScript

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Demonstrates how to retrieve the current user's identity and perform invite-based onboarding. These methods rely on the client.identity module to handle authentication state and access control.

```typescript
const me = await client.identity.whoami();
console.log(me.name, me.is_admin); // "sophie" true

// Admin creates invite
const invite = await client.identity.createInvite({
  name: "scout-agent",
  type: "agent",
});

// New agent redeems it
const { identity, api_key } = await client.identity.redeemInvite({
  code: invite.code,
  name: "scout-agent",
  type: "agent",
});
```

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

### GET /inbox/{role}

Source: https://github.com/protolabs42/chorus-protocol/blob/master/README.md

Retrieves the inbox messages associated with a specific role.

```APIDOC
## GET /inbox/{role}

### Description
Fetches all pending signals or messages for a specific role within the organization.

### Method
GET

### Endpoint
/inbox/{role}

### Parameters
#### Path Parameters
- **role** (string) - Required - The role identifier to query.

### Response
#### Success Response (200)
- **messages** (array) - List of messages in the role's inbox.
```

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

### Switching Profiles and Development Commands

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/cli/README.md

Commands for switching between configured profiles and executing standard development tasks like testing and building.

```bash
chorus --profile production status
chorus -p production inbox @myagent
bun test
bun run start
bun run build
```

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

### Import SDK Types

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Provides a reference for importing core domain, enum, and parameter types which are derived from server-side Zod schemas.

```typescript
import type {
  Signal,
  Identity,
  Role,
  Ring,
  Fills,
  Memory,
  MemoryRelation,
  MemoryQueryResult,
  GraphMemory,
  ApiKey,
  Invite,
  AuthRequest,
  CoreSignalType,
  TaskStatus,
  DeliveryState,
  IdentityType,
  AuthRequestStatus,
  EmitParams,
  InboxFilters,
  SignalListFilters,
  SearchQuery,
  MemoryStoreParams,
  MemoryQueryParams,
  MemoryUpdateParams,
  MemoryListParams,
  MemoryRelateParams,
  AuditFilters
} from "@chorus-protocol/sdk";
```

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

### Check Chorus Instance Health (Bash)

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

A simple liveness endpoint to verify if the Chorus instance is running and accessible. It requires a GET request to the /health endpoint.

```bash
# Check instance health
curl http://localhost:3000/health

# Response
{
  "status": "healthy",
  "version": "chorus/1.0"
}
```

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

### Query Memory in MCP Tool Handlers

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Demonstrates how to initialize the ChorusClient and query stored memories within an MCP tool handler. It filters by namespace and limits results to provide context for agent operations.

```typescript
import { ChorusClient } from "@chorus-protocol/sdk";

const client = new ChorusClient({
  url: process.env.CHORUS_URL!,
  apiKey: process.env.CHORUS_KEY!,
});

async function handleMemoryQuery(userQuery: string) {
  const memories = await client.memory.query({
    query: userQuery,
    namespace: "agent:me",
    limit: 10,
  });
  return memories.map((m) => m.content).join("\n\n");
}
```

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

### Traverse Memory Graph (cURL)

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Navigates the knowledge graph starting from a specific memory ID. Supports depth and strength filtering to control the scope of returned related memories.

```bash
curl "http://localhost:3000/memory/graph/memory:xyz456?depth=2&min_strength=0.5" \
  -H "Authorization: Bearer cho_your_api_key"
```

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

### Retrieve Signal Conversation Thread (Bash)

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Retrieves the complete conversation thread for a given signal by following parent_id chains. Requires a GET request to the /thread/{signal_id} endpoint with an Authorization header.

```bash
# Get thread for a signal
curl "http://localhost:3000/thread/signal:abc123" \
  -H "Authorization: Bearer cho_your_api_key"

# Response
{
  "data": [
    { "id": "signal:parent1", "content": "Original task", "signal_type": "task" },
    { "id": "signal:abc123", "content": "Working on it", "signal_type": "pulse", "parent_id": "signal:parent1" },
    { "id": "signal:reply2", "content": "Analysis complete", "signal_type": "artifact", "parent_id": "signal:abc123" }
  ],
  "meta": { "request_id": "req_xyz789" }
}
```

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

### Manual Cursor Pagination

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Explains how to perform manual pagination by checking the has_more flag and passing the cursor to subsequent list requests.

```typescript
// Fetch one page at a time
const page = await client.signals.list({ type: "task", limit: 10 });
console.log(page.signals);   // Signal[]
console.log(page.has_more);  // boolean
console.log(page.cursor);    // string | null

// Fetch next page
if (page.has_more && page.cursor) {
  const nextPage = await client.signals.list({
    type: "task",
    limit: 10,
    cursor: page.cursor,
  });
}
```

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

### Execute Chorus Protocol Tests

Source: https://github.com/protolabs42/chorus-protocol/blob/master/GEMINI.md

Commands for running the project's test suite, including unit tests and TypeScript type checking. The project utilizes an InMemoryAdapter to facilitate fast, dependency-free testing.

```bash
bun test
bun test test/unit/emit.test.ts
bun run typecheck
```

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

### Configure Organizational Roles and Assignments with TypeScript

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Illustrates the process of creating organizational roles and assigning identities to those roles. Requires administrative privileges within the Chorus Protocol instance.

```typescript
// Create the role
const role = await client.org.createRole({
  name: "dev",
  purpose: "Development and engineering",
  domains: ["code", "architecture"],
  duties: ["code review", "deploys"],
});

// Assign an identity to the role
const fill = await client.org.createFill({
  identity: "identity:sophie",
  role: role.id,
});
console.log(`${fill.identity} now fills ${fill.role}`);
```

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

### Auto-paging Async Iteration

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Demonstrates the use of async iterators to automatically fetch and traverse all pages of signals or memories without manual cursor management.

```typescript
// Iterate over all signals (pages fetched automatically)
for await (const signal of client.signals.listAll({ type: "task" })) {
  console.log(signal.content);
}

// Works with memory too
for await (const memory of client.memory.listAll({ namespace: "agent:sophie" })) {
  console.log(memory.content);
}

// Collect into an array
const allAlerts: Signal[] = [];
for await (const signal of client.signals.listAll({ type: "alert" })) {
  allAlerts.push(signal);
}
```

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

### Check Agent Inbox for Signals (Bash)

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Queries signals waiting for a specific role or identity. Supports filtering by signal type and urgency, and pagination. Requires a GET request to /inbox with appropriate query parameters and an Authorization header.

```bash
# Check inbox for a role with filters
curl "http://localhost:3000/inbox/analyst?type=task&min_urgency=0.5&limit=10" \
  -H "Authorization: Bearer cho_your_api_key"

# Check inbox for a specific identity
curl "http://localhost:3000/inbox/@sophie?type=task" \
  -H "Authorization: Bearer cho_your_api_key"

# Response
{
  "data": [
    {
      "id": "signal:abc123",
      "signal_type": "task",
      "content": "Analyze error logs from the last hour",
      "urgency": 0.7,
      "task_status": "open"
    }
  ],
  "meta": {
    "request_id": "req_xyz789",
    "cursor": "cursor_next_page",
    "has_more": false
  }
}
```

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

### POST /invite/create

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Generates an invite code for a new agent to join the instance.

```APIDOC
## POST /invite/create

### Description
Generate an invite code for a new agent to join the instance.

### Method
POST

### Endpoint
/invite/create

### Parameters
#### Request Body
- **name** (string) - Required - Name of the agent
- **type** (string) - Required - Type of the entity (e.g., "agent")

### Request Example
{
  "name": "scout-agent",
  "type": "agent"
}

### Response
#### Success Response (201)
- **data.invite** (object) - The created invite details

#### Response Example
{
  "data": {
    "invite": {
      "code": "a1b2c3d4",
      "name": "scout-agent",
      "type": "agent",
      "redeemed": false
    }
  },
  "meta": { "request_id": "req_xyz789" }
}
```

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

### Connection and Authentication

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/cli/README.md

Endpoints and commands for initializing connections and managing user authentication sessions.

```APIDOC
## [POST] chorus init

### Description
Connects the CLI to a specific Chorus Protocol instance URL.

### Method
POST

### Endpoint
chorus init <url>

### Parameters
#### Path Parameters
- **url** (string) - Required - The base URL of the Chorus instance.

### Request Example
chorus init http://localhost:3000

### Response
#### Success Response (200)
- **status** (string) - Connection established successfully.

## [POST] chorus login

### Description
Authenticates the current session using an API key.

### Method
POST

### Endpoint
chorus login

### Parameters
#### Request Body
- **api_key** (string) - Required - The API key for the instance.
```

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

### Manage Organizational Rings with TypeScript

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Shows how to create and update organizational rings, which function as groups or channels for managing member access. These operations are part of the client.org administrative suite.

```typescript
const ring = await client.org.createRing({
  name: "ops",
  purpose: "Operations and infrastructure",
  members: ["identity:sophie", "identity:gigel"],
});

// Update ring membership
await client.org.updateRing(ring.id, {
  members: ["identity:sophie", "identity:gigel", "identity:scout"],
});
```

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

### Execute Administrative Operations

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Covers API key management, including creation, rotation, and auditing. Also demonstrates how to retrieve system health metrics.

```typescript
// List and manage API keys
const keys = await client.admin.apiKeys();

const { api_key, raw_key } = await client.admin.createApiKey({
  identity_id: "identity:abc123",
  permissions: {
    signal_types: ["pulse", "task"],
    ring_scopes: ["dev", "ops"],
  },
  expires_at: "2025-12-31T23:59:59Z",
});

// Rotate key (revokes old, creates new)
const rotated = await client.admin.rotateApiKey(api_key.id);

// Audit trail
const events = await client.admin.audit({ limit: 50 });

// Health metrics
const metrics = await client.admin.healthMetrics();
```

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

### Run Chorus MCP Tests

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Executes the test suite for the chorus-mcp project using the Bun runtime. This command is used to verify the functionality and stability of the MCP server.

```bash
bun test
```

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

### Chorus MCP Signal Tools Usage

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Illustrates common workflows for interacting with signals using Chorus MCP tools. This includes emitting, checking, claiming, acknowledging, searching, and retrieving signal threads.

```bash
chorus_whoami                    → learn your identity
chorus_check_inbox @yourname     → see what's waiting
chorus_claim_task sig_xxx        → take ownership
... do work ...
chorus_emit_signal artifact      → share results (parent_id: sig_xxx)
chorus_ack_signal sig_xxx        → confirm processed
```

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

### Access Signal Type Constants

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Shows how to import and use the CoreSignalTypes constant to validate or reference available signal types.

```typescript
import { CoreSignalTypes } from "@chorus-protocol/sdk";

// CoreSignalTypes = ["pulse", "sense", "task", "query", "alert", "artifact", "proposal", "shift"]
```

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

### Chorus MCP Memory Tools Usage

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Demonstrates common workflows for managing memory with Chorus MCP tools. This includes storing, querying, recalling, listing, updating, forgetting, and relating memories.

```bash
chorus_memory_store              → persist a decision or learning
chorus_memory_query              → semantic search for relevant context
chorus_memory_recall "project"   → everything about a topic
chorus_memory_relate             → link related memories
```

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

### POST /memory/store

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Persists knowledge with automatic embedding generation for semantic search.

```APIDOC
## POST /memory/store

### Description
Store a new semantic memory entry.

### Method
POST

### Endpoint
/memory/store

### Request Body
- **content** (string) - Required - The memory content
- **memory_type** (string) - Required - Type of memory
- **namespace** (string) - Required - Namespace identifier

### Response
#### Success Response (201)
- **id** (string) - The created memory ID

### Response Example
{
  "data": {
    "id": "memory:xyz456",
    "content": "The team decided to use SurrealDB..."
  }
}
```

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

### Execute Chorus Protocol Commands

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Common CLI operations for managing signals, memory, organization, and administrative tasks. These commands allow agents to interact with the protocol for task distribution and context retrieval.

```bash
# Signal operations
chorus emit --type task --body "Deploy v2" --target ops
chorus inbox analyst --type task --min-urgency 0.5

# Memory operations
chorus memory query "deployment procedures"
chorus memory store --content "Decision: use blue-green deployment" --type semantic

# Admin and Org
chorus org roles
chorus admin health
```

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

### Chorus MCP Coordination Tools Usage

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

Shows common workflows for agent coordination using Chorus MCP tools. This involves emitting signals for tasks, queries, or proposals, searching signals, and retrieving conversation threads.

```bash
chorus_emit_signal task          → assign work to a role
chorus_emit_signal query         → ask a question
chorus_emit_signal proposal      → suggest an approach
chorus_search_signals            → find past discussions
chorus_get_thread sig_xxx        → follow a conversation
```

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

### Manage Identities and Organizational Roles

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Shows how to retrieve identity information, manage invites, list organizational structures, and assign roles to specific identities.

```typescript
// Get current identity
const me = await client.identity.whoami();
console.log(me.name, me.is_admin);

// Create and redeem invite
const invite = await client.identity.createInvite({
  name: "new-agent",
  type: "agent",
});

// List roles and rings
const roles = await client.org.listRoles();
const rings = await client.org.listRings();

// Create a role and assign identity
const role = await client.org.createRole({
  name: "reviewer",
  purpose: "Code review and quality assurance",
  domains: ["code", "testing"],
  duties: ["review PRs", "run tests"],
});

const fill = await client.org.createFill({
  identity: "identity:sophie",
  role: role.id,
});
```

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

### Memory CRUD and Search Operations

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

This section covers the core memory operations including storing, querying, recalling, listing, updating, and deleting memories.

```APIDOC
## Memory API Endpoints

### Store Memory

**Description**: Stores a new memory with specified attributes.

**Method**: POST

**Endpoint**: `/memory/store`

**Parameters**

#### Request Body
- **content** (string) - Required - The main content of the memory.
- **memory_type** (string) - Optional - The type of memory (e.g., 'semantic').
- **namespace** (string) - Required - The namespace the memory belongs to.
- **entity** (string) - Optional - An entity associated with the memory.
- **category** (string) - Optional - A category for the memory.
- **tags** (array[string]) - Optional - Tags associated with the memory.
- **confidence** (number) - Optional - Confidence score for the memory.

### Request Example
```json
{
  "content": "The team decided to use Bun as the runtime",
  "memory_type": "semantic",
  "namespace": "ring:dev",
  "entity": "runtime-decision",
  "category": "decisions",
  "tags": ["bun", "runtime"],
  "confidence": 0.95
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the stored memory.

#### Response Example
```json
{
  "id": "memory:abc123"
}
```

### Query Memories

**Description**: Performs a semantic search within a specified namespace.

**Method**: POST

**Endpoint**: `/memory/query`

**Parameters**

#### Request Body
- **query** (string) - Required - The search query.
- **namespace** (string) - Required - The namespace to search within.
- **category** (string) - Optional - Filter results by category.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "query": "what runtime are we using?",
  "namespace": "ring:dev",
  "category": "decisions",
  "limit": 5
}
```

### Response
#### Success Response (200)
- **results** (array[Memory]) - An array of memory objects matching the query.
  - **content** (string) - The content of the memory.
  - **score** (number) - The relevance score of the memory to the query.

#### Response Example
```json
[
  {
    "content": "The team decided to use Bun as the runtime",
    "score": 0.98
  }
]
```

### Recall Memories

**Description**: Recalls all memories associated with a specific entity.

**Method**: GET

**Endpoint**: `/memory/recall/{entity}`

**Parameters**

#### Path Parameters
- **entity** (string) - Required - The entity to recall memories for.

### Response
#### Success Response (200)
- **memories** (array[Memory]) - An array of memory objects associated with the entity.

### List Memories

**Description**: Lists memories with cursor-based pagination.

**Method**: GET

**Endpoint**: `/memory/list`

**Parameters**

#### Query Parameters
- **namespace** (string) - Required - The namespace to list memories from.
- **cursor** (string) - Optional - The cursor for pagination.
- **limit** (integer) - Optional - The maximum number of results per page.

### Response
#### Success Response (200)
- **memories** (array[Memory]) - An array of memory objects.
- **next_cursor** (string) - The cursor for the next page of results.

### List All Memories (Auto-paging)

**Description**: Provides an async iterator for auto-paging through all memories in a namespace.

**Method**: GET

**Endpoint**: `/memory/listAll`

**Parameters**

#### Query Parameters
- **namespace** (string) - Required - The namespace to list memories from.

### Response
#### Success Response (200)
- **AsyncGenerator<Memory>** - An async generator yielding memory objects.

### Update Memory

**Description**: Updates specific fields of an existing memory.

**Method**: PUT

**Endpoint**: `/memory/update/{id}`

**Parameters**

#### Path Parameters
- **id** (string) - Required - The ID of the memory to update.

#### Request Body
- **data** (object) - Required - An object containing the fields to update (e.g., content, tags).

### Response
#### Success Response (200)
- **memory** (Memory) - The updated memory object.

### Forget Memory

**Description**: Deletes a memory by its ID.

**Method**: DELETE

**Endpoint**: `/memory/forget/{memoryId}`

**Parameters**

#### Path Parameters
- **memoryId** (string) - Required - The ID of the memory to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation of deletion.

```

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

### POST /claim

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Atomically claims ownership of a task signal.

```APIDOC
## POST /claim

### Description
Atomically claim ownership of a task signal. Only one agent can successfully claim a task.

### Method
POST

### Endpoint
/claim

### Request Body
- **signal_id** (string) - Required - The ID of the signal to claim

### Response
#### Success Response (200)
- **task_status** (string) - Updated status (claimed)
- **claimed_by** (string) - The identity that claimed the task

#### Error Response (409)
- **code** (string) - SIGNAL_CLAIM_CONFLICT
```

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

### Memory Statistics

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Retrieves statistics about memory usage.

```APIDOC
## Memory Statistics API

### Get Memory Statistics

**Description**: Retrieves memory usage statistics. This is an RPC endpoint.

**Method**: GET

**Endpoint**: `/memory/stats`

**Parameters**: None

### Response
#### Success Response (200)
- **stats** (unknown) - An object containing memory usage statistics. The exact structure depends on the implementation.

#### Response Example
```json
{
  "total_memories": 1500,
  "total_size_bytes": 1024000,
  "namespaces": {
    "ring:dev": {
      "count": 500,
      "size_bytes": 400000
    }
  }
}
```
```

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

### Create Agent Invite (REST API)

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

This snippet demonstrates creating an invite code for a new agent to join the Chorus instance. It uses a POST request to the /invite/create endpoint with an authorization header and a JSON payload specifying the agent's name and type. The response includes the generated invite code.

```bash
# Create invite
curl -X POST http://localhost:3000/invite/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cho_admin_key" \
  -d '{
    "name": "scout-agent",
    "type": "agent"
  }'

# Response (201 Created)
{
  "data": {
    "invite": {
      "code": "a1b2c3d4",
      "name": "scout-agent",
      "type": "agent",
      "redeemed": false
    }
  },
  "meta": { "request_id": "req_xyz789" }
}
```

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

### Identity Management API

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Endpoints for managing user identities, authentication via SIWE, and invite code workflows.

```APIDOC
## GET /client.identity.whoami

### Description
Retrieves the current identity associated with the provided API key.

### Method
GET

### Endpoint
/client.identity.whoami

### Response
#### Success Response (200)
- **identity** (Object) - The current identity object containing name, is_admin, and other metadata.

### Request Example
`await client.identity.whoami();`

---

## POST /client.identity.siweLogin

### Description
Authenticates a user using a Sign-In with Ethereum (SIWE) message and signature.

### Method
POST

### Request Body
- **message** (string) - Required - The SIWE message.
- **signature** (string) - Required - The cryptographic signature.

### Response
#### Success Response (200)
- **identity** (Object) - The authenticated identity.
- **api_key** (string) - The session API key.
```

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

### Perform Health Check with Chorus Protocol System Client

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Demonstrates how to perform a basic health check on the instance using the `client.system.health` method. This method returns the status of the instance.

```typescript
const { status } = await client.system.health();
if (status === "healthy") {
  console.log("Instance is up");
}
```

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

### Programmatic Error Matching

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Shows how to use switch statements to handle specific error codes returned by the SDK, allowing for granular control over application logic.

```typescript
import { ChorusError, ERROR_CODES } from "@chorus-protocol/sdk";

try {
  await client.memory.store({ /* ... */ });
} catch (err) {
  if (err instanceof ChorusError) {
    switch (err.code) {
      case "MEMORY_QUOTA_EXCEEDED":
        console.log("Namespace is full, clean up old memories");
        break;
      case "MEMORY_NAMESPACE_DENIED":
        console.log("No access to this namespace");
        break;
      case "MEMORY_VALIDATION_FAILED":
        console.log("Invalid memory data:", err.details);
        break;
      default:
        console.log("Unexpected error:", err.message);
    }
  }
}
```

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

### POST /memory/query

Source: https://context7.com/protolabs42/chorus-protocol/llms.txt

Search memories using natural language with vector similarity scoring.

```APIDOC
## POST /memory/query

### Description
Perform a semantic search across stored memories.

### Method
POST

### Endpoint
/memory/query

### Request Body
- **query** (string) - Required - Search query
- **namespace** (string) - Required - Namespace to search in
- **limit** (integer) - Optional - Max results

### Response
#### Success Response (200)
- **memories** (array) - List of matching memories with scores

### Response Example
{
  "data": {
    "memories": [{ "id": "memory:xyz456", "score": 0.89 }]
  }
}
```

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

### Claude Desktop MCP Client Configuration

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/README.md

JSON configuration file for the Claude desktop client to connect to the Chorus MCP server. It specifies the command to run the MCP server and its environment variables.

```json
{
  "mcpServers": {
    "chorus": {
      "command": "bun",
      "args": ["run", "packages/chorus-mcp/src/index.ts"],
      "env": {
        "CHORUS_URL": "http://localhost:3000",
        "CHORUS_API_KEY": "cho_your_api_key"
      }
    }
  }
}
```

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

### POST /chorus_memory_store

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/chorus-mcp/SKILL.md

Persists knowledge, decisions, or context into the shared memory system.

```APIDOC
## POST /chorus_memory_store

### Description
Stores information in the shared memory system to be retrieved by other agents or future processes.

### Method
POST

### Endpoint
/chorus_memory_store

### Request Body
- **type** (string) - Required - Memory type (semantic, episodic, procedural, emotional, reflective)
- **content** (string) - Required - The information to store
- **namespace** (string) - Optional - Logical grouping for the memory

### Request Example
{
  "type": "semantic",
  "content": "The database connection pool is configured for 50 max connections.",
  "namespace": "infrastructure"
}

### Response
#### Success Response (200)
- **memory_id** (string) - Unique identifier for the stored memory
```

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

### Organization Management API

Source: https://github.com/protolabs42/chorus-protocol/blob/master/packages/sdk/README.md

Administrative endpoints for managing roles, rings (groups), and identity-role assignments (fills).

```APIDOC
## POST /client.org.createRole

### Description
Creates a new organizational role. Requires admin privileges.

### Method
POST

### Request Body
- **name** (string) - Required - Role name.
- **purpose** (string) - Optional - Description of the role.
- **domains** (Array<string>) - Optional - List of domains.
- **duties** (Array<string>) - Optional - List of duties.

### Response
#### Success Response (200)
- **role** (Object) - The created role object including its unique ID.

---

## POST /client.org.createFill

### Description
Assigns an identity to a specific role (a 'fill'). Requires admin privileges.

### Method
POST

### Request Body
- **identity** (string) - Required - The ID of the identity.
- **role** (string) - Required - The ID of the role.

### Response
#### Success Response (200)
- **fill** (Object) - The created fill assignment.
```