SQLite 项目记忆 MCP

基于 SQLite 的 MCP 服务器，用于将项目记忆存储为对图友好的关系型核心。

为什么选择本项目

• 将权威状态保存在 SQLite 中（单一事实来源）。

• 提供图语义（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

   安装后，确保在父项目根目录（例如 C:\CODE\TestProject）打开 VS Code，而不是 C:\CODE\TestProject\sqlite-mcp。

3. 激活运行时虚拟环境：

   & ".\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. 激活运行时虚拟环境：

   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 状态。 如果工具仍然没有出现，请先完全重新加载或重启 VS Code 并开始新的代理聊天会话。 如果重启后服务器没有运行，请从命令面板运行 MCP: Start Server，选择 sqlite-project-memory，然后重启聊天会话。