Wolbarg 实战：为 AI 编程 Agent 添加本地语义记忆
你在用 Claude Code 或 Cursor 编程时，是不是经常遇到这种情况：Agent 刚记住的项目上下文，换个会话就全忘了，每次都要重新解释一遍需求？这个问题在多人协作或多 Agent 工作流中尤其突出——每个 Agent 都像得了失忆症，独自探索一遍代码库。
Wolbarg 正是为解决这个问题而生的。它是一个模块化、与模型无关（provider-agnostic）的语义记忆 SDK，让 AI 编程 Agent 拥有持久化记忆能力，跨会话、跨项目地保持上下文连贯。本文将带你从安装开始，一步步为你的 AI Agent 接入本地语义记忆。
什么是 Wolbarg？
Wolbarg （v0.3.1）是一个 TypeScript 语义记忆 SDK，MIT 许可证，通过 npm 安装。核心设计理念很简单：用本地 SQLite 文件存储 Agent 的记忆，无需搭 PostgreSQL 服务，无需连向量数据库，一个 npm install 就能跑起来。
它支持双后端存储——SQLite 和 PostgreSQL。对本地开发来说，SQLite 是默认首选：零配置，单文件，启动只要 7.9ms，开箱即用。
安装与快速开始
npm install wolbarg
需要 Node.js 22.5+（因为用到了实验性的 node:sqlite 模块）。
如果需要处理 PDF 或 DOCX 文档，可以按需安装可选依赖：
npm install pdf-parse@1.1.4 mammoth
基本用法非常直观。初始化一个 Wolbarg 实例，指定存储后端和嵌入模型即可：
import { wolbarg, openaiEmbedding, openaiLlm, bm25 } from "wolbarg";
const ctx = wolbarg({
organization: "my-project",
database: { provider: "sqlite", url: "./memory.db" },
embedding: openaiEmbedding({
apiKey: process.env.OPENAI_API_KEY!,
model: "text-embedding-3-small",
}),
llm: openaiLlm({
apiKey: process.env.OPENAI_API_KEY!,
model: "gpt-4.1-mini",
}),
keywordSearch: bm25(),
});
这里的关键参数是 embedding——它负责将文本转换成向量，让 Agent 能按语义搜索记忆。llm 可选，用于记忆压缩和摘要。keywordSearch 提供 BM25 关键词搜索作为语义搜索的补充。
写入与读取记忆
让 Agent 记住信息用 remember 方法：
await ctx.remember({
agent: "backend-dev",
content: { text: "项目使用 Prisma 连接 PostgreSQL，数据库 schema 在 prisma/schema.prisma" },
metadata: { topic: "database" },
});
后续会话中，Agent 可以通过 recall 找回这些信息：
const hits = await ctx.recall({
query: "数据库配置",
topK: 5,
});
console.log(hits);
// [{ text: "项目使用 Prisma 连接 PostgreSQL...", score: 0.92, metadata: {...} }, ...]
支持混合搜索（语义 + 关键词）和结果筛选：
const hits = await ctx.recall({
query: "database",
topK: 5,
hybrid: true,
filter: { metadata: meta.eq("topic", "database") },
});
文档摄入 — 让 Agent 读懂文件
Agent 需要理解项目中的文档、PDF 或 CSV 文件？用 ingest 方法：
await ctx.ingest({
agent: "docs-bot",
path: "./docs/api-reference.md",
metadata: { source: "api-docs" },
});
ingest 会自动将文档拆分成块、生成嵌入并存入记忆库。这种接入了 PDF、DOCX（需可选依赖）和纯文本文件，让 Agent 在不丢失语义的前提下「通读」项目文档。
记忆的快照与回滚
Wolbarg 一个很有特色的功能是 checkpoint 系统——允许你在关键节点创建记忆快照，需要时回滚到任意历史状态：
// 在开始大重构前打个快照
await ctx.checkpoint("before-migration");
// Agent 做完修改后，检查记忆是否准确
const history = await ctx.listCheckpoints();
// [{ id: "...", timestamp: "...", label: "before-migration" }, ...]
// 如果需要回滚到快照时的记忆状态
await ctx.rollback("before-migration");
这对 AI 编程 Agent 特别有用：Agent 可以在每次大改动前保存记忆检查点，确保不会在项目过程中丢失关键的上下文信息。
其他实用操作
// 批量写入
await ctx.rememberBatch([
{ agent: "dev", content: { text: "..." }, metadata: {} },
{ agent: "dev", content: { text: "..." }, metadata: {} },
]);
// 压缩记忆（需要配置 llm）
await ctx.compress({ agent: "dev", strategy: "summary" });
// 导出记忆包（可移植的 SQLite 文件）
await ctx.export({ path: "./backup-memory.db" });
// 导入记忆
await ctx.import({ path: "./backup-memory.db" });
搭配 Telemetry 仪表盘
Wolbarg 附带一个本地遥测仪表盘（wolbarg_studio），可以可视化 Agent 的记忆活动：
cd wolbarg_studio npm install npm run dev
启动后在 http://localhost:3100 打开，连接到 ./telemetry.db，可以看到每条记忆的写入时间、检索频率、延迟分布等信息。对调试 Agent 行为特别有用。
适用场景
Wolbarg 最适合以下场景：
- 多 Agent 协作：多个 Claude Code / Cursor 实例共享同一记忆库，避免重复探索
- 跨会话持久化：AI 编程 Agent 在多次会话间保持对项目结构和约定的理解
- 文档问答：将项目文档摄入记忆库，Agent 基于语义搜索回答问题
- 增量式代码审查：Agent 记住上次审查到哪了，增量关注新变更
局限性
目前版本（v0.3）有一些已知限制：
- PDF 摄入需要额外安装
pdf-parse@1.1.4，且仅支持文本层 PDF - Node.js 的
node:sqlite仍是实验性功能，需要 Node 22.5+ - PostgreSQL 存储可选，但遥测和检查点目前仅支持 SQLite
- 它不是 Agent 框架、聊天 UI 或托管向量服务——专注解决记忆层这一件事
总结
Wolbarg 解决了 AI 编程 Agent 的一个核心痛点：持久化的语义记忆。用单文件 SQLite 作为后端，零服务依赖，设置简单，API 清晰。对于本地开发和单机多 Agent 工作流来说，它比搭一套 PostgreSQL + pgvector 的方案轻量得多。
如果你的 Agent 总是「转头就忘」，不妨试试给它装上 Wolbarg 这个记忆层。
相关链接