1. 项目概述为AI Agent构建轻量、持久的记忆系统在构建AI Agent时我们常常面临一个核心矛盾为了让Agent显得“聪明”且“善解人意”它需要记住与用户交互的历史、用户的偏好以及它自己做出的关键决策但另一方面大语言模型LLM的上下文窗口Context Window是有限的且每多一个Token文本单位都意味着更高的计算成本和更慢的响应速度。于是对话一长宝贵的Token预算就被大量重复或过时的历史消息所占据真正重要的信息反而被淹没。市面上的解决方案要么是绑定在特定框架如LangChain中的重型模块依赖众多要么是独立的云服务不仅引入网络延迟和额外成本还增加了系统复杂性。今天要介绍的ClawRecall正是为了解决这个痛点而生。它是一个轻量级的TypeScript库核心使命是为AI Agent提供三层结构化的记忆管理并确保在任何时候提供给模型的内容都不会超出你设定的Token预算。你可以把它理解为你Agent的“智能记忆管家”它知道哪些信息是必须长期记住的“身份特征”如用户说“我讲葡萄牙语”哪些是近期对话的“摘要精华”哪些是关键“决策依据”并能在需要时从海量历史中精准提取出最相关、最精简的部分打包成一个“记忆包裹”喂给LLM。它的设计哲学非常明确简单、高效、可控。整个库只有两个运行时依赖better-sqlite3和anthropic-ai/sdk数据默认存储在本地SQLite中真正做到开箱即用无需搭建任何外部服务。对于希望为自家聊天机器人、智能助手或自动化工作流赋予长期记忆能力的开发者来说ClawRecall提供了一个极其优雅的切入点。2. 核心设计思路三层记忆结构与Token预算管理为什么是“三层”记忆这源于我们对人类记忆和AI交互模式的观察。ClawRecall没有采用简单的“全部记住”或“向量数据库模糊搜索”的策略而是设计了一个更具工程实践意义的分层架构。2.1 三层记忆的职责划分ClawRecall将Agent的记忆分为三个明确的层级每个层级承担不同的职责并共享一个总的“记忆Token预算”。永久层Permanent存储最稳定、最核心的信息。这通常是关于用户或对话组Conversation Group的“身份事实”和“长期偏好”。例如“用户是后端工程师主要使用Go语言”、“用户讨厌冗长的回复喜欢bullet points”、“本次对话的目标是设计一个用户管理系统”。这些信息变化频率极低但却是理解对话背景的基石。近期层Recent存储对过去一段时间例如最近7天对话的摘要。它不是原始消息的罗列而是经过提炼的概要。例如“过去三天用户主要咨询了关于数据库索引优化和查询性能调优的问题我们讨论了B-tree索引和覆盖索引的优劣。” 这一层保证了Agent对刚刚发生的事有连贯性的认识避免了“金鱼记忆”。决策层Decisions存储Agent在对话过程中做出的关键决策及其理由。这是很多简单记忆系统忽略的部分却对构建可信、一致的Agent至关重要。例如“在03月15日的讨论中为用户推荐了SQLite而非PostgreSQL原因是项目需求轻量、单机部署且需要嵌入式支持。” 当用户后来问“我们当时为什么选SQLite”时Agent就能从这一层直接找到答案而不是重新“编造”一个理由。这种划分的好处是结构化和可预测性。开发者可以精确地知道哪类信息存在哪里也方便进行手动干预和调试。2.2 Token预算的智能分配仅有分层还不够关键是如何把这三层记忆和漫长的对话历史塞进有限的上下文窗口里。ClawRecall引入了“Token预算”的概念其默认分配策略非常直观总预算默认 8000 Tokens这是你愿意在一次LLM调用中为“系统指令记忆历史消息”所支付的最大Token成本。记忆层预算默认 2000 Tokens从总预算中划拨给上述三层记忆Permanent, Recent, Decisions的总和。ClawRecall会确保这三层内容的Token总数不超过此值。历史消息预算默认 6000 Tokens从总预算中划拨给原始对话历史addMessage存入的消息的部分。当你调用buildContext(conversationId)时ClawRecall会执行以下操作从数据库中取出三层记忆的当前内容。从数据库中取出该对话的所有历史消息按时间倒序。执行一个“装箱算法”首先确保三层记忆的内容被压缩如果超出以适应tiers预算。然后从最新的消息开始逐一将历史消息加入列表直到加入下一条消息会导致总Token数记忆已选历史超过total预算为止。返回一个BuiltContext对象其中包含格式化好的系统提示内含记忆层摘要和筛选后的历史消息数组。这个过程的精妙之处在于它总是优先保证最重要的“记忆”被包含然后用剩余的空间尽可能多地装载“近期历史”。这比简单粗暴的“保留最近N条消息”要智能得多因为它考虑了每条消息的实际长度Token数。2.3 本地优先与AI辅助压缩ClawRecall坚持“本地优先”原则。所有原始消息、记忆层内容、元数据都存储在一个本地SQLite文件中。这意味着零网络延迟addMessage和buildContext操作都是纯本地数据库读写速度极快。数据主权所有对话数据都留在你的服务器上符合更严格的数据隐私要求。离线工作即使没有网络Agent的记忆核心功能也完全正常。那么随着时间推移历史消息表会无限膨胀吗会的。这就是“AI辅助压缩”功能出场的时候。你可以定期例如每天一次调用compact(conversationId)方法。这个过程会将过去一段时间默认7天的原始消息和当前的三层记忆内容发送给AI模型默认是Claude Haiku因为它又快又便宜。请求模型分析这些内容并输出更新后的三层记忆摘要。将处理过的原始消息标记为“已归档”使其不再参与未来的buildContext筛选但它们依然在数据库里可供审计或全量分析。这个压缩过程本质上是在用AI模型对记忆进行“消化和重构”将琐碎的对话沉淀为结构化的知识存入记忆层。而归档操作则保证了活跃的历史消息池始终保持轻量。根据官方估算使用Claude Haiku对单个对话组进行每日压缩成本大约在每天0.001美元每月仅需3美分性价比极高。3. 从零开始安装、配置与基础API详解了解了核心思想后我们动手把它用起来。ClawRecall的API设计非常简洁专注于做好记忆管理这一件事。3.1 环境准备与安装首先确保你的项目环境是Node.js 20 或更高版本。然后通过npm安装npm install clawrecall安装过程会自动拉取两个核心依赖better-sqlite3高性能SQLite驱动和anthropic-ai/sdk用于压缩功能。如果你确定不需要AI压缩功能理论上可以尝试不提供Anthropic API Key但库的某些功能将受限。3.2 初始化与配置创建一个ClawRecall实例是第一步。以下是一个包含所有配置项的示例import { ClawRecall } from clawrecall; import path from path; const memory new ClawRecall({ // 必需SQLite数据库文件路径。如果目录不存在会自动创建。 dbPath: path.join(process.cwd(), data, agent_memory.db), // 可选但推荐Anthropic API Key。如果不提供compact 方法将不可用。 anthropicApiKey: process.env.ANTHROPIC_API_KEY, // 可选Token预算配置 tokenBudget: { total: 10000, // 总上下文窗口预算。根据你使用的模型调整如Claude-3.5-Sonnet-128K。 tiers: 2500, // 分配给三层记忆的预算。提高此值会让Agent“记住”更多细节。 history: 7500, // 分配给历史消息的预算。提高此值会让更长的对话历史被纳入。 }, // 可选记忆压缩配置 compaction: { model: claude-3-haiku-20240307, // 用于压缩的模型。Haiku是成本与效果的最佳平衡。 windowDays: 3, // 压缩时分析最近几天的消息对于高频对话可以缩短。 maxDecisions: 7, // 决策层最多保留几条关键决策避免过于冗长。 }, });实操心得dbPath最好指向一个持久化存储目录比如./data/。避免放在/tmp这类临时目录否则服务器重启数据就丢失了。对于tokenBudget一个实用的技巧是tiers预算至少留出500-1000 Token以确保基本的身份和近期摘要能放下history预算则根据你期望的对话回溯深度来设定。例如如果你希望Agent能记住大约20轮左右的对话可以估算一下平均每轮对话的Token数比如150 Tokens/轮那么history预算设为 3000 左右比较合适。3.3 核心API方法拆解ClawRecall的API方法不多但每个都至关重要。1.addMessage(conversationId, message)存储对话这是最常用的方法。每次用户或Agent发送一条消息都应该调用它。// 假设一个客服场景conversationId 可以是用户的唯一标识如 user_789 memory.addMessage(user_789, { role: user, // 必须是 user 或 assistant content: 我的订单#12345物流到哪里了 }); memory.addMessage(user_789, { role: assistant, content: 正在为您查询订单#12345的物流信息请稍等... });conversationId是记忆的命名空间。所有属于同一对话组如同一用户、同一项目、同一线程的消息都应使用相同的ID。2.setTier(conversationId, tier, content)手动设置记忆层虽然压缩功能会自动更新记忆层但在对话开始时或关键节点手动设置能更快建立上下文。// 设置永久层用户画像 memory.setTier(user_789, permanent, 用户张先生是我们的VIP客户偏好顺丰快递经常在晚上8点后咨询。); // 设置决策层记录一个关键操作 memory.setTier(user_789, decisions, 在2024-03-20因用户投诉物流慢已为其订单#12345升级为次日达服务并补偿了10元优惠券。);3.buildContext(conversationId)构建上下文这是核心中的核心。在需要调用LLM生成回复前调用此方法获取优化后的上下文。const context memory.buildContext(user_789); console.log(context.tokenUsage); // 输出类似{ tiers: 1245, history: 3560, total: 4805 } // 这表示本次构建记忆层用了1245 Tokens历史消息用了3560 Tokens总计4805 Tokens未超过预算。 // 接下来你可以这样使用这个上下文 const messagesToSendToLLM [ { role: system, content: 请你扮演一个专业的客服助手。以下是关于当前用户和对话的背景信息 ${context.systemPrompt} // 这里包含了格式化好的三层记忆 }, ...context.messages // 这里包含了筛选后的历史消息 ]; // 然后将 messagesToSendToLLM 发送给你选择的LLMOpenAI, Claude, 本地模型等返回的context.systemPrompt是一个字符串已经将三层记忆内容以清晰、自然语言的形式组织好了你可以直接嵌入到你的系统提示词中。4.compact(conversationId)执行记忆压缩这是一个异步方法通常放在定时任务如Cron Job中执行。async function runDailyCompaction() { try { const result await memory.compact(user_789); console.log(压缩完成。归档了${result.messagesArchived}条旧消息。); console.log(新的记忆摘要, result.newTiers); } catch (error) { console.error(压缩失败, error); // 压缩失败不应影响主流程可以记录日志并继续 } }5.close()关闭数据库连接在应用退出时例如在Node.js服务器的SIGTERM信号处理中记得关闭连接以释放资源。process.on(SIGTERM, async () { await memory.close(); process.exit(0); });4. 实战集成与不同AI Agent框架协同工作ClawRecall是一个独立的库不绑定任何特定的AI框架。这意味着你可以轻松地将它集成到现有的任何Agent系统中。下面看几个典型场景。4.1 场景一集成到自定义的聊天循环中假设你有一个基于Express.js的简单聊天机器人后端。import express from express; import { ClawRecall } from clawrecall; import { OpenAI } from openai; const app express(); app.use(express.json()); const memory new ClawRecall({ dbPath: ./memory.db, anthropicApiKey: process.env.ANTHROPIC_KEY }); const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); app.post(/chat/:userId, async (req, res) { const userId req.params.userId; const userMessage req.body.message; // 1. 存储用户消息 memory.addMessage(userId, { role: user, content: userMessage }); // 2. 构建优化上下文 const ctx memory.buildContext(userId); // 3. 准备发送给OpenAI的消息 const messages [ { role: system, content: 你是一个有帮助的助手。请根据以下背景信息进行对话 ${ctx.systemPrompt} 请保持回复简洁、准确。 }, ...ctx.messages // ClawRecall已经按时间顺序排好了 ]; // 4. 调用OpenAI const completion await openai.chat.completions.create({ model: gpt-4-turbo-preview, messages, max_tokens: 500, }); const assistantReply completion.choices[0].message.content; // 5. 存储助手的回复 memory.addMessage(userId, { role: assistant, content: assistantReply }); // 6. 返回回复给用户 res.json({ reply: assistantReply }); }); // 定时压缩任务例如每天凌晨3点运行 import nodeCron from node-cron; nodeCron.schedule(0 3 * * *, async () { // 假设你有一个获取所有活跃用户ID的方法 const activeUserIds await getActiveUserIds(); for (const userId of activeUserIds) { await memory.compact(userId).catch(e console.error(压缩用户 ${userId} 失败:, e)); } });4.2 场景二与LangChain.js结合LangChain是一个流行的AI应用开发框架。虽然ClawRecall不直接提供LangChain的“Memory”类但可以轻松适配。import { ClawRecall } from clawrecall; import { ChatOpenAI } from langchain/openai; import { HumanMessage, SystemMessage, AIMessage } from langchain/core/messages; // 1. 创建ClawRecall实例和LangChain模型 const memory new ClawRecall({ dbPath: ./lc_memory.db }); const model new ChatOpenAI({ modelName: gpt-4, temperature: 0.7 }); // 2. 创建一个包装函数将ClawRecall的上下文转换为LangChain的Message格式 async function getChatHistoryWithMemory(conversationId: string) { const ctx memory.buildContext(conversationId); const messages [ new SystemMessage(ctx.systemPrompt), // 将记忆作为系统消息 ]; // 转换ClawRecall的历史消息为LangChain的Message对象 for (const msg of ctx.messages) { if (msg.role user) { messages.push(new HumanMessage(msg.content)); } else if (msg.role assistant) { messages.push(new AIMessage(msg.content)); } } return messages; } // 3. 在对话流程中使用 async function handleLangChainChat(conversationId: string, userInput: string) { // 存储用户输入 memory.addMessage(conversationId, { role: user, content: userInput }); // 获取带有记忆的聊天历史 const messageHistory await getChatHistoryWithMemory(conversationId); // 调用LangChain模型 const response await model.invoke(messageHistory); const aiReply response.content.toString(); // 存储AI回复 memory.addMessage(conversationId, { role: assistant, content: aiReply }); return aiReply; }4.3 场景三为自动化工作流Agent赋予记忆假设你有一个自动处理GitHub Issue的Agent你需要它记住对不同仓库、不同用户的处理习惯。import { ClawRecall } from clawrecall; const workflowMemory new ClawRecall({ dbPath: ./workflow_memory.db }); // 为每个“仓库-作者”组合创建一个独特的conversationId确保记忆隔离 function getConversationId(repo: string, author: string) { return github:${repo}:${author}; } async function handleNewIssue(issue: GitHubIssue) { const cid getConversationId(issue.repo, issue.author.login); // 首次遇到此作者初始化永久层记忆。 const tiers workflowMemory.getTiers(cid); if (!tiers.permanent) { workflowMemory.setTier(cid, permanent, 作者 ${issue.author.login} 是 ${issue.author.company || 个人开发者} 的成员。过往提交风格偏向${issue.author.commitHistoryStyle || 未知}。); } // 记录本次Issue workflowMemory.addMessage(cid, { role: user, content: [Issue #${issue.number}] ${issue.title}: ${issue.body} }); // 基于记忆和历史决定如何处理例如分配标签、责任人 const ctx workflowMemory.buildContext(cid); const decision await aiDecideIssueAction(ctx, issue); // 你的决策逻辑 // 记录Agent的决策 workflowMemory.addMessage(cid, { role: assistant, content: 决策${decision.action}。理由${decision.reason} }); workflowMemory.setTier(cid, decisions, 对于 ${issue.repo}#${issue.number} 采取了 ${decision.action} 因为 ${decision.reason}); // 每周对每个活跃对话组进行压缩提炼模式 // ... (定时任务逻辑) }注意事项conversationId的设计是关键。它决定了记忆的隔离粒度。太粗如所有用户用一个ID会导致记忆混乱太细如每条消息一个ID则无法形成有效的长期记忆。通常根据业务逻辑按用户、按会话、按项目/主题来划分是合理的。5. 高级配置、性能调优与故障排查当你的Agent应用从原型走向生产环境时需要对ClawRecall进行更细致的调优并了解如何排查可能出现的问题。5.1 数据库性能与可扩展性ClawRecall使用SQLite在大多数中小规模场景下每秒几十到几百次读写性能完全足够。但为了获得最佳性能可以注意以下几点连接池与单例确保在你的应用中ClawRecall实例是单例的。反复创建和销毁实例会导致数据库连接开销。在Web服务器中通常在应用启动时初始化一个全局实例。WAL模式ClawRecall默认启用了SQLite的WALWrite-Ahead Logging模式。这显著提升了读写并发性能。你无需额外配置。索引优化库内部已经为conversation_id和created_at等关键字段创建了索引以加速按对话组和时间范围的查询。如果你的数据量极大数千万条消息并且主要按其他字段如role查询可能需要考虑自定义索引但这通常不是瓶颈。数据库文件位置将数据库文件放在高性能的SSD存储上避免网络存储如NFS以降低I/O延迟。5.2 Token预算的精细调整默认的8000/2000/6000预算分配是一个良好的起点但需要根据你的具体模型和场景调整。模型上下文窗口首先确认你使用的LLM模型的上下文窗口大小。如果是claude-3-5-sonnet-20241022200K那么8000的总预算绰绰有余甚至可以调高以容纳更多历史。如果是gpt-3.5-turbo16K8000则是一个比较保守安全的值。记忆层预算tiers如果你希望Agent记住非常详细的用户画像或复杂的项目背景可以适当增加此预算例如设为4000。但要注意这也会挤占历史消息的空间。历史消息预算history这个值决定了对话的“回溯长度”。如果你的对话通常很长且信息密集提高此值很重要。一个经验法则是history预算应至少能容纳10-20轮典型的问答交互。动态预算ClawRecall的配置是实例级别的。一个高级技巧是根据conversationId的不同类型动态创建不同配置的实例。例如对VIP用户使用更大的total预算对普通用户使用较小的预算。const memoryPool { vip: new ClawRecall({ dbPath: ./memory.db, tokenBudget: { total: 16000, tiers: 4000, history: 12000 } }), standard: new ClawRecall({ dbPath: ./memory.db, tokenBudget: { total: 8000, tiers: 2000, history: 6000 } }), }; function getMemoryForUser(userTier: vip | standard) { return memoryPool[userTier]; }5.3 压缩策略与成本控制AI压缩是核心功能但也涉及成本和稳定性。压缩频率compact操作调用AI API有成本和延迟。对于低频对话如几天一次可能不需要每天压缩可以设置为每周或每两周。对于高频对话如客服机器人每天一次是合理的。你可以在compact方法前加一个判断如果自上次压缩后新增消息少于N条则跳过本次压缩。压缩窗口windowDays默认分析最近7天的消息。对于快速变化的对话可以缩短到3天让记忆更聚焦于近期。对于长期项目讨论可以延长到30天。失败处理网络波动或API限流可能导致压缩失败。务必在调用compact时添加try-catch并做好日志记录。压缩失败不应影响主聊天流程记忆系统会回退到使用未压缩的旧摘要和更长的原始历史功能依然可用只是效率会逐渐降低。备用模型目前压缩硬编码使用了Claude Haiku。如果未来需要支持其他模型如GPT-3.5-Turbo可以 fork 库并修改内部的压缩提示词和API调用逻辑。这是一个相对高级的定制点。5.4 常见问题与排查技巧在实际使用中你可能会遇到以下情况问题1buildContext返回的历史消息比预期的少很多。排查首先检查context.tokenUsage。很可能tiers层的内容特别是permanent层写得过于冗长占用了大量预算导致留给history的预算所剩无几。解决精简permanent层的描述使用更简洁的语句。或者适当提高tokenBudget.total或调整tiers/history的比例。问题2Agent似乎“忘记”了很早以前手动设置的permanent信息。排查调用memory.getTiers(conversationId)检查该层当前内容。很可能后续执行的compact操作在AI总结时“改写”或“遗漏”了你手动设置的信息。解决AI压缩不是完全可靠的。对于极其重要、不容篡改的信息如用户ID、合同条款建议不要完全依赖压缩生成的permanent层。可以采取混合策略将这些核心信息存储在你自己应用的数据库里每次调用buildContext前通过setTier动态写入。或者在压缩后再手动用setTier把核心信息补充/覆盖回去。问题3数据库文件体积增长过快。排查SQLite文件变大是正常的因为compact只是归档消息并非物理删除。使用SQLite命令行工具查看表大小sqlite3 your.db “SELECT name, COUNT(*) as count FROM messages GROUP BY conversation_id ORDER BY count DESC LIMIT 10;”可以查看哪个对话组的消息最多。解决如果确定不需要归档数据可以定期执行清理谨慎操作。例如创建一个脚本删除archived 1且时间超过90天的消息。务必先备份# 示例清理命令 (在应用停止时执行) sqlite3 ./data/memory.db DELETE FROM messages WHERE archived 1 AND created_at datetime(now, -90 days); VACUUM;问题4在多进程/多服务器部署下SQLite文件被锁定了。排查SQLite在高并发写操作下可能遇到SQLITE_BUSY错误。虽然WAL模式改善了这一点但如果你有多个Node.js进程同时写入同一个文件仍可能发生。解决为每个进程分配不同的数据库文件不推荐会导致记忆分裂。使用中心化存储对于真正的分布式部署SQLite可能不再是最佳选择。你可以考虑修改ClawRecall的存储层将其适配到PostgreSQL或MySQL。这需要修改其内部的Storage类工程量较大但可行。使用文件锁或外部进程管理更简单的方案是确保同一时间只有一个进程实例在运行例如通过PM2的cluster模式限制实例数或使用一个专门的内存管理微服务。问题5压缩API调用超时或返回错误。排查检查网络连接和Anthropic API密钥配额、速率限制。解决实现指数退避重试机制。为compact调用设置合理的超时时间如60秒超时后自动放弃本次压缩。考虑在非高峰时段执行压缩任务。6. 架构启示从ClawRecall看AI记忆系统的设计通过深度使用和剖析ClawRecall我们可以提炼出一些设计AI Agent记忆系统的通用原则这些原则即使在你未来自研记忆模块时也同样适用。原则一记忆是结构化的摘要而非原始数据的堆砌。直接存储和检索所有原始对话是效率最低下的方式。ClawRecall通过“三层摘要”将海量信息压缩成高密度的知识点。这启示我们在设计记忆时首先要定义好信息的“抽象层级”哪些是永恒事实哪些是阶段性总结哪些是决策逻辑。不同的层级其更新频率、重要性和存储形式都应不同。原则二预算意识必须贯穿始终。Token就是金钱也是性能。任何记忆系统在设计时都必须回答一个问题“如何在有限的Token预算内传递最大的信息价值” ClawRecall的预算分配算法是一个很好的范例。更高级的系统甚至可以根据消息的“重要性评分”可通过嵌入向量相似度、关键词匹配、或一个轻量级模型实时打分来动态选择哪些历史消息入选而不是简单地按时间倒序。原则三本地化与云服务的权衡。ClawRecall选择了“本地存储 可选云API”的混合架构。这平衡了性能、成本和控制权。对于绝大多数对数据隐私和延迟敏感的应用这是一个明智的选择。如果你的应用本身就是云原生的或者需要跨地域共享记忆那么一开始就采用云数据库如PostgreSQL或向量数据库可能更合适。关键在于记忆存储层应该被设计成可插拔的。原则四压缩遗忘是记忆的一部分。人类的记忆会遗忘AI的记忆也需要“主动遗忘”机制。压缩Compaction就是一种优雅的、有信息提炼的“遗忘”。它避免了数据库的无限膨胀并将琐碎细节升华为知识。在设计压缩策略时要考虑频率多久压缩一次、深度分析多长的历史、以及成本使用何种模型。原则五评估记忆的有效性。如何知道你的记忆系统是否真的让Agent更“聪明”了需要建立评估体系。可以设计一些测试用例比如一致性测试在长对话中询问Agent之前提过的用户偏好看它是否能准确回答。相关性测试提供一段很长的历史看Agent生成的回复是否与早期关键信息相关而不是仅基于最后几条消息。Token效率测试对比使用记忆系统前后达到相同对话效果所消耗的平均Token数。ClawRecall作为一个库没有内置这些评估工具但这正是开发者可以在此基础上构建的价值。最后ClawRecall的简洁性既是其优点也意味着它可能不适合所有场景。例如它不支持基于语义的相似性搜索这是向量数据库的强项也不处理多模态记忆。但对于需要快速为Agent添加可靠、可控、低成本长期记忆的绝大多数文本型应用来说它提供了一个近乎完美的起点。它的设计哲学提醒我们在AI工程化落地的过程中有时候一个目标明确、边界清晰、简单可靠的解决方案远比一个功能庞大但复杂的系统更有生命力。