内容
# 🪻 NotNessie
**项目内存，适用于 Claude Code，存储在您自己的机器上。** NotNessie 记得一个仓库的决策、约束、偏好、已验证的命令、开放问题和错误笔记，跨会话 — 所以 Claude Code 不必每次都从头开始学习您的项目。
[](https://www.npmjs.com/package/@notnessie/cli)
[](LICENSE)
[](https://nodejs.org)
[](https://grexlin85.github.io/notnessie/)
> 📚 **完整文档位于 [grexlin85.github.io/notnessie](https://grexlin85.github.io/notnessie/)。** 本 README 是概览；文档站点是参考。
---
## 问题
每次 Claude Code 会话都从头开始。您解释说该项目使用 Fastify 而不是 Express，测试运行于 `pnpm test auth`，公共 API 响应形状已冻结，生成的 Prisma 文件无人触碰。Claude 工作得很好 — 然后会话结束，所有上下文都消失了。下一个任务，您又要全部解释一遍。
CLAUDE.md 有帮助，但它是一个单独的手动维护文件。它不会自动增长，不会排名与任务相关的信息，也不知道您上周二验证了哪个命令。
**NotNessie 是缺失的一层。** 它捕获 Claude Code 工作中的持久事实 — 决策、规则、偏好、实际有效的命令、未解决的问题 — 并在您下次就座时将其作为一个紧凑的、任务感知的上下文包返回。内存存储在 *您的* Postgres 中。无需账户，无需云，无需数据离开您的机器。
## 它如何与 Claude Code 集成
NotNessie 集成三种方式，`notnessie init` 配置所有这些：
1. **MCP 服务器** （`.mcp.json`）公开九种内存工具，Claude 可以在任务中调用 — 获取上下文、搜索内存、保存决策等。
2. **五种生命周期钩子** （`.claude/settings.json`）。SessionStart 注入上下文包作为会话打开。UserPromptSubmit 和 PostToolUse 静默捕获相关上下文和已验证的命令。Stop 和 PreCompact 在内存丢失之前将会话总结回内存。
3. **CLAUDE.md 指令块 + Claude Code 技能** 教 Claude **何时** 调用这些工具 — 在非琐碎工作之前拉取上下文，在工作期间保存更正和规则。
## 功能
- 🧠 **结构化、类型内存** — 决策、约束、偏好、已验证的命令、任务总结、错误笔记、开放问题。不是一个大块；每种类型都按其自身条件检索和排名。
- 🔍 **混合本地优先搜索** — Postgres 全文搜索 *和* pgvector 语义搜索，在 JS 中按时间、置信度、内存类型、固定状态和与您提到的文件重叠进行重新排序。嵌入通过 Transformers.js（`Xenova/all-MiniLM-L6-v2`，384-dim）本地运行 — 无 API 调用。关闭或不可用时，干净地降级为仅关键字。
- 🪝 **通过钩子自动捕获** — 好的内容被保存，无需您记住询问，由 Claude Agent SDK 总结，并在 SDK 无法访问时使用启发式回退。
- 🛡️ **机密清洗** — 私钥、凭证连接字符串和 `.env` 转储被直接拒绝；JWT、API 密钥和承载令牌在进入数据库之前被内联屏蔽。永远不会存储完整的转录和原始终端输出。
- 📋 **本地仪表板** 用于审查、编辑、固定和删除 AI 捕获的内容 — 因为自动捕获的内存永远不完美，而人类应该有最终决定权。
- 💻 **本地优先，单仓库** — 每个仓库都有自己的内存空间，以其路径为键。您的数据，您的 Postgres，离线友好。
## 快速开始
**先决条件：** Node >= 20 和 Docker（或您自己的 pgvector-enabled Postgres）。
```bash
# 1. 安装 CLI
npm i -g @notnessie/cli
# 2. 启动 NotNessie's 数据库 — 自带 Compose 文件，自动选择空闲端口
notnessie pgup
# 3. 在您希望 Claude 记住的仓库中：
notnessie init # 编写 .mcp.json、CLAUDE.md 块、技能、钩子和配置
notnessie status # 健康检查：数据库、模式、嵌入、Claude Code 连接
```
然后在仓库中打开 Claude Code。MCP 工具从 `.mcp.json` 加载，钩子从 `.claude/settings.json` 加载，Claude 会话开始时注入上下文包。在非琐碎工作之前，它会拉取上下文；在之后，它会保存值得保留的内容。
已经有一个 pgvector Postgres？跳过 `notnessie pgup` 并使用 `DATABASE_URL` 将 NotNessie 指向它：
```bash
export DATABASE_URL=postgres://user:pass@host:5432/dbname
```
### 在没有 Claude Code 的情况下试用
NotNessie 可以完全从终端使用，这是体验它的最快方式：
```bash
notnessie seed # 加载一个连贯的演示数据集（一个身份验证模块）
notnessie context "add refresh token rotation to auth" # 查看 Claude 接收的上下文包
notnessie search "refresh token" --types decision,constraint
notnessie dev # 在 http://localhost:4319 打开仪表板
```
## MCP 工具
MCP 服务器公开九种工具（默认为 stdio，具有 Streamable HTTP 传输，端口为 `4320`）：
| 工具 | 目的 |
| --- | --- |
| `notnessie_get_project_context` | 当前仓库的紧凑、任务感知的上下文包 |
| `notnessie_search_memory` | 跨存储内存的混合关键字 + 语义搜索 |
| `notnessie_save_decision` | 记录架构或实现决策 |
| `notnessie_save_preference` | 记录编码偏好 |
| `notnessie_save_constraint` | 记录具有严重性的硬规则 |
| `notnessie_save_verified_command` | 记录在此仓库中确认有效的命令 |
| `notnessie_save_task_summary` | 记录任务后总结（更改的文件、运行的命令、TODO） |
| `notnessie_get_open_questions` | 列出值得提出的未解决的问题 |
| `notnessie_get_verified_commands` | 列出以前在此处验证的命令 |
## 内存流动
```
SessionStart 钩子 在会话期间 Stop / PreCompact 钩子
┌────────────────────┐ ┌────────────────────────┐ ┌──────────────────────────┐
│ 上下文包被注入 │ ──▶ │ Claude 拉取上下文， │ ──▶ │ 会话被总结回内存 │
│ 会话开始时 │ │ 您纠正和决策，保存 │ │ 内存丢失前 │
└────────────────────┘ └────────────────────────┘ └──────────────────────────┘
▲ │
└──────────────────────────────────────────────────────────────────┘
下一个会话开始时，不再冷启动
```
简而言之：上下文在开始时进入，会话期间通过 MCP 工具和静默观察的钩子保存有用的事实，会话结束时总结并输出。每次会话都让仓库比找到它时更智能。
## CLI
`notnessie` 命令涵盖整个循环：
```
notnessie init [path] 为 Claude Code 集成和配置做好准备
notnessie status [path] 数据库、模式、嵌入、连接的健康状况
notnessie pgup 启动捆绑的 Postgres（自动选择空闲端口）
notnessie pgdown [--volume] 停止数据库（--volume 也会删除所有内存）
notnessie mcp [--http] [-p <port>] 启动 MCP 服务器（默认为 stdio；4320 端口的 HTTP）
notnessie dev [-p <port>] 启动仪表板（默认端口 4319）
notnessie search <query> 搜索内存（--types, --limit, --json）
notnessie context [task] 构建上下文包（Markdown 或 --json）
notnessie seed 加载演示内存数据集
notnessie memory list|show|delete|restore|pin|unpin
notnessie hook <event> 运行生命周期钩子（Claude Code 调用这些，不是您）
```
## 配置
NotNessie 从环境（和本地 `.env`）读取 `DATABASE_URL` 和嵌入设置。关键变量：
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `DATABASE_URL` | `postgres://notnessie:notnessie@localhost:5432/notnessie` | 每个包使用的 Postgres 连接 |
| `NOTNESSIE_EMBEDDINGS` | `1` | 设置为 `0` 以禁用本地嵌入（仅关键字搜索） |
| `NOTNESSIE_EMBEDDING_MODEL` | `Xenova/all-MiniLM-L6-v2` | 用于语义搜索的 Transformers.js 模型 |
| `NOTNESSIE_DASHBOARD_PORT` | `4319` | `notnessie dev` 的端口 |
每个仓库的行为存储在 `.notnessie/config.json` 中（由 `init` 编写）：
```json
{
"projectName": "my-project",
"projectId": "proj_…",
"memoryMode": "conservative",
"autoSaveTaskSummaries": true,
"autoSaveCommands": true,
"autoSaveFileChanges": false,
"redactSecrets": true
}
```
参见 [.env.example](.env.example) 以获取完整设置，并参见 [文档站点](https://grexlin85.github.io/notnessie/) 以获取完整参考。
## 底层
pnpm + TypeScript monorepo（ESM，Node >= 20），使用 tsup 构建，使用 Vitest 测试，使用 Biome 校验：
- **`@notnessie/core`** — 类型、Postgres 存储、清洗、嵌入、混合搜索、上下文包、总结器。
- **`@notnessie/mcp`** — MCP 服务器和九种工具，通过 stdio 和 Streamable HTTP。
- **`@notnessie/cli`** — `notnessie` 命令（这是您安装的包）。
- **`@notnessie/dashboard`** — Next.js 审查 UI，通过 `notnessie dev` 启动。
- **`examples/demo-repo`** — 预 wiring 的后端，用于展示整个流程。
存储是 PostgreSQL + pgvector，由附带的 `docker-compose.yml` 配置。默认：Postgres 在 `localhost:5432`，仪表板在 `4319`，MCP HTTP 在 `4320`。
## 从源码 / 贡献
克隆仓库，然后：
```bash
pnpm install
pnpm build # 构建 @notnessie/core, @notnessie/mcp, @notnessie/cli
pnpm test # 单元测试（无需数据库）
node packages/cli/dist/index.js pgup # 在空闲端口启动 Postgres（pgvector）
node packages/cli/dist/index.js status
```
> 💡 语义搜索需要 `onnxruntime-node` 的原生二进制文件，其安装由 pnpm 延迟，直到您运行 `pnpm approve-builds`。在此之前（或离线，或设置 `NOTNESSIE_EMBEDDINGS=0`），检索仅限关键字 — 并且稍后打开构建会激活语义排名，无需更改代码。
在 [github.com/GreXLin85/notnessie](https://github.com/GreXLin85/notnessie) 上欢迎提出问题和 PR。
## 致敬 Nessie
名字是对 **[Nessie](https://nessielabs.com/)** （由 Nessie Labs 提供）的亲切致敬 — *"让你的思考对你使用的每个 AI 都可理解。"* Nessie 吸收并同步你的 AI 会话历史，跨越 ChatGPT、Claude、Gemini、Claude Code、Codex 等，构建可重用的上下文，并通过 MCP 服务器公开，以便你的代理可以查询你的历史记录。它是云同步的、面向团队的，并具有权限控制 — 一个更广泛的理念的真正延伸。
NotNessie 是一个更狭隘的、以本地为主的版本：一个项目的内存，在您自己的本地 Postgres 中，限定在一个仓库中。它是一个独立的、开源的实验，与 Nessie 或 Nessie Labs **没有任何关联、认可或联系**。这个名字只是一个友好的致敬。如果您想要完整、跨工具、面向团队的 "让您的上下文对 AI 可理解" 版本，请查看真正的产品。 🦕
## 振动编码，人类审查
诚实披露：NotNessie 是 **振动编码** 的 — 构建快速且大量使用 AI 助手（Claude Code 本身，恰好）。然后由人类审查架构、存储、安全、隐私和 MCP 行为。AI 编写了很多行；一个人负责范围、安全规则和决策。这正是项目的全部内容。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
