Agents Remember

`Agents Remember` is a Drift-aware repository memory for coding agents in complex codebases. Captures what code can't say on its own! Retrieves memory by path, semantic search, and relationship (code-graph).

GitHub
27
Prueba este MCPPatrocinado

Documentación

Agents Remember

Registros verificados por Git de lo que saben tus agentes de codificación. Un plano de control para lo que hacen.

NPM License

📖 Documentación actual: https://foxfire1st.github.io/agents-remember/
🤖 Resumen legible por máquina: https://foxfire1st.github.io/agents-remember/llms.txt
Nota: las cachés y los fragmentos de búsqueda pueden mostrar una copia desactualizada de este README — el sitio de documentación anterior es canónico y siempre está actualizado.

Agents Remember mission-control welcome screen: Agents orchestrate attention, Tasks commit intent, and Memory preserves truth.

Tabla de Contenidos

  1. Por Qué Existe
  2. Características Principales
  3. Cómo Se Ve en la Práctica
  4. Demostración en Vivo
  5. Requisitos
  6. Inicio Rápido
  7. Ejecutar el Panel de Control
  8. Documentación
  9. Estructura del Repositorio
  10. Estado
  11. Estabilidad
  12. Contribuciones

Por Qué Existe

Los agentes de codificación modernos pueden hacer ediciones limpias y plausibles mientras pasan por alto las reglas específicas del proyecto que hacen que esas ediciones sean seguras. Un archivo de instrucciones de nivel superior puede ayudar, pero no reaparece de forma natural cuando el agente está en medio de un archivo decidiendo qué cambiar.

Agents Remember soluciona eso: la nota correspondiente es accesible en el momento de la edición — casi siempre por la misma ruta en la que el agente ya está trabajando — de modo que las reglas del proyecto aparecen exactamente cuando se está haciendo un cambio, no enterradas en un archivo de nivel superior.

Características Principales

Agents Remember da a los agentes de codificación memoria de proyecto que pueden verificar y sobre la que pueden actuar. Convierte invariantes locales, reglas de nomenclatura, cicatrices de migración, contratos entre repositorios y hechos de "esto parece seguro pero no lo es" en Markdown versionado junto al código, verifica esa memoria contra Git antes de usarla, y la actualiza solo después de que el trabajo aprobado se integra.

src/orchestrator/core_editor.py
ar-memory/onboarding/src/orchestrator/core_editor.py.md
  • Memoria direccionada por ruta: La nota de un archivo fuente vive en una ruta espejo determinista, de modo que un agente que tiene un archivo puede alcanzar el contexto correcto sin búsqueda, clasificación ni conjeturas.
  • Actualidad probada por Git: Las notas de archivo, las descripciones generales de rutas y los catálogos de entidades se verifican contra desviaciones de commits fuente, ámbitos de ruta o huellas digitales deterministas antes de confiar en ellos.
  • Búsqueda que encuentra, no decide: Los proveedores opcionales de memoria semántica y de grafo de código ayudan a localizar archivos relevantes, llamadores, dependencias y conceptos, pero el Markdown verificado y el código fuente siguen siendo la verdad.
  • Memoria que llega con el código: Los repositorios de memoria externos usan un libro mayor memory.md, árboles de trabajo duales aislados, cierre de vista previa/aplicación e integración de todo o nada para que el código y la memoria permanezcan sincronizados.
  • Comportamiento del agente propiedad del repositorio: Cada repositorio de memoria lleva archivos system/ para reglas de ruta, herramientas, pautas de codificación, fuentes de documentación, política de ramas y forma de informes, de modo que las mismas reglas del proyecto se carguen en todos los entornos.
  • Primera ejecución lista para entornos: Los paquetes iniciales para Claude Code, Codex, Cursor, Antigravity, VS Code Copilot, Hermes, Pi.dev y OpenClaw incluyen el MCP nativo, habilidades, hooks, reglas y archivos de instrucciones que cada entorno necesita.

La configuración predeterminada almacena memoria duradera en el repositorio de destino bajo ar-memory/. Los equipos que necesitan repositorios de memoria separados pueden usar memoria externa bajo ar-coordination/memory-repos/ar-<repo>/. Para el recorrido completo, consulta Características.

Cómo Se Ve en la Práctica

Un archivo fuente tiene una nota de incorporación a su lado, alcanzada por ruta:

mcp/src/agents_remember/mcp/server.py
ar-memory/onboarding/mcp/src/agents_remember/mcp/server.py.md

Al inicio de la tarea, el agente se orienta y verifica la salud de la memoria:

context_packet(repo_id="my-app")
memory_quality_check(request={"mode":"sync", "repo_id":"my-app"})

Luego lee el archivo fuente y su nota de incorporación juntos antes de proponer un cambio. Después de que el cambio se aprueba y se integra, la incorporación se actualiza y se vuelve a verificar contra el nuevo commit — de modo que la nota se mantiene fiel al código.

Demostración en Vivo

Agents Remember se ejecuta sobre sí mismo. El repositorio de memoria complementario es: https://github.com/Foxfire1st/ar-agents-remember

Ese repositorio contiene la capa de incorporación en vivo, para que puedas inspeccionar cómo se ven en la práctica la memoria por ruta, las actualizaciones conscientes de desviaciones y la incorporación en el momento de la contribución.

Requisitos

Antes del Inicio Rápido, asegúrate de que el host tenga:

  • uv (para uvx) o pip, y Python 3.13 — el paquete soporta >=3.13,<3.14; el desarrollo del repositorio usa el contrato 3.13.15 verificado y construido desde la fuente documentado en el README del MCP.
  • Git, con user.name / user.email configurados (los commits de memoria y de árbol de trabajo necesitan un autor; de lo contrario, se usa una identidad de marcador de posición).
  • Docker en ejecución, solo si habilitas los proveedores opcionales. El proveedor de memoria semántica (grepai) también usa un Ollama en contenedor Docker y descarga un modelo de incrustación (nomic-embed-text) en la primera configuración — no se necesita instalación de Ollama en el host.

Los proveedores, Docker y Ollama solo se necesitan para los proveedores opcionales respaldados por Docker; la memoria central por ruta funciona sin ellos. Los hooks de Claude Code no requieren jq; el paquete inicial actual usa un hook de Python. El detalle completo y la solución de problemas viven en el README del paquete MCP.

Inicio Rápido

Este es el camino corto para un nuevo espacio de trabajo. El recorrido detallado vive en Cómo Empezar.

Pídele a tu agente que:

  1. Copie el paquete del entorno — Elige tu guía de entorno bajo docs/install, copia los archivos iniciales nativos de ese entorno desde este repositorio al espacio de trabajo, y luego renderiza el paquete copiado. El script render-starter es una conveniencia: infiere la raíz del espacio de trabajo desde la carpeta del entorno copiada y completa los marcadores de posición de ruta, repositorio y comando de hook del paquete copiado desde una única lista --repo como --repo my-app shared-lib. También puedes hacer esos reemplazos a mano. Estos paquetes incluyen las habilidades visibles para el entorno, hooks/reglas/instrucciones y plantillas de configuración de MCP.

  2. Conecta el servidor MCP — Registra Agents Remember MCP desde PyPI con uvx:

    uvx agents-remember-mcp@latest --config /absolute/path/to/agents-remember-settings.json

    Usa la ruta agents-remember-settings.json del paquete del entorno copiado. Luego reinicia el entorno una vez para que cargue el servidor MCP, las habilidades nativas y los hooks/reglas/instrucciones del paquete.

  3. Incorpora tu proyecto — Invoca la habilidad copiada c-13-install-and-onboard. Ejecuta o verifica runtime_install(), pregunta si crear un nuevo repositorio de memoria o usar uno existente, inicia la incorporación cuando sea necesario y comienza la indexación de proveedores cuando los proveedores estén habilitados.

Ese es el camino normal de primera ejecución. skills_install() sigue disponible como herramienta MCP de mantenimiento/manual, pero los paquetes iniciales ya proporcionan las habilidades iniciales y los archivos del entorno.

Después de eso, el trabajo normal se ejecuta a través de la habilidad l-01-agent-lifecycles: el chat libre orientado al desarrollador responde la investigación en línea y, para el trabajo ordinario con forma de rol después de que existan el sprint duradero y la primera hoja, compila el resumen canónico del arquitecto y llama a dispatch_agent una vez sobre ese documento de sprint. Una toma de control de asiento de tarea declarada explícitamente por el desarrollador apunta al rol nombrado en su documento de tarea canónico. El lanzador sin identidad entrega el control después de que el resumen exacto sea duradero; los asientos posteriores alojados en el plano usan la misma herramienta bajo autoridad estructural de ámbito hijo. Los asientos de backend generados siguen sus resúmenes de rol. El agente resuelve el contexto activo con c-08-ar-coordination-context-resolver, verifica la calidad de la memoria con c-02-memory-quality-control, lee la incorporación relevante junto al código y actualiza la incorporación después de los cambios aprobados.

Ejecutar el Panel de Control

El panel de control de misión viaja dentro del paquete MCP. Instala la CLI una vez con uv — última versión estable, sin fijar versión — luego inicia la cabina desde cualquier lugar en tu espacio de trabajo:

uv tool install agents-remember-mcp
agents-remember dashboard

--config es opcional: la CLI sube desde el directorio actual y usa el .claude/mcp/agents-remember-settings.json más cercano, o el --config registrado en una entrada .mcp.json agents-remember — el mismo archivo de configuración desde el que arranca el servidor MCP.

Para un panel que sobreviva al cierre de la terminal, usa el modo demonio:

agents-remember dashboard --daemon    # detach; state + log under <coordinationRoot>/logs/dashboard/
agents-remember dashboard --status    # exit 0 when running, 1 when not
agents-remember dashboard --stop

O deja que el servidor MCP lo supervise: establece "dashboard": {"autoStart": true} en el JSON de configuración de MCP y cada arranque del servidor asegura el demonio — adoptando uno saludable, iniciando uno faltante y reiniciando en caso de desajuste de versión para que una actualización sea recogida en la próxima sesión (Referencia de Configuración).

Fijar una versión es la ruta de depuración/reproducción, no la predeterminada: uv tool install 'agents-remember-mcp==3.0.0rc8', o de una sola vez sin instalar, uvx --from 'agents-remember-mcp==3.0.0rc8' agents-remember dashboard.

Nota de pre-lanzamiento (hasta 3.0.0 final): el panel actualmente viaja en pre-lanzamientos 3.0.0rcN, que la resolución de versión predeterminada omite. Instala con uv tool install --prerelease allow agents-remember-mcp, y registra el servidor MCP con un pin explícito agents-remember-mcp==3.0.0rcN en lugar de @latest.

Documentación

  • Características - el recorrido concentrado de lo que Agents Remember ofrece a los usuarios.
  • Cómo Empezar - una configuración de primera ejecución más completa.
  • Conceptos - unidades de incorporación, raíces de memoria, desviaciones y puertas de aprobación.
  • Arquitectura - tiempo de ejecución, coordinación, memoria interna y memoria externa.
  • Flujos de Trabajo - la habilidad l-01-agent-lifecycles y sus modos de construcción (salida solo de investigación / tarea de habilidad w-02-light-task-workflow / serie de maestro + sub-tarea ligera), y cuándo usar cada uno.
  • Metodología de Benchmark - cómo se capturan y comparan las ejecuciones emparejadas codex exec --json.
  • Preguntas Frecuentes - principios de diseño, objeciones y comparaciones.
  • Guía de Memoria Externa - repositorios de memoria separados para repositorios de código seleccionados.
  • Bootstrap Consciente de Costos - opciones de modelo y dimensionamiento de oleadas para el bootstrap de repositorios con uso intensivo de tokens.
  • Referencia de Configuración - capa de memoria system/settings.json y configuración de autoridad MCP.
  • Referencia de Habilidades - las familias de habilidades instaladas.

Estructura del Repositorio

agents-remember/
  AGENTS.md                         # source checkout instructions
  README.md                         # public front door
  skills/                           # canonical skill source tree
  scripts/sync-skills.py            # sync skills into package/harness copies
  scripts/sync-runtime.py           # sync runtime assets into package data
  scripts/sync-harness.py           # generate the nine harness configuration trees
  scripts/harness/                  # canonical source for those trees
  agents-md-files/                  # canonical installed AGENTS.md templates
  benchmarks/                       # canonical optional benchmark package source
  providers/                        # canonical provider runtime assets
  system/defaults/examples/         # canonical scaffold examples
  mcp/                              # package-local MCP server and services
    src/agents_remember/package_data/
      runtime/
        agents-md-files/            # generated copy of root agents-md-files/
        skills/                     # generated package copy of root skills/
        providers/                  # generated copy of root providers/
        system/defaults/examples/   # generated copy of root system/defaults/examples/
      benchmarks/                   # generated copy of root benchmarks/
  docs/                             # user-facing documentation

Edita las habilidades en la raíz skills/, luego ejecuta python3 scripts/sync-skills.py para actualizar los datos del paquete MCP y cada paquete inicial del entorno. Los hooks de pre-commit y pre-push ejecutan python3 scripts/sync-skills.py --check.

Edita los activos de tiempo de ejecución en la raíz agents-md-files/, benchmarks/, providers/, y system/, luego ejecuta python3 scripts/sync-runtime.py para actualizar solo los datos del paquete MCP. Los hooks de pre-commit y pre-push ejecutan python3 scripts/sync-runtime.py --check.

Edita la configuración del entorno autoalojado en la raíz scripts/harness/, luego ejecuta python3 scripts/sync-harness.py para regenerar los nueve árboles .claude/, .codex/, .cursor/, .github-vscode/, .vscode/, .hermes/, .openclaw/, .pi/ y .agents/. Los hooks de pre-commit y pre-push ejecutan python3 scripts/sync-harness.py --check, y mcp/tests/test_sync_harness.py ejecuta la misma verificación dentro de la suite.

Los hooks están escalonados, y ambos son envoltorios delgados sobre .githooks/_gate.sh. pre-commit ejecuta el nivel rápido sobre el contenido en stage: las verificaciones de copia generada anteriores, más Ruff, ruff format --check, Pyright y verificaciones deterministas del panel. pre-push repite esas verificaciones no de prueba contra los bytes del checkout actual y registra las refs empujadas. No ejecuta la aceptación. GitHub ejecuta sus verificaciones deterministas no de prueba una vez por solicitud de extracción, no una vez más por cada push de rama. Un grafo Dagger v0.21.8 fijado reconstruye el candidato Git exacto en un contenedor Ubuntu limpio, instala desde cero, ejecuta una sonda de protocolo de solo lectura Codex real incluida y ejecuta el envoltorio de aceptación. Dagger dirigido se ejecuta una vez cuando cada cierre de hoja crea su commit. La integración de hoja integra ese commit certificado exacto sin una re-ejecución. Dagger completo se ejecuta una vez cuando cada maestro se integra en super. La validación de PR, el etiquetado y la publicación no re-ejecutan la aceptación. Consulta CONTRIBUTING.md para la tabla de niveles y el contrato de contenido en stage. Agents Remember declara que el grafo de Dagger en su mcp/certification-profile-v1.json propiedad del repositorio, seleccionado explícitamente por repositories.agents-remember.certificationProfile en la configuración de autoridad de MCP. El framework no descubre un envoltorio ni lleva un inventario de comandos/reportes de Agents Remember. El desarrollo ordinario de Python usa pytest directamente, sin admisión de Dagger, cobertura, certificación de repositorio, ni un grafo de servicios de aplicación autouse:

mcp/.venv/bin/python -m pytest                         # default unit loop
mcp/.venv/bin/python -m pytest mcp/tests/test_example.py # one changed behavior
mcp/.venv/bin/python -m pytest -m integration           # delivery boundary checks

El valor predeterminado excluye el marcador integration. Las entradas locales, los recursos temporales y los dobles de prueba explícitos siguen siendo pruebas ordinarias; la publicación/recuperación real, los escritores en competencia, el cableado de la aplicación y las observaciones de todo el repositorio se ejecutan por separado. Las clases de prueba importadas solo se ejercitan en su módulo definidor. Cuatro workers son el valor predeterminado; usa -n=0 para depuración en serie. Las pruebas usan directorios desechables de home/config/caché y depuran los selectores de Git heredados, las opciones de participación activa y las credenciales. Nunca declaran una identidad de daemon.

La entrega ejecuta ambas poblaciones juntas (-m "") en el entorno Dagger compartido existente. Solo el --certify explícito carga los plugins de certificación retenidos y requiere una admisión genuina de Dagger. La cobertura de ramas combinada alimenta el piso del 90% de líneas de producción modificadas y el umbral CRAP existente de 30. Las pruebas y el soporte solo de verificación se excluyen de la puntuación de producción. La cobertura y el CRAP no forman parte del comando unitario ordinario. Los comandos directos y dirigidos de pruebas unitarias/componentes de Vitest también siguen disponibles.

La taxonomía completa de evidencia, los metadatos del ciclo de vida, la regla de autoridad de fixtures, el comportamiento de selección/reintento propiedad de dependencias, la cadencia de estrés y el contrato de fallos causales están documentados en docs/design/python-evidence-system.md. La aceptación de hoja/enfocada es Dagger mode=targeted, mientras que la aceptación única de altitud maestra de todo el repositorio es Dagger mode=full. Ambas requieren un diff-base de Git explícito; la función pública de Dagger rechaza una base vacía en lugar de comparar el candidato con el árbol vacío de Git. Ejecuta dagger call quality --help para ver los modos actuales y el contrato de argumentos. No hay respaldo directo de Docker o host: un motor Dagger no disponible falla explícitamente. El grafo recibe un paquete de ascendencia de Git separado más la fuente exacta en stage, nunca la raíz de coordinación en vivo, las credenciales o el socket del contenedor. Su traza en vivo y los artefactos finales de pytest, cobertura, sonda Codex y resultados reemplazan los archivos correspondientes bajo el directorio reports/ del recinto de tareas.

Dentro del grafo Dagger atestiguado por nonce, el envoltorio ordena rieles deterministas baratos antes del riel de prueba costoso: Ruff, formato, tamaño de archivo, Pyright, informes de Radon, luego pytest. La cobertura de CRAP y líneas modificadas puntúa el artefacto de cobertura de ramas de esa ejecución al final. La prueba de reintento exacta o solo de prueba con direccionamiento por contenido es una optimización interna de Dagger; cualquier deriva de fuente, configuración, suite seleccionada, runtime, entorno o artefacto ejecuta la selección ordinaria en el mismo grafo. No hay ruta de reintento en host ni respaldo. La aceptación del ciclo de vida deshabilita la reutilización de pruebas por defecto con AR_QUALITY_NO_RETRY=1.

Cada riel de Dagger imprime una línea de procedencia que nombra su entrada real, configuración resuelta y conteo de unidades. El hook determinista de pre-push reenvía por separado las actualizaciones de refs de Git y verifica los bytes del checkout actual en rutas conocidas por índice; no ejecuta pruebas y nunca reclama aceptación para el rango de commits empujado.

El runtime instalado vive en ar-coordination/ — por defecto <workspace>/ar-coordination/, dentro del workspace (nunca tu directorio home) — no en el checkout de la fuente. La habilidad c-13-install-and-onboard muestra esto y cada otra ruta de instalación como un valor predeterminado de workspace-primero que puedes aceptar o sobrescribir:

ar-coordination/
  AGENTS.md
  skills/
  system/
  memory-repos/
  providers/                        # provider runtimes (images, runners, indexes)
  benchmarks/                       # optional, installed with --include-benchmarks
  tasks/
  notes/
  worktrees/
  temp/

Estado

Agents Remember está en 3.0.0rc8 y en desarrollo activo. La ruta central — incorporación por ruta, verificaciones de deriva y actualizaciones con aprobación — está en uso real y es lo suficientemente estable para confiar en ella. Los contratos públicos listados bajo Estabilidad se mantienen estables entre versiones menores y solo cambian en un salto mayor; los internos debajo de ellos y los proveedores opcionales de semántica/relaciones pueden seguir evolucionando, así que fija una versión y lee las notas para tu versión objetivo en GitHub Releases — el changelog canónico del repositorio — antes de actualizar. La ruta de Claude Code es la más ejercitada; otros harnesses son compatibles pero menos probados en batalla.

El arco 3.0: la sesión de trabajo en sí ahora es observable y dirigible — un ciclo de vida de agente gestionado por el sistema con puertas de aprobación duraderas y una capa de eventos/proyecciones, servido como la cabina de control del navegador de misión directamente desde el paquete MCP (agents-remember dashboard; #2, #43). La etiqueta rc significa que la superficie de la cabina aún se está asentando hacia el contrato final 3.0.0; la arquitectura debajo es la descrita anteriormente.

Estabilidad

Siguiendo el versionado semántico desde 1.0.0, estos contratos públicos no cambiarán sin un salto de versión mayor: IDs de habilidades (por ejemplo, las habilidades c-08-ar-coordination-context-resolver y w-02-light-task-workflow), nombres de herramientas MCP y sus entradas/salidas, el layout de ar-coordination/ y ar-memory/, y el esquema de configuración. Los módulos internos, los internos de proveedores y la redacción de prompts no forman parte de esta promesa y pueden cambiar en versiones menores.

Contribuciones

Las contribuciones deben hacer la capa de memoria más clara, segura y fácil de aplicar de manera consistente. Comienza con CONTRIBUTING.md y mantén las reglas centrales intactas: verificación de deriva antes de planificar, aprobación antes de implementar y actualizaciones de incorporación solo después de cambios aprobados.

Agents Remember se ejecuta sobre sí mismo, así que la mejor manera de contribuir es con la capa de memoria activa. Descarga o clona la memoria propia de este proyecto en Foxfire1st/ar-agents-remember y úsala como la memoria de Agents Remember para tu checkout: obtienes la incorporación por ruta del proyecto en el momento de editar, y tus actualizaciones de incorporación aterrizan junto con tus cambios de código — el mismo bucle que este repo pide de cada contribución.