pi-mem · 基于第一性原理的记忆引擎

纯 markdown + BM25 + 计数器 · 零依赖 · 零网络 · 框架无关 pi 扩展 / MCP server 双适配 —— 一个记忆引擎，任何 AI 客户端可用

它是什么

一个给 AI 编程助手用的跨会话记忆系统。从第一性原理出发设计，只做五件事（写/存/读/忘/反馈），并且为每件事确立了原理级不变量：

不变量	含义
可追溯性	每条记忆必答"谁写的(via)、何时(created)"——来源可审计，错误可定位，投毒可清除
价值信号	injected（被情境提取次数）与 adopted（被确认采纳次数）分离——老化只看活动时间与采纳，不把"话题频率"当"使用价值"
更新不变式	写入自动做同主题冲突检测 → replace 旧条目并归档历史——不制造第二份真理

外加两条工程护栏：隐私过滤（强信号捕获拒收 key/密码/URL 等敏感内容）、写锁（并发会话不互相覆盖）。

特性

• 🧩 纯 Markdown：记忆就是 MEMORY.md 索引 + Lore/ 细节文件，人能读、能编辑、能 git；数据库只是加速索引
• 🚀 零依赖零网络：中文 BM25（2+3-gram）本地检索，2.5~3ms/轮，不烧 API、不外传数据
• 🔌 双适配：pi 原生扩展（自动情境注入+强信号捕获）｜标准 MCP server（任何 MCP 客户端）
• ⚖️ 克制的老化：90/120 天零活动→休眠、180 天→待归档，只报告不自动删；身份类永留
• 🔐 隐私护栏：强信号捕获自动拒绝敏感内容（sk-密钥/URL/密码/账号/临时）

架构

core.ts       引擎（框架无关）：存储/BM25 检索/注入/捕获/老化/三态 —— 谁都能 import
index.ts      pi 适配层：before_agent_start 注入钩子 + 6 工具 + /mem 命令
mcp/server.ts MCP 适配层：stdio JSON-RPC 2.0，任何 MCP 客户端接入

快速开始

作为 pi 扩展

# 复制到 pi 扩展目录（或以 pi 包安装）
git clone https://github.com/May5921/pi-mem ~/.pi/agent/extensions/pi-mem
# 或 pi install（发布后）
pi install npm:pi-mem
# 重启 pi 或 /reload —— 自动生效

每轮对话自动情境注入（BM25 命中才注入 ≤3 条）；查看更多：memory_status / /mem status。

作为 MCP server（任何客户端）

// Claude Code: claude mcp add 示例
{
  "mcpServers": {
    "pi-mem": {
      "command": "node",
      "args": ["/路径/to/pi-mem/mcp/server.ts"],
      "env": { "PI_MEM_DIR": "~/.agent-memory" }   // 可选：自定义存储目录
    }
  }
}

Cursor（.cursor/mcp.json）、Codex（.codex/config.toml）、OpenCode 等所有 MCP 客户端配置方式相同。工具：memory_write / memory_search / memory_read / memory_status / memory_forget / memory_prune。

记忆格式

# MEMORY.md（索引，一行一条）
- [项目] 考研：首选合工大、次选安大 → Lore/项目.md

# Lore/项目.md（细节）
- 目标院校：首选合肥工业大学（合工大）、次选安徽大学（安大）

元数据在 .meta.json（计数器/来源/状态），与可读文件分离。

设计哲学

一次关于"记忆系统是什么"的第一性原理分析：记忆 = 跨时间的信息投资系统（写/存/读/忘/反馈），唯一矛盾是保真 vs 减噪，三条推论（容量约束下的选择性是本质 / 价值只在提取时刻兑现 / 遗忘挂钩提取不挂钩时间）。本实现是这些推论的直接落地：

• 读 = 情境驱动注入（挂钩情境，不挂钩轮次）
• 忘 = 最后活动时间驱动（挂钩提取，不挂钩日历）
• 写 = 三态内建（追加/replace/归档是存储层不变式，不是模型礼仪）

详细拆解见 docs/DESIGN.md。

License

MIT