Clawdi

---
name: clawdi
description: "Cross-agent long-term memory + session history for the current user: their preferences, coding habits, named projects / repos / tools, past bugs and architecture decisions, AND their past agent conversations across Claude Code / Codex / OpenClaw / Hermes. Surface this skill BEFORE answering any question about the user themselves, their work, or their history — even when phrased abstractly (e.g. 'what do I usually use for X', 'find the session where I worked on auth'). Also provides connected-service tools (Gmail, GitHub, Notion, Drive, Calendar, etc.) and reads Clawdi share URLs (https://cloud.clawdi.ai/s/...) the user pastes."
---

# Clawdi Cloud

You have access to Clawdi Cloud tools via the `clawdi` MCP server. Use them aggressively — memory + session retrieval is the highest-leverage capability you have here.

## Memory

Three tools for cross-agent memory:

- `memory_search` — Search long-term memory by natural-language query (any language).
- `memory_add` — Save a durable memory for cross-agent recall. Do not store plaintext tokens, API keys, or bearer credentials; store those in Vault and save only the `clawdi://` reference. Categories: `fact` (technical facts, API details, config values), `preference` (user preferences, coding style, workflow choices), `pattern` (recurring patterns, pitfalls, team conventions), `decision` (architecture decisions and their reasoning), `context` (project context, deadlines, ongoing work).
- `memory_extract` — Batch-extract durable memories from the CURRENT conversation. Call this when the user says "extract memories", "save what we discussed", "remember this conversation", or equivalent. The tool returns instructions that walk you through a list-then-confirm flow using `memory_search` and `memory_add` — follow them exactly, including **waiting for the user's approval before writing anything**. Never skip the confirmation step, never save more than 5 memories in one invocation, and do not narrate your internal workflow to the user.

### When to search — bias toward calling

**Default assumption: the user has stored context you don't have. Call `memory_search` BEFORE answering any question about them, their project, their preferences, or their history. A call that returns empty costs ~100ms; a missed hit makes you look amnesic and forces them to re-teach you every session.**

The single most common failure mode is NOT calling memory_search on abstract self-referential questions. If the user's message has any of these shapes, you MUST call it — no judgment, no exceptions:

1. **Preference / habit questions**, even without a specific entity named.
   Examples: "what do I usually use for X", "how do I normally do Y", "what's my preferred tool for Z", "what's my coding style". Pass a short paraphrase as the query.
2. **Callbacks to prior context.** "as I mentioned", "like last time", "you know the one", "we discussed before", "what was that X we set up".
3. **Named entities specific to this user.** Their project / repo / service / team / tool name. A person by name.
4. **Past bugs, decisions, investigations, design choices.**
5. **Start of a new session where they reference anything about themselves or their work.**

Do NOT search for:
- Purely textbook programming questions with no user-specific signal ("how does `useEffect` work", "what is the time complexity of quicksort").
- Questions the current code already answers directly.

**When unsure, search.** Empty results cost you nothing. Missing the user's context costs you their trust.

### When to save

- After fixing a non-obvious bug (save root cause + fix)
- After making an architecture decision (save reasoning)
- After discovering a useful pattern or workaround
- When the user explicitly says "remember this" / "save this"
- After learning a user preference you'd otherwise have to re-ask ("I prefer rg", "I always use pnpm")

Write memories as standalone sentences with full context — include names, not pronouns. A future session will read this without knowing today's conversation.

Do NOT save trivial facts that are obvious from the code itself, or generic programming knowledge.

Do NOT save plaintext tokens, API keys, bearer credentials, or private keys in memory. Use Vault for secret values and save only a `clawdi://` reference when future agents need to know where a secret lives.

## Sessions

Two tools for reading and finding past agent conversations stored in Clawdi Cloud:

- `session_read` — Fetch a single session by reference and return its full conversation as Markdown. Accepts a Clawdi share URL (`https://cloud.clawdi.ai/s/{uuid}`) OR a session UUID for one of the user's own sessions. Handles owned and shared sessions transparently — you don't need to know which one.
- `session_search` — Find sessions in the user's history by keyword. Trigram-ranked substring search with typo tolerance. Returns matching sessions with summary, project, timestamps, and **session UUIDs you can pass back to `session_read`**.

### When to read — call `session_read` whenever the user references a specific session

MUST call when the user's message includes:
- A Clawdi share URL (e.g. `https://cloud.clawdi.ai/s/11111111-2222-3333-4444-555555555555`) — pass the full URL
- A direct reference like "open the session where I did X" or "the one from yesterday about auth" — first call `session_search` to find the UUID, then `session_read` to load it

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

### When to search — bias toward calling, similar to `memory_search`

MUST call `session_search` when:
- The user asks about prior work: "what did I do about the focus bug", "find the session where I migrated auth", "show me last week's debugging session"
- They reference a past investigation by topic but don't name a specific session
- They want to continue / reuse approach from a prior conversation

### Difference from `memory_search`

- `memory_search` finds **stored facts / preferences / decisions** the user (or a previous agent run) explicitly extracted. Short rows; high signal.
- `session_search` finds **full conversations** in the corpus. Long rows; useful when the user wants the original context, not just the takeaway.

When the user's request is **conceptual** ("how do I usually do X"), prefer `memory_search`. When they want to **revisit a specific past conversation** ("the session where..."), use `session_search`. When unsure, try `memory_search` first (cheaper, faster), fall back to `session_search` if empty.

## Projects

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

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

Hosted runtimes see only their bound Project. Treat a not-found response as an
access boundary as well as a possible unknown UUID; do not try to bypass it
through another tool.

## Vault Metadata

Two read-only MCP tools expose safe Vault metadata without secret values:

- `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.

Use `vault_resolve` only when the current task requires one referenced plaintext value. Pass
the exact Project-scoped reference. Treat the result as sensitive: never echo it, save it to
Memory, or include it in logs.

The metadata tools never resolve or return plaintext. Never imply that a returned key name
is a secret value. Preserve their exact references for `vault_resolve` or 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; the local
stdio command only transports the protocol.

## Wallet Funding

Use `clawdi wallet status --json` to inspect the authenticated Wallet balance, verified
binding, and x402 readiness. Binding and Base USDC top-up are available only through the
browser wallet surface; Clawdi does not store the payment private key. Ask the user to fund
there. Command-line spending requires a future owner-only or hardware signer authority and is not
available.

## Connectors

Use the Composio Tool Router meta-tools returned by `tools/list` on the `clawdi` MCP server.
Treat their live names and schemas as authoritative; never assume a fixed meta-tool set.

1. Start each external-app workflow with `COMPOSIO_SEARCH_TOOLS`. Follow its exposed
   `queries` and `session` schema, reuse the returned session ID throughout that workflow,
   and use only the exact toolkit and tool slugs it returns. If a required schema is absent
   or incomplete, call `COMPOSIO_GET_TOOL_SCHEMAS`; never invent fields or inputs.
2. Before a side effect, require a complete target identity and all schema-required inputs.
   Explicit intent authorizes the exact requested action and target, but never authorizes
   guessing a missing recipient, account, resource, or other target. Ask only for what is
   missing, and do not request redundant confirmation once the exact action is authorized.
3. When search reports no active connection, call `COMPOSIO_MANAGE_CONNECTIONS` with its
   exposed schema and interpret only the fields it returns. Continue on `active`. On
   `initiated`, present its non-empty `redirect_url` as a clickable authentication link with
   a concise explanation that authorization is pending; the link URL must be exactly that
   value. If `initiated` has no non-empty `redirect_url`, report that authorization cannot
   continue and stop. On `failed`, report the returned error and stop. Never construct a
   substitute link, ask for OAuth credentials, API keys, or tokens, or suggest an
   out-of-band fallback.
4. Use a wait or status operation only when `tools/list` exposes one. Follow its actual schema
   and status values without inventing polling arguments. Continue only when it reports an
   active connection; keep waiting only for a non-terminal status its schema defines, and
   report any terminal failure. If none is exposed, stop until the user reports completing
   authorization, then re-run search to verify the active connection before continuing.
5. Execute exact returned slugs through `COMPOSIO_MULTI_EXECUTE_TOOL` with schema-compliant
   arguments. Batch only independent calls. Keep ordinary results inline. Set
   `sync_response_to_workbench` only when a result may be large or needs later remote
   processing; use `COMPOSIO_REMOTE_WORKBENCH` / `COMPOSIO_REMOTE_BASH_TOOL` only for large
   responses saved remotely or remote artifacts.
6. Preserve dependencies and returned semantics. Follow signed-file metadata, pagination
   fields, and termination signals exactly as exposed. Select an account only when the schema
   supports it, and use additional or future meta-tools only according to their live schemas.

## Vault Management

Vault mutation is intentionally not an Agent MCP capability. Do not use raw HTTP, daemon
control RPC, or execute foreground Vault CLI commands on the user's behalf. When the user
asks to write, import, attach, detach, or delete Vault data, explain that a human operator
must perform it and provide the safest exact foreground command. Prefer `clawdi vault set
KEY --prompt` for one value and `clawdi vault import ...` for migrations; never place a
plaintext secret in command arguments or your response.

## AI Provider Management

Provider configuration is also a human operator workflow, not an Agent MCP capability. Do
not execute provider CLI commands or handle provider credentials on the user's behalf. When
asked, provide an exact `clawdi ai-provider` command for the operator to run and explain its
effect; suggest `validate` or a non-live `test` before any explicitly requested live probe.

- Treat the local Provider Catalog as multi-record metadata. Do not activate it into local agent config; Core Hosted activation is supplied by the runtime manifest/controller, whose configured runtime binds exactly one provider and whose unmanaged runtime binds none.
- Keep Codex OAuth ownership singular across Hosted runtimes. Hermes/OpenClaw native refresh, revoke, and ownership state belongs to Hosted convergence, not a local CLI materialization command.
- Default export/import is metadata-only; `--include-secrets` requires passphrase-encrypted secret export.
- BYOK model requests go directly from the agent runtime to the configured provider. Clawdi stores metadata and secret references but is not a model proxy.