caura-ai/caura · 上手攻略

• 仓库：caura-ai/caura
• 链接：https://github.com/caura-ai/caura
• 分类：AI Agent Infrastructure / Memory
• 作者：Tom
• 更新：2026-09-06

是什么

Caura（前身 MemClaw）是一个面向多租户、多 Agent 舰队（fleet）的开源共享记忆系统。它解决的核心问题是：当企业部署数十甚至数千个 AI Agent 时，如何让它们共享学习成果、统一治理记忆、避免重复犯错。

三个核心支柱：写（write）→ 召回（recall）→ 复合（compound），每轮交互都让下一次更聪明。Agents 只写纯文本，Caura 自动完成分类、摘要、实体抽取、矛盾检测，并存入可检索的记忆层。

⚠️ 注意：原名 MemClaw，工具前缀已从 memclaw_* 迁移到 caura_*；旧工具名、环境变量、URL 保持兼容，但 memclaw-client / @caura/memclaw-client 包名和 MemClaw 类别名已废弃。

解决什么问题

单 Agent 记忆方案（Mem0、Zep、Letta 等）在单一 Agent 场景表现相近，差距在 fleet 场景才真正显现：

• 跨 Agent 成果传播：Agent #17 今天犯的错，能否自动阻止 Agent #1~#40 下午重犯？Caura 的 outcome-based learning（Karpathy Loop）让这一机制开箱即用。
• 作用域记忆：记忆写入时即标注 scope_agent（私有）、scope_team（舰队内共享，默认）、scope_org（跨舰队，但需权限升级）。
• 信任层级 + 锚定策略：每个 Agent 有四级信任级别，跨舰队读写受 keystone policies 控制，不是开放通道。
• PII 隔离：写入时自动检测 PII，跨舰队暴露前自动隔离。
• 矛盾检测 + 自动 supersession：检测到冲突记忆时自动 supersede，保留完整矛盾链。
• 完整审计日志：每次写入、删除、状态转换均记录在案。

快速安装

方式一：单机无 Key 快速尝鲜（推荐先用这个）

git clone https://github.com/caura-ai/caura.git
cd caura
cp .env.example .env && echo "IS_STANDALONE=true" >> .env
docker compose up -d --wait

30 秒左右启动完成，内含 PostgreSQL + pgvector + Redis + API 服务。使用 dummy embeddings（无需配置任何 AI Provider），即可体验完整写入 / 检索流程。

⚠️ Standalone 模式仅用于本地演示，生产部署请配置真实的 embedding provider（OpenAI / Gemini / Anthropic / OpenRouter）。

方式二：Managed 平台（最简生产路径）

# 1. 在 https://caura.ai 注册，获取 API Key（mc_xxx 格式）
# 2. 在任意 MCP Client 配置：
{
  "mcpServers": {
    "caura": {
      "url": "https://caura.ai/mcp",
      "headers": { "X-API-Key": "mc_your_api_key_here" }
    }
  }
}

方式三：OpenClaw 插件

# 已在运行 OpenClaw 的环境，执行：
# 参考 https://github.com/caura-ai/caura/blob/main/AGENT-INSTALL.md
# 然后配置 MCP 连接 managed 或 self-hosted 实例

Python / Node 客户端

# Python
pip install caura-client

# Node 18+
npm install @caura/client

核心用法

MCP 工具调用（推荐方式）

安装 MCP client 后，四个核心工具：

写入记忆（caura_write）：

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

召回记忆（caura_recall）：

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

⚠️ visibility 可选值：scope_agent（私有）、scope_team（舰队内，默认）、scope_org（跨舰队，需 trust 升级）。不填默认 scope_team。

删除记忆（caura_delete）和更新记忆（caura_evolve）也有对应工具，详见 API Reference。

REST API

# 写入
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."
  }'

# 检索（无 Provider Key 时靠关键词匹配；配好 embedding 后支持语义检索）
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"
  }'

write_mode: strong 表示使用 deterministic local heuristic 生成 memory_type / title / summary / weight；配置 AI Provider 后改为 model-inferred 路径，并支持 tags。

Agent 级凭证（生产推荐）

不要在生产环境使用 tenant-scoped key 给每个 agent 共享，应为每个 agent 单独 mint 凭证：

POST /api/v1/admin/agent-keys/provision
# 原子操作：同时创建 key + row + trust + fleet

典型适用场景

坑与注意

1. Standalone 模式无语义检索：dummy embeddings 只能做关键词匹配；想体验语义召回必须配一个 embedding provider key（OpenAI / Gemini 等），不能跳过这一步验证语义搜索效果。
2. MemClaw → Caura 迁移：旧 memclaw_* 工具名、环境变量、URL 仍兼容，但 memclaw-client / @caura/memclaw-client 包已废弃；新项目不应再引用旧包名。
3. Trust 升级需要显式操作：scope_org 写入 / 读取不是自动开放的，必须走 trust ladder 流程提升权限，否则会报权限错误。
4. Agent-scoped credential 不能共享：每个 Agent 必须持有独立凭证；共用 tenant-scoped key 会导致审计日志混乱且无法做 per-agent 权限控制。
5. mcp-agent 是保留名：使用 tenant-scoped dashboard key 时，每个 MCP 工具调用必须显式传 agent_id，不能传 mcp-agent 这个默认值，否则会被 gateway 拒绝。
6. benchmark 数字是单 Agent 场景：LoCoMo 77.6%、LongMemEval 72.5% 是单 Agent 精度分数；Caura 的 fleet 维度（跨 Agent 传播、治理感知召回）没有公开 benchmark，是产品自称能力，需结合自身场景验证。
7. Single-pass LLM enrichment 不是免费的：每次写入触发一次 LLM 调用（分类 + 摘要 + 实体抽取 + PII 检测）；高频写入场景需考虑 token 成本。
8. 文档路径有时404：GitHub 上 /caura-ai/caura/blob/main/docs/xxx.md 有些文件不存在（如 docs/integration-guide.md），实际文档在 /blob/main/static/docs/integration-guide.md，或直接看 README 内联内容。

与同类对比

结论：Mem0、Zep、Letta 在单 Agent 场景都是成熟选择，精度指标也相近。Caura 的差异化在于 fleet-native：多 Agent 共享学习、治理、信任层级、跨团队隔离这些能力是其他产品没有明确解决的维度。如果你的场景只需要"给一个 Agent 加记忆"，选 Mem0 或 Zep 足矣；如果你的场景是"几十到上千个 Agent 在一个企业内协同"，Caura 是目前唯一把治理和跨 Agent 学习做进核心设计的开源方案。

一句话推荐结论

多 Agent 舰队场景，选 Caura；单 Agent 记忆需求，Mem0 / Zep 更轻量。