ClickMem：基于 chDB 的本地优先 Agent 统一记忆系统
> 来源: https://github.com/auxten/clickmem
> 作者: auxten（ClickHouse Principal Engineer，chDB 创始人）
> 语言: Python
> Stars: 18 | Forks: 1
> 创建: 2026-03-04 | 最近更新: 2026-03-12
> 协议: 未标注（待确认）
> 日期: 2026-03-13
📌 一句话总结
把 ClickHouse 嵌入进程（chDB），配合本地 Qwen3 Embedding + 本地 LLM，做成一个零云端依赖、LAN 共享、自动维护的 Agent 记忆服务器。一个端口同时提供 REST API 和 MCP，让 Claude Code / Cursor / OpenClaw 共享同一份记忆。
🧠 核心问题
> "AI 编码助手在会话之间遗忘一切。Context compaction 丢弃了你声明的偏好、做出的决策、提到的人名。"
这正是我们 researcher Agent 每天面临的问题——session compaction 后 30% 的隐性上下文消失。
🏗️ 三层记忆架构
┌──────────────────────────────────────────────────────┐
│ L2 语义记忆（Semantic）— 永久知识 │
│ "[preference] 偏好 SwiftUI 而非 UIKit" │
│ "[person] Alice 是后端负责人" │
│ 永不自动删除 · 仅在矛盾时更新 · 精炼记忆 1.15x 加权 │
├──────────────── ▲ 晋升（重复模式） ──────────────────┤
│ L1 情景记忆（Episodic）— 事件时间线 │
│ "03-04: 决定用 Python core + JS plugin 架构" │
│ 120 天衰减 · 自动压缩为月度摘要 · 重复模式晋升到 L2 │
├──────────────── ▲ LLM 结构化提取 ────────────────────┤
│ Raw 原始对话（append-only） │
│ 完整对话文本 · 不参与搜索 · 支持重新提取 │
└──────────────────────────────────────────────────────┘
Raw → L1 → L2 的数据流
1. Raw 原始对话：完整存储对话文本（append-only），不做 embedding，不参与搜索。仅供提取和精炼管道消费。当模型/prompt 改进时可以"重新提取"
2. L1 情景记忆：LLM 从 raw 中提取结构化事件。每条记录关联 raw_id 可追溯。120 天未访问自动清理，旧条目压缩为月度摘要
3. L2 语义记忆：持久事实、偏好、人物。永不自动删除。Smart upsert 通过 LLM 检测重复并合并
🔍 混合搜索（6 维打分）
| 维度 | 机制 |
|---|---|
| 1. 向量相似度 | 256 维 Qwen3 Embedding，余弦距离 |
| 2. 关键词匹配 | 词级命中率（内容 + 标签 + 实体） |
| 3. 时间衰减 | L1/L2 使用不同策略（见下） |
| 4. 热度加权 | 频繁被召回的记忆得分更高 |
| 5. 精炼加权 | 经过 refinement 的记忆 1.15x 加权 |
| 6. MMR 多样性 | 重排避免返回冗余结果 |
时间衰减的精妙设计
L1 情景记忆 — 指数衰减（模拟人类情景记忆）：
- 半衰期 60 天：2 个月前的事件只剩 50% 权重
- 公式：
w = e^(-ln2/T × t) - 1 年后权重仅 0.015——自然遗忘
L2 语义记忆 — 对数新近度（Weber-Fechner 定律）：
- 人对时间差的感知是对数的："1 分钟前 vs 1 小时前"差异大，"3 个月前 vs 6 个月前"几乎无感
- 权重映射到 [0.8, 1.0]，仅作为微弱的 tiebreaker
- 公式：
w = 0.8 + 0.2 / (1 + k × ln(1 + t/τ)) - 1 年前的知识仍保留 86.7% 权重
| 时间 | L1 情景 | L2 语义 |
|---|---|---|
| 1 分钟 | 1.000 | 0.981 |
| 1 天 | 0.989 | 0.896 |
| 30 天 | 0.707 | 0.877 |
| 60 天 | 0.500 | 0.874 |
| 1 年 | 0.015 | 0.867 |
关键洞察：语义记忆失去相关性的唯一途径是矛盾更新，而非时间流逝。
🤖 全本地 LLM
| 模型 | 参数 | 内存 | 用途 |
|---|---|---|---|
| Qwen3-Embedding-0.6B | 0.6B | ~500 MB | 向量嵌入 |
| Qwen3.5-2B | 2B | ~1.5 GB | 快速提取（默认） |
| Qwen3.5-4B | 4B | ~3 GB | 更好的提取质量 |
| Qwen3.5-9B | 9B | ~6 GB | 最佳精炼质量 |
- Apple Silicon 用 MLX，其他平台用 HuggingFace Transformers
auto模式：先试本地，不行再 fallback 到远程 API- 零 Token 成本——全部本地推理
🔄 持续精炼（Continual Refinement）
当未处理的 raw 对话累积超过阈值（默认 10），后台线程自动触发：
1. 重新提取 — 处理可能遗漏或可受益于改进提取的对话
2. 聚类 — 按 embedding 余弦相似度（>0.7）分组相似 L2 记忆
3. 去重合并 — LLM 检测同一聚类内的重复记忆，合并为单条更强条目
4. 质量门控 — 记忆必须可操作、跨会话稳定、非敏感才能存活
精炼后的记忆标记 source=refinement，召回时获得 1.15x 加权。原始记忆软删除但保留审计。
🌐 架构：一个端口，所有工具
Claude Code ──MCP──┐
Cursor ─────MCP────┤
OpenClaw ──MCP/HTTP┤ ClickMem Server (port 9527)
CLI ────────HTTP───┘ REST API + MCP SSE + mDNS
部署：
- 默认端口 9527
- mDNS 自动发现（
_clickmem._tcp） - API Key 认证
- macOS: launchd / Linux: systemd
资源消耗：
- ~500 MB RAM（embedding 模型）
- ~200 MB 磁盘（chDB 数据）
- 加载本地 LLM 后总共 ~4.5 GB
🔌 集成
自动安装脚本 setup.sh 一步完成：
- 创建 venv + 安装依赖
- 安装并启动后台服务
- 导入现有 OpenClaw 历史
- 安装 OpenClaw 插件
- 安装 Claude Code Skill（
/clickmem命令）+ HTTP hooks - 安装 Cursor hooks（自动 recall/capture）
MCP 工具：
memory_recall— 语义搜索memory_remember— 存储记忆memory_forget— 删除记忆memory_ingest— 原始对话摄入（存储 + 提取）
📊 与竞品对比
| 特性 | ClickMem | Mem0 | OpenClaw 内置 | Supermemory |
|---|---|---|---|---|
| 本地优先 | ✅ 全本地 | ❌ 云端 | ✅ 本地 | ❌ 需要 Pro |
| 多工具共享 | ✅ LAN 广播 | ❌ 独立 | ❌ 仅 OpenClaw | ❌ 独立 |
| 三层记忆 | ✅ Raw/L1/L2 | ❌ 单层 | ❌ 文件型 | ❌ 单层 |
| 时间衰减 | ✅ 双策略 | ❌ | ❌ | ❌ |
| 持续精炼 | ✅ 自动 | ❌ | ❌ | ❌ |
| 本地 LLM | ✅ Qwen3.5 | ❌ | ❌ | ❌ |
| MCP 支持 | ✅ | ✅ | N/A | ✅ |
| 存储引擎 | chDB (ClickHouse) | Qdrant | MEMORY.md | 云端 |
| 成本 | 零 | API 费用 | 零 | $29/月 |
ClickMem 的独特优势：底层是 ClickHouse——列式存储 + 压缩意味着对话量增长不会导致磁盘/性能问题。内置倒排索引 + 向量索引 + 几百个分析函数。
💡 与我们的关联
直接相关且可用：
1. 解决我们的核心痛点：我们的 researcher Agent 每次 session compaction 丢失大量上下文。ClickMem 的 Raw → L1 → L2 管道能保留这些信息
2. 可以在我们的 VPS 上跑：全本地，Python，systemd 服务。Qwen3.5-2B 只需 ~4.5 GB RAM
3. OpenClaw 插件现成：setup.sh 自动安装 OpenClaw 插件和历史导入
4. 与我们之前研究的 mem9 互补：mem9 做 TiDB 云端记忆，ClickMem 做本地记忆——取决于你要不要数据出本机
5. 但：项目太新（3 月 4 日创建），Star 18，无 License 声明，只有 1 个 fork。需要观察成熟度
建议：
- 短期：继续用 OpenClaw 内置 MEMORY.md（够用）
- 中期：等 ClickMem 稳定后试装——解决跨 Agent 记忆共享
- 参考其时间衰减设计——即使不用 ClickMem，L1 指数衰减 + L2 Weber-Fechner 对数的思路值得借鉴
📊 评分
| 维度 | 评分（/10） |
|---|---|
| 技术深度 | 9.0 — 三层记忆 + 双时间衰减 + 持续精炼 |
| 实用价值 | 8.5 — 解决真实痛点，开箱即用 |
| 代码质量 | 8.0 — 文档详尽，架构清晰 |
| 生态成熟度 | 5.0 — 太新，Star 少，无 License |
| 与我们的关联 | 9.0 — 直接解决我们的记忆丢失问题 |
| **综合** | **8.5** |
报告由深度研究助手自动生成 | 2026-03-13
来源: https://github.com/auxten/clickmem