Memoria de Proyecto SQLite MCP

Servidor MCP respaldado por SQLite para almacenar la memoria del proyecto como un núcleo relacional compatible con grafos.

Por qué este proyecto

• Mantiene el estado autoritativo en SQLite (fuente única de verdad).

• Proporciona semántica de grafos (entities, relationships, content, tags).

• Admite lecturas estructuradas (query_view) y vistas en markdown generadas explícitamente.

• Diseñado para flujos de trabajo seguros para agentes de IA.

Modelo central

• entities

• attributes

• relationships

• content

• tags

• events, snapshots, snapshot_entities (auditoría/historial)

Objetivos compatibles con sync-document

• Documentos principales: architecture, decisions, plan, notes, roadmap

• Documentos extendidos: kpi, okr, strategy, risk, issue, epic, story, feature, milestone, release, dependency, objective, initiative, metric, capability, assumption, problem_statement, retrospective, action_item

Instalación

Clona el repositorio en una subcarpeta sqlite-mcp de tu proyecto y luego ejecuta el instalador una vez. El script detecta su ubicación, coloca todos los archivos de tiempo de ejecución dentro de Project Memory/ y escribe .vscode/mcp.json.

No se requiere instalación de Python. El instalador descarga uv y lo utiliza para obtener un intérprete CPython 3.12.9 fijado automáticamente. El intérprete se almacena en caché en Project Memory/.uv/python/ y el entorno virtual se crea en Project Memory/.venv. Si la descarga de uv falla (por ejemplo, detrás de un firewall), el instalador recurre a cualquier Python 3.11+ que ya esté en la máquina.

Importante: abre VS Code en la raíz de tu proyecto (la carpeta principal), no en la subcarpeta sqlite-mcp. La configuración de MCP se escribe en la raíz del proyecto en .vscode/mcp.json.

Windows (PowerShell)

# from your project root
git clone https://github.com/WebRTCGame/SQLITE-MCP.git sqlite-mcp
.\sqlite-mcp\install.ps1

Bandera opcional:

• -LogFile install.log — guarda una transcripción completa para depuración

• -AppendInstructions — añade el fragmento al archivo de instrucciones sugerido (idempotente)

Linux / macOS

# from your project root
git clone https://github.com/WebRTCGame/SQLITE-MCP.git sqlite-mcp
chmod +x ./sqlite-mcp/install.sh
./sqlite-mcp/install.sh

Bandera opcional:

• --log-file install.log — guarda una transcripción completa para depuración

• --append-instructions — añade el fragmento al archivo de instrucciones sugerido (idempotente)

Para actualizar: después de una instalación anidada exitosa, los scripts residen bajo Project Memory/ porque el checkout de sqlite-mcp se mueve allí. Vuelve a ejecutar el instalador desde la raíz de tu proyecto con Project Memory\install.ps1 (Windows) o Project Memory/install.sh (Linux/macOS). Para instalaciones in-place/de desarrollador, vuelve a ejecutar el mismo comando.

Solo pip (desarrollador / avanzado)

Se utiliza cuando deseas gestionar el entorno tú mismo (requiere Python 3.11+):

python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\Activate.ps1 on Windows
pip install -e .

O con uv directamente (no se necesita Python del sistema — uv descarga Python automáticamente):

uv venv --python 3.12.9 .venv
uv pip install -e .

Ejemplo completo:

./sqlite-mcp/install.sh

Iniciar servidor

& ".\Project Memory\.venv\Scripts\python.exe" -m sqlite_mcp_server

Rutas

• Project Memory/.venv — entorno virtual (Python 3.12.9 fijado)

• Project Memory/.uv/bin/uv[.exe] — gestor de tiempo de ejecución uv (descargado por el instalador)

• Project Memory/.uv/python/ — intérprete CPython fijado (obtenido por uv en la primera ejecución)

• Project Memory/pm_data/project_memory.db

• Project Memory/pm_exports

• .vscode/mcp.json

• .vscode/settings.json también puede ser creado automáticamente por Copilot/VS Code con entradas chat.mcp.serverSampling para sqlite-project-memory; esto es esperado.

Para anular la versión de Python fijada:

$env:SQLITE_MCP_PYTHON_VERSION = "3.13.0"; .\sqlite-mcp\install.ps1

SQLITE_MCP_PYTHON_VERSION=3.13.0 ./sqlite-mcp/install.sh

Herramientas CLI

sqlite-project-memory-admin bootstrap-self --repo-root .
sqlite-project-memory-admin project-state
sqlite-project-memory-admin health
sqlite-project-memory-admin sync-document architecture --input-path architecture.md
sqlite-project-memory-admin sync-document decisions --input-path decisions.md
sqlite-project-memory-admin sync-document roadmap --input-path roadmap.md
sqlite-project-memory-admin export-views --user-requested --request-reason "User asked for a roadmap export" --require-existing-dir exports todo roadmap architecture
sqlite-project-memory-admin export-views --user-requested --request-reason "User asked for refreshed generated docs" --force todo roadmap architecture
sqlite-project-memory-admin export-json --output-path exports/project_memory.snapshot.json
sqlite-project-memory-admin import-json --input-path exports/project_memory.snapshot.json

Configuración

Variables de entorno:

• SQLITE_MCP_PROJECT_ROOT

• SQLITE_MCP_DB_PATH

• SQLITE_MCP_EXPORT_DIR

• SQLITE_MCP_TRANSPORT (stdio o streamable-http)

• SQLITE_MCP_LOG_LEVEL (INFO por defecto)

• SQLITE_MCP_LOG_FORMAT (json o text)

Hook post-instalación

• Crea .scripts/post_install.ps1 (PowerShell) o .scripts/post_install.sh.

• El script de instalación ejecuta el hook si está presente.

Inicio rápido (Windows)

1. Clona el repositorio en tu proyecto.

2. Ejecuta el instalador:

   git clone https://github.com/WebRTCGame/SQLITE-MCP.git sqlite-mcp
   .\sqlite-mcp\install.ps1

   Después de la instalación, asegúrate de que VS Code esté abierto en la raíz del proyecto principal (por ejemplo C:\CODE\TestProject), no en C:\CODE\TestProject\sqlite-mcp.

3. Activa el venv de tiempo de ejecución:

   & ".\Project Memory\.venv\Scripts\Activate.ps1"

4. Ejecuta la autocomprobación:

   sqlite-project-memory-admin --db-path "Project Memory/pm_data/project_memory.db" project-state
   sqlite-project-memory-admin --db-path "Project Memory/pm_data/project_memory.db" health

5. Inicia el servidor:

   python -m sqlite_mcp_server

Inicio rápido (Linux/macOS)

1. Clona el repositorio en tu proyecto.

2. Ejecuta el instalador:

   git clone https://github.com/WebRTCGame/SQLITE-MCP.git sqlite-mcp
   chmod +x ./sqlite-mcp/install.sh
   ./sqlite-mcp/install.sh

   Después de la instalación, asegúrate de que VS Code esté abierto en la raíz del proyecto principal, no en la subcarpeta sqlite-mcp.

3. Activa el venv de tiempo de ejecución:

   source "Project Memory/.venv/bin/activate"

4. Ejecuta la autocomprobación:

   sqlite-project-memory-admin --db-path "Project Memory/pm_data/project_memory.db" project-state
   sqlite-project-memory-admin --db-path "Project Memory/pm_data/project_memory.db" health

5. Inicia el servidor:

   python -m sqlite_mcp_server

Notas

• render_markdown_views/export_markdown_views requieren user_requested=true y request_reason.

• sync-document está anclado (no hay registros de texto libre no estructurado en el estado del roadmap).

• project_state y health son diagnósticos primarios.

Diseño centrado en IA

• Escribe entidades/contenido a través de herramientas MCP.

• Genera documentos solo bajo solicitud explícita del usuario.

Añade instrucciones de IA a tu proyecto

Después de ejecutar el instalador, pega el fragmento a continuación en tu archivo de instrucciones de IA (copilot-instructions.md, AGENTS.md, CLAUDE.md o equivalente). El instalador también imprime este fragmento en la terminal como recordatorio.

## SQLite Project Memory

This project uses the **`sqlite-project-memory` MCP server** as the single source of truth for all project state.

### Mandatory rules

- **NEVER** create, modify, or delete `.md` files for notes, tasks, decisions, roadmaps, or architecture.
- **ALWAYS** use `sqlite-project-memory` MCP tools to store and retrieve project knowledge.
- `README.md` is the **only** markdown file you may edit directly.
- Files in `Project Memory/pm_exports/` are read-only derived artifacts — never edit them directly.

### Tool usage guide

| Intent | Tool to use |
|--------|-------------|
| Add a task / todo | `create_entity` (entity_type: `task`) |
| Record a decision | `create_entity` (entity_type: `decision`) |
| Document a component | `create_entity` (entity_type: `component`) + `write_content` |
| Add a note to an item | `write_content` or `append_content` |
| Query project state | `query_view`, `list_entities`, `get_entity` |
| Search knowledge | `search_content` |
| Link two items | `add_relationship` or `connect_entities` |
| Export to markdown | `export_markdown_views` with `user_requested: true` — only when explicitly asked |

### First action each session

Before making changes, call `get_project_context` to confirm the database path and project root, then call `get_recent_activity` or `query_view` to orient yourself.

Lista de verificación de puertas de uso

Para obtener la mejor fiabilidad, confirma todo lo siguiente:

1. .vscode/mcp.json contiene el servidor sqlite-project-memory.

2. Se aceptó el aviso de aprobación/confianza de MCP de VS Code para este espacio de trabajo.

3. El chat está en modo Agente (no en modo chat/edición normal).

4. El agente Project Memory está disponible en el menú desplegable de agentes.

5. La habilidad /sqlite-project-memory está disponible en los comandos de barra diagonal.

6. Tu archivo de instrucciones del proyecto incluye el fragmento de Memoria de Proyecto SQLite.

7. Inicia cada sesión con get_project_context y luego get_recent_activity o query_view.

El instalador imprime un Usage Gates Report con PASS o ACTION REQUIRED para las puertas que puede validar automáticamente. Si las herramientas aún no aparecen, primero recarga o reinicia completamente VS Code e inicia una nueva sesión de chat de Agente. Si el servidor no se está ejecutando después del reinicio, ejecuta MCP: Start Server desde la Paleta de Comandos, selecciona sqlite-project-memory y reinicia la sesión de chat.