memalyze

memalyze

原生支持 MCP、可自托管的 AI Agent 记忆方案——具备企业真正会要求的治理能力。

一个静态二进制文件。本地嵌入。无需云服务、图数据库或 Python 技术栈。 写入任何内容之前就会进行脱敏；每次读取都会记录审计日志。

./memalyze          # MCP over stdio, for Claude Code / Cline / any harness

v0.1.0 已发布 — 已提供 linux/darwin/windows 静态 二进制文件，并随附校验和。

---

问题

每个 Agent 框架都有自己的记忆：这里一个向量表，那里一个 JSON 文件，别处还有一个 “notes” 文件夹。由此带来三个问题，在生产环境中都很棘手：

1. 无法审计。“上周二 Agent 读取了哪位客户的数据？”这个问题没有答案，安全审查因此会叫停项目。
2. **无法离线部署。**大多数方案要么调用云 API，要么在运行时从 HuggingFace 下载模型权重——这两种方式在银行、医院或工厂的环境中都行不通。
3. **无法保持精简。**23 个工具、一个图数据库，再加上一套 Python 依赖树之后，“记忆功能”就成了需要单独运维的第二个产品。

memalyze 是解决这三个问题的中间件，仅此而已。

有何不同

	云端记忆 API	框架内置功能	个人笔记应用	memalyze
数据存放位置	供应商云端	框架内部	本地 Markdown	你的服务 / 你的笔记本电脑
连接方式	专有 API	绑定单一框架	MCP	MCP，支持任意宿主、stdio 或 HTTP
写入前脱敏	❌	❌	❌	✅ 8 类规则，可配置，默认不可逆
读取审计	部分支持	❌	❌	✅ 仅追加*，按操作者记录，可导出
离线使用	❌	部分支持	⚠️ 需要下载模型	✅ 本地嵌入，无需联网
部署方式	SaaS	随框架提供	173 个 Python 包	✅ 一个静态二进制文件 / 一个 compose 文件
工具数量	—	—	23 个工具	4 个工具

* 数据库触发器会拒绝对 audit_log 执行 UPDATE；不会阻止 DELETE，因此任何拥有数据库文件的人都可以删除记录。它在 SQL 层面是仅追加的，并非 WORM——如果删除操作也属于你的威胁模型，请导出到启用了对象锁定的存储或 syslog 存储 （SECURITY.md）。

这既不是另一个 mem0，也不是 Basic Memory：它们擅长记忆。memalyze 假设记忆正逐渐成为一项普遍能力，并以治理、离线运行和刻意精简的功能表面作为竞争优势。

30 秒演示

无需 Ollama、无需联网、无需 MCP 客户端：

./examples/demo/demo.sh
# or: go run ./cmd/memalyze demo

它会写入一条包含电话号码、电子邮件和居民证件号码的记忆，然后展示：

• 实际存储的内容（[REDACTED:phone]，而非 13800138000）；
• 搜索原始号码会返回 0 条结果；
• 按业务词语搜索仍能命中，并返回脱敏后的文本；
• 两次写入和两次读取对应的审计记录。

详情和演示记录：docs/s15-redaction-audit.md。

快速开始

1. 二进制文件 + 本地嵌入模型

预构建且已验证校验和（Linux/macOS；Windows 用户请从发布页面下载 .exe）：

curl -fsSL https://raw.githubusercontent.com/mahaoboy/memalyze/main/scripts/install.sh | sh
ollama pull qwen3-embedding:0.6b      # ~640 MB, 1024-dim, strong on Chinese
memalyze --version

从源代码构建（Go 1.27+）：运行 make build，然后执行 ./memalyze --version。

2. 将其接入宿主

Claude Code（项目级配置）：

claude mcp add --scope project memalyze -- "$(pwd)/memalyze"
cp examples/claude-code/CLAUDE.md ./CLAUDE.md   # makes Claude search before answering

Cline：复制 examples/cline/cline_mcp_settings.json 和 .clinerules。 通用宿主：examples/custom-harness/ — 包含一份提示词约定 和伪代码。所有选项见：examples/README.md。

3. 或在 Claude Desktop 中一键安装（MCPB）

从 v0.1.0 发布页下载适用于你平台的安装包并打开。 Claude Desktop 会显示安装界面，并询问将 memalyze.db 保存在哪里。

平台	文件
macOS Apple Silicon	memalyze-0.1.0-darwin-arm64.mcpb
macOS Intel	memalyze-0.1.0-darwin-amd64.mcpb
Windows x64	memalyze-0.1.0-windows-amd64.mcpb
Linux x64	memalyze-0.1.0-linux-amd64.mcpb

其中的二进制文件与上文的 v0.1.0 版本相同。这些安装包是新推出的，尚未在真实的 macOS/Windows 桌面上打开过——如果没有出现安装界面，请使用普通二进制文件。该服务也已列入 MCP Registry。

4. 或在 Docker 中运行（memalyze + Ollama + 模型拉取）

printf 'MEMALYZE_HTTP_TOKEN=%s\n' "$(openssl rand -hex 24)" > .env
docker compose up -d --build
curl -s http://127.0.0.1:8080/healthz     # {"status":"ok","version":"dev"}

将支持 Streamable-HTTP 的 MCP 客户端指向 http://127.0.0.1:8080/mcp，并设置 Authorization: Bearer $MEMALYZE_HTTP_TOKEN。参见 docs/s16-docker.md。

工具

有意只提供四个。每增加一个工具，都意味着模型必须多做一个选择。

工具	功能	值得注意的语义
memory_add	存储记忆	重复内容会返回已有 ID；嵌入失败时仍会保留记忆（embedding_failed=true）；返回 redacted 和规则名称
memory_search	检索	优先使用向量，再用关键词补充；向量路径不可用时返回 degraded 和 degrade_reason；查询为空时列出最近的记忆
memory_delete	软删除	对已删除的 ID 幂等；未知 ID 会返回工具错误
echo	检查连接	验证 MCP 链接是否正常；不包含业务逻辑

没有 memory_context 工具：memory_search 已会返回可粘贴到提示词中的文本，而两个功能重叠的工具会让模型更难选择（D-017）。

治理

脱敏（写入路径）。 规则会在 memory.Service.Add 中运行，早于去重、FTS 和嵌入处理——因此明文不会进入主表、全文索引或向量。

规则	输入示例	存储为
private_key_block	-----BEGIN RSA PRIVATE KEY-----…	[REDACTED:private_key]
id_card_cn	110101199003071234	[REDACTED:id_card]
bank_card	6222021234567890123	[REDACTED:bank_card]
jwt	eyJhbGciOi…	[REDACTED:jwt]
api_key_known_prefix	sk-…、ghp_…、AKIA…	[REDACTED:api_key]
credential_assignment	api_key=abcdef123456	api_key=[REDACTED:credential]
email	[email protected]	[REDACTED:email]
phone_cn	+86 13800138000	[REDACTED:phone]

模式：enforce（默认）、dry-run（仅计数，用于调整）、off（调试）。 自定义规则包为 JSON 格式：examples/redaction-rules.json。

审计（读取路径）。 只追加的 audit_log（数据库触发器会拒绝 UPDATE）：记录操作者、租户、范围、操作、记忆 ID、时间戳、结果数、degraded 和脱敏次数。除非显式设置 MEMALYZE_AUDIT_QUERY_PLAIN=1，否则搜索文本只会以 SHA-256 + 长度 的形式存储。

memalyze audit export --from 2026-10-01 --to 2026-10-31 --format csv --out audit.csv
memalyze audit export --tenant acme --format json

目前尚未实现： 按用户进行身份验证（每个进程一个令牌，actor 来自环境变量）、审计保留/清除、可逆脱敏、审计界面。

检索表现，实测数据

S8 在包含 60 条记忆的中文语料库上，对 16 个查询进行的实测数据，而非推测 （docs/s8-retrieval-report.md）：

方法	recall@3	MRR
qwen3-embedding:0.6b（默认）	0.94	0.92
CJK 二元组 FTS5（关键词回填）	0.88	—
nomic-embed-text	0.47	—

两个有悖直觉的发现影响了设计：SQLite FTS5 的默认分词器完全无法检索中文（存储二元组文本前，召回率仅为 0.19）；RRF 融合的得分反而低于仅用向量，因此 v0.1 不进行融合。详见 D-012。

延迟（S14，固定冷启动）：后台预热耗时 37.8 秒，随后搜索耗时 1.14 秒，且 degraded=false；空闲五分钟后，新进程可在 1.52 秒内响应。如果向量路径不可用，搜索会在 ≤3 秒内降级为关键词检索，而不是卡住（D-015/D-018）。

工作原理

harness (Claude Code / Cline / your agent)
   │  MCP: stdio or Streamable HTTP
   ▼
internal/mcp     4 tools, argument conversion only
   ▼
internal/memory  redact → dedup → store → embed; search: vector → keyword → degraded
   ├── internal/govern     rule engine (8 families, JSON configurable)
   ├── internal/store      interface; sqlite impl (memories, embeddings, audit_log)
   ├── internal/embed      float32 BLOB codec, cosine; Ollama client
   └── internal/search     CJK bigram tokenizer + FTS5 MATCH builder

• 使用 SQLite（WAL），采用 ULID ID、用于去重的部分唯一索引、软删除和 TTL。
• 向量是 float32 小端序 BLOB；搜索采用暴力余弦计算（在约 10k 条记忆以内表现良好，也是单二进制文件设计的实际限制）。
• 架构迁移通过 PRAGMA user_version 进行版本管理（v1 → v2 会添加审计表）。

运维

memalyze audit export --from 2026-10-01 --format csv --out audit.csv   # who read what
memalyze backup --out /var/backups/memalyze-$(date +%F).db             # consistent snapshot
memalyze health --url http://127.0.0.1:8080/healthz                    # probe

• systemd：deploy/systemd/memalyze.service + docs/s16-systemd.md（加固的单元文件、环境文件、备份定时器）。
• Docker：docs/s16-docker.md。
• backup 使用 VACUUM INTO，因此快照在 WAL 模式下保持一致，并包含审计表；若目标文件已存在，则会拒绝覆盖。

配置

所有配置均通过环境变量完成；默认值开箱即用。

变量	默认值	含义
MEMALYZE_DB	./memalyze.db	SQLite 路径
MEMALYZE_TENANT	default	工具调用的默认租户
MEMALYZE_OLLAMA_URL	http://127.0.0.1:11434	本地嵌入端点
MEMALYZE_EMBED_MODEL	qwen3-embedding:0.6b	嵌入模型
MEMALYZE_QUERY_TIMEOUT	3s	降级前的向量路径时间预算
MEMALYZE_KEEP_ALIVE	30m	Ollama 模型驻留时间
MEMALYZE_REDACT_MODE	enforce	enforce / dry-run / off
MEMALYZE_REDACT_RULES	(内置)	JSON 规则包的路径
MEMALYZE_AUDIT	on	追加审计记录
MEMALYZE_ACTOR	local	审计中记录的操作者
MEMALYZE_AUDIT_QUERY_PLAIN	off	存储查询文本（默认仅存哈希）
MEMALYZE_HTTP_ADDR	(空 = stdio)	例如，:8080 用于 Streamable HTTP
MEMALYZE_HTTP_TOKEN	(空)	Bearer 令牌；绑定到 loopback 地址以外时必须设置

状态

如实记录当前进展——这是一个早期阶段的项目，并非 1.0。

里程碑	状态
M0 立项与定位 (S1–S4)	✅
M1 备料与技术验证 (S5–S8)	✅
M2 核心链路 (S9–S14)	✅
M3 打磨与文档 (S15–S19)	✅ S15 治理，S16 Docker，S17 文档，S18 测试+CI，S19 示例
M4 发布 (S20–S23)	🟡 S20 ✅，S21 ✅（v0.1.0 已公开发布），S22 GitHub ✅ / HN·Reddit·V2EX 待完成，S23 ⬜
M5 复盘 (S24)	⬜ 需要真实用户
M5 复盘 (S24)	⬜

已知不足：没有按用户进行身份验证，没有审计数据保留机制，Docker 镜像尚未在 CI 中构建（开发环境没有守护进程），向量检索采用暴力扫描，默认配置以中文为先（英文可用，但分词器针对 CJK 调优）。

文档

文档	内容
docs/s15-redaction-audit.md	规则、模式、审计架构、演示记录
docs/s16-docker.md	compose 堆栈、令牌策略、验证状态
docs/s16-systemd.md	加固的 systemd 单元、环境文件、备份与恢复
docs/s8-retrieval-report.md	11 种检索方法，以及为何选择了这一种
docs/s13-context-injection.md	促使模型进行搜索的提示词约定
docs/s14-end-to-end.md	真实测试框架、两个会话、冷启动数据
docs/s21-distribution.md	发布工件、渠道、发布后检查清单
docs/s21-submissions.md	面向 MCP 目录和 ClawHub 的可复制粘贴条目
docs/s23-feedback-log.md	实时反馈日志（目前确实为空）
docs/s24-review.md	里程碑评审模板（尚未填写）
SECURITY.md	威胁模型：防护范围与范围之外的内容

非目标

• 不是 SaaS：由你自行托管，我们不会持有你的数据。
• 不是 Agent 框架：它绝不会接管测试框架。
• 不是知识图谱：没有实体提取流程，也没有图数据库。
• 不追求功能至上：只有四个工具、一个二进制文件，并且坚决拒绝任何需要操作人员介入的功能。

许可证

AGPL-3.0-or-later（LICENSE）。如需将其嵌入闭源产品并获取商业许可： 请提交标题为 commercial license 的 issue。

贡献方式：参见 CONTRIBUTING.md。安全问题报告：参见 SECURITY.md。