# Caura Memclaw

> Governed shared memory for AI agent fleets — multi-agent, multi-tenant, MCP-native. Trust tiers, keystone policies, audit trails, knowledge graph, self-improving retrieval. Apache 2.0.

- **Type:** MCP server
- **Install:** `agentstack add mcp-caura-ai-caura-memclaw`
- **Verified:** Pending review
- **Seller:** [caura-ai](https://agentstack.voostack.com/s/caura-ai)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [caura-ai](https://github.com/caura-ai)
- **Source:** https://github.com/caura-ai/caura-memclaw
- **Website:** https://memclaw.net

## Install

```sh
agentstack add mcp-caura-ai-caura-memclaw
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Fleet memory for AI agents — governed, shared, self-improving.

  
  
  
  
  

  Quick Start ·
  Features ·
  Performance ·
  MCP ·
  API Reference ·
  Plugin Docs ·
  Contributing ·
  Discord

---

## MemClaw — Fleet memory for AI agents

MemClaw is open-source memory for **multi-tenant, multi-agent** AI fleets. Your agents store what they learn, find what the fleet knows, and get smarter with every interaction — learning from each other instead of repeating mistakes.

Agents write plain text. MemClaw turns it into searchable, governed, self-improving memory.

**One loop, three pillars: write, recall, compound** — every interaction makes the next one smarter.

**Built for fleets, not single agents.** Public agent-memory benchmarks (LoCoMo, LongMemEval) measure one agent, one user, one long conversation — the single-chatbot shape. The deployment shape we see in production is the opposite: dozens or thousands of agents working on behalf of a company, sharing what they learn under governance. MemClaw is architected around that shape from day one — scoped memory, cross-agent outcome propagation, fleet-wide trust tiers — and competes on the axes that compound with agent count: latency, token efficiency, and governance. See [Performance](#performance) for the numbers, or read the [benchmarks write-up](https://memclaw.net/blog/memclaw-benchmarks).

> **In production at eToro (NASDAQ: ETOR):** 300+ AI agents on one governed
> memory — 26,500+ memories, 1,372 shared skills, 23 ms p50 search.
> [Architecture deep-dive →](https://memclaw.net/blog/etoro-company-brain/)

  

  

---

## Quick Start

### Try it locally — no API key, no signup

The fastest way to see MemClaw work. Standalone mode runs single-tenant with auth bypassed — write and recall a memory in four commands. (It boots with dummy embeddings so there's nothing to configure; add an AI provider key for semantic search — see [Self-Hosted](#self-hosted-open-source) below.)

```bash
git clone https://github.com/caura-ai/caura-memclaw.git
cd caura-memclaw
cp .env.example .env && echo "IS_STANDALONE=true" >> .env   # single-tenant, no API key
docker compose up -d                                        # Postgres + pgvector + Redis + API (~30s)

# Write a memory — no API key needed
curl -X POST http://localhost:8000/api/v1/memories \
  -H "X-API-Key: standalone" -H "Content-Type: application/json" \
  -d '{"tenant_id": "default", "content": "Our auth service uses JWT with 15-minute expiry."}'

# Search for it
curl -X POST http://localhost:8000/api/v1/search \
  -H "X-API-Key: standalone" -H "Content-Type: application/json" \
  -d '{"tenant_id": "default", "query": "authentication token lifetime"}'
```

The write response comes back enriched with an LLM-inferred `memory_type`, `title`, `summary`, `tags`, `status`, and `weight` — all from a single `content` field.

Ready for semantic recall, multi-tenant, a managed host, or an OpenClaw fleet? Pick a path below.

---

Three paths — pick the one that matches your setup:

| Path | When | Time to first memory |
|---|---|---|
| **Managed platform** | Quickest. We host the DB + scaling. | ~2 min |
| **Self-hosted (Docker)** | Privacy / on-prem / air-gapped. | ~5 min |
| **OpenClaw plugin** | You already run an OpenClaw fleet — install MemClaw as a plugin against any of the above. | ~3 min |

### Managed Platform

Get up and running in minutes — no infrastructure, automatic updates, usage analytics, and enterprise-grade security included.

1. **[Sign up free on memclaw.net](https://memclaw.net)**
2. Grab your API key from the dashboard
3. Connect via MCP or REST:

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

> **Production / team use:** the quickstart key above is a **tenant-scoped credential** — fine for personal use, but a fleet of agents should bind each one to its own **agent-scoped credential** for trust gating, fleet membership, and per-agent keystones. Provision agent-scoped credentials atomically via [`POST /api/v1/admin/agent-keys/provision`](docs/integration-without-plugin.md), or through the dashboard at `/settings/organization/api-credentials`. Both kinds use the `mc_` prefix on the wire — scope is bound at mint time on the credential itself. The MCP server accepts the credential on either `X-API-Key: mc_…` or `Authorization: Bearer mc_…`. *(Pre-existing `mca_…` and `mci_…` keys continue to authenticate via back-compat.)*
>
> Using a tenant-scoped credential? Pass an explicit `agent_id` on every MCP tool call — the gateway refuses the reserved default (`mcp-agent`) on the tenant-scoped path.

### Self-Hosted (Open Source)

The fastest path is Docker Compose — one command brings up Postgres + pgvector + Redis + the API.

> **Prefer not to use Docker?** Skip to [Manual deployment (Python + Postgres)](#manual-deployment) below for the bare-Python path.
>
> **No cloud API key, no external calls?** v2.0+ supports a self-hosted local embedder (`BAAI/bge-m3` via HuggingFace TEI) — see [`docs/local-embedder.md`](docs/local-embedder.md). The setup below walks through the OpenAI default; the local-embedder doc walks through the alternative.

#### Prerequisites

- **Docker Engine 24+** (Linux) or **Docker Desktop** (macOS / Windows). Confirm with `docker --version`.
- **Docker Compose v2** (built into modern Docker). Confirm with `docker compose version`.
- **Git** for cloning.
- ~2 GB free disk for images + Postgres data volume.

#### 1. Clone and configure

```bash
git clone https://github.com/caura-ai/caura-memclaw.git
cd caura-memclaw
cp .env.example .env
```

Set your AI provider in `.env` — minimal setup with OpenAI:

```env
EMBEDDING_PROVIDER=openai
ENTITY_EXTRACTION_PROVIDER=openai
USE_LLM_FOR_MEMORY_CREATION=true
OPENAI_API_KEY=sk-...
```

> Without any AI keys the stack still starts — dummy providers return non-semantic embeddings, useful for testing the API surface.

> 💡 **Want zero cloud API calls?** v2.0+ ships a self-hosted embedder
> profile (`BAAI/bge-m3` on a [HuggingFace TEI](https://github.com/huggingface/text-embeddings-inference)
> sidecar). Bring up the stack with `docker compose --profile embed-local up -d`
> and set the four `OPENAI_EMBEDDING_*` envs from `.env.example` — see
> [`docs/local-embedder.md`](docs/local-embedder.md) for the full setup.
> Combined with `IS_STANDALONE=true` (below) this is a fully self-contained
> deployment with no external API calls.

Other providers (Gemini, Anthropic, OpenRouter, self-hosted)

| Provider | `.env` settings | Required key |
|---|---|---|
| **OpenAI** (default) | `EMBEDDING_PROVIDER=openai``ENTITY_EXTRACTION_PROVIDER=openai` | `OPENAI_API_KEY` |
| **Google Gemini** | `EMBEDDING_PROVIDER=openai``ENTITY_EXTRACTION_PROVIDER=gemini` | `GEMINI_API_KEY` + `OPENAI_API_KEY` |
| **Anthropic** | `EMBEDDING_PROVIDER=openai``ENTITY_EXTRACTION_PROVIDER=anthropic` | `ANTHROPIC_API_KEY` + `OPENAI_API_KEY` |
| **OpenRouter** | `EMBEDDING_PROVIDER=openai``ENTITY_EXTRACTION_PROVIDER=openrouter` | `OPENROUTER_API_KEY` + `OPENAI_API_KEY` |
| **Self-hosted (TEI / bge-m3)** | `--profile embed-local` + `OPENAI_EMBEDDING_BASE_URL=http://tei:80/v1`+ `OPENAI_EMBEDDING_MODEL=BAAI/bge-m3`+ `OPENAI_EMBEDDING_SEND_DIMENSIONS=false` | none — runs locally |

Anthropic, Gemini, and OpenRouter don't offer embedding APIs here — pair them with OpenAI (or with TEI) for embeddings. You can mix providers freely. Gemini uses the [Google AI Studio](https://aistudio.google.com/) key-auth Developer API (no GCP project/ADC required). The self-hosted TEI row keeps `EMBEDDING_PROVIDER=openai` because TEI speaks the same OpenAI-compatible API; see [`docs/local-embedder.md`](docs/local-embedder.md) for hardware sizing, GPU setup, and model swapping.

#### 2. Start the stack

```bash
docker compose up -d
```

By default this **pulls the multi-arch images from `ghcr.io`** (`linux/amd64` + `linux/arm64`) on first run — takes ~30 seconds. Subsequent `up` commands re-use the cached image (no registry round-trip, works offline). To pin a specific version, set `MEMCLAW_VERSION=v1.2.3` in your `.env`. To build from local source instead (e.g. when iterating on a fork), run `docker compose up --build --no-pull`.

To upgrade to a newer image at the same tag (e.g. `:latest` after we cut a new release), run `docker compose pull && docker compose up -d`. Without an explicit `pull`, the local cache wins — there's no silent version drift.

> **Offline / air-gapped operation**: depending on whether the image is already cached locally:
> - **Image cached, no network**: `docker compose up -d` works as-is — `pull_policy: missing` doesn't try to pull when the image is present. Use `docker compose up --no-pull` if you want to be explicit.
> - **No local image, no network**: `docker compose up --build --no-pull` (build from source, don't try to pull).
> - **Strict no-network guarantee** (e.g. an air-gapped pipeline that should never reach `ghcr.io`): drop a `docker-compose.override.yml` setting `pull_policy: never` for both services — Compose then fails fast if the image is absent rather than attempting a pull.

| Service | URL |
|---|---|
| Core API (REST + MCP) | http://localhost:8000 |
| Core Storage API | http://localhost:8002 |
| PostgreSQL (pgvector) | localhost:5432 |
| Redis | localhost:6379 |

#### 3. Verify

```bash
curl http://localhost:8000/api/v1/health
# {"status":"ok","storage":"connected","redis":"connected","event_bus":"ok"}
```

#### 4. Write and search

```bash
# Write a memory (standalone mode — no API key needed)
curl -X POST http://localhost:8000/api/v1/memories \
  -H "X-API-Key: standalone" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "default", "content": "Our auth service uses JWT with 15-minute expiry."}'

# Search for it
curl -X POST http://localhost:8000/api/v1/search \
  -H "X-API-Key: standalone" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "default", "query": "authentication token lifetime"}'
```

The write response carries an LLM-inferred `memory_type`, `title`, `summary`, `tags`, `status`, and a `weight` (the importance score) — all derived from a single `content` field. On the default fast-write path, enrichment is applied asynchronously: the immediate response is marked `enrichment_pending` and the inferred fields populate within moments.

`POST /search` returns matches under an `items` array, each entry the full memory plus a `similarity` score:

```json
{
  "items": [
    {
      "id": "…",
      "agent_id": "mcp-agent",
      "memory_type": "fact",
      "title": "Auth service uses JWT with 15-minute expiry",
      "similarity": 0.47,
      "visibility": "scope_team",
      "status": "active"
    }
  ]
}
```

Embedding is asynchronous too, so a just-written memory may not surface in semantic `search` for a moment after the write returns (watch `metadata.embedding_pending`); the non-semantic `GET /memories` list shows it immediately.

---

⭐ **If MemClaw just worked for you,
[star the repo](https://github.com/caura-ai/caura-memclaw/stargazers)** —
it's how other fleet builders find us, and it shapes how much time we can
invest in the OSS edition.

---

Auth modes

OSS supports three auth paths. Pick one and add it to your `.env`, then `docker compose up -d` to restart.

**Standalone** — single-tenant (`tenant_id="default"`), simplest for local / self-install:
```env
IS_STANDALONE=true
```
No API key required for REST. MCP still expects a non-empty `X-API-Key` header — any value works.

> Pair Standalone mode with `--profile embed-local` (see [`docs/local-embedder.md`](docs/local-embedder.md)) for a fully self-contained deployment: no admin keys, no external API calls, all embeddings computed locally. Useful for offline / air-gapped environments and personal-laptop installs.

**Admin key** — multi-tenant with full access:
```env
ADMIN_API_KEY=your-long-random-admin-key
```
Pass `X-API-Key: your-long-random-admin-key` and include `tenant_id` in request bodies / query params.

**Shared gate** — for network-exposed OSS deployments:
```env
MEMCLAW_API_KEY=your-shared-key
```
Clients send `X-API-Key: your-shared-key` plus `X-Tenant-ID: `.

> See [AGENT-INSTALL.md](AGENT-INSTALL.md) for the full agent self-install walkthrough.

Running tests

```bash
# Unit tests (no DB needed)
pytest tests/ -m "unit"

# All tests (requires PostgreSQL)
docker compose up -d db
pytest tests/ -m "not benchmark"

# Smoke test against live API (~30s, auto-cleanup)
python scripts/smoke_test.py --url http://localhost:8000 --api-key 
```

### OpenClaw Plugin

Already running an OpenClaw fleet? Install MemClaw as a plugin against either the managed platform or your self-hosted stack:

```bash
# Point at whichever URL hosts your MemClaw API
export MEMCLAW_URL=https://memclaw.net          # managed
# or:  export MEMCLAW_URL=http://localhost:8000  # self-hosted
export MEMCLAW_KEY=your-key                      # `standalone` works in self-hosted standalone mode
export MEMCLAW_FLEET=my-fleet

curl -sf -H "X-API-Key: $MEMCLAW_KEY" \
  "$MEMCLAW_URL/api/v1/install-plugin?fleet_id=$MEMCLAW_FLEET&api_url=$MEMCLAW_URL" | bash

# Restart the gateway to load the plugin
openclaw gateway restart
```

The plugin claims the OpenClaw `memory` slot (replacing `memory-core`) and exposes the same 12 MCP tools. Full setup, agent prompts, and trust levels: [static/docs/integration-guide.md](static/docs/integration-guide.md).

### Python client

Talk to any MemClaw deployment (managed or self-hosted) from Python:

```bash
pip install memclaw-client
```

```python
from memclaw_client import MemClaw

mc = MemClaw("mc_xxx", tenant_id="my-team", agent_id="my-agent")
mc.write("Q3 revenue target is $4M, set on 2026-04-15.")
print(mc.recall("Q3 revenue target").summary)
```

A thin wrapper over the REST API — see [`clients/python/`](clients/python/) for the full client.

### TypeScript client

Same, from TypeScript / JavaScript (Node 18+, zero dependencies):

```bash
npm install @caura/memclaw-client
```

```ts
import { MemClaw } from "@caura/memclaw-client";

const mc = new MemClaw("mc_xxx", { tenantId: "my-team", agentId: "my-agent" });
await mc.write("Q3 revenue target is $4M, set on 2026-04-15.");
console.log((await mc.recall("Q3 revenue target")).summary);
```

See [`clients/typescript/`](clients/typescript/) for the full client.

---

## Features

### Governance

- **Tenant isolation** — row-level database separation per tenant; PII auto-detected and flagged on every write (surfaced in memory metadata as `contains_pii`/`pii_types`)
- **Visibility scopes** — every memory is stamped at write time: `scope_agent` (private), `scope_team` (fleet-wide, default), or `scope_org` (cross-fleet). Cross-fleet recall is permissioned, not open
- **Agent trust tiers** — four levels control cross-fleet reads, writes, and deletes. Agents are either provisioned atomically via `POST /admin/agent-keys/provision` (recommended — mints key + row + trust + fleet in one call) or auto-registered on first write (legacy fallback)
- **Full audit log** — every write, delete, and transition logged with tenant and scope context

### Memory Pipeline

- **Single-pass LLM enrichment** — every write auto-classifies into one of 14 memory types, generates title/summary/tags, scores importance, flags PII, and extracts entities — from a single `content` field
- **Hybrid search** — pgvector semantic similarity + full-text keyword matching + knowledge graph expansion (up to 2 hops), ranked by composite score of similarity, importance, freshness, and graph boost
- **Live knowledge graph** — people, orgs, locations, and concepts extracted into entities and relations on every write. Semantic entity resolution (>0.85 cosine) auto-merges duplicates
- **Contradiction detection** — RDF triple comparison + LLM semantic analysis detects conflicting memories and automatical

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [caura-ai](https://github.com/caura-ai)
- **Source:** [caura-ai/caura-memclaw](https://github.com/caura-ai/caura-memclaw)
- **License:** Apache-2.0
- **Homepage:** https://memclaw.net

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-caura-ai-caura-memclaw
- Seller: https://agentstack.voostack.com/s/caura-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.