memory-mcp-lite

memory-mcp-lite

一款小巧、观点鲜明的 AI 编码助手记忆服务（适用于 Windsurf、Cursor、Claude Desktop 等任何支持 MCP 的工具）。

它在本地运行，将持久知识存储在你的磁盘上，并会尽可能避免打扰你的 Agent，直到你真正需要它。

为什么要做这个项目

大多数 AI 客户端都已经具备某种短期记忆功能。它们会记住当前对话，也许还会记住你设置的几条规则，仅此而已。它们无法提供一个地方来存放那些应该跨会话保留的内容——比如你上周做出的架构决策、这个代码库里那个特别的构建命令，或是连续三次坑到你的注意事项。

memory-mcp-lite 就是这样一个地方。它可以存储：

• 技术决策及其背后的理由，
• 项目架构和约定，
• 命令、环境说明、链接和注意事项，
• 任务状态，方便你稍后继续工作，
• 全局／项目／任务级别的汇总摘要。

它有意不存储原始聊天记录，不取代客户端内置规则，不运行嵌入或向量搜索，也不需要服务器或云连接。

组织方式

记忆以树形结构存储：

global
└── project
    ├── [project_summary]
    └── task
        ├── [task_summary]
        └── atomic  // decision | fact | gotcha | command | link | convention

你还可以在树形结构之上，为任意两个节点绘制可选的轻量级图关系边——related_to、depends_on、affects、caused_by、supersedes、references。当某个决策使另一个决策过时，或某条注意事项只在特定命令的上下文中适用时，这就很有用。

检索部分的设计力求低成本。服务的指令会引导 Agent 分三个阶段进行检索，从成本最低到最高：

Stage 1 — summaries              get_global_summary / get_project_summary / get_task_summary
        │
        ▼ (only if summaries aren't enough)
Stage 2 — FTS5 light search      search_memory_light → compact candidates
        │
        ▼ (only for the 1–3 most relevant hits)
Stage 3 — full detail            get_memory_detail

实际使用中，这意味着你的 Agent 会先请求摘要，只有在有明确理由时才获取较大的数据内容。跳过这项策略，只会让你无端将一堆采用字符串类型的 JSON 倒进上下文。

技术栈

• TypeScript、Node ≥ 20
• 基于 libSQL（@libsql/client）的 Drizzle ORM
• 用于词法搜索的 SQLite FTS5
• 用于高效遍历子树的闭包表
• MCP TypeScript SDK（@modelcontextprotocol/sdk）

你可以将它指向本地文件、远程 libSQL 实例或 Turso 数据库——它们的工作方式都一样。

安装

最快的方法是让你的 MCP 客户端通过 npx 获取此软件包。

Windsurf — ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "npx",
      "args": ["memory-mcp-lite"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "npx",
      "args": ["memory-mcp-lite"]
    }
  }
}

其他任何兼容 MCP 的客户端也使用相同的配置方式；只需更改配置文件路径。

从源码安装

npm install
npm run build    # outputs dist/index.js; the schema is created on first run

然后将客户端指向编译后的包：

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "node",
      "args": ["/absolute/path/to/memory-mcp-lite/dist/index.js"]
    }
  }
}

如果你想不经构建步骤直接修改代码，可以使用 tsx：

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/memory-mcp-lite/apps/server/src/index.ts"]
    }
  }
}

数据存储位置

默认位置：~/.memory-mcp/memory.db。可通过以下任一方式覆盖：

环境变量	用途
MEMORY_DB_PATH	完整路径或 libsql://… / file: URL。
MEMORY_DATA_DIR	目录；文件名仍为 memory.db。
DATABASE_URL	为向后兼容而接受。
MEMORY_DB_AUTH_TOKEN	用于远程 libSQL / Turso 的 Bearer 令牌。

因此，使用 Turso 只需：

MEMORY_DB_PATH="libsql://your-db.turso.io" \
MEMORY_DB_AUTH_TOKEN="eyJhbGci..." \
npm run dev

工具

所有 9 个工具都会同时返回人类可读的 JSON 块和供程序化客户端使用的 structuredContent 对象。服务器还会为每个工具提供严格的 description 和 annotations 负载，让 Agent 无需猜测就能选对工具。

工具	适用场景……
get_global_summary	常见偏好、跨项目约定
get_project_summary	架构、关键决策、长期项目背景
get_task_summary	恢复某项具体工作
search_memory_light	摘要不够用；需要精简的候选结果
get_memory_detail	已选定候选项，需要查看完整内容
remember_decision	架构选择、权衡或被否决的方案
remember_fact	命令、环境说明、注意事项、链接或约定
upsert_project_summary	架构变更或新增值得记录的约定之后
upsert_task_summary	取得进展、遇到阻碍或计划变更之后

服务器要求 Agent 遵循以下检索原则：

1. 先查摘要，
2. 只有在摘要不够时才进行轻量搜索，
3. 对最多 1–3 条命中结果查看完整详情，
4. 绝不要因为能查看所有记忆，就把它们全部列出。

项目身份

项目按以下优先级查找：

1. 规范化的 Git 远程 URL — 最稳定；目录移动和克隆后仍然有效。
2. Git 根路径 — 没有远程地址时使用。
3. 规范化的工作区路径 — 兜底选项。

这意味着，即使不同客户端提供的路径略有差异，同一个项目也会保留相同的记忆；迁移代码库也不会导致已存储的内容失去关联。

开发

npm run typecheck      # TypeScript
npm run lint           # oxlint
npm run test           # vitest
npm run build          # esbuild bundle to dist/
npm run dev            # tsx watch
npm run db:studio      # Drizzle Studio for poking at the DB
npm run db:generate    # generate migration SQL when the schema changes

架构定义在 apps/server/src/db/schema.ts 中，并会在每次启动时由 ensureSchema() 再次应用（参见 apps/server/src/db/migrate.ts）。该函数还会创建 FTS5 虚拟表及其触发器 — Drizzle 不管理虚拟表，因此我们使用普通 SQL 手动创建。此操作具有幂等性，因此无需手动运行任何内容。

路线图

• 可选的语义回退（本地嵌入，受功能标志控制）。
• 面向长期项目的节点归档 / 清理。
• 等有了完善的身份验证方案后，提供团队共享记忆。