SQLite 프로젝트 메모리 MCP

프로젝트 메모리를 그래프 친화적인 관계형 코어로 저장하기 위한 SQLite 기반 MCP 서버입니다.

이 프로젝트의 목적

• SQLite에 권한 있는 상태를 유지합니다 (단일 정보원).

• 그래프 의미론(entities, relationships, content, tags)을 제공합니다.

• 구조화된 읽기(query_view) 및 명시적으로 생성된 마크다운 뷰를 지원합니다.

• 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+를 사용합니다.

중요: sqlite-mcp 하위 폴더가 아닌 프로젝트 루트(상위 폴더)에서 VS Code를 여십시오. 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 — 제안된 지침 파일에 스니펫 추가 (멱등성)

업데이트 방법: 성공적인 중첩 설치 후, sqlite-mcp 체크아웃이 이동되었으므로 스크립트는 Project Memory/ 아래에 위치합니다. 프로젝트 루트에서 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 프로젝트 메모리 스니펫이 포함되어 있습니다.

7. 각 세션을 get_project_context로 시작한 다음 get_recent_activity 또는 query_view를 사용하십시오.

설치 프로그램은 자동으로 검증할 수 있는 게이트에 대해 PASS 또는 ACTION REQUIRED가 포함된 Usage Gates Report를 출력합니다. 도구가 여전히 나타나지 않으면, 먼저 VS Code를 완전히 새로 고침하거나 다시 시작하고 새 에이전트 채팅 세션을 시작하십시오. 다시 시작한 후에도 서버가 실행되지 않으면 명령 팔레트에서 MCP: Start Server를 실행하고 sqlite-project-memory를 선택한 다음 채팅 세션을 다시 시작하십시오.