SQLite Project Memory MCP

MCP-сервер на базе SQLite для хранения памяти проекта в виде реляционного ядра с поддержкой графов.

Почему этот проект

• Хранит авторитетное состояние в SQLite (единственный источник истины).

• Предоставляет семантику графов (entities, relationships, content, tags).

• Поддерживает структурированное чтение (query_view) и явную генерацию Markdown-представлений.

• Разработан для безопасных рабочих процессов с ИИ-агентами.

Основная модель

• 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 с записями chat.mcp.serverSampling для sqlite-project-memory; это ожидаемое поведение.

Чтобы переопределить фиксированную версию 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), а не C:\CODE\TestProject\sqlite-mcp.

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 являются основными диагностическими данными.

Дизайн, ориентированный на ИИ

• Записывайте сущности/контент через инструменты MCP.

• Генерируйте документы только по явному запросу пользователя.

Добавление инструкций ИИ в ваш проект

После запуска установщика вставьте приведенный ниже фрагмент в ваш файл инструкций ИИ (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. Запрос на одобрение/доверие MCP в VS Code был принят для этой рабочей области.

3. Чат находится в режиме агента (не в обычном режиме чата/редактирования).

4. Агент Project Memory доступен в выпадающем списке агентов.

5. Навык /sqlite-project-memory доступен в слэш-командах.

6. Файл инструкций вашего проекта включает фрагмент SQLite Project Memory.

7. Начинайте каждый сеанс с get_project_context, затем get_recent_activity или query_view.

Установщик выводит «Отчет о шлюзах использования» с пометкой PASS или ACTION REQUIRED для тех шлюзов, которые он может проверить автоматически. Если инструменты все еще не появились, сначала полностью перезагрузите или перезапустите VS Code и начните новый сеанс чата с агентом. Если сервер не запущен после перезапуска, выполните MCP: Start Server из палитры команд, выберите sqlite-project-memory и перезапустите сеанс чата.