> ## Documentation Index > Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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… 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](https://skills.plungeai.com/plungeai-memory.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-memory/SKILL.md) 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), 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: ""} plungeai_learn {action: "list"} # your learned skills plungeai_learn {action: "forget", name: ""} # 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. | Job | REST | MCP `plungeai_memory` | CLI `ocean-cli memory …` | |---|---|---|---| | read entries | `GET /v1/memory/recall?q=&limit=` (1–100, default 50) → `{entries: [{id, scope, text}], count}` | `recall` (the whole snapshot as text) | `recall [query]` (query is advisory) | | write | `POST /v1/memory/remember {text, scope?}` → `201`, or `200` if that text is already stored | `remember` `{target, operation, content}` | `remember --add \| --replace OLD NEW \| --remove` | | delete | `POST /v1/memory/forget {id}` or `{text}` (exactly one) → `{removed}` | `remember` `operation: remove` + `old_text` | `remember --remove TEXT` | | past runs | `GET /v1/memory/runs?q=` (`q` required, limit ≤ 100, default 10) → `{runs: [{run_id, ts, goal, snippet}], count}`; `GET /v1/memory/runs/{id}` → `{run_id, content}` | `search_runs` / `get_run` | `search-runs QUERY` / `get-run ID` | | skills | `GET /v1/skills` → `{skills: [{id, description}], count}`; `POST /v1/skills/learn {name, body, description?}` → `201 {skill}`; `DELETE /v1/skills/{id}` → `204` | `plungeai_learn` `list` / `learn` / `forget` | `learn list` / `add` / `forget` | 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`](/skills/plungeai-memory/references/memory) — 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 PlungeAI has TWO memory systems with different jobs: