API Documentation

Everything you need to integrate MemClaw into your agents. This page is a curated onboarding surface — for the complete, auto-generated OpenAPI reference (every parameter, schema, response code) see Swagger at /api/docs.

Looking for practical patterns instead of endpoints?

Copy-pasteable skill prompts for session continuity, decision journaling, fleet governance, and more.

Agent Skills →

Authentication

Include your API key in the X-API-Key header on every request. Pass tenant_id in the request body for writes (POST / PATCH / PUT) and as a query parameter for reads (GET / DELETE). In standalone mode (IS_STANDALONE=true) the tenant is auto-resolved and can be omitted.

API Key Header

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://memclaw.net/api/v1/health"

Endpoint Reference

Grouped by capability. All paths are under /api/v1/ except /mcp, which is mounted at the app root.

Memory

CRUD over individual memories. Writes auto-enrich (classify, title, summary, tags, embed, entity-extract, contradiction-check).

POST	/api/v1/memories	Write a single memory — LLM infers type/title/tags
POST	/api/v1/memories/bulk	Write up to 100 memories in one transaction (batched embeddings)
GET	/api/v1/memories	List memories — filter by type, status, agent; paginate
GET	/api/v1/memories/:id	Full memory detail — embedding stats, entity links, RDF triple
PATCH	/api/v1/memories/:id	Update content or metadata (re-embeds if content changes)
PATCH	/api/v1/memories/:id/status	Transition status (active → confirmed → outdated → archived)
DELETE	/api/v1/memories/:id	Soft-delete (sets status to `deleted`)
GET	/api/v1/memories/:id/contradictions	Contradiction chain — what this memory superseded and what superseded it
GET	/api/v1/memories/stats	Memory counts by type, status, agent (set include_deleted=true to also receive deleted + total_including_deleted)

Search & Recall

Hybrid semantic + keyword search with graph expansion up to 2 hops.

POST	/api/v1/search	Hybrid semantic + keyword search; supports `fleet_ids`, `status`, `valid_at`
POST	/api/v1/recall	Search + LLM summarization — returns a context paragraph plus source memories

Ingest

Two-step flow: extract atomic facts from a URL or long text (preview), then commit the selected ones.

POST	/api/v1/ingest/preview	Extract 5-20 atomic facts from URL or raw text (no writes yet)
POST	/api/v1/ingest/commit	Persist the previewed facts as memories

Knowledge Graph

Entities and relations are auto-extracted on every write. These endpoints expose the live graph.

GET	/api/v1/entities	List entities — filter by type, search by name
GET	/api/v1/entities/:id	Entity detail with relations and linked memories
POST	/api/v1/entities/upsert	Create or update an entity (merges by name + type)
POST	/api/v1/relations/upsert	Create or update a relation between two entities
GET	/api/v1/graph	Full entity + relation graph for visualization

Documents

Structured JSONB collections — use for customer records, config, task lists. Exact-match lookups, not semantic.

POST	/api/v1/documents	Upsert a structured JSON document in a named collection
GET	/api/v1/documents	List collections and recent documents
GET	/api/v1/documents/:id	Retrieve a document by collection + doc_id
POST	/api/v1/documents/query	Query documents by field equality filters with ordering and pagination
DELETE	/api/v1/documents/:id	Delete a document from a collection

Agents

Per-agent identity, trust level (0-3), and retrieval tuning. Agents auto-register on first write.

GET	/api/v1/agents	List registered agents with trust levels
GET	/api/v1/agents/:id	Single agent detail (trust, home fleet, stats)
PATCH	/api/v1/agents/:id/trust	Set trust level: 0=restricted, 1=standard, 2=cross-fleet read, 3=admin
PATCH	/api/v1/agents/:id/tune	Tune per-agent retrieval parameters (top_k, similarity, graph hops)
PATCH	/api/v1/agents/:id/fleet	Reassign an agent to a different fleet

Fleet

Fleet management + plugin heartbeat + remote command queue for OpenClaw gateway nodes.

POST	/api/v1/fleet	Create a new fleet
GET	/api/v1/fleet	List fleets for the tenant
POST	/api/v1/fleet/heartbeat	Plugin heartbeat — reports node status, returns pending commands
GET	/api/v1/fleet/nodes	List nodes reporting into the fleet (online / stale / offline)
POST	/api/v1/fleet/commands	Queue a command for a node (ping, restart, update_plugin, educate)

Karpathy Loop

Outcome-driven memory evolution — adjust weights, surface failure patterns, auto-generate preventive rules.

POST	/api/v1/insights/generate	Analyze memory store; `focus`: contradictions \| failures \| stale \| divergence \| patterns \| discover
POST	/api/v1/evolve/report	Report an outcome against recalled memories — adjusts weights, creates preventive rules on failure

Memory Crystallizer

Nightly health analysis + auto-deduplication of near-duplicate memories.

POST	/api/v1/crystallize	Trigger crystallization for the tenant now
GET	/api/v1/crystallize/latest	Most recent completed report
GET	/api/v1/crystallize/reports	List historical crystallization reports

Settings

Per-tenant provider and feature configuration. Encrypted at rest via `SETTINGS_ENCRYPTION_KEY` in production.

GET	/api/v1/settings	Current tenant settings (provider choice, feature flags, API keys)
PUT	/api/v1/settings	Update tenant settings
GET	/api/v1/settings/providers	Available LLM / embedding providers

System & Meta

Service health, version, OpenAPI, audit, and MCP transport endpoints.

GET	/api/v1/health	Liveness + DB connectivity check (no auth required)
GET	/api/v1/version	Currently-running version (no auth required)
GET	/api/v1/tool-descriptions	Canonical MCP tool descriptions (used by the plugin installer)
GET	/api/v1/audit-log	Full audit trail of writes, deletes, and admin actions
GET	/api/v1/stats	Usage stats (memory counts, per-tenant usage)
POST	/mcp	MCP Streamable HTTP endpoint — mounted at app root, NOT under /api/v1

Write Memory

Store a memory — MemClaw auto-classifies type, extracts entities, generates an embedding, and checks for contradictions. Use the bulk variant when writing more than one at a time (batches embeddings into a single API call).

Write Memory (single)

curl -X POST "https://memclaw.net/api/v1/memories" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT",
    "fleet_id": "YOUR_FLEET",
    "agent_id": "my-agent",
    "content": "The user prefers dark mode and concise responses.",
    "memory_type": "preference"
  }'

Write Memories (bulk, up to 100)

curl -X POST "https://memclaw.net/api/v1/memories/bulk" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT",
    "fleet_id": "YOUR_FLEET",
    "agent_id": "researcher-1",
    "items": [
      { "content": "Customer A uses PostgreSQL 16 in production" },
      { "content": "Customer B migrated to AlloyDB last quarter" },
      { "content": "Customer C prefers email notifications" }
    ]
  }'

Semantic Search

Hybrid semantic + keyword search with graph expansion up to 2 hops. Returns ranked results with similarity scores.

Semantic Search

curl -X POST "https://memclaw.net/api/v1/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT",
    "fleet_id": "YOUR_FLEET",
    "query": "user preferences",
    "top_k": 5
  }'

Context Recall

Recall wraps Search with an LLM summarization step — returns a concise context paragraph plus the source memories.

Context Recall (search + LLM summary)

curl -X POST "https://memclaw.net/api/v1/recall" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT",
    "fleet_id": "YOUR_FLEET",
    "query": "What are the user settings?",
    "filter_agent_id": "my-agent"
  }'

Knowledge Graph

Every write auto-extracts entities and relations. The /graph endpoint returns the full graph; individual entities carry their linked memories.

Full Graph (entities + relations)

curl "https://memclaw.net/api/v1/graph?tenant_id=YOUR_TENANT&limit=500" \
  -H "X-API-Key: YOUR_API_KEY"

Entity Detail

curl "https://memclaw.net/api/v1/entities/ENTITY_ID?tenant_id=YOUR_TENANT" \
  -H "X-API-Key: YOUR_API_KEY"

Document Store

Structured JSON collections alongside the semantic memory store — for records that need exact-field lookups (customer records, config, task lists).

Upsert Document

curl -X POST "https://memclaw.net/api/v1/documents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT",
    "collection": "customers",
    "doc_id": "acme-corp",
    "data": { "plan": "enterprise", "seats": 25 }
  }'

Query Documents

curl -X POST "https://memclaw.net/api/v1/documents/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT",
    "collection": "customers",
    "where": { "plan": "enterprise" },
    "limit": 20
  }'

Status Update

Mark memories as active, confirmed, outdated, or archived. Active memories are prioritized in search and recall.

Update Status

curl -X PATCH "https://memclaw.net/api/v1/memories/MEMORY_ID/status?tenant_id=YOUR_TENANT" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived"}'

Karpathy Loop — Report Outcome

After acting on recalled memories, report the outcome. Successful recalls get reinforced; failures auto-generate preventive rule-type memories that surface next time.

Report Outcome (Karpathy Loop)

curl -X POST "https://memclaw.net/api/v1/evolve/report" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT",
    "agent_id": "my-agent",
    "outcome": "Followed the auth pattern and it worked",
    "outcome_type": "success",
    "related_ids": ["mem_abc123"]
  }'