v3.0.0

Release notes — v3.0.0

Highlights

• Conversations that persist. Each chat keeps one agent session, reused across messages and resumed after a restart: no more rolling history window, faster follow-up replies (~1.6–3 s instead of a 4–8 s cold start each time), and a prompt that can be cached. /new starts a fresh conversation.
• A MEMORY.md that stays useful. Permanent memory is now a short profile of you plus an index pointing to the daily notes that hold the details. Credentials, document numbers and instructions stay in your notes and are read only when you ask for them; they're no longer sent with every message.
• Daily consolidation with a stronger model. Each finished day with notes is distilled into MEMORY.md on Claude Opus 5.5 (medium effort), configurable separately from the chat model.
• Pick your model from Telegram. /model and /effort show button menus, for both Claude and Cursor.
• Much more reliable memory. A full review of storage, indexing, search and consolidation fixed 20+ bugs, backed by a new end-to-end test suite that runs against the real APIs.

⚠️ Breaking changes

• memclaw save --permanent is removed. MEMORY.md is written only by consolidation now; memclaw save writes to today's notes, and the fact reaches MEMORY.md after the day.
• Library API: MemoryStore.save() no longer takes permanent, and MemclawConfig no longer takes conversation_history_limit / conversation_history_window_minutes (conversations live in the backend's session now).
• Your MEMORY.md gets restructured by the first consolidation after upgrading (profile + index). The previous version is kept in ~/.memclaw/.history/ (the last 60 versions are kept).
• Memclaw no longer loads your ~/.claude settings, plugins or MCP servers, and runs the Claude CLI with only its own tools.
• Defaults changed: chats use claude-sonnet-5-5 at medium effort (was claude-sonnet-4-6); consolidation uses claude-opus-5-5 at medium effort, after each day with notes (was every 7 days, on the chat model). On an API key that's a small daily cost; set CLAUDE_CONSOLIDATION_MODEL to change it.

No .env changes are required: your keys, memories, index and reminders carry over as they are.

New features

• Persistent sessions (~/.memclaw/sessions.json), with a per-message <context> block carrying the time, relevant memories, delivered reminders and any AGENTS.md / MEMORY.md change.
• /new: a menu command on Telegram, or send a message of exactly /new in Slack, WhatsApp or the terminal.
• /model and /effort on Telegram, saved to ~/.memclaw/.env without losing the conversation. Claude model selection also arrives in the setup wizard (CLAUDE_MODEL, CLAUDE_EFFORT).
• Progress message on Telegram: a silent "Working… step N" that follows the agent's tool calls and disappears when the reply arrives.
• Native Cursor conversations. One SDK bridge per process and one agent per chat, resumed after a restart, plus /model and /effort for Cursor (CURSOR_EFFORT).
• Image retrieval picks the right image. The agent sees the closest matches and sends only what you asked for (image_send), each image once.
• Consolidation settings: CLAUDE_CONSOLIDATION_MODEL / CLAUDE_CONSOLIDATION_EFFORT.
• Docker setup for running Memclaw on a VPS (docs/docker.md).

Bug fixes

• Search: keyword search failed on questions with punctuation ("What's…?") and ranked the best match lowest; a re-indexed file could leave search on stale vectors; a file filter could return nothing.
• Consolidation: today's notes were marked consolidated too early and never merged; files past the size budget were skipped for good; a permanent memory saved during consolidation was overwritten; saved credentials could be replaced by placeholders like "see prior backup"; facts could be attributed to the wrong person.
• Index: AGENTS.md showed up as a memory; emptied files kept their chunks; entries carried the previous entry's heading.
• Reliability: an OpenAI outage no longer fails every message or the bot's start; concurrent chats no longer share tool state (a reminder could land in the wrong Slack channel); a failed consolidation is retried an hour later instead of after every reply.
• Safety: the agent can't read or overwrite Memclaw's own files (memclaw.db, .env, sessions, hooks), MEMORY.md or the daily notes.
• Images: search was limited to the current platform (a Telegram image can't be sent through Slack), and the stored image count now covers every platform.
• Telegram: /new sent right before a message can no longer resume the old conversation; /model refuses an id it can't check instead of saving a typo.
• Cursor: a slow run no longer kills the shared bridge, a crashed bridge is relaunched before the next message, and long bridge log lines no longer stall it.
• memclaw.__version__ reported 0.1.1; it now comes from the package metadata.

Internal

• End-to-end suite in tests/e2e/ (real OpenAI + Claude, throwaway vault): MEMCLAW_E2E=1 pytest tests/e2e. A manual GitHub workflow runs it with repository secrets.
• Unit tests run fully offline with a fake embedder.
• claude-agent-sdk 0.2.x; cursor-sdk pinned to 0.1.x.

Upgrade from 2.x

pip install --upgrade memclaw
# with the Cursor backend:
pip install --upgrade "memclaw[cursor]"
# pipx users
pipx upgrade memclaw

See docs/upgrading.md for the short version.

New Contributors

• @kkomelin made their first contribution in #10
• @mistercap179 made their first contribution in #11

Full Changelog: v2.0.0...v3.0.0