SQLite Project Memory MCP

プロジェクトのメモリをグラフフレンドリーなリレーショナルコアとして保存するためのSQLiteベースのMCPサーバー。

このプロジェクトの目的

• SQLiteに信頼できる唯一の情報源（Single Source of Truth）として状態を保持します。

• グラフセマンティクス（entities、relationships、content、tags）を提供します。

• 構造化された読み取り（query_view）と、明示的に生成されたMarkdownビューをサポートします。

• AIエージェントにとって安全なワークフローを想定して設計されています。

コアモデル

• entities

• attributes

• relationships

• content

• tags

• events、snapshots、snapshot_entities（監査/履歴）

サポートされている sync-document ターゲット

• コアドキュメント: architecture、decisions、plan、notes、roadmap

• 拡張ドキュメント: kpi、okr、strategy、risk、issue、epic、story、feature、milestone、release、dependency、objective、initiative、metric、capability、assumption、problem_statement、retrospective、action_item

インストール

リポジトリをプロジェクトの sqlite-mcp サブフォルダーにクローンし、インストーラーを一度実行します。 スクリプトは自身の場所を検出し、すべてのランタイムファイルを Project Memory/ 内に配置し、.vscode/mcp.json を書き込みます。

Pythonのインストールは不要です。 インストーラーは uv をダウンロードし、それを使用して固定されたCPython 3.12.9インタープリターを自動的に取得します。インタープリターは Project Memory/.uv/python/ にキャッシュされ、仮想環境は Project Memory/.venv に作成されます。 uv のダウンロードが失敗した場合（ファイアウォールの背後など）、インストーラーはマシン上に既に存在するPython 3.11+にフォールバックします。

重要: VS Codeは sqlite-mcp サブフォルダーではなく、プロジェクトのルート（親フォルダー）で開いてください。 MCP設定はプロジェクトルートの .vscode/mcp.json に書き込まれます。

Windows (PowerShell)

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

オプションフラグ:

• -LogFile install.log — デバッグ用に完全なトランスクリプトを保存します

• -AppendInstructions — 推奨される指示ファイルにスニペットを追記します（冪等）

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

オプションフラグ:

• --log-file install.log — デバッグ用に完全なトランスクリプトを保存します

• --append-instructions — 推奨される指示ファイルにスニペットを追記します（冪等）

更新方法: ネストされたインストールが成功した後、スクリプトは Project Memory/ 配下に存在します（sqlite-mcp のチェックアウトがそこに移動されるため）。プロジェクトルートから Project Memory\install.ps1 (Windows) または Project Memory/install.sh (Linux/macOS) を使用してインストーラーを再実行してください。インプレース/開発者インストールの場合も、同じコマンドを再実行します。

pipのみ（開発者/上級者向け）

環境を自分で管理したい場合に使用します（Python 3.11+が必要）:

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

または uv を直接使用する場合（システムPythonは不要 — uv が自動的にPythonをダウンロードします）:

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

完全な例:

./sqlite-mcp/install.sh

サーバーの起動

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

パス

• Project Memory/.venv — 仮想環境（固定されたPython 3.12.9）

• Project Memory/.uv/bin/uv[.exe] — uv ランタイムマネージャー（インストーラーによってダウンロード）

• Project Memory/.uv/python/ — 固定されたCPythonインタープリター（初回実行時に uv が取得）

• Project Memory/pm_data/project_memory.db

• Project Memory/pm_exports

• .vscode/mcp.json

• .vscode/settings.json は、Copilot/VS Codeによって sqlite-project-memory 用の chat.mcp.serverSampling エントリと共に自動的に作成される場合があります。これは想定通りの動作です。

固定されたPythonバージョンを上書きするには:

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

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

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

設定

環境変数:

• SQLITE_MCP_PROJECT_ROOT

• SQLITE_MCP_DB_PATH

• SQLITE_MCP_EXPORT_DIR

• SQLITE_MCP_TRANSPORT (stdio または streamable-http)

• SQLITE_MCP_LOG_LEVEL (デフォルトは INFO)

• SQLITE_MCP_LOG_FORMAT (json または text)

インストール後のフック

• .scripts/post_install.ps1 (PowerShell) または .scripts/post_install.sh を作成します。

• インストールスクリプトは、フックが存在する場合にそれを実行します。

クイックスタート (Windows)

1. リポジトリをプロジェクトにクローンします。

2. インストーラーを実行します:

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

   インストール後、VS Codeが C:\CODE\TestProject\sqlite-mcp ではなく、親プロジェクトルート（例: C:\CODE\TestProject）で開かれていることを確認してください。

3. ランタイムvenvをアクティブ化します:

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

4. 自己診断を実行します:

   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. サーバーを起動します:

   python -m sqlite_mcp_server

クイックスタート (Linux/macOS)

1. リポジトリをプロジェクトにクローンします。

2. インストーラーを実行します:

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

   インストール後、VS Codeが sqlite-mcp サブフォルダーではなく、親プロジェクトルートで開かれていることを確認してください。

3. ランタイムvenvをアクティブ化します:

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

4. 自己診断を実行します:

   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. サーバーを起動します:

   python -m sqlite_mcp_server

注意事項

• render_markdown_views/export_markdown_views には user_requested=true と request_reason が必要です。

• sync-document はアンカーされています（ロードマップの状態に非構造化のフリーテキストレコードはありません）。

• project_state と health が主要な診断情報です。

AIファースト設計

• エンティティ/コンテンツはMCPツールを通じて書き込みます。

• ドキュメントはユーザーの明示的な要求があった場合にのみ生成します。

プロジェクトへのAI指示の追加

インストーラーを実行した後、以下のスニペットをAI指示ファイル（copilot-instructions.md、AGENTS.md、CLAUDE.md など）に貼り付けてください。 インストーラーは、リマインダーとしてこのスニペットをターミナルにも出力します。

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

使用ゲートチェックリスト

信頼性を最大限に高めるため、以下をすべて確認してください:

1. .vscode/mcp.json に sqlite-project-memory サーバーが含まれていること。

2. このワークスペースに対してVS CodeのMCP承認/信頼プロンプトが許可されていること。

3. チャットがエージェントモードになっていること（通常のチャット/編集モードではない）。

4. エージェントのドロップダウンで Project Memory エージェントが利用可能であること。

5. スラッシュコマンドで /sqlite-project-memory スキルが利用可能であること。

6. プロジェクトの指示ファイルにSQLite Project Memoryのスニペットが含まれていること。

7. 各セッションの開始時に get_project_context を実行し、次に get_recent_activity または query_view を実行すること。

インストーラーは、自動的に検証可能なゲートについて PASS または ACTION REQUIRED を含む Usage Gates Report を出力します。 ツールが表示されない場合は、まずVS Codeを完全にリロードまたは再起動し、新しいエージェントチャットセッションを開始してください。 再起動後にサーバーが実行されていない場合は、コマンドパレットから MCP: Start Server を実行し、sqlite-project-memory を選択して、チャットセッションを再起動してください。