memoria-projetos — encuentra cualquier proyecto y consulta lo que ya se decidió

Qué es

Dos partes independientes

Puedes instalar solo una. El índice funciona completamente en local; la memoria guarda todo en local, pero usa Claude para extraer los datos. Ambas se actualizan automáticamente todos los días.

Banner con las seis funciones: índice de proyectos, búsqueda semántica, local y GitHub, memoria que responde, carga diaria e informe semanal

🔎 Encuentra cualquier proyecto

projeto "o que faz" busca por palabras y por significado en más de mil proyectos, incluidos los que solo existen en GitHub, y avisa cuando la carpeta local está desactualizada respecto a GitHub.

🧠 Memoria que responde

memoria "pode X?" lee tus lecciones, fallas y la memoria del agente, y devuelve una respuesta breve con fecha y fuente, en lugar de muchas líneas de grep.

📊 Medido, no prometido

Se registra cada uso. Cada semana se genera un informe: cuántas veces lo usó el agente, cuánto tardó, cuánto costó y si las respuestas fueron útiles.

Cómo funciona

De lo que ya tienes a lo que pregunta el agente

Índice: las carpetas y los repositorios se convierten en una línea cada uno. Para buscar por significado, cada línea se convierte en un vector (una lista de números que representa el significado del texto), calculado por el modelo bge-m3 en Ollama local. Memoria: Hindsight, un servidor de memoria de código abierto para agentes de código (MIT), guarda los datos en una base de datos local y usa Haiku, el modelo más pequeño y rápido de Claude, mediante tu suscripción, para extraer datos de las anotaciones y responder. Un modelo local de reordenamiento coloca los fragmentos más relevantes al principio.

Carpetas + GitHub→ Índice diario 05:40→ projeto "X"

Lecciones, fallas, memoria→ Carga diaria 06:10 (solo lo nuevo)→ memoria "pregunta"→ Informe semanal

Requisitos previos

Qué debe estar instalado

El instalador solo comprueba estas cosas; no instala nada del sistema.

Python 3.11+ y Ollama

Ollama proporciona los vectores multilingües (los usan ambas partes).

# modelo de vectores
ollama pull bge-m3

GitHub CLI (índice)

Con la sesión iniciada en cada cuenta que quieras indexar. Sin esta herramienta, el índice solo incluye las carpetas locales.

gh auth login   # una vez por cuenta
gh auth status

Claude Code con sesión iniciada (memoria)

La memoria usa tu suscripción mediante el proveedor claude-code de Hindsight, recomendado para uso personal y local. Los horarios automáticos usan systemd de usuario; enable-linger permite que los temporizadores funcionen aunque hayas cerrado sesión. Sin systemd, usa --sem-systemd y ejecútalo manualmente.

claude --version
loginctl enable-linger "$USER"

Guía de uso · paso a paso

Desde la clonación hasta la primera respuesta

Comandos del README del repositorio. La primera vez que se inicia el servidor de memoria, descarga la base de datos integrada y el modelo de reordenamiento; después, todo funciona en local.

Descargar y ver qué haría el instalador

--dry-run muestra todo primero, sin guardar nada.

git clone https://github.com/inematds/memoria-projetos.git
cd memoria-projetos
./instalar.sh --dry-run

Instalar ambas partes

Crea los accesos directos projeto y memoria en ~/.local/bin, los servicios con límite de memoria e instala Hindsight (unos 2 GB). Para instalar solo una parte: --so-indice o --so-memoria. Si ya existe un acceso directo o servicio con el mismo nombre que no pertenece al kit, lo omite y avisa; para reemplazarlo, usa --forcar. Comprueba que ~/.local/bin esté en tu PATH.

./instalar.sh --instalar-hindsight
echo $PATH | grep -q .local/bin || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc   # o abre una terminal nueva
systemctl --user status memoria-hindsight   # el primer inicio descarga la base de datos: espera "active (running)"

Indicar dónde están las cosas

En indice/config.json: la carpeta raíz de los proyectos y las cuentas de GitHub (cambia sua-conta-github por la tuya, o deja [] para usar solo carpetas locales). En memoria/fontes.json: los archivos de lecciones, fallas y memoria. En memoria/.env: el nombre de la base de datos de memoria (una por persona o proyecto).

# una fuente en memoria/fontes.json (modelo completo en fontes.exemplo.json)
{"nome": "licoes", "tipo": "linhas",
 "caminho": "~/meu-projeto/LESSONS.md",
 "contexto": "lição aprendida no projeto", "tag": "licao"}
# la memoria de Claude Code está en ~/.claude/projects/<pasta>/memory
ls ~/.claude/projects/   # <pasta> = ruta del proyecto con / reemplazado por -

Crear el primer índice

Mil proyectos tardan de 1 a 2 minutos. Después, busca algo que sepas dónde está para comprobarlo.

projeto --atualizar
projeto "publica vídeo no youtube" -n 5   # * = coincidieron todas las palabras

Primera carga de la memoria

Primero, revisa qué se enviaría. Cada documento genera una llamada a Haiku y consume una pequeña parte de la cuota de tu suscripción: en la prueba piloto, unos 5,6 mil tokens de entrada por documento; 100 documentos tardaron 8 minutos.

python3 memoria/carga.py --simular   # no envía nada
python3 memoria/carga.py --max 200  # carga inicial

Hacer una pregunta

Respuesta lista (30 a 75 s) o solo los fragmentos (7 a 17 s, sin LLM para la respuesta). Después, califica la última respuesta (el texto entre comillas explica el motivo): se incluirá en el informe.

memoria "¿puedo ejecutar un proceso largo sin límite de memoria?"
memoria -r "systemd PATH"
memoria --nota util "encontró la regla correcta"

Hacer que el agente lo use

El agente solo usa lo que indican sus reglas. Copia el bloque «Encontrar proyectos y consultar la memoria» del README en CLAUDE.md o AGENTS.md. La memoria no se carga al inicio de la sesión: el agente consulta cuando la necesita y así la cuota solo se consume cuando hay una pregunta.

# fragmento de la regla
- Pregunta sobre una regla o decisión: ejecuta `memoria "pregunta"` ANTES de buscar con grep en las lecciones y fallas.

Dejarlo funcionando y leer el informe

Los temporizadores actualizan el índice a las 05:40, guardan solo lo nuevo a las 06:10 y generan el informe cada lunes a las 08:00. Con él puedes decidir si lo mantienes, cambias la regla o lo desactivas.

python3 memoria/semana.py   # → memoria/semana-AAAA-MM-DD.md
python3 memoria/avalia.py   # grep × fragmentos × respuesta en tus preguntas (consume cuota)

Detener o desinstalar

Para detener todo, desactiva los servicios. Para eliminarlo, borra también los accesos directos, el entorno de Python de Hindsight y la base de datos local (~/.pg0).

systemctl --user disable --now memoria-hindsight.service memoria-carga.timer memoria-semana.timer memoria-indice.timer
rm ~/.config/systemd/user/memoria-*.service ~/.config/systemd/user/memoria-*.timer
systemctl --user daemon-reload
rm ~/.local/bin/projeto ~/.local/bin/memoria
rm -rf memoria/.venv   # desde la carpeta del kit
rm -rf ~/.pg0   # solo si ningún otro programa usa pg0: borra la memoria guardada

Ejemplos

Lo que aparece en pantalla

Resultados reales de una máquina con cerca de mil proyectos; los nombres corresponden a sus proyectos.

🔎 Encontrar según lo que hace el proyecto

Sin recordar el nombre, solo qué hace. El * indica que coincidieron todas las palabras:

projeto "publica vídeo no youtube" -n 2
1.01* yt-pubx — Publica cualquier video en
      YouTube con un comando…
0.96* yt-pub-livesx2 — Publicador de videos
      en YouTube para N canales…

🧠 Fragmentos en lugar de grep

Con -r, solo aparecen los fragmentos relevantes, cada uno con su origen:

memoria -r "systemd PATH codex"   # 12,7 s
- systemd-run sin PATH ejecutó el antiguo
  /usr/bin/codex… definir PATH con ~/.npm-global/bin

📏 Prueba piloto: 10 preguntas con respuestas conocidas

grep (como funciona hoy): 10 de 10, pero el agente tuvo que leer 43,6 mil tokens de líneas mezcladas. Fragmentos (-r): 9 de 10, con 5,3 mil tokens. Respuesta lista: 10 de 10, con 4,3 mil tokens, cerca de 10 veces menos texto. Este resultado corresponde a una prueba piloto pequeña, evaluada por quien la preparó, y el uso real se está midiendo con el informe semanal.

Hoja de ruta

Estado actual y próximos pasos

El índice se usa a diario. La memoria está en prueba: el informe semanal define los próximos pasos.

Listo

Índice de proyectosCarpetas locales y varias cuentas de GitHub, búsqueda por palabras y por significado, aviso de carpetas desactualizadas respecto a GitHub y actualización diaria.

En prueba

Memoria que respondeCarga diaria solo de lo nuevo, comando memoria con calificación de utilidad e informe semanal de uso y costo.

Después

Más fuentes y más agentesMás tipos de anotaciones como fuentes; una herramienta que el agente pueda invocar directamente, sin pasar por la terminal (MCP), si el comando resulta útil; y una base de datos de memoria por cliente.