Memclaw

Caura — AI Agent 的共享治理记忆

AI Agent 的集群记忆 — 受治理、共享、持续自我改进。

MemClaw 现已更名为 Caura — 产品不变，仅统一名称。
现有的 memclaw_* 工具调用和受支持的 MEMCLAW_* 环境别名仍可继续使用；配置时请使用 caura_* 名称和当前 Caura URL。PyPI 名称 memclaw-client 仅作为重定向占位包保留（0.5.1），用于安装 caura-client；它不提供 memclaw_client 导入，也不提供 MemClaw 类。npm 包 @caura/memclaw-client 从未发布。

快速开始 · 功能 · 集群记忆指南 · 性能 · MCP · API 参考 · 插件文档 · 参与贡献 · Discord

---

Caura（原名 MemClaw）—— AI Agent 集群的共享治理记忆层

Caura（原名 MemClaw）是面向多租户、多 Agent AI 集群的开源记忆系统。你的 Agent 会存储学到的内容、查找集群掌握的知识，并在每次交互中变得更聪明——彼此学习，不再重蹈覆辙。

Agent 只需写入纯文本。Caura 会将其转化为可搜索、受治理且能自我改进的记忆。

一个循环，三大支柱：写入、回忆、累积——每次交互都会让下一次变得更智能。

为集群而构建。 一个 Agent 就能运行，这也是大多数团队的起点——以下内容对单 Agent 配置没有任何改变。Caura 带来的是更大的扩展空间：从首次写入开始，就能使用范围限定的记忆、跨 Agent 的结果传播，以及集群范围的信任层级；随着 Agent 数量增加，这些能力会持续发挥价值。公开的 Agent 记忆基准测试（LoCoMo、LongMemEval）衡量的是一个 Agent、一个用户和一段长对话——也就是单聊天机器人的模式。集群治理和特定工作负载的延迟仍需在其实际应用环境中验证。经批准的基准测试结果请见生成的性能区块和证据登记表，也可阅读基准测试说明。

生产案例研究： eToro 在其 AI Agent 项目中使用 Caura 作为受治理的共享记忆层。 深入了解架构 →

---

快速开始

本地试用 — 无需 API 密钥，无需注册

最快了解 Caura 如何运行的方式。独立模式以单租户方式运行，并绕过身份验证 — 启动 Caura，写入一条记忆，再把它找回来。（没有密钥就无需配置：记忆会在不使用嵌入的情况下存储，并通过关键词查找。添加 AI 提供商密钥即可进行语义搜索 — 见下文的自托管。）

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"}'

无密钥的强写入响应包含 memory_type、title、status 和 weight — 以及 metadata 下的 summary — 这些内容均由本地确定性启发式算法根据单个 content 字段生成。配置 AI 提供商后，这些值将由模型推断，metadata 还可以包含 tags。

想尝试语义释义匹配？ 无密钥查询会有意复用记忆中的词语。在下一节 配置嵌入提供商后，试试 "authentication token lifetime" — 将该短语与“JWT with 15-minute expiry”匹配，即可体验语义回忆。

查看集群效果

如需了解架构、评估清单和稳定的 GitHub 原生引用 目标，请参阅面向 AI Agent 集群的共享持久记忆。

将两个 MCP 客户端连接到同一集群。Agent A 使用 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 从该集群调用 caura_recall：

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

结果将 deploy-agent 标识为作者：一个 Agent 学到了这条经验，另一个 Agent 则复用了它。scope_agent 会将记忆设为私有； scope_team 会在集群内共享记忆；scope_org 则支持受治理的 跨集群回忆，并遵循信任阶梯。 在生产环境中，为每个客户端提供独立的 Agent 范围凭证。

准备好进行语义回忆、使用多租户、托管主机或 OpenClaw 集群了吗？请从下方选择一种方式。

---

有四种方式 — 选择适合你设置的一种：

方式	适用场景	首次记忆所需时间
托管平台	最快捷。我们托管数据库并负责扩展。	~2 分钟
自托管（Docker）	注重隐私 / 本地部署 / 隔离网络。	~5 分钟
OpenClaw 插件	你已经在运行 OpenClaw 集群 — 将 Caura 作为插件安装，可连接上述任一种方式。	~3 分钟
Rail SDK	你使用 Python 或 TypeScript 自行编写 Agent，并希望它在每轮交互前回忆规则和事实、之后存储所学内容。适用于上述任一种方式。	~2 分钟

托管平台

几分钟即可开始使用 — 无需基础设施，包含自动更新、使用分析和企业级安全保障。

1. 在 caura.ai 免费注册。
2. 在控制面板的 Connect › Keys 下创建 API 密钥。
3. 通过 MCP 或 REST 连接：

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

对于生产集群，为每个 Agent 配置一个 Agent 范围凭证。有关凭证范围、 请求头和配置方式，请参阅 不使用 OpenClaw 插件进行集成。

使用租户范围的控制面板密钥？在每次 MCP 工具调用中传入明确的 agent_id；网关会拒绝该路径上的保留默认值 mcp-agent。

自托管（开源）

Docker Compose 会启动 PostgreSQL + pgvector、Redis、存储服务、REST/MCP API，以及 core-operations 生命周期调度器（夜间过期、归档、清除和结晶）。上面的无密钥示例是最快的入门方式；添加一个提供方即可实现语义回忆。

• 完整的自托管指南 — 提供方、身份验证、服务拓扑、安全性、离线运行和测试
• 本地嵌入器 — 完全本地的语义搜索，无需调用云 API
• 不使用 Docker 手动部署

OpenClaw 插件

已经在运行 OpenClaw 机群？将 Caura 作为插件安装，对接托管平台或自托管服务：

该插件会占用 OpenClaw 的 memory 插槽，并提供相同的面向 Agent 的记忆工具。请使用 Agent 安装程序的一行式设置，然后参阅 OpenClaw 集成指南，了解 Agent 提示词和信任级别。已经有节点在运行？如何保持节点为最新状态 — 包括自动升级和手动重新安装 — 请参阅 docs/plugin-upgrade.md。

该插件只会与您配置的 Caura 服务通信（CAURA_API_URL），并在每个请求中通过 User-Agent: openclaw-plugin/<version> (node/<major>) 标识自身，服务端的自托管心跳机制会据此统计已连接的插件安装数；同时还会通过 X-Caura-Surface: openclaw_plugin 标记其写入所生成的审计行 （审计归属）。它不会通过普通的 http:// 将 CAURA_API_KEY 发送到回环地址以外的任何位置：请将 CAURA_API_URL 指向 https://，或在插件的 .env 中设置 CAURA_ALLOW_INSECURE_HTTP=true，以便在受信任的专用网络中接受明文传输。

Python 客户端

通过 Python 连接任何托管或自托管的 Caura 部署：

pip install caura-client

示例和完整 API 请参阅 Python 客户端指南。

TypeScript 客户端

Node 18+ 客户端没有运行时依赖：

npm install @caura/client

有关安装和包名称兼容性详情，请参阅 TypeScript 客户端指南。

Rail SDK

让 Agent 在每轮交互中都具备记忆。Rail 会在 Agent 运行前获取治理规则和与当前消息相关的事实，提供可直接用于提示词的上下文，然后提取并存储本轮交互带来的信息。Python 和 TypeScript 语义一致；两者都适用于托管和自托管的 Caura。

pip install caura-rail        # Python 3.10+
npm install @caura/rail       # Node.js 22+

通过 CAURA_URL 和 CAURA_API_KEY 将其指向任意 Caura（对于上文的独立 Docker 服务：http://localhost:8000 和 standalone），然后包装每轮 Agent 交互：

from caura_rail import MemoryScope, Rail, RestMemoryStore

with RestMemoryStore.from_env() as store:
    rail = Rail(store, MemoryScope(agent_id="support-1", fleet_id="support"))
    with rail.turn("Remember: We deploy in eu-west-1.") as turn:
        # Call your model here; turn.context.text holds rules first, then facts.
        turn.reply = "Noted. " + turn.context.text
    print([w.status for w in turn.writes])   # ['written'], or ['deduplicated'] on a rerun

import { MemoryScope, Rail, RestMemoryStore } from "@caura/rail";

const rail = new Rail({
  store: RestMemoryStore.fromEnv(process.env),
  scope: new MemoryScope({ agentId: "support-1", fleetId: "support" }),
});
const turn = await rail.turn("Remember: We deploy in eu-west-1.", (_, ctx) => "Noted. " + ctx.text);
console.log(turn.writes.map(w => w.status));   // ['written'], or ['deduplicated'] on a rerun

每轮交互都会先回忆、运行您的代码，再提取并写入；如果代码引发错误，该轮不会写入任何内容；临时错误导致写入失败时，写入会留在发件箱中，供您稍后重放。只需调用 API 时，请使用上面的客户端；如果希望 Agent 记住信息并遵循规则，请使用 Rail。指南、API 参考和可靠性语义请参阅 Rail 仓库。

---

⭐ 如果 Caura 正好满足了您的需求， 请为仓库点星 — 这能帮助其他机群构建者找到我们，也会影响我们能投入多少时间来开发开源版本。

---

功能

治理

• 租户隔离 — 按租户进行行级数据库隔离；每次写入时自动检测 PII 并标记（在记忆元数据中显示为 contains_pii/pii_types）
• 可见性范围 — 每条记忆在写入时都会标记：scope_agent（私有）、scope_team（全体 Agent 可见，默认值）或 scope_org（跨团队）。跨团队检索受权限控制，并非开放访问
• Agent 信任级别 — 四个级别控制跨团队读取、写入和删除。Agent 可通过托管平台（caura.ai）上的 POST /admin/agent-keys/provision 原子化配置（可自托管的 core-api 不提供此路由），也可在首次写入时自动注册
• 完整审计日志 — 每次写入、删除和状态转换都会记录，并包含租户与范围上下文
• Agent 活动摘要 — 对已选择启用的组织，由服务端按组织设定的周期生成每个 Agent 的摘要（组织设置 agent_digest.enabled，默认关闭；agent_digest.cadence：默认 daily，也可设为 weekly 或 both；采用默认设置的组织不会收到每周摘要）。摘要由 core-operations 的 agent-digest / agent-digest-weekly cron 定时任务生成，并通过 core-api 中的报告端点读取（GET /api/v1/reports、GET /api/v1/reports/agent-activity）。未选择启用的租户无需承担任何费用

记忆处理流水线

• 单次 LLM 增强 — 每次写入都会自动将内容分类为 7 种记忆类型之一（服务器自行写入 outcome、rule 和 insight），生成标题与摘要、评估重要性、标记 PII 并提取实体，所有操作均基于单个 content 字段完成
• 混合搜索 — 结合 pgvector 语义相似度、全文关键词匹配和知识图谱扩展（最多 2 跳），并根据相似度、重要性、新鲜度和图谱加权分数进行排序。当结果集同时包含已被取代的记忆及其替代记忆时，替代记忆的排名始终紧随其上；过时记录可能会出现，但绝不会排在其自身修正内容之前
• 实时知识图谱 — 每次写入时都会提取人员、组织、地点和概念，并将其存储为实体和关系。实体消歧首先进行精确名称匹配，然后进行确定性的规范名称匹配（忽略大小写和空格差异，并忽略开头的 the/a/an/new/old/current/existing/legacy——因此 “the new analytics service” 和 “analytics service” 会被视为同一实体），最后进行语义相似度匹配（余弦相似度 >0.85）。只有在剩余至少两个词时才会忽略限定词，因此 “new york” 永远不会与 “york” 合并。实体中会保留出现过的所有表层形式，作为别名
• 矛盾检测 — 通过 RDF 三元组比较和 LLM 语义分析检测相互冲突的记忆，并自动将其标记为已被取代，同时完整追踪矛盾链

自我改进型记忆

• 基于结果的学习（Karpathy Loop） — Agent 根据检索到的记忆采取行动后，会报告成功或失败；系统会强化有效内容，并在失败时自动生成预防性的 rule 类型记忆
• 记忆结晶 — LLM 将近似重复的记忆合并为规范的原子事实，并保留完整来源信息；8 种状态的生命周期自动化机制会淘汰过时数据
• 按 Agent 调整检索 — 每个 Agent 都会根据反馈优化自己的检索配置（top_k、min_similarity、graph_max_hops、混合权重），因此搜索质量会随着每次交互不断提升

集成

• MCP 服务 — 内置 Model Context Protocol，位于 /mcp（Streamable HTTP）。使用 URL 和 API 密钥，即可连接 Claude Desktop、Claude Code、Cursor、Windsurf 或任何 MCP 客户端
• 多提供商 LLM — 每个租户都可配置主提供商和备用提供商链（OpenAI、Gemini、Anthropic、OpenRouter）；未配置的租户可使用平台默认值
• 文档存储 — 除语义记忆外，还支持结构化 JSONB 集合，用于精确字段查询（客户记录、配置、任务列表）

Caura 对比情况

准确率基准测试显示，领先工具的表现集中在一个很窄的区间内（请参阅 性能）。各工具真正拉开差距的地方在于集群能力和治理：

能力	Caura	Mem0	Zep	Letta
多集群支持	✅	❌	❌	❌
Agent 信任等级 + keystone 策略	✅	❌	❌	❌
跨供应商记忆共享	✅	❌	❌	❌
矛盾检测 + 替代处理	✅	❌	❌	❌
按 Agent 调整检索	✅	❌	❌	❌
PII 检测与标记	✅	❌	✅	❌
审计跟踪 / 来源追溯	✅	❌	⚠️ 部分支持	❌
知识图谱（自动提取）	✅	⚠️	✅	❌
原生支持 MCP	✅	✅	✅	⚠️
OSS 许可证	Apache 2.0	Apache 2.0	Apache 2.0	Apache 2.0

Mem0、Zep 和 Letta 都是可靠的项目；对于单个 Agent 来说，它们都很适用，Caura 也一样。超过一个 Agent 后，各自的定位便会分开：Caura 专注于跨 Agent 集群的受治理记忆，让多个 Agent、团队和供应商在同一个可审计的记忆平面上协作。以上比较反映了我们截至 2026 年 6 月对公开文档的解读，欢迎通过 issue 或 PR 提出更正。

---

性能

我们针对引用最多的两项公开 Agent 记忆基准测试进行了评测。完整结果、方法和复现步骤请参阅 BENCHMARKS.md；运维规模方面的背景信息请参阅 docs/performance.md；完整评测文章见博客。

• LoCoMo 准确率： Caura 在其文档说明的 LoCoMo 语义判定协议下，使用 retrieval-augmented agentic-v1 流程得分为 77.9%（1,199/1,540）。
• LongMemEval 参考判定器： 在基准测试的 GPT-4o 参考判定器下，Caura 正确回答了 500 个 LongMemEval_S 问题中的 461 个（92.2%）。
• LongMemEval 次级判定器： 同一组冻结的 500 个 LongMemEval_S 答案，在次级 Gemini 3.5 Flash-Lite 判定器下得分为 90.2%（451/500）。
• LongMemEval 令牌效率： 在 LongMemEval_S 上，检索到的紧凑上下文中位数为 22,410 个令牌，而完整 haystack 为 107,706 个令牌：仅计算上下文可节省 79.2%；计入每次读取器调用后可节省 75.4%。

此处仅列出当前有效且已批准的声明。受控、已撤回和暂不公开的记录仍保留在证据注册表中，不会用于宣传文案。 请参阅 evidence/claims.json 和 EVIDENCE.md。请勿手动编辑此区块。

---

MCP（Model Context Protocol）

只需一个配置块，即可将 Caura 添加到任意 MCP 客户端。

自托管（localhost）：

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

托管平台（caura.ai）：

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

若用于团队或生产环境，请将租户范围的密钥换成 Agent 范围的凭证——在托管平台（caura.ai）上，通过 POST /api/v1/admin/agent-keys/provision 原子化创建（或在 Caura 应用的 Connect › Keys 下选择 Create agent key），即可在一次往返中生成凭证、Agent 行、初始信任级别和集群成员关系。这两种密钥均使用 mc_ 前缀；凭证的范围在创建时设定。请参阅 docs/integration-without-plugin.md。使用租户范围的凭证？每次调用 MCP 工具时都要传入明确的 agent_id——网关会拒绝租户范围路径下保留的默认值（mcp-agent）。

配置位置：

• Claude Code——Claude Code 不会从 settings.json 读取 MCP 服务。请改用 claude mcp add 注册服务。使用 -s user，这样它就能在所有工作目录中使用——默认范围（local）只会在当前目录注册；如果你在多个文件夹中运行 Agent，就会遇到这个问题：

  claude mcp add --transport http -s user caura http://localhost:8000/mcp --header "X-API-Key: standalone"
  

  （或者，将上面的 JSON 配置块提交到项目根目录的 .mcp.json，以注册项目范围的服务。）
• Claude Desktop——~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）
• Cursor——Settings > MCP Servers > Add Server

客户端会自动发现 12 个工具：

工具	用途
caura_write	单条或批量写入（最多 100 项）。由大模型推断类型、标题、摘要、标签和嵌入向量
caura_recall	结合语义与关键词的混合回忆，使用图增强检索；可选大模型简报
caura_manage	管理每条记忆的生命周期：read、update、transition、delete、bulk_delete、lineage
caura_list	按类型/状态/Agent/权重/日期筛选，排序并通过游标分页
caura_doc	文档 CRUD：在命名 JSON 集合中执行 write、read、query、delete、list_collections、search（语义搜索）
caura_entity_get	查找实体及其关联记忆和关系
caura_tune	调整每个 Agent 的检索参数（top_k、min_similarity、graph_max_hops 等）
caura_insights	通过 6 种关注模式分析记忆库。分析结果会作为 insight 记忆持久保存
caura_evolve	汇报回忆记忆的结果——调整权重并生成规则（Karpathy Loop）
caura_stats	汇总计数：总数及按类型、Agent、状态划分的细分统计。只读
caura_keystones	读取当前范围的强制治理规则。每个会话调用一次——结果优先于与之冲突的用户指令
caura_keystones_set	创建或移除基石规则（op=set|delete）。weight 设置为 low/med/high，存储并返回为整数档位 25/50/100。为自己创建规则需要 Trust ≥ 1——scope=agent 且明确指定与调用方相同的 agent_id；scope=fleet/scope=tenant、其他 Agent，或省略 agent_id 的 scope=agent 则需要 Trust ≥ 2

技能共享现在通过 caura_doc 完成——Agent 通过向 skills 集合写入或更新文档来共享 SKILL.md（caura_doc op=write collection=skills doc_id=<slug> data={"summary": "<one-liner>", ...}）。服务器会为 data["summary"]（1-3 句、以意图为重点）生成嵌入向量，用于语义搜索；对于 collection="skills"，若未提供 summary，则会改用 data["description"]。专用的 memclaw_share_skill / memclaw_unshare_skill 工具已移除，统一由 caura_doc 提供功能。

技能工厂

手动分享技能（如上所述）只是基础。技能工厂是在 skills 集合之上构建的治理系统——它根据整个 Agent 集群的行为自动生成技能，对上线内容进行把关，并将启用的技能交付给你的 Agent。它按租户选择启用，默认关闭：在租户设置中将 skills_factory.enabled = true（使用 PUT /api/v1/settings 并传入 {"skills_factory": {"enabled": true}}，或在 caura.ai 的 Caura 应用中选择“设置”›“租户设置”）之前，skills 集合的行为与上述描述完全一致（没有生命周期，所有存储的技能均可见）。包含三大支柱：

• 创作——Agent 和 Forge。 Agent 可通过 caura_doc op=write collection=skills 直接创作技能。Forge 是驻留在服务端的组件，也会挖掘记忆和结果信号，对反复成功的流程进行聚类，并将其提炼为技能候选项——Agent 无需记得去编写技能。
• 治理——生命周期。 每项技能都有一个状态：candidate → staged → active（也可转为 rejected / quarantined / stale / deprecated）。六个自动化关卡加上 Sentinel 内容扫描共同决定哪些技能可以晋级；技能收件箱则通过 REST 接口让操作员批准、编辑、暂缓、拒绝或隔离已暂存的技能——GET /api/v1/skills-inbox 会列出已暂存的卡片，而 POST /api/v1/skills-inbox/{slug}/approve|edit|defer|quarantine|reject 会对其执行相应操作（在 caura.ai 的 Caura 应用中，组织管理员可在“审核”›“待批准技能”中处理同一队列）。Agent 写入的技能会进入 staged 状态，不会立即变为 active。
• 交付——拉取与推送。 Agent 可通过 MCP 拉取启用的技能（caura_doc op=search/op=read），也可由 OpenClaw 插件推送：它的协调器会从 POST /api/v1/skills/installable 获取所有启用的技能，并将每项技能写入节点的技能目录，还可选择将该目录注册到 OpenClaw 的加载路径中。启用此功能后，两个层级都只提供已启用的技能。

深入了解：docs/mcp-skill-delivery.md（仅交付已启用技能的约定和插件协调目标）、docs/operator-forge-cron.md（Forge 的调度），以及 docs/skills-inbox-api.md（技能收件箱的操作员 REST API）。 完整的操作员/开发者指南请参阅 Caura 文档 → 技能工厂。

Interviewer

caura_write 记录的是 Agent 选择记录的内容。Interviewer 记录的是它做过的事。它会按计划读取 Agent 自己的持久工作轨迹——运行框架本就会保留的对话记录或事件日志——并请大模型将活动综合整理为有类型的记忆，让 Agent 来不及记录的决策、阻碍和偏好也能保存下来。它绝不会重新运行 Agent——只会使用真实轨迹，因此内容有实际活动作为依据。（大模型综合整理仍可能误读或夸大，因此请将 Interviewer 记忆视为有用的近似记录，而非逐字记录。）

这是 Caura 引入记忆的第三种方式，与实时写入和摄取并列。和 Skill Factory 一样，它按租户选择启用，且默认关闭——只有在租户设置中将 interviewer.enabled = true（通过 PUT /api/v1/settings，或在 caura.ai 的 Caura 应用中进入 Settings › Tenant settings）后才会启用。

• 写入内容。 六个报告部分映射到记忆类型枚举： worked_on → episode、decisions → decision、outcomes → outcome、 blockers → task、open_questions → fact、preferences_learned → preference。这些内容会作为普通的、经过丰富处理、嵌入并受治理的记忆写入，同时保留轨迹中的真实事件时间戳。
• 捕获活动的方式。 两类方式，共用一种提交协议：
  • 插件缓冲 — OpenClaw 插件会在节点本地维护一个持久缓冲区，并提交时间窗口（在插件环境变量中添加 CAURA_INTERVIEWER=true）。
  • 磁盘解析器 — caura-interviewer CLI（随 caura-client 软件包一同发布）以只读方式读取运行框架磁盘上的对话记录，并提交时间窗口。目前支持 Claude Code（~/.claude/projects）和 Cursor（~/.cursor/…/agent-transcripts）；计划支持 Hermes 等其他产品。
• 从设计上确保崩溃安全。 每个窗口都会先使用确定性的尝试 ID（sha1(node_id:cursor_from:cursor_to)）写入，然后推进每个节点的水位标记——如果中途崩溃，重新提交时会进行去重，因此不会遗漏，也不会重复。本地不保存游标状态；服务器水位标记是唯一可信来源。
• 隐私。 磁盘解析器默认拒绝——除非将项目加入允许列表，否则不会收集任何内容——并且会在本地提交前清除类似凭据的字符串，随后在服务器端再次屏蔽。

触发方式包括定期 run（cron）和／或会话结束时的 hook；两者可以安全地组合使用，因为重复提交会被去重。完整设置说明、各运行框架的接入方式和协议请参阅 Caura 文档 → Interviewer。

Caura Broker

Caura Broker 是一个本地守护进程（caura-daemon，以前称为 memclawd，由 caura CLI 驱动），运行在开发者的机器上，将编码 Agent——Claude Code、Codex、Cursor、Gemini——连接到 Caura。它的职责是在开发者侧建立信任边界：在任何内容离开机器之前执行策略、应用脱敏，并保留防篡改审计日志。Broker 开箱即以个人模式运行；加入 Broker Fleet（由多台机器组成的机群——与 fleet_id 记忆范围不同）的安装实例由统一管理：包括心跳、策略流和共享仪表板。

Broker 本身单独发布，但其服务端身份认证机制位于此代码库中：Broker 调用通过 X-Caura-Credential-Kind: install_credential 和 X-Install-UUID 进行身份验证，其写入内容归属到 broker:<install> 所有权命名空间下——参见 core-api/src/core_api/mcp_server.py 和 core-api/src/core_api/auth.py。 Broker 与云端之间的线路协议冻结在 v1：两个代码库都在 CI 中运行 oasdiff 破坏性变更检查（此代码库中的基线由 core-api/scripts/gen_broker_openapi.py 生成，检查在 #620 中加入），因此破坏协议的变更会导致构建失败，而不会破坏已安装的 Broker。操作说明——安装、加入机群、策略——请参阅 Caura 文档 → Broker Fleet。

安装技能（Claude Code 和 Codex）

将 Caura 使用指南安装为技能，让 Agent 知道何时以及如何使用这 12 个工具——记忆/文档的思维模型、三条规则（召回、写入、取代）、信任等级、常见模式和反模式。技能按需加载（而非每轮加载），因此在 Agent 使用 Caura 之前不会产生任何开销。

前置条件： 已注册 MCP 服务（Claude Code 使用 claude mcp add -s user，Codex 使用相应配置——参见上方的配置代码块）。运行 claude mcp list 确认——你应该能看到 caura: ... ✓ Connected。

选项 A — 一行命令（最快）

自托管（localhost）：

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

托管平台：

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

选项 B — 下载、检查并运行（推荐用于 Agent）

自动化 Agent（Claude Code、Codex）可能会出于安全考虑拒绝执行 curl | 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

选项

查询参数	效果
（无）	为 Claude Code 和 Codex 安装默认的 Caura 工具参考技能
?agent=claude-code	仅安装到 Claude Code → ~/.claude/skills/<skill>/SKILL.md
?agent=codex	仅安装到 Codex → ~/.agents/skills/<skill>/SKILL.md
?skill=company-brain	安装可选的 Company Brain 姿态技能，而非默认技能（见下文；可与 ?agent= 组合）

验证

ls -la ~/.claude/skills/memclaw/SKILL.md       # Claude Code; legacy-name-floor: installed default-skill path
ls -la ~/.agents/skills/memclaw/SKILL.md       # Codex; legacy-name-floor: installed default-skill path

安装后重启 Agent——技能会在启动时加载。 随时重新运行安装程序以获取最新版本。

OpenClaw 插件用户会在安装插件时自动获得该技能；跳过此步骤。

可选：Company Brain 技能

默认技能会教 Agent 如何使用工具。company-brain 是一个精简、以概念为先的姿态技能，叠加在默认技能之上：它将 Agent 定义为共享 Company Brain 中的一个思维主体，并将所有工具使用细节交由工具参考技能处理。需要这种定位时，请同时安装这两项技能：

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

该技能会安装到 ~/.claude/skills/company-brain/SKILL.md（Claude Code）和/或 ~/.agents/skills/company-brain/SKILL.md（Codex），并遵循相同的 ?agent= 筛选条件。默认安装（不指定 ?skill=）不变——只会安装默认的工具参考技能。

---

部署

推荐通过 Docker Compose 运行 Caura（参见快速开始）。只需一条命令，即可部署可用于生产环境的 PostgreSQL + pgvector + Redis + API 技术栈。

已发布的容器映像

每次发布都会将多架构（linux/amd64、linux/arm64）映像推送到 GitHub Container Registry：

ghcr.io/caura-ai/caura-memclaw-core-api:v2.5.0 # legacy-name-floor: published GHCR repository name
ghcr.io/caura-ai/caura-memclaw-core-storage-api:v2.5.0 # legacy-name-floor: published GHCR repository name
ghcr.io/caura-ai/caura-core-operations:v2.5.0

caura-core-operations 是生命周期调度器，比另外两个组件更新，也以新名称发布，因此在它加入技术栈之前的版本没有对应映像。

标签遵循 SemVer，并提供浮动别名——:v1、:v1.0、:v1.0.0，以及指向最新稳定版本的 :latest。在自己的 compose 文件或 Kubernetes 清单中拉取这些映像，而不是从源代码构建。

手动部署（不使用 Docker）

Caura 由两个 FastAPI 服务组成，两者都可以在任何 ASGI 服务端（uvicorn、hypercorn）下运行。core-storage-api 负责数据库，并在启动时应用迁移。core-api 提供 REST 和 MCP API，且仅通过 core-storage-api 访问数据库。要求：

• Python 3.12+
• PostgreSQL 16+，并启用 pgvector 扩展，供 core-storage-api 使用
• Redis（可选——不可用时会回退到内存缓存）

两个服务都需要相同的非空 CORE_STORAGE_SHARED_SECRET，且没有该变量时 core-api 会拒绝启动。通过 CORE_STORAGE_API_URL（默认值为 http://localhost:8002）将 core-api 指向存储服务。AGENT-INSTALL.md，选项 B 介绍了完整的安装流程，其中包括 pip install -r requirements.txt。

启动每个服务之前，将 .env 导出到进程环境中。服务会从各自的 .env 加载设置，但有些参数只从环境变量读取：嵌入器（OPENAI_EMBEDDING_*、EMBEDDING_QUERY_INSTRUCTION）、重排器（RANK_*）和提供商模型覆盖项（*_DEFAULT_MODEL）。.env.example 将这些部分标记为“env-only”。Compose 的 env_file: 会将它们放入环境中；直接运行 uvicorn 则不会。导出的值优先于 .env 中的值，因此编辑 .env 后要重新导出。加载文件会将每一行都交给 shell，因此包含空格、引号或 $、&、;、反引号等 shell 字符的值（例如密码）要用单引号括起来。否则 shell 会篡改该值，而被篡改的值会覆盖 .env 中的值。

set -a; . ./.env; set +a
PYTHONPATH=.:core-storage-api/src uvicorn core_storage_api.app:app --host 127.0.0.1 --port 8002
# Then, in a second shell with the same .env exported:
WEB_CONCURRENCY=2 PYTHONPATH=.:core-api/src uvicorn core_api.app:app --host 0.0.0.0 --port 8000

如果没有指定 --workers，uvicorn 会从 WEB_CONCURRENCY 读取工作进程数，core-api 也会读取同一变量：当 USE_STM=true 且 STM_BACKEND=memory 时，如果工作进程数超过 1，它会拒绝启动，因为每个工作进程都会维护各自的 STM。此时请使用 STM_BACKEND=redis。

部署拓扑

Caura 的存储层支持两种运行模式。**单节点（默认）**是通过 Docker Compose、pip install 或任何全新部署获得的模式——一个 core-storage-api 实例同时处理读取和写入。对于写入速率没有持续达到每秒 100 次以上的部署，这是合适的选择。

读写分离是高写入速率部署可选的拓扑，可独立扩展读取能力，例如将读取流量指向 Postgres 流复制副本。启用后，需要运行两个职责不同的 core-storage-api 服务，并让 core-api 同时指向它们：

• 在处理写入的实例上设置 CORE_STORAGE_ROLE=writer；在处理读取的实例上设置 =reader。
• 在 core-api 上将 CORE_STORAGE_READ_URL 设置为读取服务的 URL。让 CORE_STORAGE_API_URL 继续指向写入服务。
• 每个 core-storage-api 上的 READ_DATABASE_URL 都可以指向只读副本（如果有）。在写入服务上，它用于处理可容忍副本延迟的读取请求。在读取服务上，每个查询都会使用它，且不会连接 DATABASE_URL。
• 在 core-api、每个 core-storage-api 写入/读取实例以及任何其他内部存储调用方上，设置相同且非空的 CORE_STORAGE_SHARED_SECRET。所有存储请求都必须携带 X-Storage-Secret；缺失或不正确的凭据会在路由前被拒绝。

拓扑默认值： CORE_STORAGE_ROLE=hybrid 且 CORE_STORAGE_READ_URL=""，因此单个存储实例仍会同时处理读取和写入。Docker Compose 会自动配置存储身份验证；手动部署必须在存储服务和每个调用方上配置 CORE_STORAGE_SHARED_SECRET（或 CORE_STORAGE_SHARED_SECRET_FILE）。

---

从 v1.x 升级

2.0 版将嵌入向量维度从 768 扩展到 1024。现有安装必须明确选择执行具有破坏性的迁移、创建数据库快照，并重新嵌入已存储的数据。

在拉取 v2 镜像前，请遵循完整的 v1.x → v2.x 升级指南。

---

API 参考

带版本号的 REST 路由位于 /api/v1/ 下；MCP 则单独挂载在 /mcp。运行中的部署会在 /api/openapi.json 提供权威的 OpenAPI 架构，并在 /api/docs 提供交互式 Swagger 文档。

请参阅精选 API 参考，了解端点分组、 身份验证、配置和仓库结构。API 表面职责章程说明哪些操作属于 REST、MCP 或 OpenClaw 插件。

---

公共 API 与稳定性

Caura 遵循 SemVer。稳定的 MCP 工具、REST 端点、插件变量、 身份验证模式和贡献者要求均载于公共 API 稳定性契约。

---

遥测

更新于 2026-09-19。 可自托管的服务每天会向 telemetry.caura.ai 发送 每个容器一条匿名心跳，与工作进程数量无关：包括其版本、Python/OS/架构、部署类型（docker 或源代码）、运行时长区间、提供商类型（绝不包括模型名称或密钥）、是否配置了 Redis 和 Sentry（绝不包括具体值）、记忆、Agent、租户和近期出现过的插件节点的分档计数，以及调用该服务的 SDK 系列分档计数。所有数值都按区间统计（0、1、2-5、6-20……）；ID 是随机 UUID，存储在你自己的数据库中，绝不会发送主机名、IP、名称、内容或配置值等任何信息。完整负载、JSON 架构、保留政策和变更日志见 docs/telemetry.md。

以下方式均可关闭遥测，且对该安装永久生效：

• 在 core-api 的环境中设置 CAURA_TELEMETRY=off（在 .env 中设置，或取消 docker-compose.yml 中 core-api 下方对应行的注释）。
• 设置 DO_NOT_TRACK=1（遵循 Console Do Not Track 约定）。
• 将 CI 设置为非空值：不会统计流水线。
• 在防火墙中屏蔽 telemetry.caura.ai:443：每天尝试一次，超时时间为 5 秒，不重试。
• 通过企业网关运行或使用平台提供商时，遥测会自动关闭。

通过 GET /api/v1/telemetry 检查服务将要发送的内容、上次尝试发送的时间及发送是否成功；通过 POST /api/v1/telemetry/rotate 使用新 ID 重新开始。每次启动时，启动日志都会显示启用/关闭决定、原因和关闭提示；如果 CAURA_TELEMETRY_URL 配置错误（使用纯 http://，且目标不是 localhost），心跳会发出警告并关闭，而不会以明文发送。

错误跟踪仍为可选功能：设置 SENTRY_DSN，即可启用可选的 Sentry 集成，用于错误跟踪和性能监控。除非你明确配置 DSN，否则不会报告任何错误。

除心跳外，可自托管的部署不会发起其他出站调用，除非你配置了 Sentry DSN 或大模型/嵌入提供商。托管平台的使用分析是托管服务功能，不属于可自托管运行时的一部分。

---

速率限制

速率限制由进程内的 slowapi 强制执行：存在 API 密钥时按 API 密钥限流，否则按远程 IP 限流。速率限制按路由应用，而非全局生效——/health、/version 和 /mcp 永不受限：

路由	默认值	设置项
POST /memories、POST /documents、POST /ingest/commit、POST /stm/promote	10/秒	RATE_LIMIT_WRITE
POST /memories/bulk	2/秒	RATE_LIMIT_WRITE_BULK
POST /search、POST /recall	30/秒	RATE_LIMIT_SEARCH

来自受速率限制的路由的每个响应都会包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset；遭拒的请求会收到 HTTP 429 响应及 Retry-After。设置 REDIS_URL 时，计数器存储在 Redis 中——这使限额能够在多个副本间生效；否则计数器存储在进程内存中，因此未使用 Redis 的多实例部署会分别限制每个实例。Redis 中断时会默认放行：请求不受限地通过，而不会报错。

X-RateLimit-* 仅表示每秒限流，除此之外没有其他用途。接入用量计量器的部署会通过 POST /memories、POST /memories/bulk 和 POST /search 上的 X-Usage-Limit / X-Usage-Remaining 报告单独的周期计划配额；OSS 独立部署没有配额，因此不会出现这些标头。

如果需要按 IP 设置应用层无法识别的 DDoS 防护阈值或限制，也请在反向代理（nginx、Caddy、Cloudflare）中添加限流。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解相关指南、开发环境设置以及如何提交 PR。

---

常见问题

Caura 是什么？ Caura 是面向 AI Agent 集群的开源治理型共享记忆： 支持跨 Agent、跨集群回忆，并提供可见性范围、信任层级、 基石策略、审计跟踪，以及在每次操作中强制执行的租户隔离， 还可通过基于结果的学习持续改进检索。

Caura 与向量数据库有何不同？ Caura 底层使用 pgvector，但并非向量数据库封装。它在混合搜索之上 增加了集群编排、按 Agent 调优检索、矛盾检测、8 种状态的生命周期、 自动提取的知识图谱、每次写入时的大模型增强、行级租户隔离， 以及每次操作的审计跟踪。

Caura 与 Mem0 或 Zep 有何不同？ Mem0 和 Zep 专注于单个 Agent 的记忆；准确率基准测试中， 这三种工具的表现都集中在一个较窄的区间内。Caura 专为集群打造： 多个团队和供应商的 Agent 共用一个受治理的记忆平面， 并提供这些工具未涵盖的信任层级、基石策略和跨集群权限。 请参阅 Caura 的比较。

Caura 能与 Claude Desktop、Claude Code、Cursor 或 Windsurf 配合使用吗？ 可以——Caura 原生支持 MCP。将包含 URL 和 API 密钥的 JSON 配置粘贴到 任何 MCP 客户端中，即可立即使用 12 个工具。

不同供应商的 Agent 能共享记忆吗？ 可以——这正是它的用途。Anthropic Agent 可以回忆 OpenAI Agent 写入的内容，并遵循相同的治理规则——由信任层级和可见性范围决定 哪些内容可以跨越集群边界。

Caura 真的免费吗？ 完整引擎——存储、12 个 MCP 工具、插件、审计跟踪——采用 Apache 2.0 许可。可永久自行运行。caura.ai 上的托管平台 则为不想运维基础设施的团队提供托管、扩展和企业治理功能。

哪些组织在生产环境中使用 Caura？ eToro（NASDAQ：ETOR）将 Caura 用作其 AI Agent 工作的受治理共享记忆层。 查看案例研究 →

---

许可证

Caura 根据 Apache License, Version 2.0 授权。

有关版权和第三方归属信息，请参阅 NOTICE。

商标

“Caura”是 Caura 的商标。Apache License 2.0 允许使用源代码， 但不允许以暗示认可任何衍生作品或与其存在关联的方式使用这些名称、 徽标或品牌标识。完整法律条款请参阅 Apache License 2.0 §6。