project-memory-ai

v0.1.7

Published

a month ago

MCP server providing project-level long-term memory for AI agents (Cursor / Claude Code)

0High
0Medium
0Low

starraiser

Project Memory AI

为 AI Agent（Cursor / Claude Code 等）提供项目级长期记忆的 MCP Server。已发布 npm：project-memory-ai（全局命令：project-memory）

它解决什么问题

每次新开对话，AI Agent 都会"失忆"——它不记得这个项目之前的技术决策、踩过的坑、解决方案。Project Memory AI 让 Agent 拥有跨会话的项目记忆：

打开项目 → Agent 自动了解项目背景（project_context）
遇到问题 → Agent 先检索历史经验（memory_search）
学到新知识 → Agent 主动保存（memory_save，存为 draft 等你确认）

知识以 SQLite 存在项目内部的 .project-memory/，完全本地、无云依赖。

核心特性

| 能力 | 说明 | |---|---| | 3 个 MCP tools | memory_search / memory_save / project_context（stdio） | | status 防污染机制 | Agent 保存 = draft（不进检索）→ 你 confirm 后才生效；archived 归档 | | git 历史总结 | git summarize：LLM 把提交历史总结为一条知识（增量：只总结新增 commit） | | LLM 接入 | OpenAI 兼容端点，已验证 DeepSeek（deepseek-chat）；缺 key 自动降级为规则化摘要 | | 轻量 Scanner | scan 识别 9 类项目清单（package.json / oh-package.json5 等）自动填充项目背景 | | draft 巡检 | memory review 汇总待确认条目，防止知识库积压 | | FTS5 检索 | 中文友好（LIKE 兜底），reindex 可修复索引 |

支持生态：Node/JS/TS、Flutter、Go、Rust、Python、Gradle/Android、Java/Maven、HarmonyOS（ArkTS/ArkUI）等。

安装

npm i -g project-memory-ai
project-memory --version   # 0.1.4+

快速开始（3 分钟）

1. 初始化项目（自动生成 Cursor MCP 配置）

cd 你的项目目录
project-memory init
# ✓ 已初始化 .project-memory/
# ✓ 已生成 Cursor MCP 配置（绑定项目绝对路径） .cursor/mcp.json

init 生成的配置会把当前项目绝对路径写进 args 和 cwd。Cursor 启动本地 MCP server 时进程工作目录不一定是项目目录，必须显式绑定，否则多个项目会串到同一个知识库（见 FAQ）。

2. 自动识别项目背景

project-memory scan
# 例：✓ 已从 oh-package.json5 识别项目并填充 config（project.tech = HarmonyOS, ArkTS, ArkUI）

未识别的字段可手动补：

project-memory config set project.name "我的项目"
project-memory config set project.tech "HarmonyOS, ArkTS"
project-memory config add project.modules 蓝牙

3. 配置 LLM（git summarize 用，可选）

export OPENAI_API_KEY=sk-xxx
export OPENAI_BASE_URL=https://api.deepseek.com   # DeepSeek，已验证；不带 /v1 亦可
export OPENAI_MODEL=deepseek-chat

key 只走环境变量，不写入项目文件。

4. 让 Cursor 用上记忆

IDE 模式（已由 init 自动生成 .cursor/mcp.json，重启 Cursor 生效）：

{ "mcpServers": { "project-memory": { "command": "project-memory", "args": ["serve", "D:/你的项目绝对路径"] } } }

init 生成的配置已自动写入项目绝对路径（args + cwd），无需手动修改。

Agent 模式（Cursor Agent 只读用户级配置，且内置 Node 与 better-sqlite3 可能 ABI 不兼容，需显式用系统 Node）：

编辑 ~/.cursor/mcp.json，加入：

"project-memory": {
  "command": "C:/Program Files/nodejs/node.exe",
  "args": [
    "C:/Users/EDY/AppData/Roaming/npm/node_modules/project-memory-ai/bin/project-memory.js",
    "serve",
    "D:/你的项目绝对路径"
  ]
}

然后完全重启 Cursor。验证：问 Agent「介绍一下这个项目」→ 应返回项目背景。

全局配置只能绑定一个项目。多项目场景请删除全局 ~/.cursor/mcp.json 里的 project-memory 条目，改用各项目 init 生成的项目级配置，避免所有项目写入同一知识库。

5. 验证全链路

在 Cursor 里让 Agent「把当前技术栈决策保存到项目记忆」→ 终端执行：

project-memory memory review      # 应看到 Agent 刚保存的 draft
project-memory memory confirm all # 确认后进入默认检索

日常使用节奏

| 时机 | 操作 | |---|---| | 项目启动 | Agent 自动调 project_context（无需操作） | | 遇到问题 | 让 Agent 查 memory_search："项目记忆里有没有相关经验" | | 学到新东西 | 让 Agent "保存到项目记忆"（存 draft） | | 每天收尾 | project-memory memory review + confirm all | | 每周 | project-memory git summarize --limit 50 + confirm all |

命令速查

| 命令 | 作用 | |---|---| | init | 初始化知识库 + 自动生成 Cursor MCP 配置（绑定项目绝对路径） | | setup | 为已有项目补/升级 .cursor/mcp.json（合并，不覆盖自定义 server；旧 ["serve"] 配置自动升级绑定项目路径） | | scan | 识别项目清单文件，填充 config 缺失字段 | | config get [key] / set / add | 查看 / 设置 / 追加项目配置 | | memory add <type> <title> <content> | 保存知识（CLI 保存直接 confirmed） | | memory list [--type] [--status] | 列出知识 | | memory review | 巡检待确认的 draft | | memory confirm <id\|all> | draft → confirmed（知识生效的关键） | | memory archive <id> / unarchive <id> | 归档 / 恢复 | | git summarize [--limit N] [--force] | LLM 总结提交历史（增量） | | reindex | 重建 FTS 索引 | | serve [dir] | 启动 MCP Server（stdio；可选 dir 指定项目目录；PROJECT_MEMORY_DIR 可覆盖知识库目录） |

工作原理

Cursor / Claude Code ──(MCP stdio)──▶ project-memory 进程
                                          │
                            ┌─────────────┼─────────────┐
                     MCP Server     Memory Store      CLI
                     (3 tools)      (SQLite+FTS5)   (init/config/...)
                                          │
                            .project-memory/
                              memory.db      # 单表 memories + FTS5 索引 + meta
                              config.json    # project.name / tech / modules

数据位置：知识库随项目走，存 <项目>/.project-memory/；备份/迁移 = 复制该目录
目录覆盖：设置 PROJECT_MEMORY_DIR 环境变量可显式指定知识库目录（优先级高于 serve [dir] 与进程 cwd）
status 机制：draft ──confirm──▶ confirmed ──archive──▶ archived；默认检索只返回 confirmed，防知识库污染
检索：SQLite FTS5（unicode61）+ LIKE 兜底（中文友好）；默认最多 5 条、内容截断 800 字

常见问题（FAQ）

Q：Cursor Agent 模式连不上 / 报未初始化？ 全局配置的 args 里 serve 后要跟项目绝对路径；重启 Cursor 生效。

Q：报 better_sqlite3.node ABI 版本错误？ Cursor 内置 Node 与系统 Node 版本不一致导致。MCP 配置里 command 用系统 Node 绝对路径（C:/Program Files/nodejs/node.exe），args[0] 用全局 bin 绝对路径。

Q：git summarize 输出"缺 OPENAI_API_KEY"？ 未配置 LLM 环境变量，已自动降级为规则化摘要（仍入库为 draft）。配置方法见上"配置 LLM"。

Q：Agent 保存的知识搜不到？ 它是 draft，需 project-memory memory confirm <id>（或 confirm all）后才会进入默认检索——这是防污染机制，不是 bug。

Q：英文关键词搜不到中文内容？ LLM 总结输出为中文后，英文词（如 crash）与中文内容（崩溃）不匹配，属预期。搜索时用中文关键词。

Q：为什么所有项目的记忆都写到了同一个目录？ Cursor 启动本地 MCP server 时进程工作目录不一定是项目目录，旧配置 args 只有 ["serve"] 时会按进程 cwd 定位知识库，导致跨项目串库。修复：升级到新版后重跑 project-memory init / setup（自动把项目绝对路径写入 args 和 cwd）；删除全局 ~/.cursor/mcp.json 里的 project-memory 条目，只保留各项目自己生成的配置；也可用 PROJECT_MEMORY_DIR 环境变量显式指定知识库目录。

项目结构

src/
├── index.ts          # CLI 入口（commander）
├── mcp/              # MCP Server（server.ts + context.ts）
├── memory/           # SQLite 存储与检索（database/store/search/review）
├── config/           # config.json 读写 + Cursor MCP 配置生成
├── git/              # git log 读取 / 规则化摘要 / 增量判定
├── llm/              # OpenAI 兼容端点总结
└── scanner/          # 轻量 Scanner（清单识别）

开发文档导航

START_HERE.md — 新会话/新开发者起点
AI_CONTEXT.md — 技术决策与开发规则
docs/architecture.md — 架构设计（v0.2）
docs/quickstart.md — 交付说明与验证
PROJECT_PLAN.md / PROJECT_STATUS.md / TASK_QUEUE.md / DEVELOPMENT_LOG.md — 计划与进度

技术栈与许可

TypeScript + Node.js ≥20 · better-sqlite3 · MCP SDK (stdio) · MIT License