claude-mem

Patch release — ship the rebuilt plugin bundles

v13.24.0 bumped every manifest to 13.24.0 but never re-ran the build, so the committed plugin/scripts/*.cjs artifacts still carried the 13.23.1 bytes. Because the Claude Code marketplace installs straight from this repo (.claude-plugin/marketplace.json → "source": "./plugin"), marketplace users on 13.24.0 were executing 13.23.1 code.

That mismatch put the worker in an unbounded kill/respawn loop: ensureWorkerRunning() compares the resolved plugin version (13.24.0, from the plugin cache directory name) against the worker's baked-in __DEFAULT_PACKAGE_VERSION__ (13.23.1, reported by /api/health), SIGKILLs on mismatch, and respawns the same stale file on the next hook event — taking the in-flight observer down with it every time.

What's in this release

• Rebuilt plugin bundles (#3857, merged as #3878) — plugin/scripts/worker-service.cjs, mcp-server.cjs, server-service.cjs, transcript-watcher.cjs and plugin/sqlite/SessionStore.js are regenerated from source, so the shipped artifacts match the manifest version.
• Clean patch version — 13.24.1 so existing 13.24.0 installs actually pull the corrected artifacts on upgrade rather than sitting on a cached, byte-identical 13.24.0.

Upgrading

Marketplace users: update the plugin. npm users: npx claude-mem@13.24.1.

Ships the fix for #3857 (PR #3878).

Independent Cursor and Grok Bot marketplace plugins

Ship claude-mem as two store plugins plus a host-observer install path (#3842)

claude-mem now installs as two independent Cursor marketplace plugins — claude-mem-cursor and claude-mem-grok-bot — instead of one glued listing. Each host can be installed alone. Grok Bot does not require Cursor hooks, the Claude CLI, or an xAI API key.

Install matrix

• npx claude-mem install --ide cursor
• npx claude-mem install --ide grok-bot
• both flags together is optional

Observer

• --provider host uses a local OpenAI-compat loopback so the already-logged-in host agent writes observations. No API key. Alias of OpenRouter + loopback URL + dummy key + host model.
• --provider openrouter remains the remote path (cmem.ai inference or any OpenAI-compat URL)
• Claude and Gemini providers stay

Worker

• Default stays local. Existing --runtime server --server-url still points at a remote worker.
• The host-observer shim never binds the worker port. If 37777 is taken, the shim uses 37778 (or CLAUDE_MEM_HOST_OBSERVER_PORT). A healthy worker is not restarted.

Ingest

• Cursor: existing hook cursor events with platformSource=cursor
• Grok Bot: no hooks. Transcript watcher on agent-transcripts/*/*.jsonl with platformSource=grok-bot
• POST /api/memory/save honors metadata.platformSource

CLI

• npx claude-mem mcp stdio entry
• npx claude-mem hook cursor

Docs: docs/store-plugins.md install matrix and public Mintlify page docs/public/grok-bot/index.mdx. Plugin ids locked: claude-mem-cursor, claude-mem-grok-bot.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v13.23.1...v13.24.0

Fix: the quota guard and usage_limit_hit never fired

The SDK's rate-limit message was matched by the wrong shape (#3838)

The quota guard (#2234) and the usage_limit_hit telemetry event added in 13.23.0 (#3837) both read the observer's SDK stream for a system message with subtype rate_limit. The SDK has never sent that. SDKRateLimitEvent in the pinned SDK (0.3.172) is a top-level { type: 'rate_limit_event', rate_limit_info } message in the SDKMessage union, and no system subtype named rate_limit exists in its declarations.

So the guard never matched, RateLimitStore stayed empty, the subscription quota abort never fired, and usage_limit_hit stayed at zero across more than a thousand Claude-provider installs already running 13.23.0.

extractRateLimitInfo in RateLimitStore.ts now accepts the real shape and still tolerates the legacy system/rate_limit form. ClaudeProvider routes the stream through it. The guard logic and the event emission are unchanged.

Verified against the SDK's own type declarations and, independently, by Greptile's mocked-stream harness: subscription and OAuth sessions abort after a rejected event, API-key sessions stay exempt, and unrelated or malformed messages leave the store untouched.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v13.23.0...v13.23.1

Telemetry: know when users run out of Claude Code usage

New usage_limit_hit event (#3837)

claude-mem now reports to PostHog when the Claude subscription behind a session runs out of usage. Nothing tracked this before: the only quota signal was abort_reason: quota on the observer rollup, which fires when claude-mem's own guard stops early, not when the user's session is blocked. The Stop hook never fires on a limit-hit turn, so the transcript path could not carry it either.

The observer runs on the same account as the observed session, so the SDK's rate_limit stream reporting a window as rejected is the moment the user's own Claude Code session ran out. The worker captures the event there with:

• limit_window — five_hour / seven_day / seven_day_opus / seven_day_sonnet / overage / unknown
• overage_status — allowed / allowed_warning / rejected / unknown
• is_using_overage — boolean
• resets_in_minutes — whole minutes until the window resets, floored at 0
• plus the existing ide, provider, observed_model, observed_billing

Closed enums, a boolean, and one integer. The provider's limit message text never leaves the machine. All four keys are on the scrub whitelist and documented in telemetry.mdx.

Deduped. RateLimitStore.set now reports only a fresh rejection, so a window that stays rejected across many observer requests emits once. It emits again after a reset or an allowed snapshot in between. A worker restart while still capped re-emits once.

Limits. Fires only when the observer runs on Claude with a subscription login. API-key, Gemini, and OpenRouter observers never see the SDK rate_limit stream.

Fix: quota refusals in Claude Code's real wording no longer drop work

isQuotaLimitedObserverOutput only matched "claude usage limit", "weekly", and "subscription" wordings. Claude Code actually writes "You've hit your session limit · resets …", "You've reached your Fable 5 limit…", and "You're out of usage credits…". Those turns were classified as ordinary prose and the queued batch was dropped. They now pause the generator and preserve the batch like every other quota refusal. The detector also skips XML like its two siblings.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v13.22.0...v13.23.0

What's new

Telemetry: observed model, source, and billing tier (#3836)

PostHog previously only knew the observer model (the model claude-mem uses to write observations). The observer_turn_rollup event now also reports the session being observed:

• observed_model — the model the user's IDE session is running (e.g. claude-fable-5-1), read from the transcript's last assistant entry on each Stop hook.
• observed_billing — a closed, low-cardinality enum: max | pro | team | enterprise | subscription | api_key | bedrock | vertex | foundry | unknown, detected in the hook process from Claude Code's environment and ~/.claude.json's oauthAccount.organizationType.
• ide and provider now actually reach PostHog on the rollup. The docs already claimed this; the rollup computation was dropping them.

Storage

• sdk_sessions gains two nullable columns, observed_model and observed_billing (schema version 50). The migration is idempotent and runs on worker start.

Privacy

• Only oauthAccount.organizationType, oauthAccount presence, and customApiKeyResponses.approved are read from .claude.json, and the parsed object is projected to those fields immediately. Parse failures log only the error class name, never the message.
• Both new properties are whitelisted in the telemetry scrubber and documented in docs/public/telemetry.mdx.

Performance

• The Stop hook now reads the transcript once for both the last assistant message and the observed model (previously one read; the new field did not add a second).

Payment is deferred until after you've read the offer.

Picking CMEM Pro in the installer opened a browser on a bare Stripe card form. /api/pro/trial/claim redirected a non-entitled user straight into Checkout, so /pro — the page that actually explains the plan — was only ever reached on an error or a cancellation.

The claim route now sends those users to /pro?from=installer&pairing=…&trial=30 and starts Checkout only when the offer page's CTA asks for it. Nothing about the Checkout session changed — same trial length, same pairing metadata, same success and cancel URLs. It just happens after the offer instead of before.

That half is server-side and already live for 13.21.0 and 13.21.1 too — it changes where the route sends people, not the URL the installer opens.

In this release:

• CMEM Pro is pre-selected on the provider prompt. It is the recommended path, and selecting it no longer means "pay now".
• Claude Code is pre-selected on the IDE prompt, along with anything else detected.

Both prompts opened with nothing checked, which made the recommended path a required chore before the install could continue. They are still multiselects — uncheck and pick something else if you want.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v13.21.1...v13.21.2

The trial is 30 days everywhere now.

The installer's provider screen already advertised a 30 Day Free Trial and the server already issued 30-day checkout URLs — but every other surface still said 7, and the promo links carried no trial length at all.

That last part mattered more than copy. cmem.ai/pro is deliberately length-neutral without an explicit ?trial=, so a click from the session-start banner, the viewer, or the context banner landed on a page that never named a trial length and sent no trial into Stripe Checkout. Those links now carry it.

• Every promo link emits ?from=<surface>&trial=30 — session-start banner, context banner, welcome hint, viewer header, installer, fallback notice.
• PRO_TRIAL_DAYS in src/shared/pro-promo.ts is the single knob, mirrored in the viewer's own copy (its tsconfig pins rootDir and cannot import the shared module).
• The installer's Next Steps screen shows the trial link again. 'installer' was a declared promo source with no caller after the Next Steps trim in v13.21.0, so the last screen of the funnel never mentioned the offer. It shows for non-Pro installs only.
• Copy: "free week" → "free trial" in the fallback notice and the countdown line. README and install docs now say 30 days.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v13.21.0...v13.21.1

Installer release. Fixes the outage that made 13.20.0 uninstallable, and reworks the account/provider flow.

Installs no longer hard-fail when cmem.ai is unreachable

13.20.0 required browser OAuth before the provider choice, unconditionally. When the server endpoint it depended on turned out not to be deployed, every install died on "Could not start OAuth login."

--provider claude now skips login entirely. It configures memory against your own Anthropic plan and never contacts cmem.ai, so there is no account question for login to answer.

Keyed on the explicit flag, not on reachability: falling back to a local install whenever cmem.ai happened to be down would silently change what you get. gemini and openrouter stay gated, because openrouter is the transport for the cmem gateway.

The trial length is no longer pinned to 7 days

The installer used to require the checkout URL to say exactly trial=7, so the server could not change its own offer without breaking every published installer — and the rejection surfaced as "Could not start OAuth login", naming nothing. The URL shape is still validated strictly; the number is now the server's to choose.

The provider screen is two lines

Select Provider:
================
[ ] CMEM Pro (30 Day Free Trial: Tokens for Observations + Real-Time Cloud
    Sync for Claude.ai, ChatGPT.com, anything that accepts an MCP Connector)
[ ] Use your Anthropic Max Plan (no cloud sync, uses tokens for observations)

The nine-bullet benefits note that printed above it is gone.

The billing acknowledgement moved to checkout

It was a terminal prompt asking you to confirm charge terms before you could see what you were agreeing to. It is a term of the charge, so it now appears on the screen that takes the card, above the pay button.

Login is only about logging in

• A server-reported checkout stage during login no longer renders "Waiting for CMEM Pro setup in the browser...".
• The login hand-off prints the URL, then waits: Continue setup in browser... (hit return to open automatically). The URL comes first, so headless and SSH sessions are never blocked.
• The post-login browser page now says "Close this window and go back to your terminal" instead of linking to the dashboard, which abandoned an install still waiting on that round-trip.

Fixed: the checkout hand-off briefly also waited for Return, which stalled the install outright. It opens directly again.

Next Steps is shorter

Dropped the CLAUDE_MEM_WELCOME_HINT_ENABLED opt-out, the uninstall warning, and the A/B framing that presented "just start working" as a decision.

Consolidates the observer, quota, and installer work onto one release.

Observer no longer burns your allowance on doomed requests

An exhausted allowance used to buy one refused request per captured tool call, for the rest of the billing cycle: the generator exits on the refusal, and the next observation starts a fresh one that earns the same refusal.

• A quota breaker now withholds requests for a cooldown and then admits exactly one probe to re-check, instead of letting every live session through the moment the window elapses.
• The breaker persists, so restarting the worker no longer resets it.
• Quota returned as assistant prose (which aborts rather than throwing) now arms the breaker and the health ledger too. That path was previously invisible: the allowance was spent, nothing would ever store, and you were told nothing.
• Probe claims are scoped to the generator that took them, so an earlier generator's exit can't clear a later session's probe and wedge the provider shut.

Capped users are no longer told to restart

Hitting your allowance is not an outage. The session-start warning stopped presenting it as one, and stopped recommending a restart that cannot help.

Observer conversations are bounded

The observer now runs in bounded generations seeded from memory, and a recycled generation is briefed from the real session-start context rather than starting cold. A recycle resumes on its own, so the last observation of a session is no longer stranded waiting for a tool call that never comes. Two unbounded request loops were closed.

Automatic fallback when the claude-mem key is exhausted

When the cmem gateway terminally rejects the delivered key, memory falls back to your Anthropic plan and says so once at session start. This is treated as the promised switch, not an outage, so it stays out of the health ledger and never triggers the outage warning.

Installer: the login step is only about logging in

Every install is account-first, and the provider choice (CMEM Pro vs. your own Anthropic plan) now happens strictly after login. The login step carries no plan or pricing language:

• A server-reported checkout stage during login no longer renders "Waiting for CMEM Pro setup in the browser…". That wording is scoped to enrollment.
• The pre-login note explaining provider mechanics is gone. Both browser hand-offs now print the URL, then wait: Continue setup in browser... (hit return to open automatically). The URL prints first, so headless and SSH sessions are never blocked — open it by hand and the wait clears on Return.
• Signup links were replaced with OAuth pairing, and signed-in provider transitions were hardened.

Known limitation: a non-interactive install that cannot reach cmem.ai now fails rather than silently configuring a local-only install, including runs that pass --provider claude. A bypass for explicit local providers is coming in the next release.

Restart the memory worker in one click

When the observer stops saving, the outage warning used to point at ~/.claude-mem/settings.json. A restart clears nearly every one of these outages (a wedged or SIGKILL'd provider subprocess), so the warning now leads with the restart, offered two ways:

Restarting the memory worker clears almost every outage. Do one of these:
  Click to restart:  http://localhost:37777/restart
  Or in a terminal:  npx claude-mem restart

Still failing after the restart? Run: npx claude-mem doctor

GET /restart serves a page whose button restarts the worker and waits until the replacement is actually up before telling you so.

The warning is also easier to see

• Moved below the injected context. The timeline runs long enough that a warning at the top had already scrolled off by the time context finished printing.
• Shown in red in the terminal. The agent's copy stays clean — ANSI escapes there are just noise in the model's context.

Safety notes

The restart page is deliberately conservative:

• The GET is inert. Restarting is a POST behind a real click, so a page that merely names the URL in an <img> cannot bounce your worker.
• The route refuses to be framed (frame-ancestors 'none', X-Frame-Options: DENY), so an attacker cannot frame it and harvest the click through an overlay.
• Success requires the successor, not the corpse: a different pid on /health (the dying worker answers for the whole graceful-shutdown window) and /api/readiness ok (a bound port is not a ready worker).

/health now reports pid to make that check possible.

Observer sessions stay silent and never contact other agents

The memory observer is a passive recorder by design, but nothing in its prompt actually said so. This release makes both rules explicit in observer_role, which is injected into the observer's prompt on every turn.

SILENT BY DESIGN — the observer session runs invisibly in the background. The session it watches does not know it is being observed, and it must stay that way: an agent that knows it is being watched changes its behavior in unpredictable ways, which corrupts the very record the observer exists to create.

NO CONTACT — never contact, message, ping, or notify any other agent or session, including the observed one. No spawning subagents, no asking for input, no attempting to influence work in progress. One-way recorder: observations in, XML out.

Scope

Applied to all four base modes — code, email-investigation, law-study, and meme-tokens. The 32 localized and --chill variants override only placeholders and footers, so they inherit the new text automatically.

The mode-creator authoring reference also gained the rule (worked example plus a prompt-quality checklist item), so modes authored later carry it forward.

Full changelog: https://github.com/thedotmack/claude-mem/compare/v13.18.0...v13.18.1

Every CMEM Pro trial offer is now 30 days.

The 7/14/30 installer split has been called — 30 won on signups. The installer offers 30 days on every run, and the session-start banner, context banner, welcome hint, viewer header, and cursor-hooks docs now say 30 days and pass trial=30 explicitly, so a click can't land on a shorter arm. 7 and 14 remain valid values on cmem.ai.

What changed

• Fast, bounded Codex startup context. Removes the synchronous version/dependency check and duplicate one-shot MCP startup from Codex SessionStart, uses the persistent local worker path, caps API requests at 2 seconds, and keeps the supported cold-start path bounded. Warm startup verification returned injected context in under one second. (#3789)
• 7/14/30 installer-offer measurement. Records every user-visible CMEM Pro offer surface as pro_offer_viewed, with trial_days, canonical trial_variant, and installer source/surface labels. Total displays and unique anonymous installs can now be compared with trial starts per arm. (#3792)

Privacy and behavior

Offer measurement uses the existing consent-gated anonymous install UUID and strict property whitelist. It never sends email addresses, sign-in links, pairing secrets, device codes, prompts, paths, or source content. This release does not change trial assignment, offer copy, pricing, or checkout behavior.

Installer trial-length offers

• Assigns one stable 7-, 14-, or 30-day CMEM Pro trial offer per installer flow.
• Shows the exact assigned length consistently in prompts, retry/resend flows, activation summaries, and cmem.ai links.
• Sends the same trial length to the web start API and preserves it across reruns.
• Adds focused coverage for all three arms and legacy-state recovery.

🪟 The Windows Megafix

Windows support goes from technically works to actually solid. Rollup of five fixes (#3661), validated on real Windows 11 hardware by a community tester who could reproduce the production failure on demand.

Fixed

• Chroma process-tree cleanup (#3644) — worker shutdown/restart now kills the entire uvx → uv → python → chroma-mcp chain on Windows and POSIX, with PID-identity checks so a recycled PID is never mistaken for ours. No more zombie Python processes, no more port 37777 wedged under a dead PID.
• tree-sitter.exe resolution (#3647) — smart file reads no longer silently return nothing on Windows.
• ~\ tilde paths (#3648) — Windows-style home paths in settings expand correctly; POSIX paths containing backslashes are now explicitly left untouched (previously they could be mangled).
• Git Bash preflight (#3649) — install/doctor fail loudly with a clear message when Git Bash is unreachable, instead of every hook crashing cryptically. Checks every git on PATH, so non-standard installs (e.g. D:\...) resolve.
• npm run build-and-sync on Windows (#3657) — no rsync or POSIX shell needed; a portable mirror reproduces rsync -a --delete semantics on all platforms, and worker:logs/worker:tail work in PowerShell (and fix a broken tail -f invocation on macOS).

Review hardening

• Mirror refuses overlapping source/destination roots before touching the filesystem (Greptile P1).
• Log tailing survives rename-and-recreate rotation via file-identity tracking (Greptile P2).
• Doctor: a missing npx install marker with deps present is a warning, not a failure — marketplace and dev installs never have one.

Verification

2,700+ tests green on macOS/Linux/Windows CI, Greptile 5/5, cross-platform regression review found no blockers, and both doctor fixes re-confirmed on the tester's Windows 11 machine.

claude-mem for Cowork 🧠

Claude started remembering Cowork tasks today — this release takes it further.

New: claude-mem-cowork plugin

A second plugin in the marketplace, built for Cowork (native Claude app — mobile, web, desktop cloud sessions):

• Hooks capture tool use in ephemeral Cowork containers and stream fragments to cmem.ai, where Pro runs the observer server-side
• Compiled observations are injected into every new session and every spawned agent
• Fail-soft by design: no API key → silent no-op; cmem.ai unreachable → events spool locally and flush later; every hook exits 0 unconditionally
• Credential redaction hardened: short and whitespace-bearing values, any Authorization scheme, Cookie headers, full URI userinfo
• mem-search + mem-setup skills bundled

Install in any Cowork session:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem-cowork@thedotmack

Then say "set up claude-mem".

Landing page: https://cmem.ai/cowork

Also in this release

• Memory Prize scorecard and slides (hackathon 05)
• Overflow spool re-spools the remainder instead of dropping oldest events
• Marketplace version alignment

What's Changed

OpenRouter attribution overhaul

• Renamed the OpenRouter app entry to Claude-Mem (display title only — the ranking identity is the referer URL, which is unchanged, so the accumulated leaderboard history stays intact)
• Centralized all attribution headers into a shared module (src/shared/openrouter-attribution.ts) so the worker and server providers can never drift apart and split the app entry
• Migrated from the legacy X-Title header to the canonical X-OpenRouter-Title
• Claimed marketplace categories via X-OpenRouter-Categories: cli-agent,creative-writing
• Env overrides (CLAUDE_MEM_OPENROUTER_SITE_URL / CLAUDE_MEM_OPENROUTER_APP_NAME) still work for forks and self-hosted gateways

Fixes

• wowerpoint skill: corrected the share URL format (dropped the /d/ path segment)

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v13.15.2...v13.15.3

Observer errors now tell you what happened and what to do

When the memory observer stops working — most commonly a CMEM Pro allowance that's been used up — claude-mem now says so in plain words, once, with the one thing to do about it. No more silent OpenRouter upstream error (status 502) retry loops.

Fixes

• Worker carries the gateway's error envelope (#3601): the OpenRouter classifier now understands the cmem.ai gateway's {code, message, action, url, request_id} errors and, for plain OpenRouter, keeps the upstream body (e.g. Key limit exceeded … Manage it using <url>) instead of discarding it. 402 and "key limit exceeded" bodies are classified as quota exhausted and are not retried.
• One log line per failure: Observer failed {kind, code, requestId} <message — action url (req id)> replaces the five-line fan-out.
• Session-start warning says the right thing (#3601, #3612): the observer-health warning now shows the message, a What to do: line, the link, and the request id — and no longer tells Pro users to edit ~/.claude-mem/settings.json. It also appears for projects that have no memories yet (previously the welcome hint hid it).
• Observer-health alerting (#3538): claude-mem alerts you at session start when observations stop flowing.

Pro trial

• 7-day Pro trial surfaced everywhere the viewer URL is shown (#3613): session-start banner, per-message banner, first-session welcome hint, installer "Next Steps", viewer header, and cursor-hooks docs — one source of truth (src/shared/pro-promo.ts) with per-surface ?from= attribution links to https://cmem.ai/pro.

Pairs with the cmem.ai gateway change (claude-mem-pro #106): honest status codes (402/401/429/503, never 502), a 6-code error taxonomy, and an x-request-id on every error.

Note: v13.15.1 was tagged but never released or published; 13.15.2 supersedes it.

7-day Pro trial in the installer

The npx installer can now start a free week of CMEM Pro end to end:

• Trial funnel in npx claude-mem install — pitch → email entry → magic-link → Stripe checkout, with the installer polling the pairing API and finishing setup automatically once the trial starts (#3524)
• Device-code approval — the terminal shows a short code (XXXX-XXXX) that you confirm in the browser before credentials are delivered, closing a pairing-secret disclosure vector (#3524)
• Live model pricing — the installer now fetches model pricing from the API instead of shipping hardcoded numbers (#3515)

Requires the cmem.ai backend released today (trial routes + cli_pairings device-authorization grant).

CMEM Pro is now the first option in the installer

npx claude-mem now leads its provider prompt with CMEM Pro, and every option shows what it actually costs per 1,000 observations — so the choice is made on price rather than brand recognition.

◆  Which memory provider do you want to use?
│  ● CMEM Pro — observer model, off your plan  ($0/1k observations · $30/mo, cloud sync included)  Recommended
│  ○ OpenRouter / any OpenAI-compatible key    (~$2.73/1k observations, billed to you)
│  ○ Gemini API key                            (~$3.39/1k observations, billed to you)
│  ○ Use your Anthropic plan                   (~$8.91/1k observations, billed to your Claude plan)

Anthropic moves last: it is the most expensive per observation and it bills your own Claude plan.

Picking CMEM Pro

Opens cmem.ai/pro?from=installer, waits for the cm_pro_… key the signup flow hands back, writes it to settings, and points you at the browser to finish cloud sync. The key is pasted by hand — no polling, no device-code handshake.

No new provider code

OpenRouterProvider is already a generic OpenAI-compatible client whose base URL and model both come from settings, so CMEM Pro is four settings writes:

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://cmem.ai/api/inference/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "cmem-observer",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "cm_pro_<hex>"
}

'cmem' is a prompt-only sentinel and never reaches settings.json — the worker still only understands claude | gemini | openrouter.

Cost figures

New src/npx-cli/cmem-pro-costs.ts derives every label from one constant (ratePerM × TOKENS_PER_OBSERVATION / 1000), so re-pricing is a one-line edit. CMEM Pro deliberately carries no computed $/1k — it is a flat subscription that does not bill your tokens.

CMEM_PRO_ORIGIN overrides the origin so the whole funnel can be walked against a dev server.

Notes

• openBrowser() is best-effort; the URL is printed first, so headless boxes just get a copy-pasteable link.
• Existing installs are unaffected — this changes the prompt, not any persisted provider.

Full Changelog: https://github.com/thedotmack/claude-mem/compare/v13.13.1...v13.14.0

What’s new

• Adds an interactive /mode-creator workflow that turns a user’s domain and note-taking needs into a custom claude-mem mode.
• Guides capture-type and tag design, including specialized suggestions when standard code mode is a useful baseline.
• Installs custom modes in durable user storage and reports the active mode in startup context.
• Adds optional tag-triggered Telegram notifications with guided bot configuration and verification.
• Includes mode-authoring and Telegram references, secure helper scripts, documentation, distribution coverage, and runtime tests.

Compatibility

This patch release has no intended breaking changes.

Sensitive observation type

Adds a ninth observation type to the code mode: sensitive — information that isn't quite private, but that you wouldn't want leaking into further content development in the wrong context. Internal URLs, unreleased plans, personal details, business metrics, client or partner names.

These fire a Telegram notification by default, the same way security_alert does.

Configuring

Notifications are controlled by CLAUDE_MEM_TELEGRAM_TRIGGER_TYPES in ~/.claude-mem/settings.json. The default is now security_alert,sensitive. Set the key to any comma-separated list of types, or to an empty string to turn notifications off entirely.

Existing installs are migrated automatically: if your trigger list is still the old default of exactly security_alert, it is rewritten to include sensitive. A customized list is left untouched. Without this migration the new type would never have notified on any existing install, because a fresh settings.json is seeded with every default and persisted values win on load.

If you had deliberately set your trigger list to exactly security_alert and want it to stay that way, set it to something explicitly different after upgrading — the migration cannot distinguish that case from the seeded default.

Also in this release

• Observer prompt fix. The type_guidance prompt still described "6 options" and never listed security_alert or security_note from #2084. That string is the only type prose the observer model sees — the per-type description fields are never injected into any prompt — so those types have been under-emitted since April. It now enumerates all nine.
• Corpus filters, the OpenClaw detailed feed, and the weekly-digests legend all recognize the new type.
• BMP-safe fallback for the new emoji, so injected context can't contribute a surrogate pair (the #2787 failure class).
• Built plugin artifacts are regenerated, picking up the chroma concurrent-write fix from #3462 that had not yet been built into the shipped bundles.

Full changelog: https://github.com/thedotmack/claude-mem/compare/v13.12.4...v13.13.0

Four root-cause fixes from the post-v13.12.2 issue batch.

Fixes

Shutdown teardown no longer skipped on a non-listening server handle (#3380)

performGracefulShutdown treated Node's ERR_SERVER_NOT_RUNNING from server.close() as fatal in step 1, which skipped session drain, MCP close, Chroma stop, DB close, and supervisor stop — the Windows port-hold symptom. An already-closed server now counts as closed (explicit code check, everything else still rejects), and Server.listen() assigns the handle only once actually listening, so a failed bind can no longer leave a stale non-listening handle for shutdown to trip on. (#3387)

Concept tags participate in context injection again (#3379)

The observer prompt's own guidance format taught the model to emit keyword: description concept tags, which the exact-match injection SQL silently excluded — observations tagged that way never surfaced. Concepts are now truncated at the first colon at the parse boundary, the producer prompts in all four modes require bare keywords, and migration v49 backfills stored rows — requeueing corrected native rows for cloud re-push (sync_rev bump + synced_at reset, mirroring the prompt-repair convention) and guarded by json_valid so a malformed row cannot abort boot. The injection query itself is unchanged. (#3389)

Background init no longer aborts on orphaned rows; adoption race and logging fixed (#3378)

The v7/v9 table-rebuild migrations copy child tables with foreign keys enforced, so historical orphaned observations/summaries (no sdk_sessions parent) threw FOREIGN KEY constraint failed in the SessionStore constructor and the worker never reported ready. A pin-down test proved the site red→green; the fix repairs stub parents in-place before both rebuild copies — orphaned rows are user data and are never deleted. Also: adoption errors now log as real text instead of [object Object], and the worktree-adoption kick moved after DB init so its write connection no longer races boot migrations (database is locked). Complements the stale-worker recycle fix shipped in 13.12.3. (#3390)

Maintainer directives no longer ship to end users (#3381)

Root CLAUDE.md's Local Status Notes and Daily Maintenance sections — including an autonomous upgrade-and-commit directive — shipped verbatim to every marketplace git-clone install and were obeyed by end-user Claude instances (the #2537 .npmignore guard only covers the npm tarball, see #3359). Those sections now live in gitignored CLAUDE.local.md; tracked CLAUDE.md keeps only contributor content, and the maintainer sync copies the slim file over any stale marketplace copy. (#3391)

Verification

Full suite 2539 pass / 0 fail, tsc clean, anti-pattern sweep over the round's diff clean, worker restart cycle at 13.12.4 shows none of the fixed failure signatures.

Hotfix: self-perpetuating stale-worker recycle loop (#3378)

The bug. On a version mismatch, hooks asked the running (stale) worker to restart itself — and the dying worker spawned its successor using its own install's code and resolver. A ≤13.11.0 worker would respawn its own version, re-bind the worker port before the hook's correctly-resolved lazy-spawn could, and the mismatch recurred on every prompt, forever. One report measured 2,424 recycles in a single day, with every UserPromptSubmit ending in a ~40s hook timeout. Because the buggy handoff ran inside the old install's process, fixing the new version's resolver alone could never break the loop.

The fix. Hooks no longer delegate the recycle to the corpse. On version mismatch the hook now:

1. reads the owner-verified worker PID file,
2. SIGKILLs the stale worker — the only teardown guaranteed to execute zero stale-version code,
3. waits for the port to actually close, and
4. spawns the resolved installed version itself, via the existing lazy-spawn path and the single version oracle.

The dying-worker successor handoff now serves only CLI-initiated claude-mem restart, where the running install is the resolved install.

If you're currently stuck in the loop: just update. The first hook that runs after this version installs will kill the resident stale worker and take over — no manual cleanup needed.

Not addressed in this release (still open): the FOREIGN KEY constraint failed background-init error also reported in #3378, and the Windows stale-socket port hold in #3380.

54 community bug-fix PRs merged in one pass. Every open PR in the repo (157 total) was evaluated against a strict rubric — now codified in docs/merge-rubric.md: root-cause corrections only, with no guards, circuit breakers, fallbacks, retries, fail-open modes, self-healing machinery, truncation, or bolt-on second systems.

Windows

• Zombie-held worker ports now detected correctly, ending infinite startup-failure loops (#3356)
• Console-flash sweep: windowsHide on every remaining live spawn path — git, npm, IDE detection, Codex installer, worker wrapper, taskkill, MCP launcher (#3335, #3320, #3319, #3305, #2921)
• bun.exe resolved to its absolute path and spawned directly, skipping cmd.exe (which silently drops >8191-char PATH) (#3235, #3247)
• Worker ESM main detection via pathToFileURL (#3318); UTF-8 BOM tolerated in settings JSON read (#3307)
• Start-Process argument quoting survives spaced profile paths (#3293); codex.cmd shim quoting fixed (#3220)
• PowerShell call operator (&) added to Cursor/Windsurf hook commands (#2507)
• Missing Windows credential treated as absent instead of a spurious read failure (#3265); tests run on Windows via fileURLToPath (#3312)

Search & data integrity

• Semantic search preserves Chroma relevance ranking instead of silently reordering by recency (#3325)
• type=<custom> and non-category type filters no longer return empty results (#3281); date_from/date_to honored in worker searches (#3201)
• Merged-project records hydrate correctly on semantic-search ID lookups and worktree adoption patches Chroma by typed doc targets (#3342)
• getUserPromptsByIds applies limit after relevance reordering (#3347)
• Chroma watermark gaps persist across bootstrap and live sync — no more permanently stranded rows (#3364); duplicate IDs reconciled in place, stopping unbounded index growth (#3268)
• Custom observation types preserved instead of being misclassified as bugfix (#3185); files_modified is now evidence-gated from actual write/edit tool events (#3180)
• Tool payloads no longer double-encoded in observation prompts (#3150)
• Context generation opens SQLite strictly read-only under concurrent sessions (#3233)
• MCP tools/list advertises only tools that work in the active runtime (#3065); search routes to the Postgres-backed /v1/search in server runtime when it can serve the query faithfully (#3082)

Worker & providers

• CLAUDE_MEM_MAX_CONCURRENT_AGENTS actually enforced via atomic slot reservations (#3294)
• Observations attributed to the current prompt's project after repo/worktree switches (#3237); claimed batches preserved on auth-failure prose instead of being deleted (#3236)
• Worker startup waits through cold and concurrent readiness windows (#3238)
• Observer thinking disabled so thinking-only skips can't trigger harness re-prompts (#3256); observer SDK sessions no longer pollute the user's project transcript tree (#2942)
• CLAUDE_MEM_TIER_SUMMARY_MODEL honored on OpenAI-compatible providers (#3257)
• Stale default model ids updated: Sonnet/Opus (#3187) and retired Gemini models (#3283)
• __IMPORTANT MCP tool renamed important_workflow so strict clients can load the server (#3295); tsconfig moduleResolution moved to bundler for TS 6 (#3296)

Hooks, context & installers

• CLAUDE_MEM_EXCLUDED_PROJECTS honored on session-start injection (#3358); subagents without MCP tools skip file-context injection (#3341)
• ~ expanded in CLAUDE_MEM_DATA_DIR (#3350) and CLAUDE_CODE_PATH (#3275); Homebrew uvx path shared with the worker preflight (#3276)
• SessionStart no longer dumps raw JSON at the top of every session (#3282); Codex no longer receives a duplicate context payload (#3241) and transcripts continue after archival (#3223)
• Worktree compound keys preserved from subdirectories (#3304)
• Azure AI Foundry auth env preserved through the SDK sanitizer (#3314); invalid corpus names return 400 instead of 500 (#3251)
• Codex plugin cache actually installs during setup — best-effort wrapper deleted, fail-fast (#3066)
• mergeSettings and server bootstrap no longer destroy top-level settings keys (#2928, #2929)
• version-bump skill frontmatter name matches its directory (#3313)

Docs

• New docs/merge-rubric.md — the acceptance bar for bug-fix PRs, distilled from this sweep.

Thanks to everyone who contributed fixes: @rodboev, @stantheman0128, @huiihao, @jamincollins, @quinnmacro, @justindeisler, @davertor, @BBD-Resources, @povesma, @laihenyi, @LPdsgn, @KJJisBetter, @Steaeavean, @XX888QM, @rapidtackgithub, @SamuelZ12, @DNA, @girish-kanjiyani7, @E0993599799, @eslonaguiar, @desmond-rai, @Reese-max, @Wasabi-221, @mic2112, @yaw-sh, @derrickchwong, @SaadSharif4, @katsugtgz, @manoi-bms, @percy-raskova, @ShiroKSH, @eralpozcan, @anupamme, @SejiL, @remten341, @danscMax, @jamesdsizemore, and the PostHog bot fleet.

Critical fix: worker restart storm

Fixes an infinite worker restart loop triggered by plugin upgrades. The worker-script resolver ranked plugin cache directories by mtime, so when Claude Code stamped a superseded version dir with .orphaned_at (bumping its mtime), every restart respawned the old version while hooks on the new version kept demanding a restart — spawning hundreds of processes until the host machine exhausted its process table.

All four resolvers (worker successor, MCP launcher, Codex Windows launcher, POSIX hook prelude) now rank cache dirs by version — never mtime — skip orphan-stamped dirs, and share one deterministic version oracle with the staleness detector (checkVersionMatch), making the restart loop structurally impossible.

Recommended upgrade for all users. Note: the vulnerable resolver is the one running during an upgrade, so machines are protected from the next upgrade onward.

Details: #3371

Two-Lane Cloud Sync (cmem.ai Pro)

This release ships the complete two-lane sync architecture between your local claude-mem database and the cmem.ai sync hub (PR #3333):

• Per-user Durable Object sync hub — a Cloudflare Worker (workers/sync-hub) serving isolated HTTP push/pull lanes per user (Phase 1)
• Client apply path + schema migration v41 — deterministic application of remote changes into the local SQLite store (Phase 2)
• Hub push/pull transport + mutation outbox — local mutations queue durably and survive offline periods and retries (Phase 3)
• Advisory WebSocket speed layer — near-real-time sync nudges; correctness never depends on the socket staying up (Phase 4)
• Guardrails + monitoring — kill switch, watchdog, canary, and a full sync-matrix E2E suite (Phase 5)
• Canonical v2 projection pipeline and SyncHub-only client cutover
• Hardened verifier authentication on the sync hub

Sync is OFF by default. CLAUDE_MEM_CLOUD_SYNC_HUB_URL defaults to empty — nothing leaves your machine unless you configure a hub URL (see the cloud-sync skill or https://docs.claude-mem.ai/cloud-sync).

Fixes

• Restored process-global mock.module cleanup that broke CI under Linux readdir ordering

Worker-native cloud sync (PR #3182)

The standalone cloud-sync.mjs daemon is retired. The worker now syncs memories itself — every local write nudges a background flusher that drains unsynced rows to cmem.ai, with no separate process to install or babysit.

New:

• CloudSync flusher: write-site nudges, 1.5s debounce coalescing write bursts, single-flight flush, 200-row/2MB pages, 30s request timeout, capped exponential backoff on failure
• GET /api/sync/status — pending counts per kind, last flush time, last error
• /cloud-sync skill — status checks, first-run credential migration from the legacy .cloud-sync.env, daemon retirement, and worker restart runbook

Fixed:

• Prompts now join through sdk_sessions to push their real memory_session_id/project instead of an unresolvable fallback — cloud-side prompt-to-session views (Summary ⇄ Prompt toggle, Replay) can now actually find their prompt
• Schema v40 self-repair: on upgrade, every previously-synced prompt (including ones uploaded by the legacy daemon) is re-queued and re-pushed through the fixed mapper; a backfill lane header suppresses realtime broadcast storms during that re-push
• Closed a race where a session's memory id registering while its prompt's upload was still in flight could leave that prompt permanently mis-keyed in the cloud — the stamp is now guarded per row and re-pushes with the corrected mapping instead

Migration: fully automatic and backward compatible. Existing standalone cloud-sync users are migrated on first /cloud-sync run after upgrading; installs with no cloud sync configured are unaffected.

Patch release focused on cross-platform stability and worker/runtime correctness.

Fixes

• Worker host: clients now honor CLAUDE_MEM_WORKER_HOST (the address the server actually binds), with IPv6 literals bracketed correctly in health checks and display URLs.
• Worker identity: cache/marketplace/MCP/CLI/restart launches converge on one worker bundle (stops version-skew from two builds on one port).
• Windows: centralized spawn shims remove the shell:true footgun; codex hooks emit a Windows-executable command instead of a POSIX-only one.
• Install: repair now restores the marketplace runtime root (not just the cache); ships the plugin/sqlite runtime modules that were causing MODULE_NOT_FOUND on clean installs.
• SQLite/settings: atomic settings writes, busy_timeout to avoid SQLITE_BUSY under concurrent worker/hook access, a migration column re-check, and removal of an index create that could crash boot on legacy duplicate rows.
• Supervisor: preserves HTTPS_PROXY and Bedrock/Vertex skip-auth env for the SDK subprocess.
• Worktree: relative gitdir: pointers resolved correctly.

Docs

• New Release Branches guide (main / core-dev / community-edge) with instructions for running the non-stable lines locally.

Deliberately excluded: client-side observer truncation (kept out per #3096) and project-identity re-keying (kept the #2663 repo-root key).

Fixes

• Codex SessionStart hook no longer fails at startup. When a hook errored before its handler ran (missing session_id, invalid cwd, or a missing transcript path), claude-mem fell back to a bare {"continue":true} regardless of which hook fired. Codex's strict SessionStart validator rejects that shape as "invalid session start JSON output," breaking context injection at Codex startup. The fallback now emits a valid hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: "" } for the context hook, matching what Codex expects.
• Fixed a related gap where the Codex adapter silently dropped an explicit empty-string additionalContext from its output instead of preserving it, which could leave the SessionStart payload incomplete.

Closes #2947, #2972. Supersedes #2953 and #2948.

Antigravity CLI support, Gemini CLI removed

Google deprecated Gemini CLI's free/individual tier (cutoff June 18, 2026) in favor of Antigravity CLI, the official successor announced May 19, 2026. This release migrates claude-mem accordingly.

Removed

• Gemini CLI host integration (adapter, installer, IDE-detection entry, hooks, dedicated docs/tests). The separate, still-supported Gemini LLM/observation provider (CLAUDE_MEM_GEMINI_API_KEY, GeminiProvider) is unaffected.

Added

• Full Antigravity CLI (agy) support at feature parity: hooks (7-event map sharing Gemini CLI's proven ~/.gemini/settings.json), dual MCP server registration, and GEMINI.md/rules-file context injection.
• npx claude-mem antigravity-cli install|status|uninstall subcommand support.

Verified end-to-end against a real live Antigravity CLI install, including hook firing, MCP tool registration, and context injection.