SQLite Project Memory MCP

SQLite-basierter MCP-Server zum Speichern von Projektgedächtnis als graph-freundlicher relationaler Kern.

Warum dieses Projekt

• Hält den maßgeblichen Zustand in SQLite (Single Source of Truth).

• Bietet Graph-Semantik (entities, relationships, content, tags).

• Unterstützt strukturierte Lesevorgänge (query_view) und explizit generierte Markdown-Ansichten.

• Entwickelt für KI-Agenten-sichere Workflows.

Kernmodell

• entities

• attributes

• relationships

• content

• tags

• events, snapshots, snapshot_entities (Audit/Historie)

Unterstützte sync-document-Ziele

• Kerndokumente: architecture, decisions, plan, notes, roadmap

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

Installation

Klonen Sie das Repo in einen sqlite-mcp-Unterordner Ihres Projekts und führen Sie dann einmalig das Installationsprogramm aus. Das Skript erkennt seinen Speicherort, platziert alle Laufzeitdateien in Project Memory/ und schreibt .vscode/mcp.json.

Keine Python-Installation erforderlich. Das Installationsprogramm lädt uv herunter und verwendet es, um automatisch einen fixierten CPython 3.12.9-Interpreter abzurufen. Der Interpreter wird in Project Memory/.uv/python/ zwischengespeichert und die virtuelle Umgebung wird in Project Memory/.venv erstellt. Wenn der uv-Download fehlschlägt (z. B. hinter einer Firewall), greift das Installationsprogramm auf ein bereits auf dem Computer vorhandenes Python 3.11+ zurück.

Wichtig: Öffnen Sie VS Code in Ihrem Projektstammverzeichnis (dem übergeordneten Ordner), nicht im sqlite-mcp-Unterordner. Die MCP-Konfiguration wird in das Projektstammverzeichnis unter .vscode/mcp.json geschrieben.

Windows (PowerShell)

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

Optionale Flags:

• -LogFile install.log — speichert ein vollständiges Transkript für das Debugging

• -AppendInstructions — hängt den Schnipsel an die vorgeschlagene Anweisungsdatei an (idempotent)

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

Optionale Flags:

• --log-file install.log — speichert ein vollständiges Transkript für das Debugging

• --append-instructions — hängt den Schnipsel an die vorgeschlagene Anweisungsdatei an (idempotent)

Zum Aktualisieren: Nach einer erfolgreichen verschachtelten Installation befinden sich die Skripte unter Project Memory/, da der sqlite-mcp-Checkout dorthin verschoben wurde. Führen Sie das Installationsprogramm erneut von Ihrem Projektstammverzeichnis aus mit Project Memory\install.ps1 (Windows) oder Project Memory/install.sh (Linux/macOS). Für In-Place-/Entwicklerinstallationen führen Sie denselben Befehl erneut aus.

Nur pip (Entwickler / Fortgeschrittene)

Wird verwendet, wenn Sie die Umgebung selbst verwalten möchten (erfordert Python 3.11+):

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

Oder direkt mit uv (kein System-Python erforderlich — uv lädt Python automatisch herunter):

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

Vollständiges Beispiel:

./sqlite-mcp/install.sh

Server starten

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

Pfade

• Project Memory/.venv — virtuelle Umgebung (fixiertes Python 3.12.9)

• Project Memory/.uv/bin/uv[.exe] — uv-Laufzeitmanager (vom Installationsprogramm heruntergeladen)

• Project Memory/.uv/python/ — fixierter CPython-Interpreter (wird beim ersten Ausführen von uv abgerufen)

• Project Memory/pm_data/project_memory.db

• Project Memory/pm_exports

• .vscode/mcp.json

• .vscode/settings.json kann ebenfalls automatisch von Copilot/VS Code mit chat.mcp.serverSampling-Einträgen für sqlite-project-memory erstellt werden; dies ist zu erwarten.

Um die fixierte Python-Version zu überschreiben:

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

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

CLI-Tools

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

Konfiguration

Umgebungsvariablen:

• SQLITE_MCP_PROJECT_ROOT

• SQLITE_MCP_DB_PATH

• SQLITE_MCP_EXPORT_DIR

• SQLITE_MCP_TRANSPORT (stdio oder streamable-http)

• SQLITE_MCP_LOG_LEVEL (INFO Standard)

• SQLITE_MCP_LOG_FORMAT (json oder text)

Post-Install-Hook

• Erstellen Sie .scripts/post_install.ps1 (PowerShell) oder .scripts/post_install.sh.

• Das Installationsskript führt den Hook aus, falls vorhanden.

Schnellstart (Windows)

1. Klonen Sie das Repo in Ihr Projekt.

2. Führen Sie das Installationsprogramm aus:

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

   Stellen Sie nach der Installation sicher, dass VS Code im übergeordneten Projektstammverzeichnis geöffnet ist (zum Beispiel C:\CODE\TestProject), nicht in C:\CODE\TestProject\sqlite-mcp.

3. Aktivieren Sie die Laufzeit-Venv:

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

4. Führen Sie die Selbstprüfung aus:

   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. Starten Sie den Server:

   python -m sqlite_mcp_server

Schnellstart (Linux/macOS)

1. Klonen Sie das Repo in Ihr Projekt.

2. Führen Sie das Installationsprogramm aus:

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

   Stellen Sie nach der Installation sicher, dass VS Code im übergeordneten Projektstammverzeichnis geöffnet ist, nicht im sqlite-mcp-Unterordner.

3. Aktivieren Sie die Laufzeit-Venv:

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

4. Führen Sie die Selbstprüfung aus:

   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. Starten Sie den Server:

   python -m sqlite_mcp_server

Hinweise

• render_markdown_views/export_markdown_views erfordern user_requested=true und request_reason.

• sync-document ist verankert (kein unstrukturierter Freitext-Datensatz im Roadmap-Zustand).

• project_state und health sind primäre Diagnosen.

KI-First-Design

• Schreiben Sie Entitäten/Inhalte über MCP-Tools.

• Generieren Sie Dokumente nur auf explizite Benutzeranfrage.

KI-Anweisungen zu Ihrem Projekt hinzufügen

Fügen Sie nach dem Ausführen des Installationsprogramms den unten stehenden Schnipsel in Ihre KI-Anweisungsdatei ein (copilot-instructions.md, AGENTS.md, CLAUDE.md oder gleichwertig). Das Installationsprogramm gibt diesen Schnipsel zur Erinnerung auch im Terminal aus.

## 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.

Checkliste für Nutzungsvoraussetzungen

Bestätigen Sie für beste Zuverlässigkeit Folgendes:

1. .vscode/mcp.json enthält den sqlite-project-memory-Server.

2. Die MCP-Genehmigungs-/Vertrauensaufforderung von VS Code wurde für diesen Arbeitsbereich akzeptiert.

3. Der Chat befindet sich im Agenten-Modus (nicht im normalen Chat-/Bearbeitungsmodus).

4. Der Project Memory-Agent ist im Agenten-Dropdown verfügbar.

5. Die /sqlite-project-memory-Fähigkeit ist in den Slash-Befehlen verfügbar.

6. Ihre Projektanweisungsdatei enthält den SQLite Project Memory-Schnipsel.

7. Starten Sie jede Sitzung mit get_project_context und dann get_recent_activity oder query_view.

Das Installationsprogramm gibt einen Usage Gates Report mit PASS oder ACTION REQUIRED für die Gates aus, die es automatisch validieren kann. Wenn Tools immer noch nicht erscheinen, laden Sie VS Code vollständig neu oder starten Sie es neu und beginnen Sie eine neue Agenten-Chat-Sitzung. Wenn der Server nach dem Neustart noch nicht läuft, führen Sie MCP: Start Server aus der Befehlspalette aus, wählen Sie sqlite-project-memory und starten Sie die Chat-Sitzung neu.