claude-mem y tus límites de Claude: quién paga la memoria

¿claude-mem gasta tu límite de Claude o lo estira?

claude-mem puede hacer que tu límite de Claude dure más o que se acabe antes. Lo que decide el resultado es quién ejecuta su observador. Con la configuración por defecto, el observador usa tu propia sesión de Claude Code, así que gasta del mismo plan Pro o Max con el que programas. Si lo pasas a una clave de Gemini u OpenRouter, a una clave de API de Anthropic o al servicio de pago CMEM Pro, ese coste sale de otro sitio.

Lo que falta es una medición. No he encontrado ninguna cifra de cuántos mensajes ganas o pierdes con claude-mem en el README ni en la documentación del proyecto. Las promesas de ahorro que verás son afirmaciones del propio proyecto, y más abajo explico a qué se refiere cada una.

Esta guía está fijada a claude-mem v13.35.0, publicada el 9 de octubre de 2026. No es la última versión: el 13 de octubre salió la v13.37.0, y el 6 de octubre el proyecto publicó seis versiones en un solo día. El proyecto cambia casi a diario. Antes de fiarte de los valores por defecto que cito aquí, compruébalos en tu propia instalación.

Qué hace claude-mem y por qué consume tokens

claude-mem es un plugin para Claude Code que guarda memoria entre sesiones. Si no tienes claro qué es un plugin y qué puede tocar en tu máquina, empieza por cómo funcionan los plugins de Claude Code.

El plugin registra hooks. Son pequeños programas que Claude Code ejecuta en momentos fijos, por ejemplo después de usar una herramienta. También arranca un proceso de fondo, el worker. Cuando Claude lee un archivo o ejecuta un comando, el hook manda esa observación al worker. El worker se la pasa a un observador: un agente que comprime la observación en una nota corta. Esa compresión es una llamada a un modelo de lenguaje, y cada llamada la paga alguien.

En el camino por defecto, el observador usa el Claude Agent SDK. Según el issue #1826 del repositorio, la función query() del SDK lanza un subproceso claude (el código está en SDKAgent.ts). Ese subproceso usa la sesión de Claude Code que ya tienes iniciada. Por eso el coste cae en tu plan.

Las notas se guardan en tu disco. Después, Claude las consulta con herramientas MCP (Model Context Protocol, el protocolo con el que Claude Code habla con herramientas externas). Una de ellas es mem_search, que llegó en la v13.35.0. Según las notas de esa versión, la búsqueda automática con mem_search no hace llamadas adicionales al modelo.

El balance tiene dos lados. En contra: cada observación comprimida es trabajo de modelo. A favor: si la memoria te evita volver a explicar el proyecto en cada sesión, tu conversación principal lleva menos contexto. Cuál de los dos pesa más depende de cómo trabajas. Para entender el segundo lado, conviene saber en qué gasta tokens Claude Code. Para compararlo con otros enfoques, mira qué cuesta cada tipo de memoria de agente.

Cómo instalar claude-mem de verdad

npm install -g claude-mem no instala el plugin. Ese comando instala solo el SDK y la librería. No registra los hooks ni configura el worker, así que tienes el paquete pero no tienes memoria. Hay dos formas reales de instalarlo.

Con el instalador, fijando la versión de esta guía:

npx claude-mem@13.35.0 install

Sin el @13.35.0, npx claude-mem install instala la versión más reciente. La otra vía es el marketplace de plugins, desde dentro de Claude Code:

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

Estos dos comandos no nombran ninguna versión, así que instalan lo que el repositorio publique en ese momento. La documentación pide Node.js 20.0.0 o superior. También necesita Bun 1.0 o superior y uv, pero el instalador los instala si faltan.

Lee la pregunta del instalador. El instalador interactivo te pregunta qué observador quieres, y la opción marcada por defecto es cmem, el servicio alojado CMEM Pro. En cambio, el valor por defecto del código y de las instalaciones sin preguntas (headless) es claude, es decir, tu propio plan. Si pulsas Enter sin leer, eliges CMEM Pro. Si eliges Claude, el observador gasta de tu plan desde la primera sesión.

No he podido ejecutar estos pasos en un entorno limpio. El plugin necesita un Claude Code con sesión iniciada y un proveedor de modelo real. Ejecútalos tú y comprueba cada resultado. Primero, comprueba que el worker responde:

curl -sS "http://127.0.0.1:$((37700 + $(id -u) % 100))/api/health"

El puerto por defecto del worker es 37700 más el resto de dividir tu UID entre 100. Si has fijado CLAUDE_MEM_WORKER_PORT, usa ese número. Si el worker contesta, está en marcha. Si ves un error que empieza por curl: (7) Failed to connect, nada escucha en ese puerto.

Después, mira qué camino tienes configurado:

grep -E 'PROVIDER|AUTH_METHOD|_MODEL' ~/.claude-mem/settings.json

El archivo se crea con los valores por defecto en el primer arranque. Ten en cuenta que una variable de entorno con el mismo nombre que un ajuste tiene prioridad sobre el archivo.

Los cuatro caminos del observador y quién paga cada uno

Camino 1: tu plan Pro o Max, el valor por defecto

En v13.35.0, CLAUDE_MEM_PROVIDER vale claude por defecto, CLAUDE_MEM_CLAUDE_AUTH_METHOD vale subscription y CLAUDE_MEM_MODEL vale claude-haiku-4-5-20251001. El comentario del código lo dice claramente: por defecto se usa la sesión iniciada del SDK, no una clave de API.

¿Cuenta eso para tu límite? A 13 de octubre de 2026, el centro de ayuda de Anthropic dice (traducción mía): "Puedes seguir usando el Claude Agent SDK, claude -p y aplicaciones de terceros con los límites de tu suscripción". Anthropic había anunciado un cambio para el 15 de junio de 2026. La misma página muestra un aviso de que ese cambio está en pausa. El observador es un subproceso del Agent SDK, así que entra en esa frase y gasta de tus límites. La página habla del Agent SDK en general y no nombra a claude-mem.

Hay una tensión que no puedo resolver por ti. La documentación del Agent SDK dice que Anthropic no permite que desarrolladores externos ofrezcan en sus productos el inicio de sesión de claude.ai ni sus límites, salvo aprobación previa. Eso incluye los agentes construidos con el Agent SDK, y la página les pide usar autenticación con clave de API. Las dos páginas son de Anthropic. Si esto te importa, pregunta al soporte de Anthropic.

El issue #1826 es la fuente de muchas alarmas sobre este camino, así que conviene leerlo bien. Lo abrió un usuario, ArtemisAI, el 15 de abril de 2026, con un título que habla de una prohibición de Anthropic del 4 de abril. No es un comunicado de Anthropic y no cita ningún texto de Anthropic. Sus predicciones, como que el observador fallaría en silencio o quedaría bloqueado, son suposiciones del autor. El mantenedor lo cerró el mismo día con el comentario "Closed during backlog cleanup", sin ningún cambio.

Hay un freno. La documentación de configuración dice que, con autenticación por suscripción, el observador se detiene cuando una ventana de uso llega a su umbral. No he encontrado el valor de ese umbral, así que no sé cuánto de tu ventana puede gastar antes de parar. Además, las ejecuciones con Claude están limitadas por CLAUDE_MEM_MAX_CONCURRENT_AGENTS, que vale 2 por defecto. Tampoco he encontrado cuánto pesa en tu límite una llamada de Haiku del observador comparada con tus mensajes con Opus o Sonnet.

Camino 2: el observador alojado CMEM Pro

CMEM Pro es el servicio de pago del proyecto. Con él, las observaciones pasan por el gateway de cmem.ai y las procesa un modelo llamado cmem-observer. La página de precios ofrece una prueba gratis de 30 días y después tres niveles: Pro a $30 al mes, Heavy a $70 y Max a $100. Cada nivel trae una cantidad de uso incluida, pero la página no dice cuánta. El nivel Max cobra el exceso.

Dos detalles de la página de precios importan antes de dar la tarjeta. Primero, la facturación puede empezar cuando termina la prueba o cuando se acaba el uso incluido en ella, lo que ocurra antes. Por eso la prueba puede durar menos de 30 días. Segundo, piden una tarjeta de crédito o débito y no aceptan tarjetas prepago. Según los términos del servicio, el cobro se hace con Stripe.

La página solo muestra el símbolo $ y no dice en qué moneda cobra. Si pagas desde España, México, Argentina o Colombia, mira la moneda en la pantalla de pago antes de confirmar. Consulta también la comisión de tu banco por cambio de divisa. No encontré ni en la página de precios ni en los términos cómo se tratan el IVA y los reembolsos.

Lo más importante de este camino es qué pasa al salir de él. Si el gateway rechaza tu cuenta porque gastaste el uso incluido, porque la suscripción no está activa o porque tu clave no vale, la memoria pasa a tu plan de Anthropic. El README lo dice así: cuando termina la prueba, la memoria vuelve a tu plan de Anthropic salvo que te suscribas. El cambio lo dispara ese rechazo, no una fecha del calendario, y tú no tienes que hacer nada para que ocurra. Si la prueba acaba y no pagas, vuelves al camino 1.

Camino 3: tu propia clave de Gemini u OpenRouter

Puedes mandar el observador a otro proveedor con tu propia clave. Edita ~/.claude-mem/settings.json y añade estas líneas dentro de las llaves del archivo. Para Gemini:

"CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "tu-clave",
"CLAUDE_MEM_GEMINI_MODEL": "gemini-flash-latest"

Para OpenRouter:

"CLAUDE_MEM_PROVIDER": "openrouter",
"CLAUDE_MEM_OPENROUTER_API_KEY": "tu-clave"

Según la documentación de Gemini, los ajustes se aplican al momento y no hace falta reiniciar el worker. El modelo por defecto para Gemini es gemini-flash-latest. Es un alias de Google que siempre apunta al modelo Flash estable del momento, así que el modelo concreto puede cambiar sin que toques nada. La documentación de claude-mem dice que puedes empezar sin activar la facturación en Google. También dice que los proyectos sin facturación tienen límites de peticiones por minuto, y que claude-mem mete pausas entre peticiones para respetarlos. Consulta los límites y las condiciones actuales en Google AI Studio.

Para OpenRouter, el modelo por defecto es cohere/north-mini-code:free, una variante gratuita. La documentación avisa de que los modelos gratuitos pueden tener límites de uso más estrictos. Ten presente qué envías: el observador manda el texto de tus observaciones, es decir, lo que Claude ha visto en tus archivos y comandos. Antes de pasar código de trabajo por un modelo gratuito, lee las condiciones de privacidad de OpenRouter.

Mientras el proveedor responde, este camino no gasta de tu plan de Claude. El problema llega cuando deja de responder. Si el proveedor agota su cuota, claude-mem lo pausa 30 minutos (90 segundos si es un límite de peticiones o una caída). La documentación dice que, por defecto, ese trabajo pasa a tu plan de Anthropic. El código de v13.35.0 dice otra cosa: el valor por defecto de CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER es una cadena vacía, y el código la trata como desactivado. No sé cuál de las dos fuentes acierta en tu instalación, así que fija el valor tú mismo:

"CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER": ""

Según el código de v13.35.0, con el valor vacío escrito en el archivo el respaldo queda desactivado. Así, un proveedor sin cuota no puede pasar el trabajo a tu plan. Según la documentación, los valores admitidos son claude, gemini, openrouter, openai-compatible y off.

Camino 4: ANTHROPIC_API_KEY en ~/.claude-mem/.env

El cuarto camino usa una clave de API de Anthropic, que se factura en tu cuenta de la Console y no en tu plan. claude-mem solo lee esa clave de un archivo propio, ~/.claude-mem/.env, con el formato CLAVE=VALOR:

nano ~/.claude-mem/.env
chmod 600 ~/.claude-mem/.env

Dentro del archivo escribe una sola línea, ANTHROPIC_API_KEY=sk-ant-..., con tu clave completa. El chmod 600 deja el archivo legible solo para tu usuario, que es el modo que indica la documentación.

claude-mem bloquea a propósito una ANTHROPIC_API_KEY exportada en tu shell. El código de v13.35.0 dice que esa variable se toma "solo de ~/.claude-mem/.env, nunca del shell padre" (traducción mía). La documentación explica el motivo: evitar cobros accidentales con una clave que se filtra desde el shell. Cuando el archivo tiene la clave, el código se salta la búsqueda de la sesión OAuth.

No exportes la clave en tu shell pensando en claude-mem. Claude Code sí lee esa variable. Si tienes una suscripción activa y ANTHROPIC_API_KEY en el entorno, Claude Code usa la clave en cuanto la apruebas, y con claude -p la usa siempre que exista. El resultado es que tu sesión principal pasa a cobrarse por API. La diferencia está explicada en iniciar sesión con la suscripción o con una clave de API en Claude Code.

Este camino no tiene el freno del camino 1. La documentación dice que la autenticación por clave de API nunca se detiene, así que el gasto sigue mientras trabajes. Revisa el consumo en la Console después de tu primera sesión. Para comparar precios, mira cuánto cuesta la API frente a la suscripción.

¿Y los créditos de API que ahora traen algunos planes? Según el centro de ayuda de Anthropic, los planes Max y Team incluyen créditos mensuales de API: $100 en Max 5x y $200 en Max 20x. Pro no tiene derecho a ellos. Para reclamarlos hay que tener el plan desde hace 7 días, y los créditos sin usar caducan al final de cada ciclo de facturación. Cubren el Agent SDK y claude -p solo cuando usan una clave de API de la organización de la Console vinculada. No he podido confirmar que la clave de claude-mem cuente así. Revisa la facturación de tu cuenta después de una sesión.

Queda una duda. La documentación lista tres modos para CLAUDE_MEM_CLAUDE_AUTH_METHOD: subscription, api-key y gateway. No he podido confirmar si basta con el archivo .env o si también hay que poner ese ajuste en api-key. Cuando el código de v13.35.0 carga la clave, describe el método como API key (from ~/.claude-mem/.env). Si el worker lo escribe en su log, esta búsqueda lo encuentra:

grep -i "api key" ~/.claude-mem/logs/worker-$(date +%F).log

Si no aparece nada, la prueba segura es la Console: haz una sesión corta y mira si aparece consumo con esa clave.

¿Son reales el "~10x" y el "hasta 100% más de uso" del README?

El README hace dos promesas. Ninguna viene con una medición publicada.

La primera es "~10x token savings". En el README va unida al flujo de búsqueda MCP, que filtra antes de traer los detalles. Habla de los tokens de una búsqueda en la memoria, no del observador ni de tu límite semanal. Aunque la cifra fuera exacta, no dice nada de cuánto gasta el observador al crear esa memoria.

La segunda es "up to 100% more usage from your plan". Está en la sección de inicio rápido, junto al observador alojado de cmem.ai y la prueba de 30 días. Se refiere a sacar el observador de tu plan. No habla del camino por defecto, en el que el observador gasta de ese mismo plan. Además, "hasta" marca un máximo, no un resultado típico.

Las notas de versión del proyecto son más prudentes que el README. La v13.34.2 corrigió un fallo del proveedor HTTP compartido, el que usan los proveedores compatibles con OpenAI. Desde la v13.29.0, el worker recortaba el historial del observador, y eso impedía reutilizar la caché de prompts en sus sesiones. Las notas dicen textualmente que el efecto sobre el coste del proveedor "has not been measured in production", y que por eso la versión no promete ningún ahorro. Las notas de v13.35.0 añaden que esa versión no cambia el observador, ni el modelo por defecto, ni el enrutado entre proveedores, ni la facturación.

Ten esto en mente con cualquier herramienta que prometa ahorrar tokens, por ejemplo la skill caveman para agentes de código. La cifra útil es la que mides tú con tu forma de trabajar.

Dónde se guarda tu memoria

Por defecto, todo queda en tu máquina, en ~/.claude-mem/. Hay una base de datos SQLite en ~/.claude-mem/claude-mem.db con sesiones, observaciones y resúmenes. También hay una base de datos vectorial Chroma para la búsqueda por similitud. Puedes mover la carpeta con la variable CLAUDE_MEM_DATA_DIR.

La sincronización con la nube de cmem.ai es una función aparte y opcional. Si la activas, sube a cmem.ai las narraciones de tus observaciones y el texto completo de tus prompts. cmem.ai dice que también guarda esos datos. Para apagarla, deja vacío uno de sus ajustes: el token, el ID de usuario o la URL del hub. Para que un fragmento sensible no se guarde nunca, el README indica envolverlo en etiquetas <private>. No he leído la política de privacidad de cmem.ai. Léela tú antes de activar la sincronización.

Usar el observador de CMEM Pro y activar la sincronización son cosas distintas. Con CMEM Pro, el texto de cada observación pasa por el gateway de cmem.ai para que el modelo lo procese. Con la sincronización, además se guarda una copia allí.

Cómo saber si claude-mem te está gastando el límite

Como no hay una medición publicada, la única cifra fiable es la tuya. Primero confirma tu camino con el grep de settings.json de más arriba. Si ves claude y subscription, el observador gasta de tu plan.

Después compara. Antes de una sesión de trabajo normal, anota el porcentaje de uso que muestra tu cuenta, y vuelve a mirarlo al terminar. Repite con el observador en Gemini u OpenRouter y una tarea parecida. La diferencia entre las dos sesiones es, aproximadamente, lo que el observador te cuesta en el camino 1. No es una medida exacta, porque dos sesiones nunca son iguales, pero vale más que cualquier cifra del README.

Si ya te has quedado sin margen esta semana, cambiar de proveedor no te devuelve lo gastado. Para ese caso, mira qué hacer cuando llegas al límite de Claude.

Lo que esta guía no puede saber

• Cuántos mensajes ganas o pierdes con claude-mem. No encontré ninguna medición en el README, en las notas de v13.34.2 y v13.35.0 ni en la documentación que revisé. No busqué en los demás issues, en las discusiones del repositorio ni en pruebas de terceros.
• El umbral exacto en el que se detiene el observador con autenticación por suscripción.
• Si el respaldo de cuota va por defecto a Claude, como dice la documentación, o está desactivado, como dice el código de v13.35.0.
• Si la clave de ~/.claude-mem/.env cuenta para los créditos mensuales de API de Max.
• En qué moneda cobra CMEM Pro y cómo trata el IVA y los reembolsos.
• Qué cambiará en la próxima versión. La documentación sigue la rama principal, no la v13.35.0, y el proyecto publica casi a diario.

FAQ

¿claude-mem gasta mi límite de Claude Pro o Max?

Con la configuración por defecto, sí. El observador que comprime tus observaciones funciona como un subproceso del Claude Agent SDK con tu sesión de Claude Code. A 13 de octubre de 2026, el centro de ayuda de Anthropic dice que el uso del Agent SDK y de aplicaciones de terceros sale de los límites de tu suscripción. Si pasas el observador a Gemini, a OpenRouter, a CMEM Pro o a una clave de API en ~/.claude-mem/.env, deja de gastar de tu plan mientras ese proveedor responda.

¿Por qué npm install -g claude-mem no guarda ninguna memoria?

Porque ese comando instala solo el SDK y la librería. No registra los hooks de Claude Code ni configura el worker, así que nada captura tus sesiones. Instala con npx claude-mem install. También puedes instalarlo desde Claude Code con /plugin marketplace add thedotmack/claude-mem y después /plugin install claude-mem.

¿Qué pasa cuando termina la prueba gratis de CMEM Pro?

Si no te suscribes, el gateway de cmem.ai rechaza tu cuenta y la memoria pasa a tu plan de Anthropic sin que hagas nada. La prueba dura 30 días o hasta que gastas el uso incluido, lo que ocurra antes. Si no quieres que el observador vuelva a tu plan, cambia CLAUDE_MEM_PROVIDER a otro proveedor antes de que acabe la prueba.

¿Puedo pagar el observador con los créditos de API de mi plan Max?

Quizá, pero no he podido confirmarlo. Anthropic incluye créditos mensuales de API en Max y Team, no en Pro. Solo cubren el Agent SDK y claude -p cuando usan una clave de la organización de la Console vinculada a tu plan. claude-mem lee su clave de ~/.claude-mem/.env. Haz una sesión corta con la clave puesta y mira en la facturación de tu cuenta si el consumo se descuenta de los créditos o se cobra aparte.