Skip to content
Back to search

caura

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/caura-ai/caura with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/caura-ai/caura'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/caura-ai--caura/badge.svg)](/listings/caura-ai--caura)

HTML

<a href="/listings/caura-ai--caura"><img src="/api/listings/caura-ai--caura/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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. (With no key there's nothing to configure: memories are stored without embeddings and found by keyword. Add an AI provider key for semantic search — see [Self-Hosted](#self-hosted-open-source) below.)

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 + scheduler (~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", "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`:

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

Agent B asks `caura_recall` from that fleet:

{
  "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](docs/integration-without-plugin.md#4-elevate-trust-when-needed). For production, give each client its own [agent-scoped credential](docs/integration-without-plugin.md#1-mint-an-agent-scoped-credential).

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

---

Four 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 Caura as a plugin against any of the above. | ~3 min | | **Rail SDK** | You write the agent yourself, in Python or TypeScript, and want it to recall rules and facts before every turn and store what it learned after. Works against any of the above. | ~2 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](https://caura.ai).** 2. Copy an API key from the dashboard. 3. Connect through MCP or REST:

{
  "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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 860 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">Caura &mdash; Shared governed memory for AI agents</h1>
  2. <h3 align="center">Fleet memory for AI agents &mdash; governed, shared, self-improving.</h3>
  3. <p align="center"><strong>MemClaw is now Caura</strong> &mdash; same product, one name.<br /> <!-- legacy-name-floor: taught as legacy alias -->
  4. Existing <code>memclaw_*</code> tool calls and supported <code>MEMCLAW_*</code> environment aliases continue to work; use <code>caura_*</code> names and current Caura URLs for new configuration. The PyPI name <code>memclaw-client</code> is kept only as a redirect shell (0.5.1) that installs <code>caura-client</code>; it provides no <code>memclaw_client</code> import and no <code>MemClaw</code> class. The npm package <code>@caura/memclaw-client</code> was never published.</p> <!-- legacy-name-floor: migration guidance and package evidence -->
  5. <p align="center">
  6. <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License" /></a>
  7. <a href="https://github.com/caura-ai/caura/stargazers"><img src="https://img.shields.io/github/stars/caura-ai/caura?style=social" alt="GitHub Stars" /></a>
  8. <a href="https://github.com/caura-ai/caura/actions"><img src="https://img.shields.io/github/actions/workflow/status/caura-ai/caura/ci.yml?label=CI" alt="CI" /></a>
  9. <a href="https://github.com/caura-ai/caura/releases"><img src="https://img.shields.io/github/v/release/caura-ai/caura" alt="Release" /></a>
  10. <a href="https://discord.com/invite/aNfpgfpj"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Join us on Discord" /></a>
  11. </p>
  12. <p align="center">
  13. <a href="#quick-start">Quick Start</a> &middot;
  14. <a href="#features">Features</a> &middot;
  15. <a href="docs/agent-fleet-memory.md">Fleet Memory Guide</a> &middot;
  16. <a href="#performance">Performance</a> &middot;
  17. <a href="#mcp-model-context-protocol">MCP</a> &middot;
  18. <a href="#api-reference">API Reference</a> &middot;
  19. <a href="static/docs/integration-guide.md">Plugin Docs</a> &middot;
  20. <a href="CONTRIBUTING.md">Contributing</a> &middot;
  21. <a href="https://discord.com/invite/aNfpgfpj">Discord</a>
  22. </p>
  23. ---
  24. ## Caura (formerly MemClaw) — the shared governed memory layer for AI agent fleets <!-- legacy-name-floor: taught as legacy alias -->
  25. 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. <!-- legacy-name-floor: taught as legacy alias -->
  26. Agents write plain text. Caura turns it into searchable, governed, self-improving memory.
  27. **One loop, three pillars: write, recall, compound** — every interaction makes the next one smarter.
  28. **Built 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. Fleet governance and workload-specific latency still need validation in the environment where they matter. See the generated [Performance](#performance) block and [evidence registry](EVIDENCE.md) for approved benchmark results, or read the [benchmarks write-up](https://caura.ai/blog/caura-benchmarks).
  29. > **Production case study:** eToro uses Caura as a governed shared-memory layer
  30. > for its AI-agent work.
  31. > [Architecture deep-dive →](https://caura.ai/blog/etoro-company-brain/)
  32. <p align="center">
  33. <img src="static/images/caura-concept.png" alt="Caura — Fleet Memory that Compounds" width="700" />
  34. </p>
  35. <p align="center">
  36. <img src="static/images/caura-demo.gif" alt="Caura demo — write, recall, and governed cross-fleet memory in action" width="700" />
  37. </p>
  38. ---
  39. ## Quick Start
  40. ### Try it locally — no API key, no signup
  41. The fastest way to see Caura work. Standalone mode runs single-tenant with auth bypassed — start Caura, write a memory, and find it again. (With no key there's nothing to configure: memories are stored without embeddings and found by keyword. Add an AI provider key for semantic search — see [Self-Hosted](#self-hosted-open-source) below.)
  42. ```bash
  43. git clone https://github.com/caura-ai/caura.git
  44. cd caura
  45. cp .env.example .env && echo "IS_STANDALONE=true" >> .env # single-tenant, no API key
  46. docker compose up -d --wait # Postgres + pgvector + Redis + API + scheduler (~30s)
  47. ```
  48. <!-- readme-quickstart-ci:start -->
  49. ```bash
  50. # Write a memory — no API key needed
  51. curl -X POST http://localhost:8000/api/v1/memories \
  52. -H "X-API-Key: standalone" -H "Content-Type: application/json" \
  53. -d '{"tenant_id": "default", "agent_id": "quickstart", "write_mode": "strong", "content": "Our auth service uses JWT with 15-minute expiry."}'
  54. # Find it by keyword — no provider key needed
  55. curl -X POST http://localhost:8000/api/v1/search \
  56. -H "X-API-Key: standalone" -H "Content-Type: application/json" \
  57. -d '{"tenant_id": "default", "query": "JWT expiry"}'
  58. ```
  59. <!-- readme-quickstart-ci:end -->
  60. 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`.
  61. > **Want semantic paraphrases?** The keyless query deliberately reuses words from the memory. After
  62. > configuring an embedding provider in the next section, try `"authentication token lifetime"`
  63. > instead — matching that phrase to "JWT with 15-minute expiry" exercises semantic recall.
  64. ### See the fleet effect
  65. For the architecture, evaluation checklist, and a stable GitHub-native citation
  66. target, see [Shared persistent memory for AI agent fleets](docs/agent-fleet-memory.md).
  67. Connect two MCP clients to the same fleet. Agent A records an operational
  68. lesson with `caura_write`:
  69. ```json
  70. {
  71. "agent_id": "deploy-agent",
  72. "fleet_id": "platform",
  73. "visibility": "scope_team",
  74. "content": "Roll back auth-service with: deployctl rollback auth-service --to <version>."
  75. }
  76. ```
  77. Agent B asks `caura_recall` from that fleet:
  78. ```json
  79. {
  80. "agent_id": "incident-agent",
  81. "fleet_ids": ["platform"],
  82. "query": "How do I roll back auth-service?"
  83. }
  84. ```
  85. The result identifies `deploy-agent` as the author: one agent learned it, and
  86. another reused it. `scope_agent` would keep the memory private;
  87. `scope_team` shares it within the fleet; `scope_org` enables governed
  88. cross-fleet recall subject to the [trust ladder](docs/integration-without-plugin.md#4-elevate-trust-when-needed).
  89. For production, give each client its own
  90. [agent-scoped credential](docs/integration-without-plugin.md#1-mint-an-agent-scoped-credential).
  91. Ready for semantic recall, multi-tenant, a managed host, or an OpenClaw fleet? Pick a path below.
  92. ---
  93. Four paths — pick the one that matches your setup:
  94. | Path | When | Time to first memory |
  95. |---|---|---|
  96. | **Managed platform** | Quickest. We host the DB + scaling. | ~2 min |
  97. | **Self-hosted (Docker)** | Privacy / on-prem / air-gapped. | ~5 min |
  98. | **OpenClaw plugin** | You already run an OpenClaw fleet — install Caura as a plugin against any of the above. | ~3 min |
  99. | **Rail SDK** | You write the agent yourself, in Python or TypeScript, and want it to recall rules and facts before every turn and store what it learned after. Works against any of the above. | ~2 min |
  100. ### Managed Platform
  101. Get up and running in minutes — no infrastructure, automatic updates, usage analytics, and enterprise-grade security included.
  102. 1. **[Sign up free on caura.ai](https://caura.ai).**
  103. 2. Create an API key in the dashboard under **Connect › Keys**.
  104. 3. Connect through MCP or REST:
  105. ```json
  106. {
  107. "mcpServers": {
  108. "caura": {
  109. "url": "https://caura.ai/mcp",
  110. "headers": { "X-API-Key": "mc_your_api_key_here" }
  111. }
  112. }
  113. }
  114. ```
  115. For a production fleet, provision one agent-scoped credential per agent. See
  116. [Integrating without the OpenClaw plugin](docs/integration-without-plugin.md)
  117. for credential scopes, headers, and provisioning.
  118. Using the tenant-scoped dashboard key? Pass an explicit `agent_id` on every MCP
  119. tool call; the gateway rejects the reserved `mcp-agent` default on that path.
  120. ### Self-Hosted (Open Source)
  121. Docker Compose starts PostgreSQL + pgvector, Redis, the storage service, the
  122. REST/MCP API, and the `core-operations` lifecycle scheduler (nightly expiry,
  123. archival, purge and crystallization). The keyless example above is the shortest
  124. path; add a provider for semantic recall.
  125. <a id="prerequisites"></a>
  126. <a id="1-clone-and-configure"></a>
  127. <a id="2-start-the-stack"></a>
  128. <a id="what-the-stack-contains--and-what-it-doesnt"></a>
  129. <a id="3-verify"></a>
  130. <a id="4-write-and-search"></a>
  131. - [Complete self-hosting guide](docs/self-hosting.md) — providers, auth,
  132. service topology, security, offline operation, and tests
  133. - [Local embedder](docs/local-embedder.md) — fully local semantic search with
  134. no cloud API calls
  135. - [Manual deployment without Docker](#manual-deployment-without-docker)
  136. ### OpenClaw Plugin
  137. <a id="openclaw-plugin-1"></a>
  138. Already running an OpenClaw fleet? Install Caura as a plugin against either the managed platform or your self-hosted stack:
  139. The plugin claims OpenClaw's `memory` slot and exposes the same agent-facing
  140. memory tools. Use the
  141. [agent installer's one-line setup](AGENT-INSTALL.md#connect-via-openclaw-plugin-alternative-to-mcp),
  142. then see the [OpenClaw integration guide](static/docs/integration-guide.md) for
  143. agent prompts and trust levels. Already have nodes running? Keeping them current
  144. — auto-upgrade and the manual re-install — is covered in
  145. [`docs/plugin-upgrade.md`](docs/plugin-upgrade.md).
  146. The plugin talks only to the Caura server you configure (`CAURA_API_URL`) and
  147. identifies itself on every request with
  148. `User-Agent: openclaw-plugin/<version> (node/<major>)`, which the server's
  149. self-hosted heartbeat uses to count connected plugin installs, and with
  150. `X-Caura-Surface: openclaw_plugin`, which labels the audit rows its writes
  151. produce ([Audit attribution](docs/api-reference.md)). It will not send
  152. `CAURA_API_KEY` over plain `http://` to anything but loopback: point
  153. `CAURA_API_URL` at `https://`, or set `CAURA_ALLOW_INSECURE_HTTP=true` in the
  154. plugin `.env` to accept cleartext on a trusted private network.
  155. ### Python client
  156. Talk to any managed or self-hosted Caura deployment from Python:
  157. ```bash
  158. pip install caura-client
  159. ```
  160. See the [Python client guide](clients/python/) for examples and the full API.
  161. ### TypeScript client
  162. The Node 18+ client has no runtime dependencies:
  163. ```bash
  164. npm install @caura/client
  165. ```
  166. See the [TypeScript client guide](clients/typescript/) for installation and
  167. package-name compatibility details.
  168. ### Rail SDK
  169. Give an agent memory around every turn. Rail fetches the governance rules and
  170. the facts relevant to the current message before your agent runs, hands you
  171. prompt-ready context, then extracts and stores what the turn taught. Python
  172. and TypeScript share the same semantics; both work against managed and
  173. self-hosted Caura.
  174. ```bash
  175. pip install caura-rail # Python 3.10+
  176. npm install @caura/rail # Node.js 22+
  177. ```
  178. Point it at any Caura with `CAURA_URL` and `CAURA_API_KEY` (for the standalone
  179. Docker server above: `http://localhost:8000` and `standalone`), then wrap each
  180. agent turn:
  181. ```python
  182. from caura_rail import MemoryScope, Rail, RestMemoryStore
  183. with RestMemoryStore.from_env() as store:
  184. rail = Rail(store, MemoryScope(agent_id="support-1", fleet_id="support"))
  185. with rail.turn("Remember: We deploy in eu-west-1.") as turn:
  186. # Call your model here; turn.context.text holds rules first, then facts.
  187. turn.reply = "Noted. " + turn.context.text
  188. print([w.status for w in turn.writes]) # ['written'], or ['deduplicated'] on a rerun
  189. ```
  190. ```js
  191. import { MemoryScope, Rail, RestMemoryStore } from "@caura/rail";
  192. const rail = new Rail({
  193. store: RestMemoryStore.fromEnv(process.env),
  194. scope: new MemoryScope({ agentId: "support-1", fleetId: "support" }),
  195. });
  196. const turn = await rail.turn("Remember: We deploy in eu-west-1.", (_, ctx) => "Noted. " + ctx.text);
  197. console.log(turn.writes.map(w => w.status)); // ['written'], or ['deduplicated'] on a rerun
  198. ```
  199. Each turn recalls, runs your code, extracts, and writes; a turn whose code
  200. raises writes nothing, and writes that fail on a temporary error wait in an
  201. outbox you replay. Use the clients above when you only need to call the API;
  202. use Rail when an agent should remember and follow rules. Guide, API reference,
  203. and reliability semantics live in the [Rail repository](https://github.com/caura-ai/caura-rail).
  204. To see each turn's recall and writes in Langfuse, Datadog or another
  205. OpenTelemetry backend, see [`docs/opentelemetry.md`](docs/opentelemetry.md).
  206. ---
  207. ⭐ **If Caura just worked for you,
  208. [star the repo](https://github.com/caura-ai/caura/stargazers)** —
  209. it's how other fleet builders find us, and it shapes how much time we can
  210. invest in the OSS edition.
  211. ---
  212. ## Features
  213. ### Governance
  214. - **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`)
  215. - **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
  216. - **Agent trust tiers** — four levels control cross-fleet reads, writes, and deletes. Agents are either provisioned atomically via `POST /admin/agent-keys/provision` on the managed platform (caura.ai; a self-hosted core-api has no such route) or auto-registered on first write
  217. - **Full audit log** — every write, delete, and transition logged with tenant and scope context
  218. - **Agent activity digests** — per-agent digests, generated server-side for opted-in orgs (org setting `agent_digest.enabled`, off by default) on the org's cadence (`agent_digest.cadence`: `daily` by default, or `weekly` or `both`; an org on the default gets no weekly digest). 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
  219. ### Memory Pipeline
  220. - **Single-pass LLM enrichment** — every write auto-classifies into one of 7 memory types (the server writes outcome, rule and insight itself), generates title/summary, scores importance, flags PII, and extracts entities — from a single `content` field
  221. - **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
  222. - **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
  223. - **Contradiction detection** — RDF triple comparison + LLM semantic analysis detects conflicting memories and automatically supersedes them, with full contradiction chain tracking
  224. ### Self-Improving Memory
  225. - **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
  226. - **Crystallization** — LLM merges near-duplicate memories into canonical atomic facts with full provenance; 8-status lifecycle automation retires stale data
  227. - **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
  228. ### Integrations
  229. - **MCP server** — built-in [Model Context Protocol](https://modelcontextprotocol.io) at `/mcp` (Streamable HTTP). Connect Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP client with a URL and API key
  230. - **Multi-provider LLM** — primary + fallback provider chain per tenant (OpenAI, Gemini, Anthropic, OpenRouter) with platform defaults for zero-config tenants
  231. - **Document store** — structured JSONB collections alongside semantic memories for exact-field lookups (customer records, config, task lists)
  232. ---
  233. ## How Caura compares
  234. Accuracy benchmarks cluster the leading tools in a narrow band (see
  235. [Performance](#performance)). Where the field actually diverges is
  236. fleet capability and governance:
  237. | Capability | Caura | Mem0 | Zep | Letta |
  238. |---|---|---|---|---|
  239. | Multi-fleet support | ✅ | ❌ | ❌ | ❌ |
  240. | Agent trust tiers + keystone policies | ✅ | ❌ | ❌ | ❌ |
  241. | Cross-vendor memory sharing | ✅ | ❌ | ❌ | ❌ |
  242. | Contradiction detection + supersession | ✅ | ❌ | ❌ | ❌ |
  243. | Per-agent retrieval tuning | ✅ | ❌ | ❌ | ❌ |
  244. | PII detection & flagging | ✅ | ❌ | ✅ | ❌ |
  245. | Audit trail / provenance | ✅ | ❌ | ⚠️ partial | ❌ |
  246. | Knowledge graph (auto-extracted) | ✅ | ⚠️ | ✅ | ❌ |
  247. | MCP-native | ✅ | ✅ | ✅ | ⚠️ |
  248. | OSS license | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 |
  249. Mem0, Zep, and Letta are solid projects; for a single agent, any of them
  250. will serve you well — and so will Caura. The lanes separate above one
  251. agent, where Caura's is **governed memory across agent fleets**: multiple
  252. agents, teams, and vendors on one auditable memory plane. Comparison
  253. reflects our reading of public docs as of June 2026 — corrections welcome
  254. via issue or PR.
  255. ---
  256. ## Performance
  257. Benchmarked against the two most-cited public agent-memory benchmarks. Full results, methodology, and how to reproduce them live in [`BENCHMARKS.md`](BENCHMARKS.md); operator-scale context is in [`docs/performance.md`](docs/performance.md); the full write-up is on the blog.
  258. <!-- BEGIN GENERATED: evidence-benchmarks -->
  259. - **LoCoMo accuracy:** Caura scored 77.9% (1,199/1,540) under its documented LoCoMo semantic-judge protocol using the retrieval-augmented agentic-v1 pipeline.
  260. - **LongMemEval reference judge:** Caura answered 461 of 500 LongMemEval_S questions correctly (92.2%) under the benchmark's GPT-4o reference judge.
  261. - **LongMemEval secondary judge:** The same 500 frozen LongMemEval_S answers scored 90.2% (451/500) under the secondary Gemini 3.5 Flash-Lite judge.
  262. - **LongMemEval token efficiency:** On LongMemEval_S, the median compact retrieved context was 22,410 tokens versus a 107,706-token full haystack: 79.2% context-only savings; counting every reader call yields 75.4%.
  263. Only active, approved claims appear here. Control, withdrawn, and withheld
  264. records remain in the evidence registry and are excluded from promotional copy.
  265. See [`evidence/claims.json`](evidence/claims.json) and
  266. [`EVIDENCE.md`](EVIDENCE.md). Do not hand-edit this block.
  267. <!-- END GENERATED: evidence-benchmarks -->
  268. ---
  269. ## MCP (Model Context Protocol)
  270. Add Caura to any MCP client with one config block.
  271. **Self-hosted** (localhost):
  272. ```json
  273. {
  274. "mcpServers": {
  275. "caura": {
  276. "url": "http://localhost:8000/mcp",
  277. "headers": { "X-API-Key": "standalone" }
  278. }
  279. }
  280. }
  281. ```
  282. **Managed platform** (caura.ai):
  283. ```json
  284. {
  285. "mcpServers": {
  286. "caura": {
  287. "url": "https://caura.ai/mcp",
  288. "headers": { "X-API-Key": "mc_your_api_key_here" }
  289. }
  290. }
  291. }
  292. ```
  293. > For team or production use, swap the tenant-scoped key for an **agent-scoped credential** — on the managed platform (caura.ai), atomic provisioning via `POST /api/v1/admin/agent-keys/provision` mints the credential + Agent row + initial trust + fleet membership in one round trip. It needs the **Manage API credentials** permission; without it, ask an organization admin. **Connect › Keys** in the Caura app makes only tenant-scoped keys. Both kinds use the `mc_` prefix; scope is set at mint time on the credential. See [`docs/integration-without-plugin.md`](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.
  294. **Where to add this config:**
  295. - **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:
  296. ```bash
  297. claude mcp add --transport http -s user caura http://localhost:8000/mcp --header "X-API-Key: standalone"
  298. ```
  299. (Or commit the JSON block above to a project-root `.mcp.json` for a project-scoped server.)
  300. - **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
  301. - **Cursor** — Settings > MCP Servers > Add Server
  302. The client discovers 12 tools automatically:
  303. | Tool | Purpose |
  304. |---|---|
  305. | `caura_write` | Single or batch write (up to 100 items). LLM infers type, title, summary, tags, embedding |
  306. | `caura_recall` | Hybrid semantic + keyword recall with graph-enhanced retrieval; optional LLM brief |
  307. | `caura_manage` | Per-memory lifecycle: `read`, `update`, `transition`, `delete`, `bulk_delete`, `lineage` |
  308. | `caura_list` | Filter by type/status/agent/weight/date, sort, cursor-paginate |
  309. | `caura_doc` | Document CRUD: `write`, `read`, `query`, `delete`, `list_collections`, `search` (semantic) on named JSON collections |
  310. | `caura_entity_get` | Look up an entity with linked memories and relations |
  311. | `caura_tune` | Tune per-agent retrieval parameters (top_k, min_similarity, graph_max_hops, etc.) |
  312. | `caura_insights` | Analyze the memory store across 6 focus modes. Findings persist as `insight` memories |
  313. | `caura_evolve` | Report outcomes against recalled memories — adjusts weights, generates rules (Karpathy Loop) |
  314. | `caura_stats` | Aggregate counts: total + breakdowns by type, agent, status. Read-only |
  315. | `caura_keystones` | Read mandatory governance rules for the current scope. Call once per session — the result overrides conflicting user instructions |
  316. | `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 |
  317. Every tool carries a `title` and the MCP `readOnlyHint` / `destructiveHint` annotations, so clients can tell reads from writes. A Claude connector-directory connection gets a variant of this set that meets the directory's requirement that no tool mixes reads and writes: `caura_manage` and `caura_doc` are replaced by `caura_memory_read`, `caura_memory_update`, `caura_memory_delete`, `caura_doc_read`, `caura_doc_write` and `caura_doc_delete`, and `caura_tune` only writes there, with `caura_tune_get` for reading the current profile. These call the same handlers with the same checks. Every other client sees the 12 tools above. See [`docs/api-surfaces.md`](docs/api-surfaces.md#mcp-tool-surfaces).
  318. > **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=<slug> data={"summary": "<one-liner>", ...}`). 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. <!-- legacy-name-floor: names the removed share/unshare tools -->
  319. ### Skill Factory
  320. Sharing a skill by hand (above) is the floor. **Skill Factory** is the
  321. governed system on top of the `skills` collection — it auto-generates skills
  322. from fleet behavior, gates what goes live, and delivers active skills to your
  323. agents. It's **opt-in per tenant and off by default**: until you set
  324. `skills_factory.enabled = true` in the tenant's settings (`PUT /api/v1/settings`
  325. with `{"skills_factory": {"enabled": true}}`, or in the Caura app at caura.ai:
  326. Settings › Tenant settings), the `skills`
  327. collection behaves exactly as described above (no lifecycle, every stored skill
  328. visible). Three pillars:
  329. - **Authoring — agents *and* Forge.** Agents author skills directly via
  330. `caura_doc op=write collection=skills`. **Forge**, a server-side resident,
  331. also mines memory + outcome signals, clusters repeated successful procedures,
  332. and distills them into skill *candidates* — no agent has to remember to write
  333. the skill.
  334. - **Governance — a lifecycle.** Every skill carries a status:
  335. `candidate → staged → active` (with `rejected` / `quarantined` / `stale` /
  336. `deprecated` exits). Six automated gates plus a Sentinel content scan decide
  337. what may be promoted, and a **Skills Inbox** lets an operator approve, edit,
  338. defer, reject, or quarantine staged skills over a REST surface —
  339. `GET /api/v1/skills-inbox` lists the staged cards, and
  340. `POST /api/v1/skills-inbox/{slug}/approve|edit|defer|quarantine|reject`
  341. acts on them (in the Caura app at caura.ai the same queue is Review › Skills
  342. to approve, for org admins). An agent write lands as `staged`, never
  343. instantly `active`.
  344. - **Delivery — pull and push.** Agents *pull* active skills over MCP
  345. (`caura_doc op=search`/`op=read`), or the **OpenClaw plugin** *pushes* them:
  346. its reconciler fetches every active skill from `POST /api/v1/skills/installable`
  347. and writes each to the node's skill directory, optionally registering that
  348. directory on OpenClaw's load path. Both tiers serve **active-only** once the
  349. feature is enabled.
  350. Deep dives: [`docs/mcp-skill-delivery.md`](docs/mcp-skill-delivery.md) (the
  351. active-only delivery contract + plugin reconcile targets),
  352. [`docs/operator-forge-cron.md`](docs/operator-forge-cron.md) (scheduling Forge),
  353. and [`docs/skills-inbox-api.md`](docs/skills-inbox-api.md) (the operator REST
  354. API for the Skills Inbox).
  355. The full operator/developer guide lives in the
  356. [Caura docs → Skill Factory](https://caura.ai/docs/skill-factory).
  357. ### The Interviewer
  358. `caura_write` captures what an agent *chose* to record. **The Interviewer**
  359. captures what it *did*. On a schedule, it reads an agent's own **durable work
  360. trail** — the transcript or event log the harness already keeps — and asks an
  361. LLM to synthesize the activity into typed memories, so the decisions,
  362. blockers, and preferences an agent never stopped to journal still get stored.
  363. It never re-runs the agent — it works only from the real trail, which grounds
  364. it in actual activity. (LLM synthesis can still mis-read or overstate, so
  365. treat Interviewer memories as a useful approximation, not a verbatim record.)
  366. It's a third way memories enter Caura, alongside realtime writes and
  367. ingestion. Like Skill Factory it's **opt-in per tenant and off by default** —
  368. inert until you set `interviewer.enabled = true` in the tenant's settings
  369. (`PUT /api/v1/settings`, or in the Caura app at caura.ai: Settings › Tenant
  370. settings).
  371. - **What it writes.** Six report sections map onto the memory-type enum:
  372. `worked_on → episode`, `decisions → decision`, `outcomes → outcome`,
  373. `blockers → task`, `open_questions → fact`, `preferences_learned →
  374. preference`. They land as ordinary enriched, embedded, governed memories,
  375. with the trail's real event timestamps preserved.
  376. - **How activity is captured.** Two families, one submit protocol:
  377. - **Plugin-buffer** — the OpenClaw plugin keeps a durable node-local buffer
  378. and submits windows (add `CAURA_INTERVIEWER=true` to the plugin env).
  379. - **Disk-parser** — the `caura-interviewer` CLI (shipped in the
  380. `caura-client` package) reads a harness's on-disk transcript read-only
  381. and submits windows. Ships for **Claude Code** (`~/.claude/projects`) and
  382. **Cursor** (`~/.cursor/…/agent-transcripts`) today; **Hermes** and others
  383. are planned.
  384. - **Crash-safe by construction.** Each window is written under a
  385. deterministic attempt id (`sha1(node_id:cursor_from:cursor_to)`) *then* the
  386. per-node watermark advances — a crash mid-flight re-submits and dedups, so
  387. never a gap and never a duplicate. There is no local cursor state; the
  388. server watermark is the source of truth.
  389. - **Privacy.** The disk-parser is default-deny — it harvests nothing until
  390. you allowlist projects — and credential-shaped strings are scrubbed locally
  391. before submit and masked again server-side.
  392. Triggers are a periodic `run` (cron) and/or a session-end `hook`; combining
  393. them is safe because duplicate submissions dedup. Full setup, per-harness
  394. wiring, and the protocol are in the
  395. [Caura docs → Interviewer](https://caura.ai/docs/interviewer).
  396. ### The Caura Broker
  397. The **Caura Broker** is a local daemon (`caura-daemon`, formerly `memclawd`, <!-- legacy-name-floor: taught as legacy alias -->
  398. driven by the `caura` CLI) that runs on a developer's machine and connects coding agents — Claude
  399. Code, Codex, Cursor, Gemini — to Caura. Its job is to be the trust boundary
  400. on the developer side: it enforces policy, applies redaction, and keeps a
  401. tamper-evident audit log **before anything leaves the machine**. The Broker
  402. runs in **personal mode** out of the box; installs that join a **Broker
  403. Fleet** (a fleet of *machines* — distinct from the `fleet_id` *memory* scope)
  404. are governed together: heartbeats, a policy stream, and a shared dashboard.
  405. The Broker itself ships separately, but its server-side identity plumbing
  406. lives in this repo: a Broker call authenticates with
  407. `X-Caura-Credential-Kind: install_credential` plus `X-Install-UUID`, and its
  408. writes are attributed under the `broker:<install>` ownership namespace — see
  409. `core-api/src/core_api/mcp_server.py` and `core-api/src/core_api/auth.py`.
  410. The broker↔cloud wire contract is **frozen at v1**: both repos run oasdiff
  411. breaking-change gates in CI (in this repo the baseline is generated by
  412. `core-api/scripts/gen_broker_openapi.py`, gate added in
  413. [#620](https://github.com/caura-ai/caura/pull/620)), so a
  414. contract-breaking change fails the build rather than breaking installed
  415. Brokers. Operations — install, fleet join, policy — are documented at
  416. [Caura docs → Broker Fleet](https://caura.ai/docs/broker-fleet).
  417. ### Install the skill (Claude Code & Codex)
  418. Install Caura's usage guide as a **skill** so your agent knows *when* and
  419. *how* to use the 12 tools — the memory/doc mental model, the three rules
  420. (recall, write, supersede), trust levels, common patterns, and
  421. anti-patterns. The skill is loaded on-demand (not per-turn), so it costs
  422. nothing until the agent reaches for Caura.
  423. > **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`.
  424. #### Option A — one-liner (fastest)
  425. Self-hosted (localhost):
  426. ```bash
  427. curl -s "http://localhost:8000/api/v1/install-skill" | bash
  428. ```
  429. Managed platform:
  430. ```bash
  431. curl -s "https://caura.ai/api/v1/install-skill" | bash
  432. ```
  433. #### Option B — download, inspect, run (recommended for agents)
  434. Automated agents (Claude Code, Codex) may refuse `curl | bash` for
  435. safety. Two-step install lets them audit the script first:
  436. ```bash
  437. curl -s "http://localhost:8000/api/v1/install-skill" > /tmp/install-caura-skill.sh
  438. less /tmp/install-caura-skill.sh # review — it only does mkdir + curl + write
  439. bash /tmp/install-caura-skill.sh
  440. ```
  441. #### Options
  442. | Query param | Effect |
  443. |---|---|
  444. | (none) | Install the default Caura tool-reference skill for both Claude Code and Codex |
  445. | `?agent=claude-code` | Only Claude Code → `~/.claude/skills/<skill>/SKILL.md` |
  446. | `?agent=codex` | Only Codex → `~/.agents/skills/<skill>/SKILL.md` |
  447. | `?skill=company-brain` | Install the optional **Company Brain** posture skill instead of the default skill (see below; combine with `?agent=`) |
  448. #### Verify
  449. ```bash
  450. ls -la ~/.claude/skills/memclaw/SKILL.md # Claude Code; legacy-name-floor: installed default-skill path
  451. ls -la ~/.agents/skills/memclaw/SKILL.md # Codex; legacy-name-floor: installed default-skill path
  452. ```
  453. Restart your agent after installing — skills are loaded at startup.
  454. Re-run the installer any time to pull the latest version.
  455. OpenClaw-plugin users get the skill automatically when the plugin
  456. installs; skip this step.
  457. #### Optional: the Company Brain skill
  458. The default skill teaches the agent the tools. **`company-brain`** is a thin,
  459. concept-first *posture* skill that layers on top: it frames the agent as one
  460. mind in a shared **Company Brain** and defers all tool mechanics back to the
  461. tool-reference skill. Install the two together when you want that framing:
  462. ```bash
  463. curl -s "https://caura.ai/api/v1/install-skill?skill=company-brain" | bash
  464. ```
  465. It installs to `~/.claude/skills/company-brain/SKILL.md` (Claude Code) and/or
  466. `~/.agents/skills/company-brain/SKILL.md` (Codex), and obeys the same
  467. `?agent=` filter. The default install (no `?skill=`) is unchanged — it
  468. installs the default tool-reference skill only.
  469. ---
  470. ## Deployment
  471. The recommended way to run Caura is via Docker Compose (see [Quick Start](#quick-start)). This gives you a production-ready PostgreSQL + pgvector + Redis + API stack with a single command.
  472. ### Published container images
  473. Each release publishes multi-arch (linux/amd64, linux/arm64) images to [GitHub Container Registry](https://github.com/orgs/caura-ai/packages):
  474. ```
  475. ghcr.io/caura-ai/caura-memclaw-core-api:v2.5.0 # legacy-name-floor: published GHCR repository name
  476. ghcr.io/caura-ai/caura-memclaw-core-storage-api:v2.5.0 # legacy-name-floor: published GHCR repository name
  477. ghcr.io/caura-ai/caura-core-operations:v2.5.0
  478. ```
  479. `caura-core-operations`, the lifecycle scheduler, is newer than the other two and
  480. is published under the new name, so releases before it joined the stack have no
  481. image for it.
  482. 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.
  483. <a id="manual-deployment"></a>
  484. ### Manual deployment (without Docker)
  485. Caura is two FastAPI services, and both run under any ASGI server (uvicorn, hypercorn). `core-storage-api` owns the database and applies the migrations when it starts. `core-api` serves the REST and MCP API and reaches the database only through it. Requirements:
  486. - Python 3.12+
  487. - PostgreSQL 16+ with the `pgvector` extension, for `core-storage-api`
  488. - Redis (optional — falls back to in-memory cache if unavailable)
  489. Both services need the same non-empty `CORE_STORAGE_SHARED_SECRET`, and core-api refuses to start without it. Point core-api at the storage service with `CORE_STORAGE_API_URL` (default `http://localhost:8002`). [AGENT-INSTALL.md, Option B](AGENT-INSTALL.md#option-b-manual-no-docker) walks through the whole install, `pip install -r requirements.txt` included.
  490. Export `.env` into the process environment before starting each service. The services load their own settings from `.env`, but some knobs are read from the environment only: the embedder (`OPENAI_EMBEDDING_*`, `EMBEDDING_QUERY_INSTRUCTION`), the reranker (`RANK_*`) and the provider model overrides (`*_DEFAULT_MODEL`). `.env.example` marks those blocks "env-only". Compose's `env_file:` puts them in the environment; a bare uvicorn run does not. An exported value takes precedence over `.env`, so export again after editing it. Sourcing hands every line to the shell, so wrap any value that contains spaces, quotes or shell characters such as `$`, `&`, `;` or backticks (a password, say) in single quotes. Otherwise the shell mangles it, and the mangled value overrides the one in `.env`.
  491. ```bash
  492. set -a; . ./.env; set +a
  493. PYTHONPATH=.:core-storage-api/src uvicorn core_storage_api.app:app --host 127.0.0.1 --port 8002
  494. # Then, in a second shell with the same .env exported:
  495. WEB_CONCURRENCY=2 PYTHONPATH=.:core-api/src uvicorn core_api.app:app --host 0.0.0.0 --port 8000
  496. ```
  497. uvicorn takes its worker count from `WEB_CONCURRENCY` when `--workers` is not given, and core-api reads the same variable: with `USE_STM=true` and `STM_BACKEND=memory` it refuses to start on more than one worker, since each worker would keep its own STM. Use `STM_BACKEND=redis` there.
  498. ### Deployment topologies
  499. 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.
  500. 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:
  501. - Set `CORE_STORAGE_ROLE=writer` on the write-serving instance; `=reader` on the read-serving instance(s).
  502. - Set `CORE_STORAGE_READ_URL` on `core-api` to the reader service URL. Leave `CORE_STORAGE_API_URL` pointing at the writer.
  503. - `READ_DATABASE_URL` on each `core-storage-api` can point at a read replica if you have one. On the writer it serves the reads that tolerate replica lag. On a reader every query uses it, and `DATABASE_URL` is not connected to.
  504. - Set the same non-empty `CORE_STORAGE_SHARED_SECRET` on `core-api`, every
  505. `core-storage-api` writer/reader, and any other internal storage caller. All
  506. storage requests must carry it as `X-Storage-Secret`; missing or incorrect
  507. credentials are rejected before routing.
  508. **Topology defaults:** `CORE_STORAGE_ROLE=hybrid` and
  509. `CORE_STORAGE_READ_URL=""`, so a single storage instance still serves both
  510. reads and writes. Docker Compose wires storage authentication automatically;
  511. manual deployments must configure `CORE_STORAGE_SHARED_SECRET` (or
  512. `CORE_STORAGE_SHARED_SECRET_FILE`) on the storage service and every caller.
  513. ---
  514. ## Upgrading from v1.x
  515. <!-- Preserve deep links from the former inline guide. -->
  516. <a id="what-changes"></a>
  517. <a id="procedure-oss-docker-compose"></a>
  518. <a id="what-if-i-skip-the-opt-in"></a>
  519. <a id="rolling-back"></a>
  520. <a id="v1x--v2x-compatibility-for-client-code"></a>
  521. Version 2.0 widened embeddings from 768 to 1024 dimensions. Existing
  522. installations must explicitly opt into the destructive migration, take a
  523. database snapshot, and re-embed stored data.
  524. Follow the complete [v1.x → v2.x upgrade guide](docs/upgrading-from-v1.md)
  525. before pulling a v2 image.
  526. ---
  527. ## API Reference
  528. <a id="project-structure"></a>
  529. Versioned REST routes live under `/api/v1/`; MCP is mounted separately at
  530. `/mcp`. A running deployment serves its authoritative OpenAPI schema at
  531. `/api/openapi.json` and interactive Swagger docs at `/api/docs`.
  532. Use the [curated API reference](docs/api-reference.md) for endpoint groups,
  533. authentication, configuration, and repository structure. The
  534. [API surface ownership charter](docs/api-surfaces.md) explains which operations
  535. belong on REST, MCP, or the OpenClaw plugin.
  536. ---
  537. ## Public API & Stability
  538. <!-- Preserve deep links from the former inline contract. -->
  539. <a id="stable-surfaces"></a>
  540. <a id="mcp-tools-12"></a>
  541. <a id="rest-endpoints"></a>
  542. <a id="plugin-environment-variables"></a>
  543. <a id="server-environment-variables"></a>
  544. <a id="auth-modes"></a>
  545. <a id="internal-not-covered-by-semver"></a>
  546. <a id="reporting-breaking-changes"></a>
  547. Caura follows SemVer. The stable MCP tools, REST endpoints, plugin variables,
  548. auth modes, and contributor requirements live in the
  549. [public API stability contract](docs/public-api-stability.md).
  550. ---
  551. <a id="telemetry-and-error-tracking"></a>
  552. ## Telemetry
  553. *Updated 2026-09-19.* A self-hosted server sends **one anonymous heartbeat a
  554. day per container**, whatever its worker count, to `telemetry.caura.ai`: its version, Python/OS/arch, deploy kind
  555. (docker or source), uptime bucket, provider *kinds* (never model names or
  556. keys), whether Redis and Sentry are configured (never the values), bucketed
  557. counts of memories, agents, tenants and recently-seen plugin nodes, and
  558. bucketed counts of which SDK families called it. Every number is a bucket
  559. (`0`, `1`, `2-5`, `6-20`, ...), the id is a random UUID stored in your own
  560. database, and nothing about hostnames, IPs, names, content or configuration
  561. values is ever sent. The exact payload, its JSON schema, the retention policy
  562. and the change log are in [docs/telemetry.md](docs/telemetry.md).
  563. Every way to turn it off, each permanent for that install:
  564. - `CAURA_TELEMETRY=off` in `core-api`'s environment (`.env`, or the commented
  565. line under `core-api` in `docker-compose.yml`).
  566. - `DO_NOT_TRACK=1` (the [Console Do Not Track](https://consoledonottrack.com/) convention).
  567. - `CI` set to a non-empty value: pipelines are never counted.
  568. - Block `telemetry.caura.ai:443` at the firewall: one attempt a day, 5 s timeout, no retry.
  569. - Running behind the enterprise gateway or with platform providers switches it off automatically.
  570. Inspect what your server would send, when it last tried and whether that
  571. worked with `GET /api/v1/telemetry`; start over with a fresh id via
  572. `POST /api/v1/telemetry/rotate`. The boot log prints the ON/OFF decision, the
  573. reason and the disable hint on every start; a mistyped `CAURA_TELEMETRY_URL`
  574. (plain `http://` to anything but localhost) turns the heartbeat off with a
  575. warning rather than sending in clear text.
  576. Error tracking stays opt-in: set `SENTRY_DSN` to enable optional
  577. [Sentry](https://sentry.io) integration for error tracking and performance
  578. monitoring. No errors are reported unless you explicitly configure a DSN.
  579. Apart from the heartbeat, a self-hosted deployment makes no other outbound
  580. calls unless you configure a Sentry DSN or an LLM/embedding provider. The
  581. managed platform's usage analytics are a hosted-service feature; they are
  582. not part of the self-hosted runtime.
  583. ---
  584. ## Rate limiting
  585. Rate limiting is enforced in-process by [slowapi](https://github.com/laurentS/slowapi). Each limit
  586. is per credential (the key auth verified; behind a gateway, the credential it accepted), or per
  587. remote IP when none was verified. Each also has a tenant-wide budget, at five times its rate by
  588. default, shared by all the tenant's credentials. It is applied per route and per MCP tool, not
  589. globally, so `/health` and `/version` are never throttled:
  590. | Route | MCP tool | Default | Setting |
  591. |---|---|---|---|
  592. | `POST /memories`, `POST /documents`, `POST /stm/promote` | `caura_write`, `caura_doc` write | 10/second | `RATE_LIMIT_WRITE` |
  593. | `POST /memories/bulk`, `POST /ingest/commit` | `caura_write` with `items` | 2/second, one budget across these | `RATE_LIMIT_WRITE_BULK` |
  594. | `POST /search`, `POST /recall`, `GET /memories`, `POST /documents/search` | `caura_recall`, `caura_list`, `caura_doc` search | 30/second | `RATE_LIMIT_SEARCH` |
  595. | `POST /ingest/preview`, `/ingest/file`, `/interview/submit`, `/insights/generate`, `/evolve/report` | `caura_insights`, `caura_evolve` | 10/minute, one budget across these | `RATE_LIMIT_LLM` |
  596. The tenant-wide budgets are `RATE_LIMIT_WRITE_TENANT`, `RATE_LIMIT_WRITE_BULK_TENANT`,
  597. `RATE_LIMIT_SEARCH_TENANT` and `RATE_LIMIT_LLM_TENANT`. A bulk write or ingest commit takes at most
  598. 100 items, and a preview at most 32 sections (one model call each). Beside the rate limits, each
  599. tenant has a cap on requests in flight per process, answered with 429 and `Retry-After: 1`: 16
  600. writes, 32 searches and 2 model-calling requests (`PER_TENANT_LLM_CONCURRENCY`). An MCP call
  601. refused by either gets a `RATE_LIMITED` error with `retry_after_seconds`.
  602. Every response from a rate-limited route carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
  603. `X-RateLimit-Reset`; a rejected request gets HTTP 429 with `Retry-After`. Counters live in Redis when
  604. `REDIS_URL` is set — which is what makes the limit hold across replicas — and in process memory
  605. otherwise, so a multi-instance deployment without Redis limits each instance separately. A Redis
  606. outage fails open: requests pass through un-throttled rather than erroring.
  607. `X-RateLimit-*` is the per-second throttle and nothing else. A deployment with a usage meter wired
  608. reports the separate per-period plan quota as `X-Usage-Limit` / `X-Usage-Remaining` on
  609. `POST /memories`, `POST /memories/bulk` and `POST /search`; OSS standalone has no quota, so those
  610. headers are absent there.
  611. Add limiting at your reverse proxy (nginx, Caddy, Cloudflare) as well if you need per-IP DDoS
  612. floors or limits the application layer can't see.
  613. ## Contributing
  614. We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, development setup, and how to submit PRs.
  615. ---
  616. ## FAQ
  617. **What is Caura?**
  618. Caura is open-source governed shared memory for AI agent fleets:
  619. cross-agent, cross-fleet recall with visibility scopes, trust tiers,
  620. keystone policies, audit trails, and tenant isolation enforced on every
  621. operation — plus self-improving retrieval through outcome-based learning.
  622. **How is Caura different from a vector database?**
  623. Caura uses pgvector under the hood but is not a vector DB wrapper. On top
  624. of hybrid search it adds fleet orchestration, per-agent retrieval tuning,
  625. contradiction detection, an 8-status lifecycle, an auto-extracted knowledge
  626. graph, LLM enrichment on every write, row-level tenant isolation, and audit
  627. trails on every operation.
  628. **How is Caura different from Mem0 or Zep?**
  629. Mem0 and Zep focus on memory for individual agents; accuracy benchmarks
  630. cluster all three tools in a narrow band. Caura is built for *fleets*:
  631. multiple agents across teams and vendors sharing one governed memory plane,
  632. with trust tiers, keystone policies, and cross-fleet permissions those
  633. tools don't address. See [How Caura compares](#how-caura-compares).
  634. **Does Caura work with Claude Desktop, Claude Code, Cursor, or Windsurf?**
  635. Yes — Caura is MCP-native. Paste a JSON config with a URL and API key
  636. into any MCP client and 12 tools appear immediately.
  637. **Can agents from different vendors share memory?**
  638. Yes — that's the point. An Anthropic agent recalls what an OpenAI agent
  639. wrote, under the same governance rules — with trust tiers and visibility
  640. scopes deciding what crosses fleet boundaries.
  641. **Is Caura really free?**
  642. The full engine — storage, 12 MCP tools, plugin, audit trail — is Apache
  643. 2.0. Run it yourself forever. The managed platform at
  644. [caura.ai](https://caura.ai) adds hosting, scaling, and enterprise
  645. governance for teams that don't want to operate infrastructure.
  646. **Who runs Caura in production?**
  647. eToro (NASDAQ: ETOR) uses Caura as a governed shared-memory layer for its
  648. AI-agent work.
  649. [Case study →](https://caura.ai/blog/etoro-company-brain/)
  650. ---
  651. ## License
  652. Caura is licensed under the [Apache License, Version 2.0](LICENSE).
  653. See [NOTICE](NOTICE) for copyright and third-party attributions.
  654. ## Trademarks
  655. "Caura" is a trademark of Caura. The Apache License 2.0 grants
  656. permission to use the source code but does not grant permission to use these
  657. names, logos, or branding in a way that suggests endorsement of, or affiliation
  658. with, any derivative work. See Apache License 2.0 §6 for the full legal terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.