marm-memory

¡Las contribuciones son bienvenidas! Explora issues abiertos para contribuir, o únete al MARM Discord para compartir flujos de trabajo, obtener ayuda de configuración y conectar con otros desarrolladores.

Tabla de Contenidos

• Inicio Rápido

• Por qué MARM Memory

• Rendimiento y Benchmarks de Escalado

• Configuración del Cliente MCP

• Comandos CLI en Tiempo de Ejecución

• Suite Completa de Herramientas MCP

• Usando MARM: Habla, No Llames Herramientas

• Entendiendo MARM Memory

• Grafos de Conocimiento: Código y Conceptos

• Arquitectura e Internos

• Solución de Problemas

• Contribuir

• Documentación del Proyecto

Related MCP server: Memory Crystal MCP Server

Inicio Rápido

1. Instala e inicializa con tus perfiles de agente preferidos:

pip install marm-mcp-server
marm-memory init --g-claude --g-codex --g-gemini

También disponibles: --g-qwen y --g-kiro. Ejecuta sin banderas para instalar en tu carpeta de proyecto actual en lugar de home

1. Pásalo a tu compañero de IA. Dile a tu agente:

"Usa la habilidad marm-init para configurar MARM."

1. Interactúa: Tu agente manejará toda la configuración (Python/Docker, HTTP/STDIO, claves y configuraciones del cliente) de forma interactiva directamente dentro de tu chat.

Configuración manual

¿Prefieres hacerlo tú mismo?:

Reemplaza "agent" con el comando CLI de tu cliente (por ejemplo, claude, gemini o qwen). Para Codex, usa codex mcp add marm-memory --url http://localhost:8001/mcp en su lugar.

• ⚡ Inicio HTTP más rápido: Ejecuta marm-memory fast-start-http para iniciar el runtime local, lanzar la consola y abrirla en tu navegador inmediatamente.

• 🖥️ Consola Web: Ejecuta marm-memory console para ver la aplicación de UI local al instante (no requiere Node.js).

• ⚙️ Gestión del Ciclo de Vida: Gestiona el demonio en segundo plano usando status, logs --follow, restart y stop.

• 💡 Banderas Rápidas: Usa --no-console o --no-browser para restringir los inicios. Ejecuta marm-memory --help para listas completas de comandos.

Por qué MARM Memory

Tu IA lo olvida todo. MARM Memory no.

marm-memory les da a tus agentes una memoria privada y compartida para el contexto que normalmente se pierde entre chats: decisiones, investigación, correcciones, notas e historial del proyecto. Cambia de Claude Code a Codex o Gemini sin perder el contexto ya recopilado.

Reúne tres cosas:

• 🧠 Memoria Central (7 herramientas) almacena conversaciones, notas, entradas de cuaderno y resúmenes para que se mantengan buscables.

• 💻 Grafo de Código (5 herramientas) mapea tu repositorio para que los agentes puedan encontrar símbolos, seguir rutas de código y entender el proyecto sin tener que releerlo todo. Apúntalo a un repositorio una vez y se mantiene actualizado mientras trabajas.

• 🧩 Grafo de Conceptos (2 herramientas) conecta personas, decisiones, errores e ideas de tus memorias almacenadas, con enlaces de vuelta al código relevante cuando esté disponible. Se construye solo a medida que almacenas memorias.

Las 14 herramientas funcionan sobre HTTP y STDIO. Tus agentes comparten la misma memoria local entre sesiones en lugar de empezar desde cero cada vez. La Consola integrada te permite ver y gestionar lo que se guarda.

Cómo Funciona

Consulta Rendimiento y Benchmarks de Escalado para latencia de recuperación, concurrencia y números de costo de escritura, y Arquitectura e Internos para los mecanismos detrás de cada capa.

Comandos CLI en Tiempo de Ejecución

marm-memory es el gestor de runtime local instalado con el paquete Python. Estos son los comandos operativos normales; usa marm-memory <command> --help para banderas y ejemplos específicos de comandos.

Trabajo diario de runtime

marm-memory fast-start-http                # start HTTP, Console, and open the browser
marm-memory start                          # start or reuse the managed HTTP runtime
marm-memory start --profile swarm          # shared multi-agent preset
marm-memory stop                           # stop the managed runtime safely
marm-memory restart                        # restart the managed runtime
marm-memory status                         # inspect runtime, database, queue, and graph status
marm-memory logs --follow                  # follow bounded runtime logs
marm-memory console                        # start or reuse the bundled local Console

Transportes y configuración

marm-memory http                           # run HTTP in the foreground
marm-memory stdio                          # run the strict local MCP STDIO transport
marm-memory init                           # install the MARM skill into detected agents (project scan)
marm-memory init --g-claude                # install the skill into the home-folder claude directory
marm-memory doctor                         # diagnose the local install
marm-memory key init                       # create or reuse ~/.marm/.env without displaying the key
marm-memory key path                       # print the managed key-file path
marm-memory key reveal                     # explicitly display the managed key
marm-memory console --import-key           # open an authenticated local Console session
marm-memory upgrade --check                # compare the installed package with PyPI
marm-memory uninstall                      # preview package removal; always preserves ~/.marm

Conocimiento, proyectos y mantenimiento

marm-memory knowledge status               # Indexers, models, and how far behind automatic indexing is
marm-memory knowledge build --all          # Rebuild the whole concept graph (new memories index themselves)
marm-memory knowledge auto off             # Stop indexing memories automatically (on, off, status)
marm-memory projects list                  # List all tracked workspaces
marm-memory projects index <path>          # Add a repo to the code graph (kept current after that)
marm-memory projects status                # Inspect target repo graph readiness
marm-memory projects auto off              # Stop re-indexing repos automatically (on, off, status)
marm-memory maintenance status             # Check internal database optimization state
marm-memory maintenance embeddings migrate # Upgrade old 384-dim vectors to 512-dim
marm-memory maintenance chunks rechunk     # Recalibrate long memory text splits

Los comandos de Docker están documentados por separado más abajo porque requieren montajes de datos explícitos, exposición de red y elecciones de manejo de claves.

Rendimiento y Benchmarks de Escalado

MARM está ajustado para una recuperación rápida primero, incluso a medida que la memoria crece y las memorias largas se dividen en fragmentos detrás de escena.

Estas mediciones utilizan el codificador jinaai/jina-embeddings-v2-small-en respaldado por fastembed y una base de datos SQLite local desechable. Cada ruta cronometrada llama al código MARMMemory enviado, no a una reimplementación local del benchmark. Las secciones 1-4 son tiempos de una sola ejecución de scripts/benchmarking/performance/bench_hotpath.py en hardware local; los milisegundos absolutos varían según la máquina, así que trata la forma de escalado como la señal. La sección 5 es un benchmark de precisión separado (run_eval.py) e informa dos ejecuciones, por la razón indicada allí.

1. Escalado de Latencia de Recuperación

Latencia de extremo a extremo de recall_similar (incluye codificación de consulta).

La varianza entre ejecuciones en $N$ pequeño es mayor que la brecha entre tamaños adyacentes, por lo que N = 250 se lee más lento que N = 500 aquí. Trata la tendencia desde N = 1,000 en adelante como la señal real.

2. Codificador + Concurrencia

• Carga de modelo en frío: 893ms

• Codificación en caliente: mediana 3.8ms, p95 4.3ms

• Recuperación concurrente: 10 recuperaciones agrupadas completadas en 151.5ms vs 176.0ms en serie (gather/serial = 0.86). No interpretes eso como paralelismo: ejecuciones repetidas de este mismo benchmark caen en cualquier lugar entre 0.63 y 0.86, por lo que la relación no es lo suficientemente estable como para afirmar una aceleración. La ruta está serializada alrededor del trabajo compartido del codificador y SQLite por diseño, y cualquier ganancia aparente es ruido de medición.

3. Costo de Ingestión en Tiempo de Escritura

• Consolidación desactivada: mediana 6.5ms, p95 7.6ms

• Consolidación activada: mediana 58.1ms, p95 106.5ms

• Compensación: la deduplicación/agrupación en tiempo de escritura añade un costo mediano de 9.0x para que la recuperación se mantenga rápida y el almacén se mantenga más limpio con el tiempo. La consolidación está desactivada por defecto.

4. Escalado de Recuperación: Escaneo Completo vs Híbrido de Producción

Por qué la recuperación se mantiene plana mientras la memoria crece: en lugar de escanear cada vector, la recuperación en producción utiliza un prefiltro FTS de palabras clave para reducir el conjunto de candidatos, luego reordena utilizando una puntuación combinada semántica + BM25 + temporal. Ambas columnas de referencia representan rutas de código asíncrono auténticas, medidas con vectores precalculados para aislar la velocidad de recuperación de la sobrecarga de codificación en bruto. Las pruebas alternan la ejecución para garantizar condiciones de caché completamente imparciales.

El escaneo completo crece aproximadamente de forma lineal con $N$ mientras que la recuperación híbrida crece mucho más lentamente, por lo que la ventaja aún se amplía con el tamaño de la sesión. Con $N$ muy pequeño, el prefiltro no vale su sobrecarga y el híbrido es más lento.

5. Precisión de recuperación de LoCoMo

Las 10 conversaciones de LoCoMo se ingieren a través de marm_log_entry (5,882 recuerdos), luego los resultados del top-5 de marm_smart_recall se puntúan frente a 1,977 preguntas anotadas con evidencia. No se utiliza ningún modelo de generación de respuestas ni juez LLM.

Las ganancias de rendimiento se aíslan en el pipeline de recuperación combinado y el espacio vectorial localizado, lo que garantiza una alta precisión de recuperación de múltiples saltos sin depender de jueces LLM alojados en la nube. Reproduzca el benchmark completo usando scripts/benchmarking/accuracy/locomo/run_eval.py.

6. vs Competidores: Arquitectura

MARM se dirige a un nicho específico: memoria local para agentes de codificación conectados a MCP, no memoria de personalización general ni un runtime de agente completo. Así es como se diferencia arquitectónicamente de nombres establecidos en la memoria de agentes de IA:

Descargos y precisión: Los panoramas de competidores evolucionan rápidamente. La matriz anterior refleja rasgos arquitectónicos centrales a partir del tercer trimestre de 2026, basados en documentación pública y READMEs, no en pruebas internas de cada sistema. Si algún dato sobre un framework alternativo ha cambiado o está mal representado, por favor abra un issue o envíe un Pull Request para actualizar la tabla. Damos la bienvenida activamente a correcciones de mantenedores pares.

Configuración del Cliente MCP para HTTP y STDIO

Instalación manual con pip

pip install marm-mcp-server

Use esta regla rápida para elegir su configuración

• HTTP/STDIO local = configuración más rápida en una sola máquina.

• Docker HTTP = servidor compartido/siempre activo (se requiere clave).

• Docker STDIO = uso local privado en contenedor (sin clave HTTP).

Nota para enjambre/multiagente: La cola de escritura está habilitada por defecto para serializar las escrituras de memoria a través de un trabajador. Para despliegues HTTP compartidos, use marm-memory start --profile swarm (200 RPM) o --profile swarm-max (600 RPM). --profile trusted deshabilita la limitación de velocidad por completo para despliegues privados. STDIO sigue siendo lo mejor para uso privado de un solo agente/local. Consulte Ajustes preestablecidos para enjambre y multiagente para la tabla completa.

"agente" se refiere a claude, gemini, grok, qwen, o cualquier cliente MCP. Codex usa --url en lugar de --transport para agregar herramientas MCP.

pip install marm-mcp-server
marm-memory start
# Stuck on client setup? Open a Q&A thread: https://github.com/Lyellr88/marm-memory/discussions
# most agents use this --transport command
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp
codex mcp add marm-memory --url http://localhost:8001/mcp

El inicio predeterminado de pip/local es de configuración cero: MARM se vincula a localhost y no requiere una clave a menos que lo exponga con SERVER_HOST=0.0.0.0.

pip install marm-mcp-server
python -m marm_mcp_server.server_stdio
# most agents use this --transport command
"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio
codex mcp add marm-memory-stdio -- marm-mcp-stdio

Reemplace marm-mcp-stdio con python -m marm_mcp_server.server_stdio si usa un virtualenv o una configuración basada en rutas. Funciona con Claude Code, Cursor, VS Code, Qwen y Gemini CLI. STDIO sigue siendo un solo proceso local sin puerto ni clave API, y expone las mismas 14 herramientas que HTTP.

Use HTTP cuando varios agentes necesiten compartir un servidor MARM activo. STDIO sigue siendo lo mejor para uso privado de un solo agente porque cada cliente posee su propio proceso local.

# HTTP shared server, normal multi-agent use
marm-memory start --profile swarm

# HTTP shared server, heavier private swarm
marm-memory start --profile swarm-max

# HTTP trusted private lab/server, rate limiting disabled
marm-memory start --profile trusted

# STDIO remains keyless/private and does not use swarm flags
marm-mcp-stdio

Docker HTTP requiere una clave API porque expone MARM como un servidor de red; STDIO permanece local al proceso del cliente y no necesita una.

Si instaló MARM a través de pip, la CLI del producto puede previsualizar o ejecutar la misma configuración de forma segura. Usa un puerto de bucle invertido por defecto, conserva ~/.marm, almacena la clave generada en ~/.marm/.env en lugar del historial del shell, y se niega a reemplazar un contenedor existente.

marm-memory docker command                 # preview the exact HTTP command
marm-memory docker run                     # create the managed HTTP container
marm-memory docker stdio-command           # print a Docker STDIO client command
marm-memory docker status
marm-memory docker logs --follow
marm-memory docker stop

# Optional: mount repositories read-only for code indexing.
marm-memory docker run --repo /absolute/path/to/repository

# Optional: preview or explicitly write a Compose configuration.
marm-memory docker compose
marm-memory docker compose --yes

Los comandos HTTP run, command y compose aceptan las mismas banderas operativas:

Por ejemplo:

# Shared local server with a custom data path and two repositories for indexing.
marm-memory docker command \
  --profile swarm \
  --data-dir /srv/marm-data \
  --repo /srv/projects/api \
  --repo /srv/projects/web

# Execute the reviewed command, pulling the image first.
marm-memory docker run --profile swarm --data-dir /srv/marm-data --pull

Docker STDIO es independiente de Docker HTTP: marm-memory docker stdio-command usa docker run -i --rm, no tiene puerto ni clave bearer, pero sigue montando el directorio de datos para que la memoria SQLite persista después de que el contenedor de corta duración termine. Use --data-dir y --tag con ese comando cuando sea necesario. No hay comandos separados docker key o docker mount; --env-file y --data-dir hacen explícitas esas opciones en el comando HTTP generado.

marm-memory docker pull solo descarga una imagen. marm-memory docker maintenance embeddings migrate se ejecuta contra el mismo montaje de datos y se niega mientras el contenedor HTTP gestionado esté en ejecución. El asistente solo está disponible con el comando marm-memory instalado mediante pip; los usuarios que solo usan Docker pueden usar los comandos sin procesar a continuación.

# Step 1: generate key (do not add < > around the key)
docker run --rm lyellr88/marm-mcp-server:latest --generate-key

# Step 2: run server
docker pull lyellr88/marm-mcp-server:latest
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest

# Step 3: connect client
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

# PowerShell: set this before starting/restarting Codex
$env:MARM_API_KEY="your-generated-key"
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

# Quick auth smoke test
curl -i -H "Authorization: Bearer $env:MARM_API_KEY" http://127.0.0.1:8001/mcp

--bearer-token-env-var toma el nombre de la variable de entorno, no la clave sin procesar. Inicie o reinicie Codex desde el mismo shell después de establecer $env:MARM_API_KEY. Para pruebas de humo locales con Docker, MARM_API_KEY=test está bien y evita problemas de escape del shell; use una clave generada para implementaciones reales. Un 406 Not Acceptable de la prueba de humo GET /mcp significa que la autenticación llegó al endpoint MCP; 401 Unauthorized significa que la clave falta o no coincide.

# --swarm: write queue on, 200 RPM - recommended for multi-agent shared servers
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest --swarm

Las herramientas de gráficos Docker se ejecutan dentro del contenedor, por lo que no pueden ver las rutas del host a menos que las monte en docker run.

$env:MARM_API_KEY="test"

# The second -v line mounts your repo; adjust the host path to your project
docker run -d --name marm-mcp-server `
  -p 127.0.0.1:8001:8001 `
  -e SERVER_HOST=0.0.0.0 `
  -e MARM_API_KEY=$env:MARM_API_KEY `
  -v ~/.marm:/home/marm/.marm `
  -v C:\Users\lyell\Desktop\marm-memory:/workspace/marm-memory `
  lyellr88/marm-mcp-server:latest

Luego indexe la ruta del contenedor, no la ruta del host de Windows:

marm_graph_index(repo_path="/workspace/marm-memory")

Las herramientas de gráficos deben usar la ruta del contenedor. No se pueden agregar montajes a un contenedor ya en ejecución; detenga y reinicie el contenedor con el montaje del repositorio cuando desee la indexación de gráficos Docker.

Docker STDIO incluye las mismas herramientas marm-graph integradas; no se requiere ninguna imagen o paso de instalación adicional.

docker run --rm -i \
  -v ~/.marm:/home/marm/.marm \
  --entrypoint python \
  lyellr88/marm-mcp-server:latest \
  -m marm_mcp_server.server_stdio

• Docker HTTP requiere una clave; Docker STDIO no.

• Si obtiene 401, verifique la coincidencia de la clave y reinicie el cliente después de los cambios en las variables de entorno.

• Para la configuración completa de la clave, rotación y solución de problemas: INSTALL-DOCKER.md

Conecte su cliente

Inicie el servidor (python -m marm_mcp_server), luego conecte su cliente a continuación. Cada bloque asume la instalación local predeterminada (sin clave). Para servidores Docker o expuestos, agregue el encabezado Authorization: Bearer que se muestra en el bloque plegable de cada cliente.

claude mcp add --transport http marm-memory http://localhost:8001/mcp

Claude Code admite HTTP, SSE y STDIO a través de claude mcp add; use HTTP para MARM. Para STDIO: claude mcp add --transport stdio marm-memory-stdio marm-mcp-stdio.

Agregue a .vscode/mcp.json en su espacio de trabajo. Use marm-memory-local para instalaciones directas de Python; marm-memory-docker para modo Docker o expuesto/con clave.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "marm-api-key",
      "description": "MARM API Key for Docker or exposed server mode",
      "password": true
    }
  ],
  "servers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${input:marm-api-key}"
      }
    }
  }
}

Abra .vscode/mcp.json, haga clic en Iniciar sobre el servidor que desee, luego use el Agente de Copilot o cualquier extensión que consuma el registro MCP nativo de VS Code.

Agregue a .cursor/mcp.json en su espacio de trabajo. Cursor usa mcpServers, no la raíz servers de VS Code.

{
  "mcpServers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MARM_API_KEY}"
      }
    }
  }
}

Para el modo Docker/clave, inicie Cursor con MARM_API_KEY establecida en el entorno.

Codex usa codex mcp add o configuración TOML en ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml en Windows).

# Direct Python install - no key needed
codex mcp add marm-memory --url http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required (set MARM_API_KEY in your shell first)
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

[mcp_servers."marm-memory"]
url = "http://localhost:8001/mcp"
enabled = true
bearer_token_env_var = "MARM_API_KEY"

# Direct Python install - no key needed
gemini mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
gemini mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalente ~/.gemini/settings.json (ámbito de usuario) o proyecto .gemini/settings.json:

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

# Direct Python install - no key needed
qwen mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
qwen mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Equivalente .qwen/settings.json (proyecto) o ~/.qwen/settings.json (usuario):

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

xAI se conecta desde su propia infraestructura, por lo que localhost no funcionará. Exponga MARM detrás de HTTPS y establezca MARM_API_KEY.

{
  "type": "mcp",
  "server_url": "https://your-marm-domain.example.com/mcp",
  "server_label": "marm-memory",
  "authorization": "Bearer your-generated-key"
}

Guías completas de plataforma, configuración de clave y notas específicas del SO: Windows · macOS · Linux · Modo Docker/clave · Otras plataformas

¿Usando un cliente que no está listado? Abra un issue y háganoslo saber; los adaptadores de cliente son una solicitud de característica de primera clase.

Requisitos

• Python: 3.10 o superior

• SQLite3: Incluido con Python (no se necesita instalación por separado)

• Almacenamiento: ~100MB mínimo para la configuración inicial, escala con el tamaño de la base de datos de memoria

• RAM: 512MB mínimo (varía según clientes concurrentes y tamaño de la base de datos)

• SO: Windows, macOS, Linux

Ubicación de datos

• Ubicación: ~/.marm/ (Linux/macOS) o %USERPROFILE%\.marm\ (Windows)

• Contenido: Base de datos SQLite con todos los recuerdos, sesiones y cuadernos; el grafo de conceptos reside en su propia base de datos ~/.marm/index/

• Copia de seguridad: Copie todo el directorio ~/.marm/ para preservar todos los datos

• Privacidad: Todo permanece en su máquina, sin sincronización en la nube ni almacenamiento externo

Verificar instalación

Use el endpoint de salud del servidor MCP para la verificación en vivo más rápida:

curl http://localhost:8001/health

La salida esperada incluye la versión del servidor, disponibilidad de características (estado de búsqueda semántica), estado de conexión a la base de datos y estado de salud del servicio.

Suite completa de herramientas MCP (14 herramientas)

💡 Consejo profesional: ¡No necesita llamar manualmente a estas herramientas! Simplemente dígale a su agente de IA lo que quiere en lenguaje natural:

• "Claude, registra esta sesión como 'Project Alpha' y añade esta conversación como 'discusión de diseño de base de datos'"

• "Recuerda este fragmento de código en tu cuaderno para más tarde"

• "Busca lo que discutimos sobre autenticación ayer"

El agente de IA usará automáticamente las herramientas adecuadas. El acceso manual a las herramientas está disponible para usuarios avanzados que deseen control directo.

🧠 Memoria Central (7 herramientas)

🕸️ Grafo de Código (5 herramientas)

🧩 Grafo de Conceptos (2 herramientas)

Las 14 herramientas están disponibles tanto en HTTP como en STDIO. Detrás de la superficie de las herramientas, el servidor maneja automáticamente la configuración del ciclo de vida, la actualización del protocolo, la indexación de documentos, el contexto de fecha, el mantenimiento de la caché de resúmenes, el manejo de la cola de escritura, la indexación de conceptos, la reindexación de código a medida que los repositorios cambian, la atribución de proyecto/plataforma y las comprobaciones de salud; nada de eso consume la atención o los tokens del agente. Los dos motores de grafo se inician de forma diferida en el primer uso y nunca bloquean las 7 herramientas de memoria central si fallan al iniciarse. Consulte Arquitectura e Internos para conocer los mecanismos.

Usando MARM: Hable, No Llame a las Herramientas

MARM maneja el trabajo del ciclo de vida internamente. Los documentos y el estado de la sesión se inicializan en la primera llamada real a una herramienta, y los documentos empaquetados se indexan en el espacio de nombres de memoria marm_system con seguimiento de hash de archivo fuente, para que su agente pueda responder preguntas sobre el uso de MARM desde la propia memoria.

Flujo de trabajo de ejemplo: Proyecto de investigación entre AIs

Un flujo de trabajo realista que muestra MARM en acción. Escenario: está investigando patrones de autenticación para un nuevo proyecto utilizando múltiples clientes de IA.

Fase 1: Enrutar sesión (Claude)

You: "Claude, create a MARM session called 'auth-research-2025-01'"
Claude calls: marm_log_entry(entry="Session: auth-research")
Result: Session routed to auth-research-[today]. MARM lifecycle/docs initialize automatically.

Fase 2: Capturar investigación (Claude)

You: "Summarize OAuth2 vs JWT for API authentication and save it"
Claude calls: marm_log_entry(entry="Research: OAuth2 is token-based with refresh cycles, better for delegated access. JWT is stateless, good for microservices...", session_name="auth-research-2025-01")
Result: Research captured in the active session log and marked for summary-cache refresh

Fase 3: Añadir referencia reutilizable (Claude)

You: "Save a JWT validation code snippet to my notebooks as 'jwt-validation-pattern'"
Claude calls: marm_notebook(action="add", name="jwt-validation-pattern", data="def verify_jwt(token):\n  # validation logic...")
Result: Reusable snippet stored for future projects

Fase 4: Recordar contexto (Gemini)

You: "Gemini, what authentication approaches did we research? Activate the JWT pattern."
Gemini calls: marm_smart_recall("authentication patterns", search_all=True)
Gemini calls: marm_notebook(action="use", names="jwt-validation-pattern")
Result: Gemini sees previous research + has JWT code available as context

Fase 5: Síntesis y resumen (Qwen)

You: "Qwen, pull everything from the auth research and create a summary"
Qwen calls: marm_smart_recall("authentication", session_name="auth-research-2025-01", limit=20)
Qwen calls: marm_summary(session_name="auth-research-2025-01")
Result: Qwen generates an implementation guide from all captured research

Fase 6: Finalizar sesión (Claude)

You: "Log final decision - we're using JWT for APIs, and OAuth2 for user auth"
Claude calls: marm_log_entry(entry="DECISION: JWT for API auth, OAuth2 for user flows. Rationale: stateless APIs + delegated user access", session_name="auth-research-2025-01")
Result: Decision logged and searchable by all future AI clients

Resultado: Tres clientes de IA diferentes investigaron colaborativamente un tema, compartieron ideas y documentaron decisiones. Todo sin tener que reexplicar el proyecto a cada nueva IA.

Patrones avanzados

Project Structure:
├── project-name-planning/          # Initial design and requirements
├── project-name-development/       # Implementation details
├── project-name-testing/           # QA and debugging notes
├── project-name-deployment/        # Production deployment
└── project-name-retrospective/     # Lessons learned

Bucle de base de conocimiento:

1. Capturar: Usa marm_log_entry para aprendizajes estructurados de sesión

2. Organizar: Crea sesiones temáticas para áreas de conocimiento

3. Sintetizar: marm_summary regular para consolidación de conocimiento

4. Aplicar: Convierte resúmenes en entradas marm_notebook(action="add", ...)

Colaboración multi-IA: cada IA trabaja en sesiones dedicadas en sus fortalezas, usa marm_smart_recall para basarse en el trabajo de las demás, luego una sesión colaborativa combina las ideas.

• Nombrado de sesiones: Incluye el nombre del LLM para referencias cruzadas

• Registro estratégico: Enfócate en decisiones clave, soluciones, descubrimientos, configuraciones

• Búsqueda global: Usa search_all=True para buscar en todas las sesiones

• Búsqueda en lenguaje natural: "problemas de autenticación con tokens JWT" supera a "error de auth"

• Profundidad de recuerdo en capas: detail=1 devuelve una vista de resumen corta (~200 caracteres), detail=2 una vista de contexto más amplia (~500 caracteres), detail=3 contenido completo de la memoria

• Apilamiento de cuaderno: Combina múltiples entradas para flujos de trabajo complejos

• Compactación: Deja que MARM muestre candidatos de compactación, luego usa marm_compaction para preparar, revisar, aplicar o descartar resúmenes

• Ciclo de vida de sesión: Iniciar → Trabajar → Referencia → Revisar compactación preparada cuando MARM lo solicite

Entendiendo la Memoria de MARM

Dos búsquedas, dos problemas muy diferentes, una herramienta:

User: "I discussed machine learning algorithms yesterday"
MARM Search: Finds related memories about "ML models", "neural networks", "AI training"

User: "What was the COMPACTION_TRIGGER_COUNT setting?"
MARM Search: Finds the exact config memory even if the rest of the text differs

La primera consulta trata sobre significado, por lo que MARM reordena candidatos con incrustaciones vectoriales locales — búsqueda semántica estilo RAG sin una base de datos vectorial alojada. La segunda tiene forma de sintaxis (una clave de configuración), por lo que MARM lo detecta automáticamente y lo enruta a través de coincidencia exacta determinista. Este carril de recuperación exacta es la diferencia entre un sistema de memoria que funciona en demostraciones y uno que responde las preguntas que los desarrolladores realmente hacen: claves de configuración, banderas de CLI, rutas de archivos, nombres de API, cadenas de error. Los sistemas de memoria puramente semánticos fallan exactamente en esas consultas.

MARM usa recuerdo híbrido de filtro→reordenación más un carril de recuperación exacta:

1. Carril exacto (exact_mode="auto", el predeterminado): claves de configuración, banderas de CLI, rutas de archivos, nombres de API/herramientas, espacios de nombres con puntos, rutas HTTP, URLs y cadenas de comandos entrecomilladas se detectan y enrutan a través de FTS5 BM25 determinista con un respaldo LIKE. No hay incrustaciones involucradas, por lo que los resultados son estables y literales.

2. Carril de filtro→reordenación: las consultas en lenguaje natural primero extraen un conjunto candidato acotado del índice FTS (FTS_CANDIDATE_LIMIT, predeterminado 200), luego las incrustaciones semánticas reordenan esos candidatos por significado. La ponderación temporal conservadora da a las memorias más recientes un modesto impulso cuando las coincidencias son cercanas.

3. Respaldo semántico acotado: cuando la cobertura de FTS es débil o inutilizable, MARM recurre a un escaneo semántico acotado (RECALL_SCAN_LIMIT). Si la respuesta incluye recall_scan_truncated=true, el respaldo alcanzó su límite; reduce la sesión/consulta o aumenta la variable de entorno para almacenes más grandes.

4. Puntuación consciente de fragmentos: las memorias largas (aproximadamente 180+ palabras) se incrustan internamente como filas de fragmentos superpuestos, y el recuerdo colapsa las puntuaciones de los fragmentos de vuelta a una memoria padre usando el fragmento que mejor coincide. Tanto el carril de reordenación como el carril de respaldo son conscientes de fragmentos.

Por eso la latencia de recuerdo se mantiene casi plana a medida que el almacén crece (ver benchmarks): la reordenación semántica siempre puntúa un conjunto acotado en lugar de escanear cada incrustación.

Control de recuerdo exacto: exact_mode="auto" suele ser correcto. Usa exact_mode="exact" cuando una consulta debe coincidir con texto literal como RECALL_SCAN_LIMIT, --generate-key o settings.py. Usa exact_mode="semantic" cuando una consulta con apariencia de sintaxis aún debe tratarse como recuerdo basado en significado.

Tipos de memoria y clasificación

1. Registros de contexto - Memorias de conversación clasificadas automáticamente

2. Entradas manuales - Información importante guardada explícitamente

3. Entradas de cuaderno - Instrucciones y conocimiento reutilizables

4. Resúmenes de sesión - Historial de conversación comprimido

MARM categoriza automáticamente el contenido al escribir: Código (fragmentos de programación y discusiones técnicas), Proyecto (conversaciones de trabajo y planificación), Libro (literatura, materiales de aprendizaje, investigación) y General (todo lo demás).

Atribución de proyecto y plataforma

MARM almacena columnas project y platform anulables en memorias, entradas de registro y entradas de cuaderno. El proyecto se detecta desde el directorio de trabajo y la plataforma desde el cliente conectado (Claude Code, VS Code, Cursor, ...); MARM_PROJECT y MARM_PLATFORM anulan la detección. marm_smart_recall(project=..., platform=...) limita el recuerdo sin cambiar el comportamiento predeterminado sin filtrar, por lo que un servidor compartido puede contener varios proyectos sin contaminación cruzada.

Grafos de Conocimiento: Código y Conceptos

MARM incluye dos sistemas de grafo que complementan el almacén de memoria: un grafo de código que entiende la estructura de tu repositorio, y un grafo de conceptos que entiende de qué tratan tus memorias almacenadas. Cuando ambos están indexados para el mismo proyecto, las entidades de concepto se enlazan de forma cruzada a símbolos de código.

Grafo de Código: indexación de repositorio y búsqueda de código

marm-graph está integrado en ambos transportes. Indexa un repositorio una vez, luego permite a los agentes hacer preguntas sobre la estructura del código sin escanear archivos repetidamente:

Use marm_graph_index to index this repository.
Then use marm_code_lookup when you need symbols, files, or source snippets.
Use marm_graph_trace for call paths, marm_graph_architecture for an overview, and marm_graph_impact for change-risk checks.

El flujo de trabajo de agente recomendado: indexa una vez, luego marm_code_lookup antes de lecturas amplias de archivos, marm_graph_trace cuando importa el contexto de llamantes/llamados o flujo de datos, marm_graph_architecture para orientación, y marm_graph_impact antes de refactorizaciones arriesgadas. Una consulta de grafo reemplaza docenas de ciclos de grep/lectura, de ahí proviene el ahorro de tokens.

Una vez que un repositorio está indexado, MARM lo mantiene actualizado por sí mismo. Un sondeo en segundo plano nota cuando el repositorio ha cambiado y lo reindexa, por lo que no es necesario reindexar manualmente después de un commit. Mientras tienes trabajo sin confirmar, se actualiza en cada ciclo, ya que ninguna verificación barata puede ver ediciones repetidas en un archivo que ya está modificado. Para indexar solo a petición:

marm-mcp-server projects auto off

Un agente puede hacer lo mismo con marm_graph_index(action="auto_off"), y action="auto_status" informa qué se está vigilando y cuándo se indexó cada proyecto por última vez. El cambio persiste entre reinicios y anula la variable de entorno GRAPH_AUTO_INDEX.

Internamente, el motor es codebase-memory-mcp (MIT), un binario estático sin dependencias que analiza 158 lenguajes a través de tree-sitter con resolución de tipos LSP híbrida para los principales, indexa un repositorio promedio en segundos y responde búsquedas de símbolos y trazado de llamadas en menos de un segundo. Medido en un grafo de 149,107 nodos sobre la conexión persistente que MARM mantiene: búsqueda de símbolos 146ms, trazado de llamadas 67ms, y la visión general completa de arquitectura 1.23s, que es la única consulta que no es de menos de un segundo. MARM fija una versión específica, verifica su esquema de herramientas al inicio y enruta el conjunto de herramientas ascendente a través de 5 herramientas MCP enfocadas para que la superficie del modelo se mantenga pequeña. El backend del grafo se inicia de forma perezosa en el primer uso de la herramienta de grafo, por lo que las herramientas de memoria, registro, cuaderno y resumen aún se inician rápido. En Docker, el binario del motor está incluido en la imagen; las instalaciones locales con pip lo descargan en el primer uso del grafo (~269MB, una sola vez).

Modo degradado: si el motor de grafo falla al iniciar (sin red para la descarga inicial, disco lleno, desviación de esquema) o se establece GRAPH_ENABLED=false, las herramientas de grafo devuelven {"status": "error", "message": "graph backend unavailable"} mientras las otras 9 herramientas siguen funcionando normalmente. Los fallos de grafo nunca pueden derribar la memoria.

Grafo de Conceptos: de qué tratan tus memorias

MARM extrae un grafo de conocimiento de las memorias que almacenas, produciendo entidades tipadas (conceptos, decisiones, patrones, errores, herramientas, personas, organizaciones) conectadas por relaciones tipadas (corrige, implementa, depende_de, usa, causa, reemplaza, extiende). Esto ocurre automáticamente: almacenar una memoria la pone en cola, y un trabajador en segundo plano la añade al grafo aproximadamente 30 segundos después. marm_concept_build sigue estando disponible para una reconstrucción completa o limitada. Una vez que hay un grafo, marm_smart_recall añade entidades relacionadas acotadas, relaciones y código enlazado como un acompañante graph_context sin cambiar la clasificación de memoria primaria. marm_concept_recall sigue disponible para exploración explícita del grafo:

marm_concept_recall(query="write queue")            → the entity, its relationships, linked code symbols
marm_concept_recall(query="related to SQLite", depth=3) → multi-hop traversal of everything connected

Cómo usarlo:

• Automático por defecto: los nuevos recuerdos llegan al grafo sin una llamada de herramienta. Establece CONCEPT_AUTO_INDEX=false para volver solo a las compilaciones manuales, lo que detiene el trabajador pero mantiene las filas de la cola de registro, de modo que volver a activarlo retoma todo lo escrito mientras estaba desactivado; CONCEPT_INDEX_DEBOUNCE_SECONDS (30) y CONCEPT_INDEX_BATCH_SIZE (20) controlan el ritmo.

• Seguro en ambos transportes a la vez: un bloqueo con concesión en la base de datos de memoria evita que una recompilación en un proceso elimine tablas del grafo mientras otro proceso escribe en ellas. Una compilación que encuentra el grafo ocupado lo indica en lugar de colisionar.

• El fallo nunca llega a tus recuerdos: la indexación se ejecuta en una cola duradera fuera de la ruta de escritura. Los problemas de extracción se reintentan, un recuerdo que falla repetidamente se aparca con su error, y el recuerdo en sí mismo se almacena y recupera con normalidad durante todo el proceso.

• Limpiar un retraso cuesta algo de velocidad de recuperación: la extracción de entidades consume mucha CPU, por lo que mientras el trabajador procesa una cola, la recuperación medida pasa de ~8 ms a ~16 ms mediana en un corpus real de 768 recuerdos. Las escrituras no se ven afectadas. Solo se aplica mientras se drena un retraso, que para la mayoría de las personas ocurre una vez, después de la recompilación de la actualización. Reproducelo con scripts/benchmarking/performance/bench_concept_worker.py --from-live.

• Compila para el retraso: marm_concept_build limitado a un session_name, project o search_all=True indexa recuerdos almacenados antes de que existiera la indexación automática, y reconstruye después de una actualización que lo requiere.

• Dos actualizaciones hasta ahora: los grafos construidos antes de la atribución de plataforma, o antes de que las fuentes de compactación reemplazaran los resúmenes como filas indexadas, requieren marm_concept_build(search_all=True). Una compilación completa hace una copia de seguridad y restablece solo la base de datos de conceptos derivados; las compilaciones dirigidas se niegan a adivinar la propiedad de la plataforma.

• Ámbito completo, paginado: las compilaciones leen cada recuerdo dentro del ámbito. CONCEPT_BUILD_ROW_CAP (predeterminado 500) es el tamaño de página, así que reducirlo hace que una compilación lea más páginas más pequeñas en lugar de saltarse el resto.

• Sesiones compactadas: los recuerdos originales se indexan y el resumen generado no, por lo que los conceptos permanecen atribuidos a donde se declararon realmente.

• La recuperación falla de forma abierta: un grafo de conceptos faltante, vacío, incompatible o no disponible nunca bloquea la recuperación normal de recuerdos. La respuesta informa del estado del grafo por separado.

• Enlace cruzado de código: cuando el grafo de código ha indexado el mismo proyecto, las entidades de concepto que coinciden con símbolos de código se vinculan, conectando "lo que decidimos" con "dónde vive en el código".

• Entorno de ejecución de extracción incluido: el entorno de ejecución de spaCy y el modelo de extracción en inglés se distribuyen con MARM pero se cargan solo en la primera extracción, que ahora ocurre por sí sola poco después de que se almacena el primer recuerdo, en lugar de cuando ejecutas una compilación. Si una instalación dañada o parcial los hace no disponibles, ambas herramientas de concepto se degradan limpiamente mientras la memoria central permanece disponible; ejecuta marm-memory knowledge status, luego reinstala MARM si es necesario.

• Almacenamiento aislado: el grafo de conceptos reside en su propia base de datos SQLite (~/.marm/index/marm_index.db) con su propio grupo de conexiones, por lo que las escrituras del grafo de conceptos nunca pueden bloquear o corromper la base de datos de memoria de producción.

• Atlas de consola: MARM Console renderiza el atlas completo hasta 750 entidades y 6 000 relaciones almacenadas. Los grafos más grandes utilizan una muestra conectada determinista de hasta 600 entidades y 4 000 bordes visuales agregados, claramente etiquetados como muestra.

Esto llena el vacío de estructura entre sesiones que deja la búsqueda plana de memoria: las sesiones organizan los recuerdos, pero el grafo de conceptos los conecta, por lo que "¿qué depende de la cola de escritura?" es respondible incluso cuando la respuesta abarca cinco sesiones de tres agentes diferentes.

Arquitectura y funcionamiento interno

Todo lo anterior se ejecuta sobre un pequeño número de mecanismos deliberados. Esta sección es el mapa completo, para que tú (o tu agente) nunca tengan que adivinar qué está haciendo el servidor.

Motor de almacenamiento

• SQLite en modo WAL en ~/.marm/marm_memory.db con un grupo de conexiones (5 conexiones). WAL mantiene a los lectores desbloqueados durante las escrituras, lo que importa cuando varios agentes recuerdan mientras uno escribe.

• Índice de texto completo FTS5 (memories_fts) se mantiene como una tabla de contenido externo sobre la tabla de recuerdos y potencia tanto el carril exacto (BM25) como la etapa de filtro de la recuperación híbrida.

• Almacenamiento de fragmentos: los recuerdos de más de ~180 palabras se dividen en fragmentos superpuestos de 150 tokens (superposición de 50 tokens) en una tabla memory_chunks, cada uno con su propia incrustación. La recuperación puntúa los fragmentos y colapsa en el recuerdo padre.

• Incrustaciones provienen del codificador jinaai/jina-embeddings-v2-small-en respaldado por fastembed: 33 millones de parámetros, 512 dimensiones, una ventana de contexto de 8 192 tokens y una licencia Apache-2.0. No requiere prefijos de texto de consulta/documento separados. El codificador se carga perezosamente en el primer uso semántico y se serializa detrás de un bloqueo para que las codificaciones concurrentes no puedan corromperse entre sí. Si no está disponible, las escrituras aún tienen éxito; los recuerdos se almacenan sin incrustaciones hasta que se cargue. La puntuación semántica se ejecuta como un único lote de NumPy (coseno matricial) en lugar de un bucle en Python.

• El grafo de conceptos tiene su propia base de datos (~/.marm/index/marm_index.db) y su propio grupo, reutilizando la misma implementación de grupo pero nunca compartiendo conexiones con el almacén de memoria. Aislamiento deliberado: una compilación experimental del grafo no debe poder detener el WAL de producción. La única excepción es la cola de indexación, que reside en la base de datos de memoria a propósito para que una memoria y su tarea de indexación se comprometan juntas; el grafo en sí permanece derivado y desechable.

Ruta de escritura

• Cola de escritura serializada (activada por defecto): todas las escrituras de memoria fluyen a través de un trabajador interno asíncrono, eliminando la contención de escritores de SQLite bajo carga de múltiples agentes. La cola es genérica; las compactaciones pasan por el mismo trabajador, por lo que hay exactamente un escritor sin importar qué subsistema esté escribiendo. MAX_QUEUE_SIZE lo limita.

• Consolidación en tiempo de escritura (opt-in, CONSOLIDATION_ENABLED=1) ejecuta dos capas antes de que aterrice un recuerdo:

  • Capa 1, deduplicación exacta: se comprueba un hash SHA-256 del contenido normalizado dentro de la sesión; los aciertos de hash se verifican contra el contenido real antes de deduplicar, por lo que una colisión de hash almacena una nueva fila en lugar de fusionar silenciosamente contenido diferente.

  • Capa 2, fusión semántica: los casi duplicados por encima de CONSOLIDATION_THRESHOLD de similitud de coseno se fusionan en lugar de acumularse. Esto nunca bloquea una escritura; si el codificador no está disponible, la escritura procede sin consolidar.

  • El equilibrio se mide y publique: aproximadamente 9 veces el costo mediano de escritura (58 ms vs 6.5 ms) a cambio de un almacén que se mantiene limpio, porque las lecturas dominan las cargas de trabajo de memoria. Consulte la sección 3 de los puntos de referencia anteriores.

• La indexación de conceptos es una bandeja de salida duradera: una escritura registra una tarea de indexación en la misma transacción que la memoria, por lo que una memoria no puede existir sin una. Un trabajador de fondo drena esa cola y escribe el grafo de conceptos. Nada en la ruta de escritura espera la extracción, y un proceso eliminado a media extracción no pierde trabajo porque la tarea es una fila en lugar de un trabajo en memoria. Ambos transportes ejecutan un trabajador, por lo que los dos se coordinan a través de un bloqueo con concesión en la base de datos de memoria en lugar de un bloqueo en proceso, que no los abarcaría.

• Compactación (opt-in, COMPACTION_ENABLED=1) es la Capa 3: después de suficientes escrituras en una sesión, un pase de fondo detecta grupos de recuerdos relacionados usando similitud de coseno más componentes conectados de unión-búsqueda, limitados por tamaño mínimo del grupo, edad mínima y un período de gracia de sesión activa para que nunca compacte trabajo en curso. MARM luego inyecta una solicitud limitada pidiéndole al agente conectado que resuma cada grupo: candidatos → etapa → revisión → aplicar o descartar. Los IDs de recuerdo fuente se conservan al aplicar, por lo que los resúmenes compactados permanecen rastreables hasta sus originales. Los resúmenes en etapa expiran (COMPACTION_STAGING_TTL_HOURS), los avisos tienen un límite y un límite de reutilización, y la inyección tiene un presupuesto de bytes. El diseño es honesto sobre para qué sirven los LLM: MARM detecta, el agente resume, y un bucle de etapa/aplicar/descartar revisable por humanos controla el paso destructivo.

Ruta de recuperación

Cubierto en Entendiendo la memoria de MARM: carril exacto (FTS5 BM25 + respaldo LIKE), filtro→reordenar (candidatos FTS limitados → reordenación semántica por lotes → mezcla temporal), respaldo semántico limitado con una bandera de truncamiento explícito, y puntuación de colapso de fragmentos. La profundidad de recuperación (detalle=1/2/3) controla cuánto de cada recuerdo se devuelve, y cada respuesta MCP pasa a través de un limitador de respuesta de 1 MB que trunca el contenido de manera inteligente en lugar de romper el protocolo.

Protocolo de subproceso del grafo de código

El motor de grafo incluido se ejecuta como un proceso hijo supervisado, no como una importación:

• Transporte: JSON-RPC 2.0 delimitado por nueva línea sobre el stdio del hijo, con un apretón de manos verificado (inicializar → capturar versión del servidor → notificación inicializada).

• Cuidado con el sobre: las respuestas se escanean en busca del primer elemento de contenido analizable como JSON en lugar de asumir el índice 0, porque el binario ascendente puede anteponer un aviso de actualización. Los errores de herramienta llegan como result.isError, no como errores JSON-RPC, y se convierten en diccionarios limpios {"status": "error"} con la propia sugerencia de remediación del ascendente adjunta.

• Serialización: un bloqueo protege cada ida y vuelta de escritura+lectura en la única tubería stdin; los llamantes asíncronos pasan por asyncio.to_thread para que el bucle de eventos nunca se bloquee en E/S de subproceso.

• Recuperación tras fallo: stderr se drena en un hilo de fondo, se detecta EOF/fallo del hijo, y el proceso se reanuda transparéntemente en la siguiente llamada. Los tiempos de espera deliberadamente no se tratan como fallos; una ejecución larga de índice puede estar todavía trabajando, y matarla destruiría el trabajo en curso.

• Supervisión: un supervisor perezoso singleton posee el cliente durante la vida del proceso. El inicio se desencadena con la primera llamada de herramienta de grafo o con el sondeo de indexación automática si el binario del motor ya está descargado, nevera se elev al capa MCP, y verifica el equema de herramienta del binario fijado para que la deriva ascendent sea detectada al inicio en lugar de en medio de la llamada.

• La reindexación automática se sondea por firma git, no se vigila por sistema de archivos: una tarea de fondo compara el HEAD de cada repositorio indexado y el estado sucio, calculado ejecutando git fuera del motor para que una comprobación inactiva no cueste bloqueo del motor. Una confirmación desencadena una reindexación. Mientras el árbol está sucio, el repositorio se reindexa cada ciclo, porque git status informa qué archivos cambiaron y no qué contienen, por lo que las ediciones repetidas a un archivo ya modificado producen una salida byte-identica que ninguna huella más barata puede distinguir. Git se ejecuta con core.fsmonitor deshabilitado y un entorno limpio, ya que esa configuración nombra un programa que git de otro modo ejecutaría desde un repositorio vigilado en un temporizador.

• Una puerta para cada mutación del almacén: los índices manuales en las tres superfices, el sondeo y la eliminación de proyecto pasan todos a través de una única fila con concesión en la base de datos de memoria. HTTP y STDIO son procesos separados con hijos de motor separados sobre un almacén de motor compartido, por lo que un bloqueo en proceso no puede abarcarlos. La concesión se libera cuando la llamada al motor realmente regresa, no cuando su llamante deja de esperar: una solicitud cancelada no puede entregar el almacén a otro proceso mientras el motor aún está escribiendo en él.

Seguridad y limitación de velocidad

• Puerta de autenticación de dos modos: sin clave en loopback (127.0.0.1), MARM_API_KEY (Bear) obligatoria en cuanto el servidor está expuesto en red (SERVR_HOST=0.0.0.0, Docker). --generate-key produce una. Seguro por defecto, cero fricción de configuración local.

• Limitación de velocidad basada en IP con ventanas deslizantes y bloques temporales, ajustados a través de preajustes de CLI en lugar de un laberinto de configuración (tabla a continución).

• Local-primero: todo vive bajo ~/.marm/; sin sincronización en la nube, sin telemetría, sin almacenamiento externo.

• Apagado elegante: los manejadores de SIGTERM/SIGINT drenan y cierran limpiamente el grupo de conexiones, y un sistema de eventos internos ejecuta devoluciones de llamada de automatización con aislamiento de errores por devolución de llamada y tiempos de espera para que un gancho defectuoso no pueda atascar el servidor.

Presets de enjambre y multiagente

La cola de escritura serializa las escrituras en memoria independientemente del preset; los indicadores de enjambre ajustan el límite de tasa HTTP además de eso. La cola controla el orden de escritura; la consolidación y la compactación son capas separadas de mantenimiento de memoria. Esta pila (WAL + pooling + un escritor serializado + presets RPM) está intencionalmente limitada a "SQLite, muchos agentes, una máquina"; la memoria distribuida multinodo está fuera del alcance del diseño actual.

Documentación automantenida

Los documentos empaquetados se indexan en el espacio de nombres de memoria marm_system al inicio y se actualizan cada 50 llamadas a herramientas, con seguimiento de hash de archivos fuente para que los documentos sin cambios se omitan y las filas modificadas o eliminadas se vuelvan a indexar. Los agentes conectados pueden responder preguntas sobre el uso de MARM con marm_smart_recall en lugar de que usted les pegue documentos.

Referencia de configuración

Solución de problemas

El valor predeterminado de Jina v2 Small utiliza embeddings de 512 dimensiones; los datos antiguos de all-MiniLM-L6-v2 son de 384 dimensiones y deben ser re-embedidos. Detenga todos los procesos MARM HTTP y STDIO, luego ejecute:

marm-memory maintenance embeddings migrate

Esto re-embedde memoria, fragmento y cualquier vector existente del grafo de conceptos (las entradas del bloc de notas ya no llevan embeddings), informa el progreso, verifica ambas bases de datos y es reanudable después de una interrupción. Se niega a iniciar contra un servidor HTTP activo; los procesos STDIO no se pueden detectar de manera confiable y deben detenerse manualmente.

Reparar memorias fragmentadas

Las memorias de más de 500 palabras también se almacenan como fragmentos más pequeños. El tamaño de los fragmentos cambió entre versiones, y la migración anterior re-embedde los fragmentos sin dividirlos nuevamente, por lo que los fragmentos antiguos mantienen límites obsoletos. Detenga cada proceso MARM, luego ejecute:

marm-memory maintenance chunks rechunk

Esto vuelve a dividir fragmentos obsoletos, completa los que se perdieron por una escritura interrumpida y elimina fragmentos de memorias que ahora están por debajo del umbral. Las memorias ya correctas se omiten sin cargar el codificador, por lo que volver a ejecutar no cuesta nada. La misma protección de servidor activo que arriba, además se niega cuando los vectores almacenados no coinciden con el modelo de embedding configurado: migre primero en ese caso. La recuperación funciona sin esto, solo que con menos precisión en memorias largas.

El servidor no arranca

• Verifique la versión de Python: python --version (debe ser 3.10+)

• Verifique que el puerto 8001 no esté en uso: lsof -i :8001 (macOS/Linux) o netstat -ano | findstr :8001 (Windows)

• Verifique errores de permisos en el directorio home (~/.marm/ debe ser legible y escribible)

• Consulte la solución de problemas específica de la plataforma: INSTALL-DOCKER.md, INSTALL-WINDOWS.md, INSTALL-MACOS.md, INSTALL-LINUX.md

La conexión STDIO falla

• Verifique que marm-mcp-stdio esté en su PATH después de la instalación con pip: marm-mcp-stdio --help

• Alternativamente, use: python -m marm_mcp_server.server_stdio

• Consulte la documentación del cliente de IA para los requisitos de transporte STDIO

• Intente la ejecución directa para ver mensajes de error: python -m marm_mcp_server.server_stdio

El cliente de IA no puede conectarse a MARM

• Verifique que el servidor esté ejecutándose con curl http://localhost:8001/health

• Verifique que el cortafuegos no esté bloqueando el puerto 8001

• Para STDIO: use marm-mcp-stdio (script de consola) o python -m marm_mcp_server.server_stdio

• Reinicie tanto el servidor como el cliente de IA

Las herramientas no aparecen en el cliente de IA

• Verifique el modo HTTP con curl http://localhost:8001/health

• Revise los registros del servidor en busca de errores de inicialización

• Desconecte y vuelva a conectar el cliente de IA para actualizar la lista de herramientas

• Tanto HTTP como STDIO exponen 14 herramientas: 7 herramientas principales de memoria/registro/bloc de notas/compactación, 5 herramientas de grafo de código incluidas y 2 herramientas de grafo de conceptos

Las herramientas de grafo devuelven graph backend unavailable

• Confirme que GRAPH_ENABLED no esté configurado como false (afecta tanto a HTTP como a STDIO; las herramientas de grafo tienen paridad completa en ambos transportes)

• El primer uso del grafo puede tardar más mientras el motor de base de código fijado se inicia o se descarga localmente

• En Docker, el binario del motor de grafo está incluido en la imagen; las instalaciones locales con pip pueden descargarlo en el primer uso del grafo

• Las herramientas de memoria principal continúan funcionando incluso si el inicio del grafo falla

Las herramientas de concepto devuelven entities_extracted: 0

• Primero confirme que una construcción de concepto con ámbito incluya realmente memorias con entidades extraíbles.

• Ejecute marm-memory knowledge status; si informa que falta un tiempo de ejecución o modelo, repare la instalación con python -m pip install -U --force-reinstall marm-mcp-server.

Las nuevas memorias no aparecen en el grafo

• Ejecute marm-memory knowledge status. index_queue.pending es cuántas memorias están esperando; index_queue.parked es cuántas se rindieron. auto_index: false significa que la indexación está desactivada.

• Espere el intervalo de debounce (30 segundos por defecto) más el tiempo de extracción. Una ráfaga de escrituras se indexa como una sola pasada, no una por memoria.

• Verifique que CONCEPT_AUTO_INDEX no esté configurado como false, 0, no o off.

• Un grafo que espera una reconstrucción no se indexa. Si la Consola o marm-memory knowledge status informa rebuild_required, ejecute marm_concept_build(search_all=True) una vez; las memorias en cola se recogen después.

• La indexación automática solo cubre memorias escritas desde la actualización. Ejecute una construcción una vez para incluir todo lo anterior.

• Una memoria que falla la extracción tres veces se estaciona en lugar de reintentarse para siempre. La razón se registra con la tarea.

Los cambios de código no aparecen en el grafo de código

• Ejecute marm-memory projects auto status. enabled: false significa que la reindexación automática está desactivada; source: override significa que un interruptor guardado la desactivó, no el entorno.

• El repositorio debe indexarse una vez antes de ser vigilado. marm-memory projects list muestra lo que está inscrito.

• Espere el intervalo (30 segundos por defecto) más el tiempo de indexación. Un commit se recoge en la siguiente comprobación.

• Un proyecto eliminado de la Consola permanece suprimido a propósito, por lo que una lista de vigilancia obsoleta no puede recrearlo. Indexarlo explícitamente lo reinscribe.

• La indexación automática necesita el motor de grafo, que permanece inactivo hasta que se haya descargado el binario del motor. Cualquier llamada a herramienta de grafo lo descarga una vez.

Un índice devuelve index_in_progress

• Otro proceso MARM mantiene la puerta de indexación, generalmente el sondeo del otro transporte o un trabajo de índice de la Consola. Eliminar un proyecto informa lo mismo, ya que una eliminación durante un índice sería deshecha por él. Ejecútelo de nuevo en un momento.

Una construcción devuelve build_in_progress

• Otro proceso MARM está escribiendo el grafo, generalmente el trabajador de indexación del otro transporte. Las construcciones son cortas a menos que sea una reconstrucción completa; ejecútelo de nuevo en un momento.

Una construcción devuelve lock_lost

• La construcción se estancó el tiempo suficiente para que otro proceso tomara el control del grafo, por lo que se detuvo a medio camino en lugar de escribir junto a él. Generalmente una máquina suspendida o una pausa del depurador. Lo que indexó antes de detenerse se conserva, y volver a ejecutar la construcción termina el resto.

Las memorias no se guardan

• Verifique que el directorio ~/.marm/ exista y tenga permisos de escritura

• Verifique el espacio disponible en disco

• Pruebe con una memoria simple: pida a la IA que guarde una sola línea y verifique con marm_log_show

• Para modo HTTP, verifique la salud del servidor con curl http://localhost:8001/health

La búsqueda no devuelve resultados

• Verifique que existan memorias: use marm_log_show para listar entradas

• Use search_all=True para buscar en todas las sesiones

• Intente consultas de búsqueda más simples y generales

• Espere unos segundos; la primera búsqueda semántica carga el modelo ML

Las memorias aparecen y luego desaparecen

• Verifique si MARM se reinició o falló (los datos persisten en ~/.marm/)

• Verifique que el espacio en disco no se haya llenado

• Revise los registros del sistema en busca de errores de base de datos

Datos perdidos o corruptos

• Detenga el servidor inmediatamente

• Verifique el directorio ~/.marm/ en busca de copias de seguridad (si las creó)

• Restaure desde la copia de seguridad: copie su copia de seguridad ~/.marm/ de vuelta al directorio home

• Reinicie el servidor

Error de base de datos bloqueada

• Cierre todas las conexiones del cliente de IA

• Detenga el servidor: Ctrl+C

• Haga una copia de seguridad de todo el directorio de la base de datos: cp -r ~/.marm ~/.marm.backup

• Verifique los procesos que mantienen la base de datos: lsof ~/.marm/marm_memory.db (macOS/Linux) o verifique el Administrador de tareas (Windows)

• Si un proceso mantiene el bloqueo, termínelo

• Verifique la integridad de la base de datos: sqlite3 ~/.marm/marm_memory.db "PRAGMA integrity_check;"

• Si la verificación de integridad falla, restaure desde su copia de seguridad

• Si la verificación de integridad pasa, el bloqueo debería liberarse; reinicie el servidor

Resultados de búsqueda lentos

• La primera búsqueda es más lenta (el modelo se carga desde el disco); las búsquedas posteriores son más rápidas

• Las bases de datos grandes (1000+ memorias) pueden tardar unos segundos

• Limite las búsquedas: use limit=10 en lugar de resultados ilimitados

• Use marm_summary para comprimir sesiones antiguas

El servidor usa demasiada memoria

• Los blocs de notas con muchas entradas pueden acumularse; use marm_notebook(action="clear") para podar entradas activas

• Cierre conexiones de cliente de IA no utilizadas

• Use marm_compaction(action="review") para inspeccionar resúmenes de compactación preparados cuando la compactación está habilitada

Para preguntas sobre el comportamiento de la memoria, transportes, clientes compatibles, compactación y copias de seguridad, consulte las FAQ.

Historial de estrellas

Contribuir

MARM da la bienvenida a colaboradores de todos los niveles. El código ayuda, pero también lo hacen los documentos, notas de configuración, pruebas con clientes, informes de errores, benchmarks y comentarios sobre flujos de trabajo reales de personas que usan herramientas de IA a diario.

Buenos lugares para ayudar:

• Pruebe MARM con más clientes MCP, agentes IDE y sistemas operativos

• Mejore documentos, capturas de pantalla, ejemplos y notas de configuración específicas de plataforma

• Reporte errores o pasos de instalación confusos con detalles claros de reproducción

• Comparta flujos de trabajo de memoria, hábitos de agentes e ideas de herramientas de uso real

• Revise los issues abiertos

💡 ¿Quiere que su nombre aparezca en esta lista? ¡Consulte nuestra guía CONTRIBUTING.md para comenzar!

Únase a la comunidad MARM

Ayude a construir el futuro de la memoria de IA: ¡no se requiere programación!

Conéctese: MARM Discord | Discusiones de GitHub

Licencia y aviso de uso

Copyright © 2026 Ryan A. Lyell. MARM se publica bajo la Licencia Apache 2.0 (consulte NOTICE para la declaración de derechos de autor), y se aceptan bifurcaciones, experimentos e integraciones. MARM también incluye componentes de código abierto de terceros como codebase-memory-mcp bajo MIT; consulte THIRD_PARTY_NOTICES.md para la atribución. Si construye sobre él, facilite que las versiones no oficiales se distingan de las publicaciones del repositorio oficial de MARM para que los usuarios sepan lo que están instalando.

Documentación del Proyecto

Guías de Uso

• README.md - Este archivo: guía de uso completa, referencia de herramientas, flujos de trabajo y arquitectura

• PROTOCOL.md - Protocolo operativo MCP

• FAQ.md - Respuestas a preguntas comunes sobre el uso de MARM

Instalación del Servidor MCP

• INSTALL-DOCKER.md - Despliegue con Docker (recomendado)

• INSTALL-WINDOWS.md - Guía de instalación en Windows

• INSTALL-MACOS.md - Guía de instalación en macOS

• INSTALL-LINUX.md - Guía de instalación en Linux

• INSTALL-PLATFORMS.md - Guía de instalación en plataformas

Información del Proyecto

• CONTRIBUTING.md - Cómo contribuir a MARM

• CHANGELOG.md - Historial de versiones y actualizaciones

• ACKNOWLEDGMENTS.md - Contribuyentes y agradecimientos

• ROADMAP.md - Funciones planificadas y hoja de ruta de desarrollo

• LICENSE - Términos de la licencia Apache 2.0