plungeai-memory

Read and write PlungeAI's per-user long-term memory over MCP (plungeai_memory: recall/remember/search_runs/get_run), the CLI (ocean-cli memory) and the One API (/v1/memory/recall, /remember, /forget, /runs), and save or distill a skill from a session (plungeai_learn, POST /v1/skills/learn) — distinct from SharedMemory (a single run's output). Use when the user says remember this, asks what the agent knows about them, wants to review past runs, or wants findings saved as a skill for future runs. For a single run's output use plungeai-results-traces; for the skill/expert/persona/background/plugin capability system a saved skill feeds into use plungeai-skills-plugins.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

Two separate systems, never confuse them: SharedMemory holds one execution's task outputs (read with plungeai_get_result); long-term memory holds what the platform has learned about the user across every run, recalled automatically at mission start and written back with plungeai_memory or the agent's in-loop memory tool.

Prerequisites

• A self-service ozk_ API key from Dashboard → One API → Keys (https://dashboard.plungeai.com (opens in a new tab)), or an MCP client connected to https://mcp.plungeai.com/v1.
• No discovery step needed for the memory tools themselves — they operate on the caller's own store. Discover agents you plan to reference (e.g. in learn) first: plungeai_list_agents.

Reading and writing (MCP)

plungeai_memory {action: "recall"}                        # read the durable store
plungeai_memory {action: "remember", target: "user",       # user | memory
                 operation: "add", content: "Prefers weekly summaries, no emojis"}
plungeai_memory {action: "search_runs", query: "competitor analysis"}
plungeai_memory {action: "get_run", run_id: "…"}

recall returns the same MEMORY.md + USER.md snapshot a mission gets automatically at launch. Use remember any time the user says "remember this" — chat context alone does not persist. replace/remove need the exact old_text; a failed attempt returns the current entries so you can copy it verbatim and retry.

Distilling a session into a skill — plungeai_learn

plungeai_learn {source: "<a URL, pasted text, or distilled findings from this chat>"}
plungeai_learn {action: "list"}                        # your learned skills
plungeai_learn {action: "forget", name: "<skill id>"}  # delete one you own

action defaults to learn (async: poll plungeai_get_workflow_status, fetch with plungeai_get_result). Offer this "learn-back" move whenever a session produced real research worth reusing — the saved skill is private to the caller and can be declared on future mission/harness tasks (plungeai-skills-plugins).

Over the One API

Same store, same ozk_ key (Authorization: Bearer; setup: plungeai-api-setup). Memory belongs to the key's user, so another user's entry or run id answers the same 404 as a missing one.

What builders get wrong:

• Same store, different spellings. REST says scope/text, MCP says target/content. Both default to the memory store; the CLI's --target defaults to user, so pass it when it matters.
• An entry id is mem_ + 12 hex of its scope and text. forget {id} is 404 memory_not_found if your stores do not hold it and 409 memory_conflict when that text is also part of another entry — then forget {text}, which purges every entry containing it from both stores.
• 422 memory_rejected (store full, or the text matched a threat pattern) carries current_entries: consolidate, then resend. 422 invalid_params: text is 1–65,536 characters, scope is memory or user.
• learn means two things. POST /v1/skills/learn saves markdown you already wrote (name kebab-case, 2–64 characters; description ≤ 60; an existing name of yours is replaced; 409 skill_name_taken for a platform or another user's name; 502 registry_unavailable is not an empty list). Having an agent distil a skill from a URL or text is plungeai_learn / ocean-cli learn add.
• Every route takes format (json default, yaml, markdown, text); plungeai_memory is plain text.

Gotchas

• Recall is a frozen snapshot taken at run start — mid-run writes are durable but do not change the running prompt; two missions launched together never see each other's writes.
• episodes.md (the append-only run log) is never injected into recall — pull run history explicitly with search_runs / get_run.
• Memory is small and curated on purpose (MEMORY ~2200 chars, USER ~1375 default, clamped 500–20000) — write a few load-bearing facts, not a dump; every entry is threat-scanned twice (rejected at write, [BLOCKED]-replaced at snapshot build if it slipped through).
• Bots do not set memory_owner (policy since 2026-08-23 — omit it entirely). Saving a workflow, agent, bot or campaign whose YAML carries memory_owner: is refused (422 invalid_workflow); a bot run reads/writes the owner's general memory namespace, shared across all their bots and runs. See orchestration/BOT-CREATION.md.
• Delegate children never write memory (the memory tool is stripped) — one writer per run.
• Standing company/product context that should apply to every run is NOT memory — it is a background card; a reusable method is a skill — see plungeai-skills-plugins.

Related skills

• plungeai-results-traces — SharedMemory / plungeai_get_result, a single run's output.
• plungeai-missions — the mission lifecycle memory recalls into and writes from.
• plungeai-scheduling — which scheduled job types keep the memory lifecycle.
• plungeai-skills-plugins — declaring the skill plungeai_learn just saved.

Reference

• references/memory.md — full SharedMemory-vs-long-term-memory comparison, the three-layer store (USER/MEMORY/episodes), budgets, safety scanning, namespaces, and the plungeai_memory / plungeai_learn MCP tool contracts.

Reference pages