DOCSEARCHbyAlgolia
Submit Docs

Caura

repository·main·Indexed 43 days ago

https://github.com/caura-ai/caura-memclaw

A production-grade persistent memory platform and governed shared memory layer for AI agent fleets. Caura enables agents to store, recall, and learn from shared knowledge using semantic search, entity/relationship graphs, and tenant isolation. It provides official Python and TypeScript SDKs, as well as the caura-interviewer CLI for synthesizing memories from Claude Code and Cursor session transcripts.

Tokens
82.1K
Snippets
198
Records
361
Agent score
55%

What's inside Caura

  1. Overview of Caura (formerly MemClaw)

    main

    Caura (formerly known as MemClaw) is an open-source, shared, and governed memory layer designed for multi-tenant, multi-agent AI fleets. It allows agents to store plain text information, which Caura then transforms into searchable, governed, and self-improving memory.

    Core functionality follows a three-pillar loop:

    1. Write: Agents store what they learn.
    2. Recall: Agents find what the fleet already knows.
    3. Compound: Interactions improve the memory, allowing agents to learn from each other and avoid repeating mistakes.

    While it works for single-agent setups, Caura is specifically optimized for agent fleets through features like scoped memory, cross-agent outcome propagation, and fleet-wide trust tiers.

  2. Understand Caura performance benchmarks and metrics

    main

    Caura's performance is evaluated across three primary dimensions: Accuracy, Token Efficiency, and Search Latency.

    Benchmark Results (Reference)

    • Accuracy (LLM-judge): ~77.6% on LoCoMo and ~92.2% on LongMemEval.
    • Token Savings: 79.2% to 96.6% compared to sending full context to an LLM.
    • Search Latency (Warm Cache): 23 ms p50 · 27 ms p95 for POST /search.

    Key Metrics Explained

    • Accuracy: Measured via an LLM-judge over benchmark questions, evaluating the entire retrieval-then-answer pipeline rather than just recall@k.
    • Token Efficiency: The ratio of total tokens sent to the answering LLM versus a baseline of sending the full prior context.
    • Search Latency: The p50/p95 latency of POST /search against a warm cache under single-tenant load. Warm cache represents the steady-state condition under real load.

    Fleet-Scale Optimization

    Unlike single-agent benchmarks, Caura is optimized for fleet-scale deployment by focusing on:

    • Latency: Minimizing overhead for millions of daily recall calls.
    • Token Efficiency: Reducing the cost of the 'bill' at scale by returning only relevant slices.
    • Governance Correctness: Enforcing scope filtering by default to prevent data leaks across teams.

  4. Swap Embedding Models in TEI

    main

    You can swap models by setting TEI_MODEL_ID. The following models are compatible with the default 1024-dim schema:

    ModelNative dimTruncate?Instruction?Notes
    BAAI/bge-m31024nonoDefault. MIT, 100+ langs, 8K ctx.
    Snowflake/snowflake-arctic-embed-l-v2.01024nonoApache-2.0, 74 langs.
    Qwen/Qwen3-Embedding-0.6B1024noyesApache-2.0, instruction-aware. Requires GPU.
    Qwen/Qwen3-Embedding-4B2560yes (=1024)yesTruncates to 1024 via Matryoshka. Requires L4 GPU.

    Important Configuration Notes:

    • OPENAI_EMBEDDING_SEND_DIMENSIONS: Must be set to false when using TEI, as TEI rejects the dimensions= kwarg.
    • OPENAI_EMBEDDING_TRUNCATE_TO_DIM: Use this if your model's native dimension is larger than the schema (1024). For example, set to 1024 for Qwen/Qwen3-Embedding-4B.
    • EMBEDDING_QUERY_INSTRUCTION: Set this for instruction-aware models (e.g., Qwen3-Embedding). It prepends Instruct: <task>\nQuery: <text> to search queries.

  5. Configure temporal validity and freshness

    main

    Memories can have temporal bounds using ts_valid_start and ts_valid_end. These are either auto-extracted by the LLM or set explicitly.

    Searching by Time

    Use the valid_at parameter in searches to return only memories valid at a specific point in time. Relative dates (e.g., "last month") resolve against the provided valid_at value.

    Backfilled Corpora

    If you are ingesting historical data where ts_valid_start represents the actual event time, you must adjust how freshness is calculated:

    • Set search.default_profile.freshness_reference to 1 in your tenant settings.
    • This ensures freshness and temporal windows are measured against valid_at (event time) rather than the current time against ingestion time.

  6. Identity requirements for Caura tool calls

    main

    Every call to a caura_* tool requires identity parameters to ensure proper attribution and access control:

    • agent_id: Your unique identifier. This is used to attribute memories, drive trust progression, and gate scope_agent privacy. You must resolve this from your runtime; never fabricate or impersonate another agent.
    • fleet_id: Your team/organization scope.
      • If omitted on a write, the server defaults to your home fleet (the fleet you registered under).
      • Explicitly pass fleet_id if you have no home fleet set (to avoid NULL persistence) or if you are writing into a different fleet (requires trust level 3).

    Note: The fleet_id in a connection URL (e.g., ?fleet_id=) sets read defaults and routing, but it is not stamped onto written rows.

  7. Understand caura_recall behavior and filtering

    main

    The caura_recall tool is used to retrieve existing memories.

    Key Behavior: By default, caura_recall excludes memories that have been superseded (where status is outdated or conflicted). If you need to walk the history of a fact or see previous versions, you must pass the status parameter explicitly.

  8. Authenticate with the Caura API

    main

    Authentication requirements depend on the endpoint and deployment type.

    Standard Authentication:

    • Most data endpoints require an X-API-Key header.
    • Admin endpoints require an ADMIN_API_KEY.

    Gateway-Injected Identity (Enterprise/Gateway deployments): If using an enterprise gateway, the following headers can scope requests:

    • X-Agent-ID: Scopes the request to a specific agent.
    • X-Tenant-ID: Identifies the tenant when using a shared CAURA_API_KEY.
    • X-Org-Read-Only: true: Enables plan-limit read-only mode. Writes that grow the store return 403 PLAN_LIMIT_READ_ONLY, but deletes and status transitions remain allowed.

    Security Note: To use gateway identity headers, you must set GATEWAY_SHARED_SECRET and provide a matching X-Gateway-Secret. In OSS deployments without a gateway, use CAURA_API_KEY to authenticate.

  9. Compare Caura capabilities with other memory tools

    main
    Caura is designed for governed memory across agent fleets, distinguishing itself from single-agent memory tools (like Mem0, Zep, or Letta) through multi-fleet support, agent trust tiers, cross-vendor memory sharing, and contradiction detection. While accuracy scores across the industry are similar, Caura focuses on fleet-scale capabilities like PII detection, audit trails, and per-agent retrieval tuning.

  10. Configure auto-chunking for long content

    main

    When content exceeds 2,000 characters, Caura automatically splits it into atomic facts using an LLM. This behavior can be toggled per tenant via the auto_chunk_enabled setting.

    Chunking Process:

    1. A parent memory is created containing the full content (tagged auto_chunked: true).
    2. Multiple child memories are created for each extracted fact (tagged source: "auto_chunk" and linked to the parent).
    3. Both parent and children inherit the same type, weight, status, and visibility.

    Note: This changes integration behavior; long content will result in multiple memory entries instead of one.

  11. How Skill Factory works

    main

    Skill Factory is a governed system for managing the skills collection. It is opt-in per tenant and must be enabled via skills_factory.enabled = true in organization settings.

    It consists of three pillars:

    1. Authoring: Agents author skills via caura_doc op=write collection=skills. The Forge (a server-side component) also mines memory and outcome signals to create skill candidates.
    2. Governance: Skills follow a lifecycle: candidate → staged → active (with exits like rejected, quarantined, stale, or deprecated). Staged skills are managed via a Skills Inbox REST API (GET /api/v1/skills-inbox and POST /api/v1/skills-inbox/{slug}/approve|edit|defer|quarantine|reject).
    3. Delivery: Agents can pull active skills via MCP (caura_doc op=search/op=read), or the OpenClaw plugin can push them by fetching from POST /api/v1/skills/installable and writing them to the node's skill directory.