Stashpad

Stashpad

适用于任何 AI 编码 Agent 的本地记忆：一个 MCP 服务和命令行工具，用来源、审核队列和搜索功能管理纯 Markdown 笔记。

可与 Claude Code、Codex、Cursor、VS Code、Gemini CLI 及任何其他 MCP 客户端搭配使用，也可以完全不使用 MCP（通过纯命令和 AGENTS.md 代码块）。无需模型、云服务或依赖：Node 20 或更高版本。

快速开始

npm install -g stashpad
stashpad setup                  # prints the MCP settings for your agent app (generic, claude-code, vscode, codex)
stashpad doctor --client        # starts the server the way your agent app does and checks it answers

预期结果：client start: the server answered with 8 tools in ... ms 和 Nothing is broken.

Claude Code 用户也可以安装插件，插件还会添加下方的钩子：/plugin marketplace add laaielichter/stashpad，然后运行 /plugin install stashpad@stashpad（或从 ReversePort 市场安装 stashpad@reverseport）。

为什么选择 Stashpad？

• 上下文压缩后，Agent 不再遗忘。 每次会话开始时以及运行 /compact 后，都会重新提供已固定的规则和最新的交接内容。
• 你设定的规则始终优先呈现给 Agent。 stashpad pin 会将少数重要规则保留在每份摘要中；每条提示词只会收到与之明显匹配的记忆。
• 不会有内容在你不知情的情况下被存入记忆。 Agent、工具和网页提交的笔记都要等待人工审核；近似重复内容、机密信息和隐藏文本都会被拒绝。
• 你可以阅读、修正并保留这些内容。 记忆是带有来源和日期的 Markdown 文件，保存在你的项目中，也可以按需存入 git。旧事实会被标记为终止，而不会被覆盖。
• 它始终可靠运行。 每个项目使用一个存储（工作树共享该存储），并发写入时使用锁，修改前创建快照，还有会指出待修复问题的 doctor 命令。

对比

	Stashpad	mem0（开源）	MCP 参考记忆服务	手动维护 CLAUDE.md / AGENTS.md
需要	Node 20	大模型和嵌入／向量存储	Node	无
存储	Markdown 文件，每条记忆一个文件	向量存储（+ 历史数据库）	单个 JSON Lines 图文件	单个 Markdown 文件
保存内容	用户编写的内容，或 Agent 提议并经用户接受的内容	大模型从对话中提取的事实	Agent 编写的内容	你编写的内容
搜索	词语（BM25）+ 同义词；无法命中部分改写后的查询	语义搜索（嵌入）	子串匹配	Agent 阅读全部内容
旧事实	标记终止并带日期，且可追溯替代关系	更新或删除	就地编辑	手动编辑
上下文压缩后仍保留	通过钩子提供摘要、固定项和交接内容	取决于客户端	取决于客户端	是（始终加载）
安全性	审核队列、机密信息和隐藏文本检查、数据标签、可选加密	取决于配置	内置功能中没有	无
许可证	MIT	Apache-2.0	MIT / Apache-2.0	–

Stashpad 不提供：语义搜索（在我们的评测中，词语搜索能找到约 3 个改写问题中的 2 个）、从聊天中自动提取记忆（这是有意为之）、电脑之间的同步（请使用 git），或供团队共享的服务。

会话的开始与结束

stashpad brief                  # short summary: pinned rules, newest memories, open handoff
stashpad recall "add a postgres migration"    # the few memories that clearly match a request
stashpad handoff leave --text "Half done: auth. Next: tests."   # a note the next session reads once
stashpad sync-agents AGENTS.md  # put the brief in a file agents already read (no MCP needed)

使用 Claude Code 插件时，这些操作会作为钩子运行：会话开始时、上下文压缩后、每次收到提示词时，以及上下文压缩前（自动交接）。请参阅 docs/HOOKS.md。Agent：请阅读 AGENT-GUIDE.md。

开发

需要 Node 20 或更高版本。没有其他依赖。

npm test                 # run the tests
npm run build            # build dist/
node bin/stashpad.mjs --help

记忆存储在项目的 .stashpad/memories 中：优先使用上方最近的、包含该目录的文件夹，否则使用 git 根目录，因此子文件夹和 git worktree 共用一个存储位置。stashpad where 会显示文件夹使用的存储位置及原因。设置 STASHPAD_DIR 或传入 --dir，即可自行选择。所有项目通用的信息（你的语言、提交风格）应放在全局存储中：添加 --global（或 -g）。

使用

stashpad save db-choice --kind decision --source-type user --source-ref "statement in chat" --text "We keep data in SQLite."
stashpad search "sqlite" --json
stashpad save db-choice-v2 --kind decision --source-type user --source-ref "later statement" --text "We keep data in Postgres." --supersedes db-choice
stashpad history db-choice-v2
stashpad search database --kind decision --as-of 2026-03-01 --explain   # what was decided on that day, and why it matched
stashpad entities                  # names, tools and files the memories talk about
stashpad about Postgres            # every memory about it, and what is mentioned with it
stashpad confirm db-choice-v2      # still true; doctor flags agent memories nobody confirmed for 180 days
stashpad handoff leave --text "Half done: auth. Next: tests."   # a note the next session reads once
stashpad handoff claim             # take it (a person's notes first); listing never takes one
stashpad feedback db-choice --signal stale   # helpful, stale or wrong; wrong also asks for it to end
stashpad lint                      # what deserves a look; changes nothing

命令行、MCP 服务和审核页面可以同时运行：每次写入都会对存储加一个短暂的锁。

Agent、工具和网页的写入会等待审核：

stashpad review
stashpad accept <id>
stashpad reject <id> --reason "not verified"
stashpad audit

在 MCP 客户端中使用

stashpad setup 会输出适用于你客户端的配置块，其中包含 Node 的完整路径（只写 node 是服务无法连接的最常见原因）。配置块如下：

{
  "mcpServers": {
    "stashpad": {
      "command": "/full/path/to/node",
      "args": ["/full/path/to/stashpad/bin/stashpad.mjs", "mcp"]
    }
  }
}

八个工具：stashpad_search、stashpad_get、stashpad_recent、stashpad_about、stashpad_save、stashpad_forget、stashpad_handoff、stashpad_feedback。

检查并导入

stashpad eval                          # 40 notes, 33 queries (English and Dutch), safety checks; no language model is called. Paraphrased questions are measured too (about 2 of 3 found): word search misses some rewordings, and that is reported openly.
stashpad import notes.jsonl            # queue memories from an export; they wait for review
stashpad export --out memories.jsonl   # back up current memories as JSON Lines (--all adds ended ones)
stashpad save <id> --kind fact --source-type user --source-file notes.txt --text "..."   # keeps a copy of the raw source

stashpad review 还会显示待审核的记忆是否可能与当前记忆冲突，以及接受它是否会使当前记忆失效。

在页面中审核

stashpad ui            # opens http://127.0.0.1:4317/ to review, search and read the audit log
stashpad ui --open     # the same, and opens the page in your browser

只有这台电脑可以访问该页面。这是一个小型本地页面，不会加载任何外部资源。请参阅决策说明。

导入内容可以是 JSON Lines（包含 id、kind、text，以及可选的 valid_from、source_ref），也可以是纯文本，每段包含一条事实。

原则

• 优先使用纯文件。文件是唯一可信来源。
• 在有人接受之前，不会存储来自 Agent、工具或网页的任何内容。
• 写入时会拒绝秘密信息（密钥、令牌、JWT、Bearer 令牌、连接字符串中的密码）。
• 会拒绝不可见字符，且相似字符或拆分后的词语无法隐藏指令或秘密。
• 类似指令的文本（英语和荷兰语）会被标记，供审核者检查。
• 守门机制会拒绝过短或与现有记忆、待审核记忆高度相似的 Agent 笔记，并在审计日志中记录拒绝原因。用户手动撰写的笔记不会被拦截。
• 限制：每条记忆最多 4000 个字符，最多 200 条写入等待审核。
• 检索到的文本会标记为数据，而非指令。

文档

• 搜索词与同义词
• 交接、反馈、lint、过期和 ReversePort
• 钩子：应对压缩、固定规则、按提示词检索
• 可选加密
• 架构
• 变更日志
• 与任意 Agent 搭配使用
• 安全更新：快照、恢复、迁移
• 记忆文件格式
• 搜索后端决策
• 暂不使用向量搜索
• 第三方声明。代码通过 npm run port 移植，该命令只接受 MIT、Apache-2.0、BSD-2-Clause、BSD-3-Clause 和 ISC 许可证。

常见问题

Stashpad 会向外发送任何内容吗？ 不会。它不会发起网络请求、调用模型或收集遥测数据。审核页面只在这台电脑上监听。

我的记忆存在哪里？ 存在项目的 .stashpad/memories 中（stashpad where 会告诉你具体位置）。这些是 Markdown 文件，你可以打开、编辑和提交。

Agent 可以随意写入记忆吗？ 不可以。Agent 的写入需要等待用户审核（使用 stashpad review 或 stashpad ui）。秘密、不可见字符和高度相似的内容会被拒绝，所有检索到的内容都会标记为数据，而非指令。

我的 MCP 客户端提示服务启动失败。 运行 stashpad doctor --client。该命令会像 Agent 应用一样启动服务，并告诉你需要修复什么。

姊妹工具

来自同一作者的本地开源工具，各自拥有 MCP 服务。

• ReversePort：对应用、游戏、二进制文件和网站进行逆向工程，并将其移植到 Godot、Unity、Unreal、three.js 和其他语言。re_case remember 会将 proof case 的发现提交到 Stashpad 的审核队列 (方式)。
• agentdisk：面向编码 Agent 的磁盘报告工具。查找 Agent 留下的工作树、检查点和依赖文件夹，并且只清理安全的内容，支持撤销。

在 Claude Code 中，你可以从同一个市场获取这三款工具：/plugin marketplace add laaielichter/reverseport， 然后运行 /plugin install reverseport@reverseport、stashpad@reverseport 或 agentdisk@reverseport。

贡献与社区

欢迎提出想法、报告 Bug 和提交拉取请求：请参阅 CONTRIBUTING.md、适合新手的议题和 讨论区。安全问题请参阅：SECURITY.md。

许可证

MIT。请参阅 LICENSE。