TheWeave

Memoria para Claude que puedes cat, grep y git.

Una arquitectura de memoria nativa de markdown para Claude y cualquier agente compatible con MCP. La memoria de tu asistente vive como archivos .md planos en un directorio que tú controlas — inspeccionable en tu editor de texto, versionable con git, portable entre máquinas — no en una base de datos vectorial opaca en algún otro lugar.

Cinco patrones componibles se asientan sobre el mismo vault:

1. Weave Core MCP — verbo de memoria de 5 acciones sobre cualquier directorio de markdown

2. PPR boot retriever — PageRank personalizado guiado por consultas, no volcados precalculados

3. Bi-temporal resolver — los hechos tienen valid_from / superseded_by; consultas de viaje en el tiempo integradas

4. Sleep-time consolidator — la actividad reciente se integra de vuelta en los archivos de entidades; la síntesis reflect se ejecuta sobre el registro de aprendizaje

5. Write-time conflict resolver — k-NN + veredicto LLM se niega a AÑADIR un duplicado cuando lo correcto es ACTUALIZAR

El sustrato es solo markdown y frontmatter YAML. Sin servicios, sin base de datos de embeddings, sin Ollama. El verbo de 5 acciones funciona con cero infraestructura; los patrones más ricos se superponen sobre los mismos archivos.

Nuevo en v0.4.0:

• Lane firewall (fail-closed) — enruta las notas hacia lanes de recuperación mediante lane_map.yaml; la fuga entre lanes se bloquea en cada punto (búsqueda densa, siembra PPR, recuperación), los archivos puente que coinciden con ambas listas de vocabulario abortan la construcción hasta que un humano los resuelve, y un hash de configuración de lanes rechaza cachés obsoletas.

• Cortex read-path hardening — una nota malformada degrada solo esa nota; los fallos se reportan, nunca se ocultan; los archivos en cuarentena no se pueden recuperar en ningún lane.

• weave lint — verbo de lint del vault con salida --paths legible por máquina.

• Prefiltro de conflictos determinista — las escrituras no relacionadas omiten por completo el veredicto LLM.

• Puerta de escritura consultiva — los verbos MCP de escritura añaden una propuesta de conflicto consultiva (fail-open; interruptor de seguridad WEAVE_WRITE_GATE=0).

• Soporte para Windows (beta) — consulta Windows (beta).

Inicio rápido

git clone https://github.com/TheWeaveSC/theweave.git ~/theweave
cd ~/theweave
pip install -e .

# verify the install end-to-end
weave-cli doctor

# try the included demo vault
weave-cli demo boot "ACME cutover with Marcus"
weave-cli demo current entity-ACME --as-of 2026-01-01   # time-travel
weave-cli demo consolidate --today 2026-05-23           # dry-run

Una instalación saludable se ve así:

🪶 Weave 2.0 Doctor

[Engine]
  ✓ Python 3.11.15 (≥3.11 required)
  ✓ Dependencies importable
      mcp 1.27.1, networkx 3.6.1, frontmatter 1.3.0, click 8.4.1, ...
  ✓ CLI + MCP entry points importable
  ℹ theweave 0.4.0

[Vault]
  ✓ Vault root resolves: ~/theweave/seed-vault
  ✓ Layout: flat (seed-vault style)
  ✓ 18 notes total — entities 6, sessions 7, signals 1, other 4
  ✓ Frontmatter parses on all notes
  ✓ Pattern 4 will scan 7 session(s)
  ✓ Pattern 2 graph: 18 nodes, 71 edges, 0 isolates (0%)
  ✓ Bi-temporal coverage: 6/6 entities (100%)

[Environment]
  ✓ Obsidian.app detected in /Applications/
  ℹ ANTHROPIC_API_KEY not set — Pattern 4/5 will run in mock mode

All checks passed.

Requiere Python ≥ 3.11. Para una ruta de instalación sin clonar (sin autenticación de GitHub), consulta Instalación.

Related MCP server: Mneme Memory MCP

Trae tu propia persona

TheWeave es nativo del vault. La identidad de tu asistente — voz, estilo de trabajo, la relación que has construido — es en sí misma solo markdown en el vault. Los recuerdos de la persona se cargan en cada sesión; los recuerdos factuales se recuperan bajo demanda. Misma primitiva, mismos archivos, diferente disciplina de carga.

Eso significa que una persona es solo un vault inicial que puedes bifurcar:

# clone a starter vault and verify the engine sees it
cp -R personas/sonnet ~/my-vault
weave-cli doctor --vault ~/my-vault --check-mcp
$EDITOR ~/my-vault/entities/entity-user.md   # personalize the user identity

Vaults iniciales incluidos en este repositorio:

• seed-vault/ — inicio ficticio neutral (entidades ACME / FOO). Ideal para probar los cinco patrones.

• personas/sonnet/ — un inicio construido alrededor de un colaborador Claude lacónico y con disciplina de auditoría. Andamiaje de voz, estilo de trabajo y relaciones precableado. Consulta personas/sonnet/README.md para la estructura y las instrucciones de bifurcación.

O salta el inicio y apunta TheWeave a cualquier directorio de markdown existente — Obsidian, tu repositorio de notas, dotfiles. El motor se adapta a cualquier estructura que ya tengas.

Qué es (y qué no es)

TheWeave no es un complemento de memoria para chat. Es la capa de memoria para Claude cuando quieres los datos en tu máquina, en tu sistema de archivos, en un formato que puedas leer.

Arquitectura

                    ┌──────────────────────────────────────┐
                    │       TheWeave — two-tier design     │
                    └──────────────────────────────────────┘

╔════════════════════════════════════════════════════════════════════╗
║  WEAVE CORE  (zero-infra, drop-in MCP server)                      ║
║                                                                    ║
║  ┌─────────────────────────────────────────────────────────────┐  ║
║  │  MCP server — 5 verbs over any markdown vault               │  ║
║  │    view  •  create  •  str_replace  •  insert  •  delete    │  ║
║  └─────────────────────────────────────────────────────────────┘  ║
║                              │                                     ║
║                              ▼                                     ║
║  ┌─────────────────────────────────────────────────────────────┐  ║
║  │  Vault (markdown + YAML frontmatter)                        │  ║
║  │    entities/   sessions/   wiki/   LearningLayer/           │  ║
║  └─────────────────────────────────────────────────────────────┘  ║
╚════════════════════════════════════════════════════════════════════╝
                              │
                              ▼ (same vault, richer engine)
╔════════════════════════════════════════════════════════════════════╗
║  WEAVE PRO  (Python engine on your machine)                        ║
║                                                                    ║
║  Pattern 2 — Query → entity-extract → Personalized PageRank →      ║
║              top-N notes (bi-temporal-aware)                       ║
║                                                                    ║
║  Pattern 3 — Bi-temporal frontmatter (valid_from / valid_until /   ║
║              superseded_by) + chain resolver                       ║
║                                                                    ║
║  Pattern 4 — Sleep-time consolidator:                              ║
║              recent sessions → per-entity activity patch           ║
║              LearningLayer signals → reflect synthesis             ║
║              (dry-run by default; --apply with _archive/ backup)   ║
║                                                                    ║
║  Pattern 5 — Write-time:                                           ║
║              TF-IDF k-NN candidates → LLM (or mock) →              ║
║              ADD / UPDATE / DELETE / NOOP verdict                  ║
║                                                                    ║
║              ┌──────────────┐         ┌─────────────────┐          ║
║              │  mock_llm    │ ◄─────► │  anthropic_llm  │          ║
║              │ (offline)    │  env    │  (live Claude)  │          ║
║              └──────────────┘  var    └─────────────────┘          ║
╚════════════════════════════════════════════════════════════════════╝

Ambos niveles comparten un solo vault. El nivel Core funciona con cero infraestructura (una entrada MCP en claude_desktop_config.json y estás dentro). El nivel Pro añade el motor más rico sin cambiar el formato de datos.

Estado de los patrones

Toda la persistencia es markdown plano. Sin ChromaDB, sin Ollama, sin servicios. El sustrato de 5 verbos soporta ~80% de la arquitectura; solo los pasos de clasificación en los Patrones 4 y 5 necesitan un LLM.

Instalación

Instalación editable (ruta actual)

git clone https://github.com/TheWeaveSC/theweave.git ~/theweave
cd ~/theweave
pip install -e .
weave-cli doctor

Instalación sin clonar (recomendada para aprender)

curl -sSL https://github.com/TheWeaveSC/theweave/releases/latest/download/install-weave.sh | bash

Descarga el tarball de la versión etiquetada, crea un venv de Python en ~/theweave/venv/, instala el paquete y crea un enlace simbólico de weave-cli en ~/.local/bin/ si está en tu PATH. Ejecuta weave-cli doctor como señal de éxito. No se requiere autenticación de GitHub — el tarball se obtiene del endpoint público de versiones.

Configurable mediante variables de entorno: WEAVE_VERSION, WEAVE_HOME, PYTHON. Consulta install-weave.sh.

Windows (beta)

v0.4.0 añade soporte para Windows: resolución de ruta de configuración de Claude Desktop consciente de la plataforma (%APPDATA%\Claude\claude_desktop_config.json), ubicaciones de caché de cortex nativas de la plataforma (%LOCALAPPDATA%\theweave\cache) y un instalador de PowerShell:

irm https://github.com/TheWeaveSC/theweave/releases/latest/download/install-weave.ps1 | iex

Etiqueta honesta: la ruta de Windows está implementada y revisada en código, pero aún no probada en hardware Windows. Si la usas, reporta lo que encuentres — bueno o malo — vía issues. Limitaciones de alcance conocidas: cortex install-nightly es solo para macOS (launchd); usa el Programador de tareas para ejecutar weave-cli cortex dream nocturnamente en su lugar.

Integración MCP con Claude Desktop

Copia docs/claude-desktop-config.snippet.json en la configuración de tu Claude Desktop bajo mcpServers — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json, Linux: ~/.config/Claude/claude_desktop_config.json. Reinicia Claude Desktop. Los 5 verbos estarán disponibles como weave-core/view, weave-core/create, etc.

Modo Claude en vivo (Patrones 4 y 5)

Los Patrones 4 y 5 usan implementaciones simuladas deterministas por defecto. Para activar el modo en vivo:

pip install anthropic
export ANTHROPIC_API_KEY=...
export WEAVE_CLAUDE_MODEL=claude-sonnet-4-6   # optional
weave-cli demo consolidate                    # reflect step now uses Claude
weave-cli demo write /tmp/foo.md              # verdict now uses Claude

El selector weave/pro/llm.py elige anthropic_llm siempre que ANTHROPIC_API_KEY esté configurada, y recurre a mock_llm en caso contrario. Las rutas de código son idénticas; solo cambia el clasificador.

Dependencias

Después de instalar, weave-cli doctor verifica toda la pila — motor, vault, entorno y, opcionalmente, el cableado MCP de Claude Desktop con --check-mcp.

Limitaciones

Lista honesta de lo que está áspero:

• El TF-IDF en el resolvedor de conflictos es frágil con documentos cortos. Las notas candidatas cortas obtienen puntuaciones de similitud bajas incluso cuando son conceptualmente idénticas. El bypass de coincidencia de nombres cubre la mayor parte de esto; los embeddings reales (p. ej., nomic-embed-text) serían la ruta de producción.

• PPR se ejecuta sobre todo el grafo por consulta, sin caché. Está bien para vaults de menos de ~1,000 notas; precalcula y guarda en caché para los más grandes.

• El paso reflect simulado del consolidator es agrupación por palabras clave. Es un stub honesto, no un sustituto del paso reflect con Claude en vivo.

• El modo LLM en vivo es solo para Claude. Sin backends de OpenAI / Gemini / Ollama — abierto a contribuciones.

Filas de experimentos abiertos

Preguntas falseables que estamos ejecutando activamente, en abierto. Protocolos preregistrados y intentos de réplica son bienvenidos — abre un issue.

Documentación

• docs/architecture.md — documento técnico más profundo

• docs/v2-switchover-guide.md — migración desde v1

• CHANGELOG.md — historial de versiones

Licencia

Licencia Apache 2.0.