clawdi-ai/clawdi/legacy-local-clawdi

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.

1. Callbacks to prior context. "as I mentioned", "like last time", "you know the one", "we discussed before", "what was that X we set up".
2. Named entities specific to this user. Their project / repo / service / team / tool name. A person by name.
3. Past bugs, decisions, investigations, design choices.
4. 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.

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

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

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

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

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