trackmcp
Back to directory

Caura (formerly 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.

479 stars PythonOthers Updated Sep 4, 2026
agent-memoryagentic-aiai-agentsai-infrastructureclaudefastapiknowledge-graphllm-memorymcpmcp-servermemory-managementmulti-agent-systemsopenaipgvectorrag

Documentation

Caura — Shared governed memory for AI agents

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

MemClaw is now Caura — same product, one name.

Tools are caura_*; the old memclaw_* tool names, env vars and URLs keep working unchanged. The memclaw-client/@caura/memclaw-client package names were retired; the MemClaw class remains a permanent alias inside caura-client.

·

·

·

·

·

·

·


Caura (formerly MemClaw) — the shared governed memory layer for AI agent fleets

Caura — formerly 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. Caura turns it into searchable, governed, self-improving memory.

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

Optimized for fleets. One agent works, and that's where most teams start — nothing below changes for a single-agent setup. What Caura adds is headroom: scoped memory, cross-agent outcome propagation, and fleet-wide trust tiers are there from the first write, and they keep paying off as agents multiply. Public agent-memory benchmarks (LoCoMo, LongMemEval) measure one agent, one user, one long conversation — the single-chatbot shape — so they score the on-ramp rather than the axes that compound with agent count: latency, token efficiency, and governance. That second shape is what we see in production: dozens or thousands of agents working on behalf of one company, sharing what they learn under governance. See Performance for the numbers, or read the benchmarks write-up.

> 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 →


Quick Start

Try it locally — no API key, no signup

The fastest way to see Caura work. Standalone mode runs single-tenant with auth bypassed — start Caura, write a memory, and find it again. (It boots with dummy embeddings so there's nothing to configure; add an AI provider key for semantic search — see Self-Hosted below.)

bash
git clone https://github.com/caura-ai/caura.git
cd caura
cp .env.example .env && echo "IS_STANDALONE=true" >> .env   # single-tenant, no API key
docker compose up -d --wait                                 # Postgres + pgvector + Redis + API (~30s)
bash
# 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", "agent_id": "quickstart", "write_mode": "strong", "content": "Our auth service uses JWT with 15-minute expiry."}'

# Find it by keyword — no provider key needed
curl -X POST http://localhost:8000/api/v1/search \
  -H "X-API-Key: standalone" -H "Content-Type: application/json" \
  -d '{"tenant_id": "default", "query": "JWT expiry"}'

The keyless strong-write response includes `memory_type`, `title`, `status`, and `weight` — plus a `summary` under `metadata` — all derived by a deterministic local heuristic from the single `content` field. With a configured AI provider, those values are model-inferred and `metadata` can also include `tags`.

> Want semantic paraphrases? The keyless query deliberately reuses words from the memory. After

> configuring an embedding provider in the next section, try `"authentication token lifetime"`

> instead — matching that phrase to "JWT with 15-minute expiry" exercises semantic recall.

See the fleet effect

Connect two MCP clients to the same fleet. Agent A records an operational

lesson with `caura_write`:

json
{
  "agent_id": "deploy-agent",
  "fleet_id": "platform",
  "visibility": "scope_team",
  "content": "Roll back auth-service with: deployctl rollback auth-service --to ."
}

Agent B asks `caura_recall` from that fleet:

json
{
  "agent_id": "incident-agent",
  "fleet_ids": ["platform"],
  "query": "How do I roll back auth-service?"
}

The result identifies `deploy-agent` as the author: one agent learned it, and

another reused it. `scope_agent` would keep the memory private;

`scope_team` shares it within the fleet; `scope_org` enables governed

cross-fleet recall subject to the trust ladder.

For production, give each client its own

agent-scoped credential.

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:

PathWhenTime to first memory
Managed platformQuickest. We host the DB + scaling.~2 min
Self-hosted (Docker)Privacy / on-prem / air-gapped.~5 min
OpenClaw pluginYou already run an OpenClaw fleet — install Caura 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 caura.ai.**

2. Copy an API key from the dashboard.

3. Connect through MCP or REST:

json
{
  "mcpServers": {
    "caura": {
      "url": "https://caura.ai/mcp",
      "headers": { "X-API-Key": "mc_your_api_key_here" }
    }
  }
}

For a production fleet, provision one agent-scoped credential per agent. See

Integrating without the OpenClaw plugin

for credential scopes, headers, and provisioning.

Using the tenant-scoped dashboard key? Pass an explicit `agent_id` on every MCP

tool call; the gateway rejects the reserved `mcp-agent` default on that path.

Self-Hosted (Open Source)

Docker Compose starts PostgreSQL + pgvector, Redis, the storage service, and the

REST/MCP API. The keyless example above is the shortest path; add a provider for

semantic recall.

service topology, security, offline operation, and tests

no cloud API calls

OpenClaw Plugin

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

The plugin claims OpenClaw's `memory` slot and exposes the same agent-facing

memory tools. Use the

agent installer's one-line setup,

then see the OpenClaw integration guide for

agent prompts and trust levels.

Python client

Talk to any managed or self-hosted Caura deployment from Python:

bash
pip install caura-client

See the Python client guide for examples and the full API.

TypeScript client

The Node 18+ client has no runtime dependencies:

bash
npm install @caura/client

See the TypeScript client guide for installation and

package-name compatibility details.


⭐ **If Caura just worked for you,

star the repo** —

it's how other fleet builders find us, and it shapes how much time we can

invest in the OSS edition.


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
  • Agent activity digests — daily and weekly per-agent digests, generated server-side for opted-in orgs (org setting `agent_digest.enabled`, off by default). They run from core-operations' `agent-digest` / `agent-digest-weekly` cron ticks and are read back via the reports endpoints in `core-api` (`GET /api/v1/reports`, `GET /api/v1/reports/agent-activity`). A tenant that hasn't opted in pays zero cost

Memory Pipeline

  • Single-pass LLM enrichment — every write auto-classifies into one of 14 memory types, generates title/summary, 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. When a result set holds both a superseded memory and the memory that replaced it, the replacement is always ranked immediately above it — a stale row can surface, but never above its own correction
  • Live knowledge graph — people, orgs, locations, and concepts extracted into entities and relations on every write. Entity resolution runs exact name match first, then a deterministic canonical-name match (case- and whitespace-insensitive, and ignoring a leading `the`/`a`/`an`/`new`/`old`/`current`/`existing`/`legacy` — so "the new analytics service" and "analytics service" are one entity), then semantic similarity (>0.85 cosine). A qualifier is only dropped while two or more words remain, so "new york" never collapses into "york". Every surface form seen is kept as an alias on the entity
  • Contradiction detection — RDF triple comparison + LLM semantic analysis detects conflicting memories and automatically supersedes them, with full contradiction chain tracking

Self-Improving Memory

  • Outcome-based learning (Karpathy Loop) — agents report success/failure after acting on recalled memories; the system reinforces what works and auto-generates preventive `rule`-type memories on failure
  • Crystallization — LLM merges near-duplicate memories into canonical atomic facts with full provenance; 8-status lifecycle automation retires stale data
  • Per-agent retrieval tuning — each agent optimizes its own retrieval profile (top_k, min_similarity, graph_max_hops, blend weights) from feedback, so search quality compounds with every interaction

Integrations

  • MCP server — built-in Model Context Protocol at `/mcp` (Streamable HTTP). Connect Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP client with a URL and API key
  • Multi-provider LLM — primary + fallback provider chain per tenant (OpenAI, Gemini, Anthropic, OpenRouter) with platform defaults for zero-config tenants
  • Document store — structured JSONB collections alongside semantic memories for exact-field lookups (customer records, config, task lists)

How Caura compares

Accuracy benchmarks cluster the leading tools in a narrow band (see

Performance). Where the field actually diverges is

fleet capability and governance:

CapabilityCauraMem0ZepLetta
Multi-fleet support
Agent trust tiers + keystone policies
Cross-vendor memory sharing
Contradiction detection + supersession
Per-agent retrieval tuning
PII detection & flagging
Audit trail / provenance⚠️ partial
Knowledge graph (auto-extracted)⚠️
MCP-native⚠️
OSS licenseApache 2.0Apache 2.0Apache 2.0Apache 2.0

Mem0, Zep, and Letta are solid projects; for a single agent, any of them

will serve you well — and so will Caura. The lanes separate above one

agent, where Caura's is governed memory across agent fleets: multiple

agents, teams, and vendors on one auditable memory plane. Comparison

reflects our reading of public docs as of June 2026 — corrections welcome

via issue or PR.


Performance

Benchmarked against the two most-cited public agent-memory benchmarks. Full results, methodology, and how to reproduce them live in `BENCHMARKS.md`; operator-scale context is in `docs/performance.md`; the full write-up is on the blog.

LoCoMoLongMemEvalSearch latency
Accuracy (LLM-judge)77.6%72.5%
Token savings vs full context96.6%98.2%
Latency23 ms p50 · 27 ms p95

Accuracy sits inside the leading cluster across the field (Mem0, Zep, Caura — scores cluster in a narrow band). The axes we push hardest are latency and token efficiency, because those are the ones that compound as agent count grows — a few hundred ms of search latency disappears behind one LLM call, but bills millions of times a day across a fleet.

> Single-agent benchmarks can't measure cross-agent recall, outcome propagation between agents, fleet-scoped visibility, or governance-aware retrieval. Those are the questions that decide whether a memory system is *deployable* inside a company. See `docs/performance.md`.

Source: Fast, Token-Efficient, and Built for Fleets (2026-04-19).


MCP (Model Context Protocol)

Add Caura to any MCP client with one config block.

Self-hosted (localhost):

json
{
  "mcpServers": {
    "caura": {
      "url": "http://localhost:8000/mcp",
      "headers": { "X-API-Key": "standalone" }
    }
  }
}

Managed platform (caura.ai):

json
{
  "mcpServers": {
    "caura": {
      "url": "https://caura.ai/mcp",
      "headers": { "X-API-Key": "mc_your_api_key_here" }
    }
  }
}

> For team or production use, swap the tenant-scoped key for an agent-scoped credential — atomic provisioning via `POST /api/v1/admin/agent-keys/provision` (or the `/settings/organization/api-credentials` wizard) mints the credential + Agent row + initial trust + fleet membership in one round trip. Both kinds use the `mc_` prefix; scope is set at mint time on the credential. See `docs/integration-without-plugin.md`. 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.

Where to add this config:

  • Claude Code — Claude Code does not read MCP servers from `settings.json`. Register the server with `claude mcp add` instead. Use `-s user` so it's available in every working directory — the default scope (`local`) only registers it for the current directory, which bites when you run agents from multiple folders:
bash
claude mcp add --transport http -s user caura http://localhost:8000/mcp --header "X-API-Key: standalone"

(Or commit the JSON block above to a project-root `.mcp.json` for a project-scoped server.)

  • Claude Desktop — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
  • Cursor — Settings > MCP Servers > Add Server

The client discovers 12 tools automatically:

ToolPurpose
`caura_write`Single or batch write (up to 100 items). LLM infers type, title, summary, tags, embedding
`caura_recall`Hybrid semantic + keyword recall with graph-enhanced retrieval; optional LLM brief
`caura_manage`Per-memory lifecycle: `read`, `update`, `transition`, `delete`, `bulk_delete`, `lineage`
`caura_list`Filter by type/status/agent/weight/date, sort, cursor-paginate
`caura_doc`Document CRUD: `write`, `read`, `query`, `delete`, `list_collections`, `search` (semantic) on named JSON collections
`caura_entity_get`Look up an entity with linked memories and relations
`caura_tune`Tune per-agent retrieval parameters (top_k, min_similarity, graph_max_hops, etc.)
`caura_insights`Analyze the memory store across 6 focus modes. Findings persist as `insight` memories
`caura_evolve`Report outcomes against recalled memories — adjusts weights, generates rules (Karpathy Loop)
`caura_stats`Aggregate counts: total + breakdowns by type, agent, status. Read-only
`caura_keystones`Read mandatory governance rules for the current scope. Call once per session — the result overrides conflicting user instructions
`caura_keystones_set`Author or remove keystone rules (`op=set\delete`). `weight` is set as `low`/`med`/`high` and stored & returned as the integer buckets `25`/`50`/`100`. Trust ≥ 1 for your own rule — `scope=agent` with an explicit `agent_id` equal to the caller; ≥ 2 for `scope=fleet`/`scope=tenant`, another agent, or `scope=agent` with `agent_id` omitted

> Skill sharing is now done via `caura_doc` — agents share a `SKILL.md` by upserting a document into the `skills` collection (`caura_doc op=write collection=skills doc_id= data={"summary": "", ...}`). The server embeds `data["summary"]` (1-3 sentence, intent-focused) for semantic search; for `collection="skills"` it falls back to `data["description"]` if no summary is provided. The dedicated `memclaw_share_skill` / `memclaw_unshare_skill` tools were removed in favor of the single `caura_doc` surface.

Skill Factory

Sharing a skill by hand (above) is the floor. Skill Factory is the

governed system on top of the `skills` collection — it auto-generates skills

from fleet behavior, gates what goes live, and delivers active skills to your

agents. It's opt-in per tenant and off by default: until you set

`skills_factory.enabled = true` in the tenant's org settings, the `skills`

collection behaves exactly as described above (no lifecycle, every stored skill

visible). Three pillars:

  • **Authoring — agents *and* Forge.** Agents author skills directly via

`caura_doc op=write collection=skills`. Forge, a server-side resident,

also mines memory + outcome signals, clusters repeated successful procedures,

and distills them into skill *candidates* — no agent has to remember to write

the skill.

  • Governance — a lifecycle. Every skill carries a status:

`candidate → staged → active` (with `rejected` / `quarantined` / `stale` /

`deprecated` exits). Six automated gates plus a Sentinel content scan decide

what may be promoted, and a Skills Inbox lets an operator approve, edit,

defer, reject, or quarantine staged skills over a REST surface —

`GET /api/v1/skills-inbox` lists the staged cards, and

`POST /api/v1/skills-inbox/{slug}/approve|edit|defer|quarantine|reject`

acts on them. An agent write lands as `staged`, never instantly `active`.

  • Delivery — pull and push. Agents *pull* active skills over MCP

(`caura_doc op=search`/`op=read`), or the OpenClaw plugin *pushes* them:

its reconciler fetches every active skill from `POST /api/v1/skills/installable`

and writes each to the node's skill directory, optionally registering that

directory on OpenClaw's load path. Both tiers serve active-only once the

feature is enabled.

Deep dives: `docs/mcp-skill-delivery.md` (the

active-only delivery contract + plugin reconcile targets),

`docs/operator-forge-cron.md` (scheduling Forge),

and `docs/skills-inbox-api.md` (the operator REST

API for the Skills Inbox).

The full operator/developer guide lives in the

Caura docs → Skill Factory.

The Interviewer

`caura_write` captures what an agent *chose* to record. The Interviewer

captures what it *did*. On a schedule, it reads an agent's own **durable work

trail** — the transcript or event log the harness already keeps — and asks an

LLM to synthesize the activity into typed memories, so the decisions,

blockers, and preferences an agent never stopped to journal still get stored.

It never re-runs the agent — it works only from the real trail, which grounds

it in actual activity. (LLM synthesis can still mis-read or overstate, so

treat Interviewer memories as a useful approximation, not a verbatim record.)

It's a third way memories enter Caura, alongside realtime writes and

ingestion. Like Skill Factory it's opt-in per tenant and off by default

inert until you set `interviewer.enabled = true` in the tenant's org

settings.

  • What it writes. Six report sections map onto the memory-type enum:

`worked_on → episode`, `decisions → decision`, `outcomes → outcome`,

`blockers → task`, `open_questions → fact`, `preferences_learned →

preference`. They land as ordinary enriched, embedded, governed memories,

with the trail's real event timestamps preserved.

  • How activity is captured. Two families, one submit protocol:
    • Plugin-buffer — the OpenClaw plugin keeps a durable node-local buffer

and submits windows (add `CAURA_INTERVIEWER=true` to the plugin env).

    `caura-client` package) reads a harness's on-disk transcript read-only

    and submits windows. Ships for Claude Code (`~/.claude/projects`) and

    Cursor (`~/.cursor/…/agent-transcripts`) today; Hermes and others

    are planned.

    • Crash-safe by construction. Each window is written under a

    deterministic attempt id (`sha1(node_id:cursor_from:cursor_to)`) *then* the

    per-node watermark advances — a crash mid-flight re-submits and dedups, so

    never a gap and never a duplicate. There is no local cursor state; the

    server watermark is the source of truth.

    • Privacy. The disk-parser is default-deny — it harvests nothing until

    you allowlist projects — and credential-shaped strings are scrubbed locally

    before submit and masked again server-side.

    Triggers are a periodic `run` (cron) and/or a session-end `hook`; combining

    them is safe because duplicate submissions dedup. Full setup, per-harness

    wiring, and the protocol are in the

    Caura docs → Interviewer.

    The Caura Broker

    The Caura Broker is a local daemon (`caura-daemon`, formerly `memclawd`,

    driven by the `caura` CLI) that runs on a developer's machine and connects coding agents — Claude

    Code, Codex, Cursor, Gemini — to Caura. Its job is to be the trust boundary

    on the developer side: it enforces policy, applies redaction, and keeps a

    tamper-evident audit log before anything leaves the machine. The Broker

    runs in personal mode out of the box; installs that join a **Broker

    Fleet** (a fleet of *machines* — distinct from the `fleet_id` *memory* scope)

    are governed together: heartbeats, a policy stream, and a shared dashboard.

    The Broker itself ships separately, but its server-side identity plumbing

    lives in this repo: a Broker call authenticates with

    `X-Caura-Credential-Kind: install_credential` plus `X-Install-UUID`, and its

    writes are attributed under the `broker:` ownership namespace — see

    `core-api/src/core_api/mcp_server.py` and `core-api/src/core_api/auth.py`.

    The broker↔cloud wire contract is frozen at v1: both repos run oasdiff

    breaking-change gates in CI (in this repo the baseline is generated by

    `core-api/scripts/gen_broker_openapi.py`, gate added in

    #620), so a

    contract-breaking change fails the build rather than breaking installed

    Brokers. Operations — install, fleet join, policy — are documented at

    Caura docs → Broker Fleet.

    Install the skill (Claude Code & Codex)

    Install Caura's usage guide as a skill so your agent knows *when* and

    *how* to use the 12 tools — the memory/doc mental model, the three rules

    (recall, write, supersede), trust levels, common patterns, and

    anti-patterns. The skill is loaded on-demand (not per-turn), so it costs

    nothing until the agent reaches for Caura.

    > Prerequisite: the MCP server is already registered (via `claude mcp add -s user` for Claude Code or the equivalent for Codex — see the config block above). Confirm with `claude mcp list` — you should see `caura: ... ✓ Connected`.

    Option A — one-liner (fastest)

    Self-hosted (localhost):

    bash
    curl -s "http://localhost:8000/api/v1/install-skill" | bash

    Managed platform:

    bash
    curl -s "https://caura.ai/api/v1/install-skill" | bash

    Automated agents (Claude Code, Codex) may refuse `curl | bash` for

    safety. Two-step install lets them audit the script first:

    bash
    curl -s "http://localhost:8000/api/v1/install-skill" > /tmp/install-caura-skill.sh
    less /tmp/install-caura-skill.sh      # review — it only does mkdir + curl + write
    bash /tmp/install-caura-skill.sh

    Options

    Query paramEffect
    (none)Install the memclaw skill for both Claude Code and Codex (default)
    `?agent=claude-code`Only Claude Code → `~/.claude/skills//SKILL.md`
    `?agent=codex`Only Codex → `~/.agents/skills//SKILL.md`
    `?skill=company-brain`Install the optional Company Brain posture skill instead of memclaw (see below; combine with `?agent=`)

    Verify

    bash
    ls -la ~/.claude/skills/memclaw/SKILL.md       # Claude Code
    ls -la ~/.agents/skills/memclaw/SKILL.md       # Codex

    Restart your agent after installing — skills are loaded at startup.

    Re-run the installer any time to pull the latest version.

    OpenClaw-plugin users get the skill automatically when the plugin

    installs; skip this step.

    Optional: the Company Brain skill

    `memclaw` teaches the agent the tools. `company-brain` is a thin,

    concept-first *posture* skill that layers on top: it frames the agent as one

    mind in a shared Company Brain and defers all tool mechanics back to the

    `memclaw` skill. Install it alongside `memclaw` when you want that framing:

    bash
    curl -s "https://caura.ai/api/v1/install-skill?skill=company-brain" | bash

    It installs to `~/.claude/skills/company-brain/SKILL.md` (Claude Code) and/or

    `~/.agents/skills/company-brain/SKILL.md` (Codex), and obeys the same

    `?agent=` filter. The default install (no `?skill=`) is unchanged — it

    installs `memclaw` only.


    Deployment

    The recommended way to run Caura is via Docker Compose (see Quick Start). This gives you a production-ready PostgreSQL + pgvector + Redis + API stack with a single command.

    Published container images

    Each release publishes multi-arch (linux/amd64, linux/arm64) images to GitHub Container Registry:

    code
    ghcr.io/caura-ai/caura-memclaw-core-api:v2.5.0
    ghcr.io/caura-ai/caura-memclaw-core-storage-api:v2.5.0

    Tags follow SemVer with floating aliases — `:v1`, `:v1.0`, `:v1.0.0`, plus `:latest` for the latest stable release. Pull them in your own compose file or Kubernetes manifests instead of building from source.

    Manual deployment (without Docker)

    The `core-api/` service is a standard FastAPI app that runs under any ASGI server (uvicorn, hypercorn). Requirements:

    • Python 3.12+
    • PostgreSQL 16+ with the `pgvector` extension
    • Redis (optional — falls back to in-memory cache if unavailable)
    bash
    uvicorn core_api.app:app --host 0.0.0.0 --port 8000 --workers 2

    Deployment topologies

    Caura ships with two operational modes for the storage layer. Single-node (default) is what you get from Docker Compose, `pip install`, or any fresh deploy — one `core-storage-api` instance serves both reads and writes. This is the right choice for any deployment that isn't seeing sustained 100+ writes/sec.

    The reader/writer split is an opt-in topology for high-write-rate deploys that want to scale reads independently of writes — e.g. by pointing read traffic at a Postgres streaming replica. Enabling it means running two `core-storage-api` services with different roles and pointing `core-api` at both:

    • Set `CORE_STORAGE_ROLE=writer` on the write-serving instance; `=reader` on the read-serving instance(s).
    • Set `CORE_STORAGE_READ_URL` on `core-api` to the reader service URL. Leave `CORE_STORAGE_API_URL` pointing at the writer.
    • `READ_DATABASE_URL` on each `core-storage-api` can point at a read replica if you have one.
    • Set the same non-empty `CORE_STORAGE_SHARED_SECRET` on `core-api`, every

    `core-storage-api` writer/reader, and any other internal storage caller. All

    storage requests must carry it as `X-Storage-Secret`; missing or incorrect

    credentials are rejected before routing.

    Topology defaults: `CORE_STORAGE_ROLE=hybrid` and

    `CORE_STORAGE_READ_URL=""`, so a single storage instance still serves both

    reads and writes. Docker Compose wires storage authentication automatically;

    manual deployments must configure `CORE_STORAGE_SHARED_SECRET` (or

    `CORE_STORAGE_SHARED_SECRET_FILE`) on the storage service and every caller.


    Upgrading from v1.x

    Version 2.0 widened embeddings from 768 to 1024 dimensions. Existing

    installations must explicitly opt into the destructive migration, take a

    database snapshot, and re-embed stored data.

    Follow the complete v1.x → v2.x upgrade guide

    before pulling a v2 image.


    API Reference

    Versioned REST routes live under `/api/v1/`; MCP is mounted separately at

    `/mcp`. A running deployment serves its authoritative OpenAPI schema at

    `/api/openapi.json` and interactive Swagger docs at `/api/docs`.

    Use the curated API reference for endpoint groups,

    authentication, configuration, and repository structure. The

    API surface ownership charter explains which operations

    belong on REST, MCP, or the OpenClaw plugin.


    Public API & Stability

    Caura follows SemVer. The stable MCP tools, REST endpoints, plugin variables,

    auth modes, and contributor requirements live in the

    public API stability contract.


    Telemetry

    The self-hosted OSS runtime supports optional Sentry

    integration for error tracking and performance monitoring:

    • Opt-in only — set the `SENTRY_DSN` environment variable to enable. No errors are reported unless you explicitly configure a DSN.
    • No built-in usage analytics — a self-hosted deployment does not collect usage statistics, feature flags, or behavioral data.
    • No phone-home — the self-hosted application makes zero outbound calls unless you configure a Sentry DSN or an LLM/embedding provider.

    The managed platform's usage analytics are a hosted-service feature; they are

    not part of the self-hosted runtime.


    Rate limiting

    Rate limiting is enforced in-process by slowapi, keyed by

    API key where one is present and by remote IP otherwise. It is applied per route, not globally —

    `/health`, `/version`, and `/mcp` are never throttled:

    RouteDefaultSetting
    `POST /memories`, `POST /documents`, `POST /ingest/commit`10/second`RATE_LIMIT_WRITE`
    `POST /memories/bulk`2/second`RATE_LIMIT_WRITE_BULK`
    `POST /search`, `POST /recall`30/second`RATE_LIMIT_SEARCH`

    Every response from a rate-limited route carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and

    `X-RateLimit-Reset`; a rejected request gets HTTP 429 with `Retry-After`. Counters live in Redis when

    `REDIS_URL` is set — which is what makes the limit hold across replicas — and in process memory

    otherwise, so a multi-instance deployment without Redis limits each instance separately. A Redis

    outage fails open: requests pass through un-throttled rather than erroring.

    Add limiting at your reverse proxy (nginx, Caddy, Cloudflare) as well if you need per-IP DDoS

    floors or limits the application layer can't see.

    Contributing

    We welcome contributions! See CONTRIBUTING.md for guidelines, development setup, and how to submit PRs.


    FAQ

    What is Caura?

    Caura is open-source governed shared memory for AI agent fleets:

    cross-agent, cross-fleet recall with visibility scopes, trust tiers,

    keystone policies, audit trails, and tenant isolation enforced on every

    operation — plus self-improving retrieval through outcome-based learning.

    How is Caura different from a vector database?

    Caura uses pgvector under the hood but is not a vector DB wrapper. On top

    of hybrid search it adds fleet orchestration, per-agent retrieval tuning,

    contradiction detection, an 8-status lifecycle, an auto-extracted knowledge

    graph, LLM enrichment on every write, row-level tenant isolation, and audit

    trails on every operation.

    How is Caura different from Mem0 or Zep?

    Mem0 and Zep focus on memory for individual agents; accuracy benchmarks

    cluster all three tools in a narrow band. Caura is built for *fleets*:

    multiple agents across teams and vendors sharing one governed memory plane,

    with trust tiers, keystone policies, and cross-fleet permissions those

    tools don't address. See How Caura compares.

    Does Caura work with Claude Desktop, Claude Code, Cursor, or Windsurf?

    Yes — Caura is MCP-native. Paste a JSON config with a URL and API key

    into any MCP client and 12 tools appear immediately.

    Can agents from different vendors share memory?

    Yes — that's the point. An Anthropic agent recalls what an OpenAI agent

    wrote, under the same governance rules — with trust tiers and visibility

    scopes deciding what crosses fleet boundaries.

    Is Caura really free?

    The full engine — storage, 12 MCP tools, plugin, audit trail — is Apache

    2.0. Run it yourself forever. The managed platform at

    caura.ai adds hosting, scaling, and enterprise

    governance for teams that don't want to operate infrastructure.

    Who runs Caura in production?

    eToro (NASDAQ: ETOR) runs 300+ agents on Caura — 26,500+ memories, 1,372

    shared skills, 23 ms p50 search.

    Case study →


    License

    Caura is licensed under the Apache License, Version 2.0.

    See NOTICE for copyright and third-party attributions.

    Trademarks

    "Caura" is a trademark of Caura. The Apache License 2.0 grants

    permission to use the source code but does not grant permission to use these

    names, logos, or branding in a way that suggests endorsement of, or affiliation

    with, any derivative work. See Apache License 2.0 §6 for the full legal terms.

    Frequently asked questions

    What is caura?

    caura is Caura (formerly 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.

    How do I install caura?

    Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

    Is caura open source?

    Yes — it is hosted on GitHub at https://github.com/caura-ai/caura and has 479 stars.

    Related MCP tools

    Run your own MCP server? See who uses it and what to fix.

    Measure it with TrackMCP