MemClaw

https://memclaw.net/docs
Admin
MemClaw is a system providing long-term memory that persists across sessions and is shared under...
Tokens:31,711
Snippets:341
Trust Score:4.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Quickstart: Air-Gapped VM Installation

Source: https://memclaw.net/docs/getting-started/on-prem

Commands for installing MemClaw Enterprise in an air-gapped environment. First, transfer the distribution tarball to the VM, then use the airgap-load script to load images, followed by the install script with offline and license flags.

```bash
# Transfer memclaw-onprem-<version>.tar.gz to the VM (USB, SCP, etc.)
./airgap-load.sh /path/to/memclaw-onprem-<version>.tar.gz
./install.sh --offline --license /path/to/license.key
```

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

### Quickstart: Connected VM Installation

Source: https://memclaw.net/docs/getting-started/on-prem

Use this command to download and run the installation script for a connected on-premise MemClaw Enterprise environment. The script handles preflight checks, secret generation, image pulling, and stack initialization.

```bash
curl -sL https://onprem.caura.ai/install.sh | bash
```

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

### Install OpenClaw Plugin

Source: https://memclaw.net/docs/getting-started/quickstart

Run this command on the gateway host to install the OpenClaw plugin. It downloads, builds, and configures the plugin to claim the memory slot.

```bash
curl -s -H "X-API-Key: $MEMCLAW_API_KEY" \
"https://memclaw.net/api/v1/install-plugin?fleet_id=YOUR_FLEET_ID" | bash
```

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

### OpenClaw Fleet Installation Plugin

Source: https://memclaw.net/docs

Installs the MemClaw plugin for OpenClaw fleet deployments via SSH. This command handles installation, building, configuration, and setup.

```bash
# SSH into your gateway, then:

curl -s -H "X-API-Key: mc_key" \
  "https://memclaw.net/api/v1/install-plugin?fleet_id=fleet-001" | bash

# Restart OpenClaw:
openclaw gateway restart

# Installs plugin, builds, configures
# allowlist, and sets up heartbeat.
# Or use Fleet UI for point-and-click.
```

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

### Authoring Keystones with MCP

Source: https://memclaw.net/docs/integrations/per-agent-keys

Example of using the `memclaw_keystones_set` tool over MCP to author governance rules.

```APIDOC
## Authoring keystones

Use `memclaw_keystones_set` over MCP to author governance rules (keystones).

### Tool Call Example
```python
result = await session.call_tool(
    "memclaw_keystones_set",
    {
        "op": "set",
        "doc_id": "no-rollback-to-cve-versions",
        "title": "Refuse rollback to CVE versions",
        "content": "Never recommend rolling back to a version listed in any CVE entry.",
        "scope": "tenant",
        "weight": "high",
    },
)
```

### Gotchas
- `agent_id` in `memclaw_keystones_set` refers to the **TARGET** agent, not the caller. Omit for `scope=tenant` or `scope=fleet`.
- The companion read tool `memclaw_keystones` returns rules under the `rules` key.
```

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

### End-to-end Agent Provisioning and Usage

Source: https://memclaw.net/docs/integrations/per-agent-keys

A comprehensive example showing the provisioning of an agent, verification, and subsequent usage via REST API calls.

```APIDOC
## End-to-end bootstrap, one block

This sequence demonstrates provisioning an agent, verifying its key, and then using it to write a memory.

### 1. Provision Agent

Provisions an agent, its associated row, trust level, and fleet in a single call.

#### Method
POST

#### Endpoint
`/api/v1/admin/agent-keys/provision`

#### Headers
- `X-API-Key`: `$TENANT_KEY`
- `Content-Type`: `application/json`

#### Request Body
```json
{
  "agent_id": "$AGENT_ID",
  "initial_trust": 1,
  "initial_fleet": "$FLEET_ID"
}
```

**Note:** The response contains a `raw_key` which should be saved securely.

### 2. Verify Agent Key

Probes the system to verify the agent's identity using its newly provisioned key.

#### Method
GET

#### Endpoint
`/api/v1/whoami`

#### Headers
- `X-API-Key`: `$AGENT_KEY`

### 3. Use Agent to Write Memory

Writes a memory using the agent's key.

#### Method
POST

#### Endpoint
`/api/v1/memories`

#### Headers
- `X-API-Key`: `$AGENT_KEY`
- `Content-Type`: `application/json`

#### Request Body
```json
{
  "agent_id": "$AGENT_ID",
  "fleet_id": "$FLEET_ID",
  "content": "Hello world"
}
```
```

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

### Install MemClaw Plugin on OpenClaw Gateway

Source: https://memclaw.net/docs/integrations/openclaw

Use this command to automatically install the MemClaw plugin on your OpenClaw gateway host. Ensure you have your MEMCLAW_API_KEY and FLEET_ID set as environment variables.

```bash
curl -s -H "X-API-Key: $MEMCLAW_API_KEY" \
"https://memclaw.net/api/v1/install-plugin?fleet_id=$FLEET_ID" | bash
```

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

### Install MemClaw Agent Skill

Source: https://memclaw.net/docs/reference/cli

Installs the memclaw agent skill using a curl command that pipes the output to bash. The agent parameter can be set to 'both' or other supported values.

```bash
curl -s "https://memclaw.net/api/v1/install-skill?agent=both" | bash
```

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

### Public Stats Response Example

Source: https://memclaw.net/docs/api-reference/stats

Example JSON response for the public stats endpoint, showing simple counter properties.

```JSON
{
  "property1": 0,
  "property2": 0
}
```

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

### Search Documents Request Body Example (JSON)

Source: https://memclaw.net/docs/api-reference/documents-search

Example of a JSON request body for the search documents API. Specifies tenant ID and the search query.

```json
{
  "tenant_id": "string",
  "query": "string"
}
```

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

### Restart OpenClaw Gateway

Source: https://memclaw.net/docs/getting-started/quickstart

After installing the OpenClaw plugin, restart the gateway to apply the changes.

```bash
openclaw gateway restart
```

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

### Clone and Run MemClaw OSS with Docker Compose

Source: https://memclaw.net/docs/getting-started/self-host

Clone the MemClaw repository, set up your environment variables in a .env file, and start the services using Docker Compose. Ensure you configure the necessary API keys and provider settings.

```bash
git clone https://github.com/caura-ai/caura-memclaw
cd caura-memclaw
cp .env.example .env       # set IS_STANDALONE=true, EMBEDDING_PROVIDER=, ENTITY_EXTRACTION_PROVIDER=, OPENAI_API_KEY=…
docker compose up -d
```

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

### Silent/Unattended Install

Source: https://memclaw.net/docs/getting-started/on-prem

Perform a silent or unattended installation of MemClaw Enterprise by specifying configuration via CLI flags, environment variables, or a configuration file. The --non-interactive flag is used for fully automated setups.

```bash
./install.sh --config /etc/memclaw/install.conf --non-interactive
```

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

### Search Documents cURL Example

Source: https://memclaw.net/docs/api-reference/documents-search

Demonstrates how to perform a POST request to the search documents endpoint using cURL. Includes setting the API endpoint, content type, and request body.

```shell
curl -X POST "https://loading/api/v1/documents/search" \
  -H "Content-Type: application/json" \
  -d '{    "tenant_id": "string",    "query": "string"  }'
```

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

### Cross-Tenant Read Audit Event Example

Source: https://memclaw.net/docs/concepts/cross-tenant-credentials

An example of a cross_tenant_read audit event. This event is logged to the source tenant when a cross-tenant read occurs, providing details for forensic traceability.

```json
{
  "action": "cross_tenant_read",
  "tenant_id": "sibling-a",
  "agent_id": "admin-rollup-bot",
  "resource_type": "memclaw_recall",
  "detail": {
    "home_tenant_id": "admin-fleet",
    "home_agent_id": "admin-rollup-bot",
    "result_count_from_this_tenant": 7,
    "query_summary": "what did we ship last week"
  }
}
```

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

### Successful Memory Persistence Response

Source: https://memclaw.net/docs/api-reference/write

This is an example of a successful response when a memory is persisted. It includes details of the created memory and its metadata.

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "tenant_id": "string",
  "fleet_id": "string",
  "agent_id": "string",
  "memory_type": "string",
  "title": "string",
  "content": "string",
  "weight": 0,
  "source_uri": "string",
  "run_id": "string",
  "metadata": {},
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "entity_links": [],
  "similarity": 0,
  "subject_entity_id": "2f43e1a1-7cec-4ccf-9421-4ab19090ca45",
  "predicate": "string",
  "object_value": "string",
  "ts_valid_start": "2019-08-24T14:15:22Z",
  "ts_valid_end": "2019-08-24T14:15:22Z",
  "status": "active",
  "visibility": "scope_team",
  "recall_count": 0,
  "last_recalled_at": "2019-08-24T14:15:22Z",
  "supersedes_id": "8149cd94-4e90-4a99-91f5-a3e0f9b829dc",
  "superseded_by": [
    {
      "old_memory_id": "07606bd2-b9bc-468a-8200-790e8b7345cf",
      "old_status": "string",
      "reason": "string",
      "old_content_preview": "string"
    }
  ],
  "usage": {
    "memories_stored": 0,
    "memories_limit": 0,
    "writes_remaining": 0
  }
}
```

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

### List Keystones

Source: https://memclaw.net/docs/api-reference/keystones

Fetches all mandatory policy rules served to agents on session start. This endpoint is open and does not require a trust gate.

```cURL
curl -X GET "https://memclaw.net/api/v1/memclaw/keystones?tenant_id=string" \
  -H "X-API-Key: "
```

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

### Install MemClaw Skill for Claude Code

Source: https://memclaw.net/docs/integrations/claude-code

Use this curl command to install the Caura memclaw skill, which provides richer prompting capabilities for Claude Code. This command should be run in your terminal.

```bash
curl -s "https://memclaw.net/api/v1/install-skill?agent=claude-code" | bash
```

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

### Anthropic SDK - Per-Agent Key Usage

Source: https://memclaw.net/docs/integrations/per-agent-keys

Example of using the Anthropic SDK to send a message with per-agent key configuration for MemClaw.

```APIDOC
## Anthropic SDK (remote-MCP)

This example demonstrates how to configure the Anthropic SDK to use a per-agent key for MemClaw interactions.

### Usage
```python
from anthropic import Anthropic

client = Anthropic()
msg = client.messages.create(
  model="claude-opus-4-7",
  max_tokens=1024,
  messages=[{"role": "user", "content": "Save this note: pricing meets 10 May." }],
  extra_body={
      "mcp_servers": [
          {
              "type": "url",
              "url": "https://memclaw.net/mcp/",
              "name": "memclaw",
              "authorization_token": "mc_...",  # agent-scoped credential
          }
      ]
  },
)
print(msg.content)
```

The SDK forwards `authorization_token` as `Authorization: Bearer mc_…`. MemClaw recognizes that shape and resolves tenant + agent identity from it.
```

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

### cURL Example for Recall API

Source: https://memclaw.net/docs/api-reference/recall

This snippet demonstrates how to make a POST request to the /api/v1/recall endpoint using cURL. It includes the necessary headers for authorization and content type, along with a sample JSON request body.

```shell
curl -X POST "https://memclaw.net/api/v1/recall" \
  -H "X-API-Key: " \
  -H "Content-Type: application/json" \
  -d '{    "tenant_id": "string",    "query": "string"  }'
```

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

### Restart OpenClaw Gateway

Source: https://memclaw.net/docs/integrations/openclaw

After installing the MemClaw plugin, restart the OpenClaw gateway service to apply the changes. This can be done using the 'openclaw gateway restart' command or 'systemctl'.

```bash
openclaw gateway restart
```

```bash
systemctl --user restart openclaw-gateway
```

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

### Interact with MemClaw via REST API

Source: https://memclaw.net/docs/getting-started/quickstart

Use this cURL command to directly interact with the MemClaw API from any language. This example adds a memory for a specific tenant.

```bash
curl -X POST "https://memclaw.net/api/v1/memories" \
-H "X-API-Key: mc_xxx" \
-H "Content-Type: application/json" \
-d '{ "tenant_id": "YOUR_TENANT_ID", "content": "User prefers dark mode." }'
```

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

### Set Agent Keystone Rule

Source: https://memclaw.net/docs/integrations/per-agent-keys

Use the `memclaw_keystones_set` tool to author governance rules for agents. This example sets a rule to prevent rolling back to CVE versions. Note that `agent_id` is only used for `scope=agent`.

```python
result = await session.call_tool(
    "memclaw_keystones_set",
    {
        "op": "set",
        "doc_id": "no-rollback-to-cve-versions",
        "title": "Refuse rollback to CVE versions",
        "content": "Never recommend rolling back to a version listed in any CVE entry.",
        "scope": "tenant",
        "weight": "high",
    },
)
```

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

### Open an MCP session with Python

Source: https://memclaw.net/docs/integrations/per-agent-keys

This Python snippet demonstrates how to establish an MCP session using an agent-scoped credential and interact with tools. It includes error handling for tool calls.

```python
import asyncio
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
  headers = {"X-API-Key": "mc_..."}  # agent-scoped credential
  url = "https://memclaw.net/mcp/"

  async with streamablehttp_client(url, headers=headers) as (read, write, _):
      async with ClientSession(read, write) as session:
          await session.initialize()
          tools = await session.list_tools()
          print([t.name for t in tools.tools])

          result = await session.call_tool(
              "memclaw_write",
              {"content": "First memory from the Python harness."},
          )
          # Always inspect both result.isError and the content envelope.
          # Gateway-side refusals (FORBIDDEN, INVALID_ARGUMENTS, NOT_FOUND, ...)
          # arrive as isError=True with a JSON {"error":{...}} body — naive
          # clients that only check content[0].text for "id" will silently
          # treat failure as success.
          if result.isError:
              print("tool refused:", result.content[0].text)
          else:
              print(result)

asyncio.run(main())
```

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

### Configure Self-Hosted OSS Auth Modes

Source: https://memclaw.net/docs/getting-started/quickstart

Set up authentication for self-hosted MemClaw OSS by configuring the .env file. Choose between single-tenant, multi-tenant with an admin key, or a shared gateway with a specific API key.

```env
# Single-tenant, no key needed
IS_STANDALONE=true

# Or: multi-tenant, full access
ADMIN_API_KEY=admin_xxx

# Or: shared gate (key + X-Tenant-ID header)
MEMCLAW_API_KEY=mc_xxx
```

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

### Mint Cross-Tenant Credential via API

Source: https://memclaw.net/docs/concepts/cross-tenant-credentials

Use this API call to mint a cross-tenant credential. Set `read_all_org_tenants` to true for live resolution of all tenants, or use `source_tenant_ids` for a static list.

```bash
curl -X POST "https://memclaw.net/api/v1/admin/orgs/$ORG_ID/api-credentials" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{ 
    "kind": "cross_tenant",
    "home_tenant_id": "admin-fleet",
    "read_all_org_tenants": true,
    "label": "org-admin-summary-agent",
    "capabilities": ["read", "write"]
  }'
```

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

### End-to-End Agent Provisioning and Usage

Source: https://memclaw.net/docs/integrations/per-agent-keys

This script provisions a new agent, sets its initial trust and fleet, verifies its identity, and then uses it to write a memory. It combines multiple API calls into a single, atomic operation.

```bash
TENANT_KEY=mc_...
AGENT_ID="quote-agent-na"
FLEET_ID="na-sales"

# 1. Provision agent + Agent row + trust + fleet in one call.
RESP=$(curl -s -X POST "https://memclaw.net/api/v1/admin/agent-keys/provision" \
-H "X-API-Key: $TENANT_KEY" \
-H "Content-Type: application/json" \
-d "{\"agent_id\":\"$AGENT_ID\",\"initial_trust\":1,\"initial_fleet\":\"$FLEET_ID\"}")
AGENT_KEY=$(echo "$RESP" | python3 -c "import json,sys; print(json.load(sys.stdin)['raw_key'])")

# 2. Verify.
curl -s "https://memclaw.net/api/v1/whoami" -H "X-API-Key: $AGENT_KEY"

# 3. Use.
curl -s "https://memclaw.net/api/v1/memories" \
-H "X-API-Key: $AGENT_KEY" \
-H "Content-Type: application/json" \
-d "{\"agent_id\":\"$AGENT_ID\",\"fleet_id\":\"$FLEET_ID\",\"content\":\"Hello world\"}"
```

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

### MemClaw CLI Tools Overview

Source: https://memclaw.net/docs

A list of available MemClaw command-line interface tools for managing and interacting with the shared memory.

```text
memclaw_write          Store content (single or batch)
memclaw_recall         Semantic + keyword hybrid search
memclaw_list           Browse by metadata (non-semantic)
memclaw_manage         Read / update / transition / delete
memclaw_doc            Structured document CRUD
memclaw_entity_get     Entity with relations
memclaw_tune           Per-agent retrieval tuning
memclaw_insights       Reflect over memory store
memclaw_evolve         Report outcomes, close the loop
memclaw_stats          Aggregate counts (total / by type / agent / status)
memclaw_keystones      Fetch scope-merged keystone rules (tenant / fleet / agent)
memclaw_keystones_set  Author or remove a keystone rule (trust >= 2)
```

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

### GET /api/v1/health

Source: https://memclaw.net/docs/api-reference/health

Checks the liveness of the MemClaw service.

```APIDOC
## GET /api/v1/health

### Description
 liveness probe.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
`null`

### Request Example
```curl
curl -X GET "https://memclaw.net/api/v1/health"
```
```

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

### Get Public Stats (Unauthenticated)

Source: https://memclaw.net/docs/api-reference/stats

A lightweight endpoint for unauthenticated access to public counters, suitable for status bars.

```cURL
curl -X GET "https://loading/api/v1/stats"
```

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

### Discover Skills with memclaw_doc op=search

Source: https://memclaw.net/docs/skills

Use `memclaw_doc op=search` to find skills based on a natural language query. Search ranks results by semantic similarity to the `data.summary` field.

```python
result = await session.call_tool(
    "memclaw_doc",
    {
        "op": "search",
        "collection": "skills",
        "query": "what to do when a customer asks for an old version",
        "top_k": 5,
    },
)

```

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

### Get Memory Stats (Authenticated)

Source: https://memclaw.net/docs/api-reference/stats

Use this endpoint to retrieve aggregate memory counts. Requires API key authentication.

```cURL
curl -X GET "https://loading/api/v1/memories/stats"
```

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

### Share Skills

Source: https://memclaw.net/docs/agents.md

Share skills by writing them as documents in the `skills` collection using `memclaw_doc`. The `doc_id` must be a filesystem-safe slug.

```bash
# Share — slug is `[a-z0-9][a-z0-9._-]{0,99}` (filesystem-safe)
memclaw_doc op=write collection=skills doc_id=<slug> \
  data={ "name": "<slug>", "summary": "<one-liner>", "content": "<full SKILL.md>" }
```

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

### Keystones

Source: https://memclaw.net/docs/api-reference

Manage keystones.

```APIDOC
## GET /api/v1/memclaw/keystones

### Description
Retrieve keystones.

### Method
GET

### Endpoint
/api/v1/memclaw/keystones
```

```APIDOC
## POST /api/v1/memclaw/keystones

### Description
Create a keystone.

### Method
POST

### Endpoint
/api/v1/memclaw/keystones
```

```APIDOC
## DELETE /api/v1/memclaw/keystones

### Description
Delete a keystone.

### Method
DELETE

### Endpoint
/api/v1/memclaw/keystones
```

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

### Keystone Rules Response Shape

Source: https://memclaw.net/docs/concepts/keystones

The structure returned by `memclaw_keystones` and the GET API endpoint. Note that the merged rules are under the `rules` field for backward compatibility.

```json
{
  "count": 3,
  "truncated": false,
  "rules": [
    { "doc_id": "...", "title": "...", "content": "...", "scope": "tenant", "weight": "high", ... }
  ]
}
```

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

### Provision Agent-Scoped Credential

Source: https://memclaw.net/docs/getting-started/managed

Use this command to mint an agent-scoped credential, create an Agent row, set trust level, and assign a fleet in a single round trip. Save the returned `raw_key` securely.

```bash
curl -X POST https://memclaw.net/api/v1/admin/agent-keys/provision \
  -H "X-API-Key: $MC_TENANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":      "your-agent-id",
    "label":         "human-readable label",
    "initial_trust": 1,
    "initial_fleet": "your-fleet-id"
}'
```

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

### Recall API JSON Response (Success)

Source: https://memclaw.net/docs/api-reference/recall

This is an example of a successful JSON response from the Recall API, typically returning a null value when no specific data is returned in the body.

```json
null
```

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

### Create New Database Migration

Source: https://memclaw.net/docs/reference/cli

Generate a new database migration script with an autogenerated revision based on schema changes. A descriptive message is required.

```bash
docker compose run --rm core-api alembic revision --autogenerate -m "what changed"
```

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

### Run Database Migrations

Source: https://memclaw.net/docs/reference/cli

Apply all pending database migrations to the head revision. This command is executed within the Docker Compose environment.

```bash
docker compose run --rm core-api alembic upgrade head
```

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

### Discover Skills

Source: https://memclaw.net/docs/agents.md

Use `memclaw_doc` to search for skills by natural language query, browse by recency, or read a specific skill by its document ID.

```bash
# Discover
memclaw_doc op=search collection=skills query=<natural language>
memclaw_doc op=query  collection=skills              # browse by recency
memclaw_doc op=read   collection=skills doc_id=<slug>  # full body
```

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

### Skill Doc ID Slug Rules

Source: https://memclaw.net/docs/skills

Skills' `doc_id` must follow specific filesystem-safe slug rules: lowercase letters, digits, '.', '_', '-'. It must start with a letter or digit and be at most 100 characters.

```regex
^[a-z0-9][a-z0-9._-]{0,99}$
```

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

### Read a Skill

Source: https://memclaw.net/docs/agents.md

Direct-MCP clients can consume skills using this read operation. No filesystem write or plugin runtime is required.

```bash
memclaw_doc op=read collection=skills doc_id=<slug>
```

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

### Claude Desktop MCP Server Configuration

Source: https://memclaw.net/docs/integrations/claude-desktop

Add MemClaw as an MCP server by editing your Claude Desktop configuration file. Ensure to use a per-agent key for production environments.

```json
{
"mcpServers": {
  "memclaw": {
    "url": "https://memclaw.net/mcp",
    "headers": { "X-API-Key": "mc_xxx" }
  }
}
}
```

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

### Write a memory

Source: https://memclaw.net/docs/api-reference/write

Persist content for later recall using the /api/v1/memories endpoint. Requires authentication via an API key.

```APIDOC
## POST /api/v1/memories

### Description
Persist content for later recall.

### Method
POST

### Endpoint
/api/v1/memories

### Authorization
APIKeyHeader: X-API-Key <token>

### Header Parameters
- **Idempotency-Key** (string|null) - Optional

### Request Body
Content type: application/json

- **tenant_id** (string) - Required - Tenant Id
- **fleet_id** (string|null) - Optional
- **agent_id** (string) - Required - Agent Id
- **memory_type** (MemoryType|null) - Optional - Memory type. Auto-classified by LLM if omitted. Valid values: fact, episode, decision, preference, task, semantic, intention, plan, commitment, action, outcome, cancellation, rule, insight.
- **content** (string) - Required - Length 1 <= length <= 10000
- **weight** (number|null) - Optional
- **source_uri** (string|null) - Optional
- **run_id** (string|null) - Optional
- **metadata** (object|null) - Optional
- **entity_links** (array<EntityLinkIn>|null) - Optional - Default: []
- **expires_at** (string|null) - Optional
- **subject_entity_id** (string|null) - Optional
- **predicate** (string|null) - Optional
- **object_value** (string|null) - Optional
- **ts_valid_start** (string|null) - Optional
- **ts_valid_end** (string|null) - Optional
- **reference_datetime** (string|null) - Optional
- **status** (string|null) - Optional
- **visibility** (string|null) - Optional
- **persist** (Persist|null) - Optional - Default: true
- **write_mode** (string|null) - Optional

### Request Example
```json
{
  "tenant_id": "string",
  "agent_id": "string",
  "content": "string"
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the memory.
- **tenant_id** (string) - The ID of the tenant.
- **fleet_id** (string) - The ID of the fleet.
- **agent_id** (string) - The ID of the agent.
- **memory_type** (string) - The type of memory.
- **title** (string) - The title of the memory.
- **content** (string) - The content of the memory.
- **weight** (number) - The weight of the memory.
- **source_uri** (string) - The URI of the source.
- **run_id** (string) - The ID of the run.
- **metadata** (object) - Additional metadata.
- **created_at** (string) - The timestamp when the memory was created.
- **expires_at** (string) - The timestamp when the memory expires.
- **entity_links** (array) - Links to entities.
- **similarity** (number) - The similarity score.
- **subject_entity_id** (string) - The ID of the subject entity.
- **predicate** (string) - The predicate.
- **object_value** (string) - The object value.
- **ts_valid_start** (string) - The start timestamp of validity.
- **ts_valid_end** (string) - The end timestamp of validity.
- **status** (string) - The status of the memory.
- **visibility** (string) - The visibility of the memory.
- **recall_count** (number) - The number of times the memory has been recalled.
- **last_recalled_at** (string) - The timestamp of the last recall.
- **supersedes_id** (string) - The ID of the memory that this memory supersedes.
- **superseded_by** (array) - Information about memories that supersede this memory.
- **usage** (object) - Usage statistics.

#### Response Example
```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "tenant_id": "string",
  "fleet_id": "string",
  "agent_id": "string",
  "memory_type": "string",
  "title": "string",
  "content": "string",
  "weight": 0,
  "source_uri": "string",
  "run_id": "string",
  "metadata": {},
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "entity_links": [],
  "similarity": 0,
  "subject_entity_id": "2f43e1a1-7cec-4ccf-9421-4ab19090ca45",
  "predicate": "string",
  "object_value": "string",
  "ts_valid_start": "2019-08-24T14:15:22Z",
  "ts_valid_end": "2019-08-24T14:15:22Z",
  "status": "active",
  "visibility": "scope_team",
  "recall_count": 0,
  "last_recalled_at": "2019-08-24T14:15:22Z",
  "supersedes_id": "8149cd94-4e90-4a99-91f5-a3e0f9b829dc",
  "superseded_by": [
    {
      "old_memory_id": "07606bd2-b9bc-468a-8200-790e8b7345cf",
      "old_status": "string",
      "reason": "string",
      "old_content_preview": "string"
    }
  ],
  "usage": {
    "memories_stored": 0,
    "memories_limit": 0,
    "writes_remaining": 0
  }
}
```

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```
```

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

### Write a Memory

Source: https://memclaw.net/docs/getting-started/first-write

Use this endpoint to write a new memory. Include tenant ID, agent ID, and the content of the memory. The response shape is defined in the OpenAPI spec.

```bash
curl -X POST "https://memclaw.net/api/v1/memories" \
-H "X-API-Key: mc_xxx" \
-H "Content-Type: application/json" \
-d '{ \
  "tenant_id": "YOUR_TENANT_ID", \
  "agent_id": "my-agent", \
  "content": "The user prefers concise answers and dark mode." \
}'
```

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

### Export Memories via REST API

Source: https://memclaw.net/docs/getting-started/delete-organization

Use this cURL command to export memories from a tenant before deleting your organization. Repeat for each tenant if necessary.

```bash
curl https://memclaw.net/api/v1/memories?tenant_id=YOUR_TENANT_ID \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" > memclaw-export.json
```

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

### Write a memory

Source: https://memclaw.net/docs/api-reference

Persist content for later recall.

```APIDOC
## POST /api/v1/memories

### Description
Persist content for later recall.

### Method
POST

### Endpoint
/api/v1/memories
```

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

### Mint an agent-scoped credential

Source: https://memclaw.net/docs/integrations/per-agent-keys

Use this endpoint to mint an agent-scoped credential and create the Agent row in a single API call. Save the raw_key immediately as it's only returned once.

```bash
curl -X POST "https://memclaw.net/api/v1/admin/agent-keys/provision" \
-H "X-API-Key: $MC_TENANT_KEY" \
-H "Content-Type: application/json" \
-d '{
  "agent_id": "quote-agent-na",
  "label": "north-america CRM",
  "initial_trust": 1,
  "initial_fleet": "na-sales"
}'
```

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

### Agent-facing tools for Keystones

Source: https://memclaw.net/docs/concepts/keystones

These are the tools agents can use to interact with keystones. `memclaw_keystones` is for reading rules, while `memclaw_keystones_set` handles upserting and deleting rules.

```APIDOC
## Agent-facing tools

Tool| Op| Trust| Purpose  
---|---|---|---
`memclaw_keystones`| (read-only)| ≥ 0| List scope-merged keystone rules. Call once per session.  
`memclaw_keystones_set`| `set`| ≥ 1 (self) / ≥ 2 (other)| Upsert a keystone by `doc_id`.  
`memclaw_keystones_set`| `delete`| ≥ 1 (self) / ≥ 2 (other)| Remove a keystone by `doc_id`.  
```

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

### Configure Entity Extraction Provider

Source: https://memclaw.net/docs/concepts/memory-pipeline

Specify the provider for entity extraction and classification. Options include 'openai', 'anthropic', 'gemini', and 'openrouter'.

```env
ENTITY_EXTRACTION_PROVIDER=openai
```

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

### Configure MemClaw MCP Server

Source: https://memclaw.net/docs/integrations/claude-code

Add this .mcp.json configuration to your repo root or global Claude Code settings to enable MemClaw integration. Restart Claude Code after adding the configuration.

```json
{
  "mcpServers": {
    "memclaw": {
      "url": "https://memclaw.net/mcp",
      "headers": { "X-API-Key": "mc_xxx" }
    }
  }
}
```

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

### List Document Collections

Source: https://memclaw.net/docs/api-reference/documents-collections

Use this endpoint to list all document collections within a specified tenant. Requires an API key for authorization.

```curl
curl -X GET "https://loading/api/v1/documents/collections?tenant_id=string"
```

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

### Open an MCP session

Source: https://memclaw.net/docs/integrations/per-agent-keys

Establishes an MCP (MemClaw Communication Protocol) session using streamable HTTP. This allows for interactive communication with MemClaw services.

```APIDOC
## MCP Session Establishment

### Description
MemClaw speaks MCP streamable-http at `/mcp`. This endpoint allows for establishing a communication session using agent-scoped credentials.

### Method
Any HTTP method can be used to initiate the stream, but the communication protocol itself is MCP.

### Endpoint
/mcp or /mcp/

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Use if you control the request shape. The agent-scoped credential key (`mc_...`).
- **Authorization** (string) - Required - Use for SDKs that only emit `Authorization` headers. Format: `Bearer mc_...` (for agent-scoped credentials) or `Bearer <jwt>` (for dashboard-issued JWTs).

### Request Example (Python using `mcp` library)
```python
import asyncio
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
  headers = {"X-API-Key": "mc_..."}  # agent-scoped credential
  url = "https://memclaw.net/mcp/"

  async with streamablehttp_client(url, headers=headers) as (read, write, _):
      async with ClientSession(read, write) as session:
          await session.initialize()
          tools = await session.list_tools()
          print([t.name for t in tools.tools])

          result = await session.call_tool(
              "memclaw_write",
              {"content": "First memory from the Python harness."},
          )
          if result.isError:
              print("tool refused:", result.content[0].text)
          else:
              print(result)

asyncio.run(main())
```

### Response
Communication is stream-based. The server responds with MCP messages. Success involves receiving tool descriptions and results. Errors are indicated within the content envelope with `isError=True`.
```

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

### Author a Skill with memclaw_doc op=write

Source: https://memclaw.net/docs/skills

Use `memclaw_doc op=write` to publish a skill to the 'skills' collection. The `data.summary` field is crucial for semantic search discovery. Ensure `doc_id` adheres to filesystem-safe slug rules.

```python
result = await session.call_tool(
    "memclaw_doc",
    {
        "op": "write",
        "collection": "skills",
        "doc_id": "triage-cve-rollback-request",
        "data": {
            "summary": (
                "Triage a customer asking to roll back to an older "
                "version: check the CVE list, refuse versions with "
                "active advisories, suggest the nearest safe build."
            ),
            "steps": [
                "Identify the requested target version.",
                "Search the kb collection for matching CVE advisories.",
                "If a match is found, refuse the rollback and cite the advisory.",
                "Otherwise, suggest the nearest patched build.",
            ],
            "owner_agent": "support-admin",
        },
    },
)

```

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

### Retrieving Crystallization Reports

Source: https://memclaw.net/docs/concepts/governance

Fetch reports on the Memory Crystallizer process or the latest crystallization report using the provided REST API endpoints.

```bash
GET /api/v1/crystallize/reports
GET /api/v1/crystallize/latest
```

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

### Regenerate OpenAPI Spec Locally

Source: https://memclaw.net/docs/api-reference

Use these commands to regenerate the OpenAPI specification locally. Ensure the API_BASE_URL is set correctly for managed or self-hosted instances.

```bash
API_BASE_URL=https://memclaw.net  npm run regen:openapi   # managed
```

```bash
API_BASE_URL=http://localhost:8000 npm run regen:openapi  # self-hosted
```

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

### MCP Configuration for Any AI Client

Source: https://memclaw.net/docs

Configuration for connecting any AI client to MemClaw using the MCP protocol. Ensure your API key is correctly set.

```json
{
  "mcpServers": {
    "memclaw": {
      "url": "https://memclaw.net/mcp",
      "headers": {
        "X-API-Key": "mc_your_key"
      }
    }
  }
}
```

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

### Configure Embedding Provider

Source: https://memclaw.net/docs/concepts/memory-pipeline

Set the embedding provider and API key for vector generation. Defaults to OpenAI, with options for 'local' and 'fake' for development.

```env
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
```
Tokens:
Raw