delx-memory

delx-memory

本地优先的持久化记忆 MCP 服务。一个共享的 SQLite 存储，任何支持 MCP 的 Agent（Claude Desktop、Cursor、Hermes、OpenClaw、Codex）都可以读写——让上下文在不同会话和工具之间延续。

为什么

每个聊天客户端都有自己的临时上下文。关闭标签页 → 偏好设置消失。从 Claude Desktop 切换到 Cursor → 一切从头开始。在 Hermes 中置顶一个副项目 → 下一个 Agent 看不到。

delx-memory 是一个轻量级 MCP 服务，将单个共享的 SQLite 文件作为键值记忆层提供。任何支持 MCP 的客户端都可以读写同一个记忆文件 → 真正的连续性和跨工具上下文。

• 15 个工具——发现 + 交接 + 批量操作 + FTS5 搜索 + 由意图控制的变更操作。
• SQLite 位于 ~/.delx-memory/db.sqlite（目录权限 0700，文件权限 0600）。
• 阻止机密信息：拒绝存储可能是凭据的键或值。
• 支持 TTL（读取时延迟过期）。
• 标签 + 前缀筛选 + FTS5 全文搜索（bm25 排序、词干提取、变音符号折叠；FTS5 不可用时回退到 LIKE）。
• 变更操作要求设置 explicit_user_intent: true，防止过于主动的 Agent 悄悄改写你的上下文。
• 零遥测。零回传。文件归你所有。

多 Agent 命名空间

# Agent A
DELX_MEMORY_NAMESPACE=claude npx -y delx-memory

# Agent B (same machine, isolated keys)
DELX_MEMORY_NAMESPACE=cursor npx -y delx-memory

键以 namespace::key 的形式存储。单一全局存储（默认）无需设置环境变量。

占用空间 / 轻量模式

• 默认传输方式为 lite：通过 stdio 提供仅含工具的 MCP，不加载 MCP SDK（为常驻 Agent 大幅降低 RSS）。
• 完整 SDK 功能（提示词 + 资源）：delx-memory --sdk 或 DELX_MEMORY_TRANSPORT=sdk。
• 可选 HTTP：delx-memory --http（Express + SDK；默认仍仅监听回环地址）。
• DELX_MEMORY_LEAN=1 仅适用于 SDK 路径（跳过提示词和资源）。
• doctor --json 会报告 rss_kb。剩余开销主要来自 Node 和原生 better-sqlite3（不使用嵌入）。

社区对比自定义传输方式与 SDK 的测量结果显示，SDK 目录树是主要开销来源——参见 issue #7。

安装并运行

# Run once (npx will download + boot)
npx -y delx-memory doctor

# Or install globally
npm install -g delx-memory
delx-memory doctor

doctor 命令会检查 Node 版本、数据库可写性和文件权限，然后打印后续步骤。

---

HTTP（v2 无状态）

默认方式为 stdio。可选的 Streamable HTTP——无会话 ID，返回 JSON，仅监听回环地址：

npx -y delx-memory --http
# GET  http://127.0.0.1:3030/health
# POST http://127.0.0.1:3030/mcp   (sessionless)

环境变量：DELX_MEMORY_HOST、DELX_MEMORY_PORT、DELX_MEMORY_TRANSPORT=http。

接入 MCP 客户端

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "delx-memory": {
      "command": "npx",
      "args": ["-y", "delx-memory"]
    }
  }
}

然后重启 Claude Desktop。参见 examples/claude-desktop.json。

Cursor

添加到 ~/.cursor/mcp.json。参见 examples/cursor.json。

Hermes

参见 examples/hermes.md。

OpenClaw

参见 examples/openclaw.md。

Codex CLI

参见 examples/codex.toml。

---

诚实地说，它有何不同

	delx-memory	典型云端记忆	Graph memory MCP
数据离开你的设备	不会	会	通常不会
多个客户端共用同一存储	可以（一个 SQLite）	与账号绑定	仅限进程内
Agent 修改安全性	explicit_user_intent	不一	少见
密钥存储	坚决拒绝	通常允许	通常允许
默认 RSS 路径	轻量版（无 MCP SDK）	不适用	完整技术栈
多 Agent 隔离	DELX_MEMORY_NAMESPACE	租户隔离	手动处理
搜索	FTS5 bm25	嵌入（有成本／泄露风险）	图遍历

它不是向量数据库，不是第二大脑 SaaS。它为已有模型的 Agent 提供本地连续性。

工具（15 个）

会话开始

工具	用途
memory_handoff	一键恢复简报：统计信息 + 最近的键（值可选）。建议在会话开始时使用。
memory_agent_manifest	面向 Agent 的机器可读安装／运维约定。
memory_connection_status / memory_stats	就绪状态 + 存储大小。
memory_capabilities / memory_data_inventory	面向 Agent 的自我描述。

读取

工具	用途
memory_list	仅返回键；筛选条件：prefix、tag、since（增量同步）。
memory_get / memory_get_many	获取指定键或批量获取（最多 50 个）。
memory_search	FTS5 bm25（+ LIKE 回退）。参见搜索快速入门。

修改（需要 explicit_user_intent: true）

工具	用途
memory_set / memory_set_batch	新增或更新一个键，或在一个事务中批量新增或更新最多 50 个键。
memory_forget / memory_forget_by_tag	删除一个键或按标签删除。
memory_export	导出为 JSON / JSONL / Markdown。

除非调用方传入 explicit_user_intent: true，否则所有修改操作都会拒绝执行。这样设计的目的：Agent 若自行决定更新记忆，就必须展示操作依据。用户可以在工具调用中看到该标志；如果并未提出要求，也可以拒绝。

---

隐私约定（请阅读）

delx-memory 不是密钥管理器。请使用 macOS Keychain / gnome-keyring / Windows Credential Manager 存储密钥。

我们拒绝存储的内容：

• 匹配以下内容的键：oauth、token、secret、password、cookie、refresh、api_key、api-key、apikey、bearer、credential、session_id（不区分大小写）。
• 匹配以下凭据格式的值：
  • JWT 令牌（eyJ…）
  • Bearer <token> 标头
  • Stripe sk_live_… / sk_test_…
  • Slack xoxb-… / xoxp-… / 等
  • GitHub github_pat_… / ghp_… / gho_… / ghs_… / ghr_…
  • OpenAI / Anthropic sk-…（长度符合实际情况）
  • AWS 访问密钥 AKIA…
  • Authorization: <scheme> <token> 字符串
• 会递归遍历嵌套对象——名为 refresh_token 的嵌套字段（即使值为空）也会被拒绝。

会保留在本地的内容：

• 数据库文件位于 ~/.delx-memory/db.sqlite。
• 目录以模式 0700 创建；文件以模式 0600 创建。（在 Windows / WSL / 非 POSIX 文件系统上尽力而为。）
• 不会上传任何内容。无遥测，不会向外部服务器发送请求。

我们不作以下承诺：

• 使用同一台设备的其他用户（root 用户、使用 sudo 的室友）可以读取该文件。如果这对你很重要，请使用全盘加密（FileVault、BitLocker、LUKS）。
• **TTL 仅尽力而为。**过期的行会在下次读取时延迟删除；SQLite 不会自动执行 VACUUM，因此释放的页面可能仍留在磁盘上。对于敏感的临时数据，请像对待其他未加密的点文件一样对待数据库文件。
• **不承诺持久性。**如果你在意数据丢失，请像备份其他点文件一样备份 ~/.delx-memory/db.sqlite。

---

会话示例

agent> memory_stats({})
→ { total_keys: 0, db_path: "/Users/me/.delx-memory/db.sqlite", … }

user> Remember that I prefer concise responses in pt-BR.

agent> memory_set({
  key: "user_preferences",
  value: { language: "pt-BR", verbosity: "concise" },
  tags: ["profile", "preferences"],
  explicit_user_intent: true
})
→ { action: "created", key: "user_preferences", … }

# … new chat, possibly different tool …

agent> memory_list({ tag: "preferences" })
→ [{ key: "user_preferences", updated_at: … }]

agent> memory_get({ key: "user_preferences" })
→ { found: true, value: { language: "pt-BR", verbosity: "concise" } }

---

存储布局

默认路径	~/.delx-memory/db.sqlite
覆盖项	DELX_MEMORY_PATH 环境变量
目录权限	0700
文件权限	0600
架构	memory(key PRIMARY KEY, value, created_at, updated_at, ttl_expires_at, tags, metadata)
索引	ttl_expires_at 上的部分索引，以及 tags、updated_at
单个值上限	64 KB（JSON 序列化后）
单个键上限	512 个字符

---

命令行

delx-memory                Start MCP stdio server
delx-memory --http         Start local HTTP MCP server (127.0.0.1:3030)
delx-memory setup          Print MCP client config snippets
delx-memory setup --json   Print as JSON
delx-memory doctor         Health check + next steps
delx-memory doctor --json  Health check as JSON
delx-memory version        Print version

环境变量

变量	默认值	用途
DELX_MEMORY_PATH	~/.delx-memory/db.sqlite	DB 文件位置
DELX_MEMORY_TRANSPORT	stdio	stdio 或 http
DELX_MEMORY_HOST	127.0.0.1	HTTP 主机
DELX_MEMORY_PORT	3030	HTTP 端口
DELX_MEMORY_ALLOWED_ORIGIN	http://HOST:PORT	CORS 来源

---

开发

git clone https://github.com/davidmosiah/delx-memory
cd delx-memory
npm install
npm test         # typecheck + build + smoke + secret-detector + ttl + tag-delete + metadata

有关仓库约定，请参阅 AGENTS.md；有关安全模型和报告政策，请参阅 SECURITY.md；有关 PR 规则，请参阅 CONTRIBUTING.md。

---

许可证

MIT © 2026 David Batista。行为准则。

技能或 MCP

同一个软件包，两种使用方式。MCP 通过 stdio/HTTP 注册工具。如果客户端不支持 MCP，技能可以通过命令行调用相同的工具：

npx -y delx-memory call memory_connection_status --json '{}'

将 skill/SKILL.md 复制到你的 Agent 技能目录。