Skip to main content
Glama
README.md
# Vigente

[![CI](https://github.com/laulys/vigente/actions/workflows/ci.yml/badge.svg)](https://github.com/laulys/vigente/actions/workflows/ci.yml)

Memoria para agentes de IA que sabe qué sigue siendo verdad.

Cuando un hecho cambia, Vigente no lo borra ni lo mezcla con el nuevo: lo marca como reemplazado y guarda la cadena de cambios. Por defecto solo devuelve lo vigente, y también puede responder qué era verdad en una fecha concreta.

> **En construcción.** Hito 4 de 5: servidor MCP sobre un núcleo local con SQLite, búsqueda por significado y validez temporal, evaluado con datos sintéticos y LongMemEval. Próximo: cierre.

## Hoja de ruta

- [x] **Hito 0. Diseño:** arquitectura, esquema y plan de evaluación, con sqlite-vec probado antes de escribir código.
- [x] **Hito 1. Núcleo:** SQLite + FTS5, reemplazos con validez temporal, borrado verificado en disco y CLI.
- [x] **Hito 2. Búsqueda semántica:** embeddings locales, índice vectorial, búsqueda híbrida y elección del modelo con un benchmark propio.
- [x] **Hito 3. Servidor MCP:** seis herramientas, probadas con el cliente oficial por stdio y con un agente real.
- [x] **Hito 4. Evaluación:** datos sintéticos y LongMemEval, con las reglas de decisión fijadas antes de medir y los resultados publicados tal como salieron.
- [ ] **Hito 5. Cierre:** README final y demo.

## Probarlo

```bash
uv sync
ollama pull embeddinggemma        # opcional: sin él, Vigente busca solo por texto
uv run vigente add "El proyecto usa PostgreSQL 15 como base de datos" --valid-from 2026-03-01
uv run vigente add "Migramos a SQLite para el MVP"     # propone reemplazar el hecho anterior
uv run vigente supersede <id> "El proyecto usa SQLite" --reason "MVP más simple"
uv run vigente search "¿qué base de datos usamos?"
uv run vigente search "base de datos" --as-of 2026-06-01
uv run vigente history <id>
```

## Usarlo desde un agente (MCP)

Vigente expone seis herramientas por MCP: `remember`, `recall`, `supersede`, `forget`, `history` y `list_memories`. El workspace lo fija la configuración, nunca el agente.

**Claude Code:**

```bash
claude mcp add vigente -e VIGENTE_WORKSPACE=mi-proyecto -- uv --directory /ruta/a/vigente run vigente-mcp
```

**Cursor** (`.cursor/mcp.json`) o **Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vigente": {
      "command": "uv",
      "args": ["--directory", "/ruta/a/vigente", "run", "vigente-mcp"],
      "env": { "VIGENTE_WORKSPACE": "mi-proyecto" }
    }
  }
}
```

Cuando el agente guarda algo que deja obsoleto un hecho anterior, `remember` se lo propone y el agente lo enlaza con `supersede`. Desde entonces el hecho anterior no se devuelve, aunque queda en el historial.

## Configuración

| Variable | Por defecto | Para qué |
|---|---|---|
| `VIGENTE_DB` | `~/.vigente/vigente.db` | Archivo de la memoria |
| `VIGENTE_WORKSPACE` | `default` | Espacio aislado de memorias |
| `VIGENTE_EMBED_MODEL` | `embeddinggemma` | Modelo de embeddings; `none` para usar solo texto |
| `VIGENTE_EMBED_BASE_URL` | `http://localhost:11434/v1` | Cualquier servicio compatible con la API de OpenAI |
| `VIGENTE_EMBED_API_KEY` | | Solo si el servicio la pide |
| `VIGENTE_ALLOW_REMOTE` | desactivado | Necesario para enviar memorias a un servicio no local |
| `VIGENTE_SEARCH_MODE` | `vector` | `hybrid` (vectores + texto) o `text`; ver [ADR-0006](docs/decisions/0006-busqueda-por-vectores.md) |

Si el servicio de embeddings no responde, Vigente sigue funcionando con búsqueda de texto y lo avisa. `vigente reindex` calcula después los vectores pendientes.

## Resultados

- **[Datos obsoletos](eval/results/e1_synthetic.md):** con una memoria que guarda cada versión como un hecho más, el primer resultado es una versión obsoleta en el 51% de las preguntas con búsqueda por vectores (44% con la híbrida). Con Vigente, en el 0%, sin perder acierto.
- **[LongMemEval](eval/results/e2_longmemeval.md), 470 preguntas:** sin reemplazos, en las preguntas de actualización la versión vieja sale antes que la nueva en torno a la mitad de las veces, con cualquier modo de búsqueda.
- **[Escala](eval/results/scale.md):** con 50.000 memorias, una búsqueda tarda 62 ms y un borrado completo 52 ms, más unos 15 ms del modelo.
- **[Decisiones](eval/results/decisions.md)** tomadas con esos datos: búsqueda por vectores por defecto, y el umbral de reemplazos se mantiene.

- [Demo con un agente real](eval/results/agent_demo.md): cuatro sesiones independientes de Claude Code que solo comparten Vigente. El agente guarda, detecta y enlaza cambios sin duplicar hechos (incluido uno anunciado para la semana siguiente) y en una sesión nueva responde con lo vigente.
- [Elección del modelo de embeddings](eval/results/embedding_choice.md): con embeddings, la detección de hechos reemplazados sube de F1 0.43 a 0.76 en un conjunto pequeño en español.

## Desarrollo

```bash
uv run pytest                                          # sin red ni modelos
VIGENTE_TEST_OLLAMA=1 uv run pytest tests/test_ollama.py   # con Ollama local
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests eval
uv run python eval/embedding_choice.py                 # repite el benchmark
# evaluación completa: ver eval/README.md
uv run python eval/agent_demo.py                       # demo con un agente (requiere la CLI de Claude)
```

## Diseño

- [Arquitectura](docs/architecture.md)
- [Decisiones (ADRs)](docs/decisions/)

## Licencia

[MIT](LICENSE)

TDQS

A3.8/5.0

Scored across 6 tools

Disambiguation4/5

Each tool maps to a distinct lifecycle step: remember (create), recall (search), forget (hard delete), supersede (version link), history (version trail), list_memories (enumerate). The main soft spot is recall vs list_memories and recall vs history, which both surface stored memories and could be picked interchangeably, though the descriptions clarify the difference (semantic search on current truths vs. chronological listing vs. full version chain).

Naming Consistency4/5

Five tools are bare, memorable verbs (remember, recall, forget, supersede) or a bare noun (history), which read consistently as a memory vocabulary. The outlier is list_memories, the only verb_noun compound, but it is still predictable and readable.

Tool Count5/5

Six tools is well-scoped for a versioned memory store: one per core operation with no redundant or filler tools. Nothing feels thin, since the supersession model is fully expressible with these six.

Completeness5/5

Full lifecycle is covered: create (remember), search/read (recall, list_memories, history), update-by-versioning (supersede, including new_content as an in-place update path), and delete (forget). The supersession model even has an error-recovery path (current_id) and a history view, so agents have no dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues