Cómo dotar a los agentes de IA de memoria a largo plazo usando Obsidian

La semana pasada me encontré explicando la estructura de nuestro servicio de autenticación a un agente de codificación por tercera vez este mes. La ventana de contexto de Claude Code es bastante grande, pero cualquier sesión eventualmente termina. Una nueva ejecución en la terminal — y la consola no sabe nada sobre decisiones arquitectónicas, acuerdos del equipo o tareas del sprint.

Hace poco descubrí el proyecto obsidian- del desarrollador Brenno Ferrari. El autor adoptó un enfoque directo: si un agente necesita memoria a largo plazo, ¿por qué no convertirla en una bóveda regular de Obsidian?

Qué hay dentro de la plantilla

El proyecto es una estructura de notas lista para usar, un conjunto de hooks de TypeScript y comandos CLI preconstruidos. Desde el primer momento, la plantilla funciona con Claude Code, Codex CLI, Gemini CLI y otros sistemas que pueden leer reglas desde archivos de instrucciones.

La idea es que el agente lee y actualiza archivos Markdown por sí mismo. Cuando inicia una sesión, un hook lee los objetivos globales desde el archivo brain/North Star.md, extrae la lista de tareas activas y pasa este fragmento a la ventana de contexto. Cuando le cuentas al agente sobre una decisión tomada o una reunión que tuvo lugar, organiza los datos en carpetas y los vincula a nombres de compañeros o proyectos.

Cómo funciona el control de uso de tokens

El problema principal con sistemas como este es el consumo de tokens. Si introduces toda la base de conocimientos en el contexto en cada solicitud, los límites se agotarán en un par de horas.

En obsidian-, esto se maneja mediante un esquema de carga multicapa:

• Cuando inicia una sesión, se lee un fragmento base: objetivos, tareas abiertas, commits recientes y la lista de archivos de la bóveda. Esto ocupa aproximadamente 20,000 tokens.
• Para la búsqueda semántica, se utiliza la utilidad QMD. Construye embeddings vectoriales localmente y encuentra los fragmentos relevantes cuando el agente necesita información específica.
• Cuando se envían mensajes, el script determina el tipo de dato (incidente, reunión, decisión arquitectónica) y pasa una pista de enrutamiento corta al agente.
• Después de escribir los archivos, se ejecuta un validador que verifica la corrección de los enlaces wiki y los parámetros YAML.

Cómo es un día laboral

Por la mañana ejecutas el comando /om-standup. El agente lee los cambios recientes en git, cruza referencias con la lista de tareas y genera un breve resumen.

Después de reuniones o discusiones en Slack, no es necesario rellenar manualmente las estructuras de documentos. Solo alimenta el texto sin formato al agente:

/om-dump Обсудили с Сарой рефакторинг авторизации. Решили отложить миграцию на Redis до второго квартала. Сара похвалила архитектуру API.

Como respuesta, el sistema hace cuatro cosas a la vez de forma automática:

1. Actualiza el archivo de historial de reuniones en org/people/Sarah Chen.md.
2. Crea una entrada de decisión en la carpeta de decisiones.
3. Registra elogios en la plantilla de attestación perf/Brag Doc.md.
4. Agrega una nueva tarea a la tarjeta del proyecto activo.

Al final del día, el comando /om-wrap-up busca notas huérfanas sin referencias cruzadas y actualiza los índices.

Ejecutar tareas en segundo plano mediante sub-agentes

Para operaciones pesadas, se configuran sub-agentes especializados dentro de la plantilla. Se ejecutan en ventanas de contexto aisladas para evitar saturar el historial principal de la conversación.

El repositorio tiene varios agentes preconfigurados:

• slack-
• cross-linker busca enlaces wiki rotos y notas olvidadas en toda la bóveda.
• brag-
• people-

Compilación y ejecución

Puedes desplegar la bóveda mediante el administrador de plantillas ShardMind o simplemente clonando el repositorio.

npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind

El comando de configuración te pedirá que ingreses tu nombre, nombre de la empresa y objetivos principales. Después de eso, solo necesitarás seguir unos pocos pasos:

1. Abre la carpeta creada como una bóveda en Obsidian.
2. Habilita el plugin de Obsidian CLI en la configuración de la aplicación (requiere Obsidian 1.12+).
3. Ejecuta el agente CLI directamente desde el directorio de la bóveda.

Para una búsqueda con todas las funciones, también deberías instalar la herramienta de búsqueda vectorial QMD:

npm install -g @tobilu/qmd
node --experimental-strip-types .scripts/qmd-bootstrap.ts

Sin QMD, el sistema continuará funcionando mediante grep y la búsqueda integrada de Obsidian, aunque la precisión de las respuestas a preguntas abstractas disminuirá ligeramente.

Para quién es este proyecto

La plantilla será útil para desarrolladores que usan activamente agentes de IA basados en CLI y que ya mantienen o planean mantener notas en Obsidian. El valor principal aquí radica en las reglas bien pensadas para vincular documentos entre sí.

Una cosa a tener en cuenta es la dependencia de Node.js versión 22+ con el flag --experimental-strip-types para ejecutar scripts de TypeScript sin precompilación. Si este flag se renombra en futuras versiones de Node.js, necesitarás actualizar la configuración de los hooks. No obstante, el proyecto proporciona una excelente base lista para usar y elimina la necesidad de construir este tipo de andamiaje desde cero.