BetterDB 实战教程：用 Valkey 原生层给 AI Agent 装上持久记忆与智能缓存
每次打开新的 AI 编码会话，Agent 又忘了刚才的上下文？LLM 调用一次就扔，同样的提示反复扣费？这些问题背后有一个共同的根因：AI Agent 缺乏高效的持久上下文层。
BetterDB 是一个 MIT 开源、Valkey 原生的 AI Agent 上下文层，在 GitHub 上已有 1200+ Star。它提供一套完整的工具包——语义缓存、Agent 内存、向量检索——全都跑在你自己的 Valkey（或 Redis）实例上，不绑定任何第三方厂商。
BetterDB 的三大核心组件
BetterDB 以 monorepo 形式发布了 10 多个 npm 和 PyPI 包，其中三个对 AI Agent 开发者最实用：
1. agent-memory：给 Agent 装上长期记忆
@betterdb/agent-memory 提供类似人类记忆的语义检索机制。它不只是存一个字符串，而是用 remember() 写入、recall() 召回，底层用向量相似度 + 时间衰减 + 重要性加权三项指标综合排序。
import { AgentMemory } from '@betterdb/agent-memory';
const agentMemory = new AgentMemory({
client: valkeyClient,
embedFn: async (text) => getEmbedding(text),
});
// AgentMemory 暴露三个缓存层级 + 一个记忆存储
const { memory, llm, tool } = agentMemory;
// Agent 保存一段记忆
await memory.remember('user prefers Python for backend projects');
// 下次会话中，Agent 自动召回相关记忆
const results = await memory.recall('what language does user prefer');
// 返回按相关度排序的结果，包含向量距离分数和时间戳
记忆达到容量上限时自动执行 eviction 策略，移除最久远或最不重要的条目——不需要手动管理。
2. agent-cache：三层缓存省 Token
@betterdb/agent-cache 将 AI Agent 的缓存拆为三层：
- LLM 响应缓存：相同或相似提示直接命中缓存，省去重复调用
- 工具结果缓存：
read_file、search_code等工具的输出按 TTL 缓存 - 会话状态缓存：Agent 的中间状态跨步骤持久化
import { AgentCache } from '@betterdb/agent-cache';
const cache = new AgentCache({ client: valkeyClient });
// 缓存 LLM 调用结果
await cache.llm.set('prompt:optimize-query', response, { ttl: 3600 });
// 缓存工具调用结果
await cache.tool.set('search:auth-module', results, { ttl: 300 });
更妙的是——每个缓存层级都有独立的 TTL 策略。工具结果可能 5 分钟过期，LLM 响应缓存 1 小时，会话状态则保持到工作流完成。
3. retrieval：类型安全的 Valkey 向量检索 SDK
@betterdb/retrieval 封装了 Valkey Search 的 FT.* 命令，提供类型化的索引创建、upsert 和混合查询：
const retriever = new Retriever({
client,
name: 'project-codebase',
schema: {
fields: { language: { type: 'tag' }, stars: { type: 'numeric', sortable: true } },
vector: { algorithm: 'hnsw', metric: 'cosine' },
},
embedFn: async (text) => embed(text),
});
// 一次调用即完成：索引创建（幂等）、向量嵌入、写入
await retriever.upsert([
{ id: 'repo1', text: 'Valkey-native context layer for AI agents', fields: { language: 'TypeScript', stars: 1200 } },
]);
// 混合查询：向量相似度 + 标签过滤
const hits = await retriever.query({
text: 'in-memory context cache',
k: 5,
filter: { language: 'TypeScript' },
});
支持纯向量查询、标签过滤、数值范围过滤，以及 hybrid: 'rerank' 重排序混合模式。
实战场景：用 BetterDB 为 Claude Code 添加持久记忆
假设你正在用 Claude Code 做一个大型项目，每次新会话都要重新解释项目结构和编码偏好。配合 BetterDB 的 agent-memory + MCP 包，可以让 Agent 跨会话保持记忆。
npm install @betterdb/mcp iovalkey docker run -p 6379:6379 valkey/valkey:7
然后在 Claude Code 的配置中注册 BetterDB 的 MCP 工具，Agent 就能通过 MCP 协议直接查询 Valkey 中的索引、缓存状态和慢日志——你不需要切换终端，直接在对话中让 Agent 诊断自己的缓存健康状况。
和现有方案有什么不同？
对比 LangChain 的 RedisCache 或 LangGraph 的 checkpoint-redis，BetterDB 的优势在于：
| 能力 | BetterDB | LangChain RedisCache | LangGraph checkpoint-redis |
|---|---|---|---|
| 多层级缓存（LLM+工具+状态） | ✅ | ❌ 仅 LLM | ❌ 仅状态 |
| 内置 OTel + Prometheus | ✅ | ❌ | ❌ |
| 无需 Valkey 模块 | ✅ | ✅ | ❌ 需 Redis 8 + 模块 |
| 框架适配器 | LangChain、LangGraph、Vercel AI | ❌ 仅 LangChain | ❌ 仅 LangGraph |
BetterDB 的包都是框架无关的——你可以在 Claude Code、OpenCode、Codex、甚至自己写的 Agent 框架中使用，不被任何一家绑定。
生态亮点：TypeScript + Python 双语言
BetterDB 的所有核心包都提供 TypeScript 和 Python 两个版本，数据格式完全兼容。一个 TypeScript 写的 Agent 写入的记忆，Python 端的 Agent 可以直接读取——这在异构技术栈的团队中格外实用。
npm 包名以 @betterdb/ 开头，PyPI 包名以 betterdb- 开头。MIT 许可证，可自由用于商业项目。
总结
BetterDB 解决的痛点是很多 AI Agent 开发者的真实困扰：会话不持久、缓存不智能、轮子重复造。它用一个 Valkey 实例就搞定了通常需要组合多个服务的上下文层，而且 MIT 开源、框架无关、自带可观测性。
如果你正在搭建或维护 AI Agent 工具链，值得花半小时把 BetterDB 纳入你的技术栈。GitHub 上有完整的文档和 Quickstart，npm 和 PyPI 上直接安装即可。
相关链接