{"slug": "openclaw-memgpt-memgpt-s-three-tier-memory-architecture-as-an-openclaw-plugin", "title": "OpenClaw-memgpt – MemGPT's three-tier memory architecture as an OpenClaw plugin", "summary": "OpenClaw-memgpt, a new plugin for the OpenClaw agent framework, implements MemGPT's three-tier memory architecture—core, recall, and archival memory—to provide persistent, searchable memory across sessions. The plugin is provider-agnostic, supports cross-session persistence and conversation summarization, and is available for OpenClaw ≥ 2026.5.31 with Python 3.11 and Node ≥ 20.12.0.", "body_md": "OpenClaw plugin providing MemGPT's three-tier memory architecture for any OpenClaw agent.\n\n`openclaw-memgpt`\n\ngives an OpenClaw agent the memory architecture from [MemGPT](https://github.com/letta-ai/letta): three tiers the agent manages itself through tool calls.\n\n**Core memory**— a small, always-in-context block holding the agent's persona and what it knows about you. The agent edits it directly as facts change.**Recall memory**— the searchable history of your conversation, so the agent can look up what was said earlier even after it has scrolled out of context.**Archival memory**— an embedding-backed long-term store for facts the agent chooses to keep, retrievable by semantic search.\n\nOn top of the tiers the plugin provides **cross-session persistence** (memory survives restarts — the default in gateway mode, and supported in one-shot `--local`\n\nmode) and **conversation summarisation** (older turns are compacted into recall memory when context fills up, instead of being lost).\n\nIt is **provider-agnostic**: the memory sidecar talks to any OpenAI-compatible endpoint (OpenAI, Anthropic, a local LLM, LiteLLM/OpenRouter, etc.), configured once through the setup wizard.\n\nUnder the hood the plugin runs a small Python sidecar built on a maintained MemGPT fork, published to PyPI as [ openclaw-memgpt-sidecar](https://pypi.org/project/openclaw-memgpt-sidecar/). The plugin spawns and manages that process for you.\n\n**OpenClaw ≥ 2026.5.31****Python 3.11**(3.12 not yet supported) — for the memory sidecar** Node ≥ 20.12.0**— the plugin uses it to run the sidecaron your`uv`\n\n`PATH`\n\n```\nopenclaw plugins install openclaw-memgpt\n```\n\nOn first use the plugin notices it isn't configured yet and points you at the setup wizard. Run it any time to (re)configure:\n\n```\nopenclaw memgpt setup\n```\n\nOptionally, warm the embedding-model cache ahead of time so your first agent turn isn't slowed by a one-time (~60 s) model download:\n\n```\nopenclaw memgpt prewarm\n```\n\nTo remove the plugin and its data:\n\n```\nopenclaw memgpt uninstall\n```\n\nThe interactive uninstall lets you **keep your memory data** or remove everything; `--keep-data`\n\n, `--force`\n\n, and `--dry-run`\n\nare also available.\n\n```\n# 1. Install the plugin\nopenclaw plugins install openclaw-memgpt\n\n# 2. Configure it (provider, API key, model, …)\nopenclaw memgpt setup\n\n# 3. (optional) Pre-download the embedding model so turn 1 is fast\nopenclaw memgpt prewarm\n\n# 4. Talk to your agent — it now remembers across turns and sessions\nopenclaw agent --message \"Hi, I'm working on a thesis due March 15. Remember that.\"\nopenclaw agent --message \"When is my thesis due?\"\n# → the agent recalls \"March 15\" from memory\n```\n\n`openclaw memgpt setup`\n\nwalks you through, in order:\n\n**Provider**— Anthropic, OpenAI, or any OpenAI-compatible endpoint.** Base URL**— only for the OpenAI-compatible option.** API key**— paste it (stored in a private mode-`0600`\n\nfile) or point the plugin at an**environment variable** you already have set (e.g`ANTHROPIC_API_KEY`\n\n/`OPENAI_API_KEY`\n\n). Keys are never written into`openclaw.json`\n\n.**Model**— the model the sidecar should use.** Observability**—`off`\n\n(default),`default`\n\n, or`verbose`\n\n(see below).**Sidecar URL**— leave blank to let the plugin spawn and manage the sidecar itself; set it only if you run the sidecar yourself.\n\nA few notes:\n\n**Conversation access.** Storing memory means reading the conversation, so the plugin needs OpenClaw's conversation-access permission. In gateway mode OpenClaw requires you to grant this explicitly; the setup wizard does it for you and tells you so.**Manual sidecar (advanced).** Set`OPENCLAW_MEMGPT_SIDECAR_URL`\n\n(or the`sidecarUrl`\n\nconfig field) to attach to a sidecar you started yourself instead of having the plugin spawn one.\n\nThe agent calls these tools itself; you don't invoke them directly.\n\n| Tool | What it does |\n|---|---|\n`core_memory_append` |\nAppend to the contents of core memory. |\n`core_memory_replace` |\nReplace the contents of core memory. To delete memories, use an empty string for new content. |\n`archival_memory_insert` |\nAdd to archival memory, phrased so it can be queried later. |\n`archival_memory_search` |\nSearch archival memory using semantic (embedding-based) search. |\n`conversation_search` |\nSearch prior conversation history using case-insensitive string matching. |\n`conversation_search_date` |\nSearch prior conversation history using a date range. |\n`send_message` |\nSend a message to the user. |\n\nWhen enabled, the plugin writes a structured event log as JSON Lines to `<OpenClaw state dir>/memgpt-observability.jsonl`\n\n(e.g. `~/.openclaw/memgpt-observability.jsonl`\n\n). Three levels:\n\n-\n(default) — no events captured.`off`\n\n-\n— one event per memory operation,`default`\n\n**metadata only**(no message/query/result text):\n\n```\n{\"kind\":\"archival_search\",\"namespace\":\"my-agent\",\"ts\":\"2026-06-23T02:27:40.833Z\",\"meta\":{\"total\":3,\"page\":0,\"numPages\":1}}\n```\n\n-\n— the same events`verbose`\n\n**plus the content**(queries, results, written text) for full provenance:\n\n```\n{\"kind\":\"archival_search\",\"namespace\":\"my-agent\",\"ts\":\"2026-06-23T02:27:40.833Z\",\"meta\":{\"total\":3,\"page\":0,\"numPages\":1},\"content\":{\"query\":\"when is my thesis due\",\"results\":[\"User's thesis is due March 15\"]}}\n```\n\nThe JSONL file is the authoritative record. You can also subscribe to events live from your own code:\n\n``` js\nimport { memoryEvents, MEMORY_EVENT_CHANNEL } from \"openclaw-memgpt\";\n\nmemoryEvents.on(MEMORY_EVENT_CHANNEL, (e) => {\n  console.log(e.kind, e.namespace, e.meta);\n});\n```\n\n**Privacy.** Your API key is stored in a private file at `<OpenClaw state dir>/plugins/openclaw-memgpt/api-key`\n\n(mode `0600`\n\n, in a `0700`\n\ndirectory). At `verbose`\n\n, the observability log contains your conversation content. If you use backup or file-sync tools (Time Machine, iCloud Drive, dotfile managers), consider excluding both of these paths.\n\n**The agent replies to you conversationally.** Unlike MemGPT's reference CLI, which forces every reply through a`send_message`\n\ntool call, this plugin lets the agent answer in free-form text. This is purely a user-experience choice and does not affect how memory is stored or recalled.**First-run cold start (~60 s).** The first time the embedding model is needed it is downloaded and cached. Run`openclaw memgpt prewarm`\n\n(or accept the wizard's offer) to get this out of the way; every run after that is fast.**One-shot** Either run`--local`\n\nmode.`openclaw memgpt prewarm`\n\nfirst, or accept the one-time cold-start cost on the first turn — it works normally afterwards.\n\n**\"The agent doesn't remember things across sessions.\"** Check that your API key is correct — that the configured environment variable is set, or the stored key is valid. Memory operations silently no-op if the sidecar can't reach the LLM.**\"My first turn times out (cold start).\"** Run`openclaw memgpt prewarm`\n\nto download and cache the embedding model up front, or wait through the first ~60 s.**\"Embedder cache appears unavailable.\"** Run`openclaw memgpt prewarm`\n\nto re-download the embedding model.\n\nThis is the first public release of `openclaw-memgpt`\n\n. Bug reports and feedback are very welcome — future versions will incorporate user reports and iterate on the plugin's design. Please open an issue on [GitHub](https://github.com/xltvy/openclaw-memgpt/issues).\n\nBuilt on the memory architecture from **MemGPT**, created by the [Letta](https://github.com/letta-ai/letta) team — full credit to the original authors. The plugin consumes a maintained MemGPT fork published as [ openclaw-memgpt-sidecar](https://pypi.org/project/openclaw-memgpt-sidecar/).", "url": "https://wpnews.pro/news/openclaw-memgpt-memgpt-s-three-tier-memory-architecture-as-an-openclaw-plugin", "canonical_source": "https://github.com/xltvy/openclaw-memgpt", "published_at": "2026-06-24 17:01:42+00:00", "updated_at": "2026-06-24 17:10:14.649283+00:00", "lang": "en", "topics": ["ai-agents", "large-language-models", "developer-tools"], "entities": ["OpenClaw", "MemGPT", "OpenAI", "Anthropic", "LiteLLM", "OpenRouter", "PyPI"], "alternates": {"html": "https://wpnews.pro/news/openclaw-memgpt-memgpt-s-three-tier-memory-architecture-as-an-openclaw-plugin", "markdown": "https://wpnews.pro/news/openclaw-memgpt-memgpt-s-three-tier-memory-architecture-as-an-openclaw-plugin.md", "text": "https://wpnews.pro/news/openclaw-memgpt-memgpt-s-three-tier-memory-architecture-as-an-openclaw-plugin.txt", "jsonld": "https://wpnews.pro/news/openclaw-memgpt-memgpt-s-three-tier-memory-architecture-as-an-openclaw-plugin.jsonld"}}