# 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 扩展

```bash
# 复制到 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（任何客户端）

```jsonc
// 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`。

## 记忆格式

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

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

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

## 设计哲学

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

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

详细拆解见 [docs/DESIGN.md](docs/DESIGN.md)。

## License

MIT