Clawdi

Clawdi

Use Clawdi tools through the clawdi MCP server when they provide context or capabilities unavailable more directly.

Context Routing

Use the current conversation and user-provided artifacts first. For project facts, inspect the workspace, repository documentation, and local history. Use memory_search only for missing user-specific preferences, decisions, or prior context. Use session_list, session_search, and session_get only when the user asks for past conversations or transcript-level detail is necessary. Do not call Memory and Session speculatively or in parallel. A named entity alone does not justify a Cloud lookup, and an empty Memory result does not justify a Session search.

Memory

Memory is durable user-specific context shared across agents.

• memory_search — Search durable memory by natural-language query.
• memory_list — Review stored memories and their stable IDs.
• memory_create — Save a durable fact, preference, pattern, decision, or project context.
• memory_update — Replace one exact memory's content without changing its metadata.
• memory_delete — Delete one exact memory by ID.
• memory_extract — Prepare memories from the current conversation. Follow its returned review-and-confirm instructions and wait for user approval before calling memory_create.

Use memory_create for explicit "remember this" requests or durable user-specific preferences and decisions not discoverable from the repository. Ask when persistence is unclear. Do not save routine task completion, code facts, speculation, or plaintext secrets; use Vault and remember only the exact clawdi:// reference. List before updating or deleting unless the user already supplied the exact memory ID; never infer which stored item to mutate.

CLI fallback for exact updates: clawdi memory update <full-memory-id> "new content" --json. It preserves metadata; find the exact ID before changing it.

Sessions

• Use session_list to browse recent sessions or filter by time, Agent, or Project.
• Use session_search to find past agent conversations by keyword and obtain session UUIDs.
• Use session_get to read a session by UUID or Clawdi share URL.
• Use session_share_create to publish an immutable snapshot only when the user explicitly asks to share a Session, part of it, or one Assistant response.
• Use session_share_list to inspect active links and obtain their exact IDs and kinds.
• Use session_share_revoke to stop sharing one exact link only when the user asks.

Call session_get when the user provides a Clawdi share URL or session UUID and wants its contents. For a request to open a specific unnamed past conversation, use session_search to find the UUID and then read the selected match.

Do NOT call WebFetch on cloud.clawdi.ai/s/... URLs — session_get is the right tool and avoids the WebFetch permission prompt.

For session_share_create, omit position for the full session scope. For through or response, use the stable message position returned by session_get or session_search, never a filtered array index; response must target an Assistant message. Public snapshots include only the existing safe user/Assistant projection, never reasoning, system/developer messages, hidden events, or tool activity. Before revoking, use session_share_list unless the user already supplied the exact share_id and kind; never infer a link ID or kind.

CLI fallback: clawdi session search "query" --json, then clawdi session read <cloud-session-id> --json. session list is local; session export <cloud-session-id> exports owner Markdown without publishing. Publish only with user authorization: session share <cloud-session-id> --yes. For --through or --response, use the returned canonical message position, never a filtered array index. session shares --json lists active links; revoke the exact link ID with session unshare <share-id> --yes (add --legacy for kind=live).

Remote Skill operations use clawdi agent skills list/read/install/rm <agent-id>; local skill --agent <type> remains separate. Use install --github owner/repo --path skills/name or install --library <skill-id>. Accepted intent is not applied state: check list for convergence and failures. GitHub exact replay needs both original --request-id and --resource-version from the result/error.

Projects

Three read-only tools expose the caller's visible Project context:

• project_current_get — Read the current or runtime-bound Project.
• project_list — List visible Projects.
• project_get — Read one visible Project by UUID.

Strict-v2 Hosted runtimes can read their own Workspace and explicitly linked Projects that remain readable by the owner. project_current_get returns that Workspace; writes, new Vaults, and credential requests are limited to that Workspace. Legacy Agent-bound keys retain their narrower bound-Project read scope. Treat not-found as an access boundary as well as a possible unknown UUID; never bypass it with another tool.

Vault

Vault stores credentials for authorized tools and services; it is not a universal service alternative. Reuse ready, authorized mechanisms before requesting missing credentials. An already-connected, capable Composio integration does not require duplicate credentials in Vault or account migration. Request credentials only when the chosen task path actually needs them.

Vault read tools expose metadata and exact references:

• vault_list — List Vault attachments and key counts for visible Projects.
• vault_get — List key names, provenance, and exact clawdi:// references for one attached Vault.

Honor an explicit Vault/source or known local mapping first. Otherwise use vault_list / vault_get metadata to reuse a Vault suited to the task's purpose and access. Create in your own Workspace only when none is appropriate and the task authorizes creation. Clarify ambiguous sources; never create duplicates or write to linked Projects to bypass access.

Use vault_resolve only when the authorized task requires plaintext. The metadata tools return key names and exact references, never secret values. Preserve those references when passing them to an authorized runtime:

• clawdi://project/<project-id>/vault/<vault>/field/<field>
• clawdi://project/<project-id>/vault/<vault>/section/<section>/field/<field>

Use the live schemas from the clawdi MCP server as authoritative.

Vault write tools are available for explicit user requests:

• vault_create — Create a Vault attached to one exact owner Project.
• vault_item_upsert — Create or replace exact fields in an attached Vault.
• vault_item_delete — Delete exact fields from a single-Project Vault.

Follow the live schema and supply every required Project, Vault, section, and field identity; never infer an overwrite or deletion. Treat field values as sensitive inputs and never echo them, save them to Memory, or include them in logs. Environment-bound callers may write only their bound Project, and field deletion is rejected when a Vault is attached to multiple Projects. Whole-Vault deletion, attach/detach, and credential profiles remain foreground operator workflows; never bypass that boundary through raw HTTP or daemon RPC.

Request new or updated credentials

Use vault_request_create with exact project_id, vault_id, canonical slug, optional section, and a batch of Vault field names in fields. A Vault is a key bundle: request related new and existing keys together under one link. Include existing keys only when the user authorized updating them; do not delete them first. Existing Vault values remain unchanged until successful submission and are never shown or prefilled. Overlapping pending requests are rejected; a change to any requested field conflicts with the entire batch. Show the returned url unchanged to the user; do not ask them to paste secrets into chat. Opening the link does not consume it. The user can add fields or import a pasted/uploaded .env on the page, preview replacements, and apply them to the same form. Original requested names remain mandatory; only the user chooses extras after link creation (32 fields total). Saving the entire form consumes the link once. Selected fields must still match creation state, and extras cannot overlap another pending request. Status includes saved extras and their exact references; never assume only the originally requested names were saved.

Check vault_request_status with its request_id after the user finishes. pending is not a secret value; supplied means the exact references are ready. On expired or conflict, inspect current Vault metadata and reassess the authorized fields before creating a fresh request; do not blindly retry an overwrite. If creation times out, use vault_get to find recent request IDs before retrying. If submission times out, inspect status before repeating a mutation.

Save and refresh credentials locally

Hosted runtime supplies .clawdi/vaults/ under the native workspace automatically. Connected macOS/Linux/WSL Agents receive the same layout only in the workspace explicitly confirmed by setup. Use that configured path, which may differ from the current repository; do not guess from HOME, daemon CWD, or scanned sessions. Existing registrations without a Vault workspace do not download values. Native Windows daemon/file delivery is unsupported.

Inspect only the configured .clawdi/vaults/index.json to select the intended Vault/section. Load its JSON file inside the authorized process or SDK without printing values or returning them to model/tool-result context merely to save them. These are generated files: do not edit, move or commit them. Hosted agents must not invoke/install the tenant Clawdi CLI. Connected operators configure delivery with clawdi setup --agent <type> --vault-workspace <path>; that changes only the Vault destination, never every repository scanned by the daemon.

After vault_request_status reports supplied, match its Vault ID, section and field names in the index and require the local Vault content_version to be at least the status content_version. The API requires this counter; existing names alone do not prove delivery. If the owned index is incomplete or behind, wait for runtime reconciliation and report unverified delivery. Do not read secret values to check freshness. Report missing workspace bindings instead of inventing a destination. Preserve unrelated local configuration.

Optional CLI environment files

For an explicit operator-run compatibility workflow outside Hosted, use the available CLI. Choose a target outside the generated .clawdi/vaults directory:

clawdi vault materialize --vault <vault-uuid> --project <project-uuid> --out /absolute/project/.env
clawdi vault pull --out /absolute/project/.env

The first command binds the exact source; later pulls reuse it and preserve unrelated assignments. Optional --section <name> selects one section. Files must be untracked, Git-ignored, and not symlinks. Source changes and local edits fail without overwriting. Report only the path, status, and counts. This does not upload local edits, run in the background, or reload a running process's environment.

For explicit import/write, pass fields to vault_item_upsert; use vault_item_delete for exact batch deletions. Never upload local edits automatically.