---
name: plungeai-memory
description: "Read and write PlungeAI's per-user long-term memory (plungeai_memory: recall/remember/search_runs/get_run) and distill a session into a reusable skill with plungeai_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`."
---

# PlungeAI Memory — long-term recall vs run data

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

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

## 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).
  A bot run reads/writes the owner's general memory namespace, shared across all
  their bots and runs; a hardcoded per-bot value is rejected by the harness guard
  unless it names the runner's own identity, so it is redundant at best. 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.