Chat, memory & skills

Source: orchestration/mcp-gateway/tools.ts (ChatSchema, plungeaiChat, MemorySchema, plungeaiMemory, LearnSchema, plungeaiLearn), orchestration/mcp-gateway/chat.ts, orchestration/mcp-gateway/tools-bots.ts (the bot actions of 10.4), orchestration/mcp-gateway/extras.ts (registrySigned), orchestration/mcp-gateway/index.ts (argument pre-screen), orchestration/mcp-gateway/server.ts (TOOL_DEFS), core/core-memory/core-memory.ts and core/core-memory/CLAUDE.md, agents/agents/harness-agent/runtime.ts (run journal write).

Three tools keep something for you across calls: a conversation, a memory, a skill. The examples use https://mcp.plungeai.com/v1. https://api.plungeai.com/v1/mcp is the same server.

Full parameter tables are in the Tool reference.

10.1 Chat: plungeai_chat

A persistent conversation with the platform assistant. One tool, four actions:

The assistant is harness-agent on Anthropic claude-sonnet-4-5, with up to 15 turns and 8,192 output tokens per reply. Its tools are web_search, registry_search, registry_lookup and task_complete. It is told to verify current facts with web search, cite source URLs, and use the registry to find platform agents when relevant. It cannot run workflows or save anything: it has no execute or save tool. When a design is settled, ask your client to build it, and it calls plungeai_build_workflow (Workflows).

One account, three surfaces. A conversation is stored the way Studio stores its plan conversations. The same conversation shows up in Studio's Think tab and in the CLI's ocean-cli chat sessions, and a thread started there can be continued here by its id.

Titles. send without a conversation_id starts a new conversation titled with the first 50 characters of your message. new titles it with the first 50 characters of message, or New conversation when there is none. That title stays: a later first send does not rename it.

Live status. A send reports Thinking…, then Streaming… <n> chars as the reply arrives (Protocol & transport).

Errors (all isError: true):

One writer per conversation. Two send calls on the same conversation at the same time can lose a turn: the conversation store has no compare-and-swap. Send turns one after another.

Chat or something else?

Try asking: "Let's design a due-diligence workflow together." The thread persists, so you can come back to it from Studio or the CLI. When you are happy with the design, say "build it".

Send a turn. This runs a model and costs credits (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_chat","arguments":{"user_request":"let us design a due-diligence workflow together","action":"send","message":"Let us design a due-diligence workflow together. What steps would you include?"}}}'

List your conversations:

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_chat","arguments":{"user_request":"show my conversations","action":"list_sessions"}}}'

Read one back (replace <conversation_id>):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_chat","arguments":{"user_request":"show me that conversation","action":"history","conversation_id":"<conversation_id>"}}}'

10.2 Memory: plungeai_memory

Long-term memory is scoped to you. It has two curated stores:

The budgets are per-user settings; the numbers above are the defaults.

Who reads it. Every mission (plungeai_run_mission, Agents & missions) recalls both stores at the start of its run and can write to them. This is the same mechanism Studio's harness uses, so a note saved here is known to every later run. The recall is a snapshot taken once per run: a write during a run is saved, but it does not change that run's prompt.

What it is not. Memory is not your run history. There are three separate things:

recall deliberately leaves the run journal out.

Actions.

recall has no query: it returns all of both stores and your client picks what is relevant.

remember operations (operation defaults to add, target to memory):

When a write is refused (all isError: true):

search_runs matches the words of your query that are longer than two characters against the goals in the journal, and ranks runs by how many words match. If no word matches, it returns your most recent runs instead of nothing. No matching runs. means the journal is empty. query is required for search_runs. and run_id is required for get_run. are isError: true.

Try asking:

• "What do you remember about Circle's acquisitions?" → recall
• "Remember that our fiscal year ends in June." → remember
• "Find my past runs about Tesla." → search_runs, then "Show me that run." → get_run
• "Forget my old office address." → forget with content

Recall (read-only):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_memory","arguments":{"user_request":"what do you remember about Circle acquisitions?","action":"recall"}}}'

Read the raw memory store (read-only):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_memory","arguments":{"user_request":"show my memory entries","action":"remember","operation":"read","target":"memory"}}}'

Save a note. This writes to your memory (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_memory","arguments":{"user_request":"remember that our fiscal year ends in June","action":"remember","content":"Our fiscal year ends in June."}}}'

Change it later with "operation":"replace","old_text":"fiscal year","content":"Our fiscal year ends in July.".

Search the run journal (read-only):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_memory","arguments":{"user_request":"find my past runs about Tesla","action":"search_runs","query":"Tesla","limit":5}}}'

10.3 Skills: plungeai_learn

plungeai_learn manages your private skill library. A skill is a reusable piece of know-how, distilled from a source, that you inject into later missions.

source is a URL, text or Markdown to distill (up to 65,536 characters), or a description of what you just did, such as a workflow you ran. name is the skill id in kebab-case: picked for you on learn when you leave it out, required on forget (take it from list).

How learn runs. It starts a one-task harness workflow named learn whose task points at the learn pre-built agent card. The card is resolved live when the run starts, so an edit to the card changes every later call without a redeploy. The run is a full agent loop (fetch, summarize, save), so it defaults to mode:"async": poll plungeai_get_workflow_status with the execution id, then read the result with plungeai_get_result (Runs, results & follow-ups). It creates an execution in your history and runs a model.

Where skills go. A learned skill is a registry skill card tagged with your user id as its owner. Only you can list it or delete it.

Using a skill. Pass its id in skills on plungeai_run_mission to inject it into the mission (Agents & missions).

Answers. Every answer is the structured outcome envelope (Tools), because the tool declares an outputSchema:

Try asking:

• "Learn a skill from https://developers.cloudflare.com/durable-objects/ (opens in a new tab)."
• "Turn what we just did into a skill called weekly-brief."
• "What skills have I learned?"
• "Forget the weekly-brief skill."

List your skills (read-only):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_learn","arguments":{"user_request":"what skills have I learned?","action":"list"}}}'

Learn one. This starts an agent run and costs credits (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_learn","arguments":{"user_request":"learn a skill from the Durable Objects docs","action":"learn","source":"https://developers.cloudflare.com/durable-objects/","name":"durable-objects-basics"}}}'

10.4 Bot chats: bindings, inbox and groups

A saved bot is talked to outside these tools too. Three kinds of conversation around a bot are read and managed with plungeai_workflow (the full action table is 8.6):

Try asking:

• "Which chats are bound to my Outreach bot?" The client runs bindings.
• "Show me what the Sales group has been saying." The client runs group_thread with group: "Sales".

Reading a group's shared thread is read-only (not run by the docs verifier; it needs a group you made):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_workflow","arguments":{"user_request":"show me what the Sales group has been saying","action":"group_thread","group":"Sales"}}}'