重构AI代理记忆：TypeScript与SQLite-vec实现本地多层存储方案
为什么AI代理需要多层记忆
在大模型应用的浪潮中，AI代理的交互体验很大程度上依赖于其“记忆”能力。然而，现有的大多数实现方式要么是简单的上下文窗口截断，要么是直接调用昂贵的云端向量数据库。对于许多开发者而言，特别是那些关注隐私保护、成本控制或离线工作的项目，后者显得既昂贵又不必要。本文旨在打破这种依赖，展示如何利用TypeScript生态和SQLite-vec库，在本地构建一个真正的多层记忆系统。
AI代理的记忆通常可以分为三个层面：首先是短暂的工作记忆，用于当前对话的上下文；其次是语义化的长期记忆，存储了关于实体、概念和过往事件的知识；最后是程序化的程序记忆，即代理在运行过程中学习到的特定技能或策略。传统的单一存储模型往往难以在性能、成本和功能之间取得平衡。本文介绍的方案通过SQLite作为底层存储引擎，利用sqlite-vec扩展实现向量搜索能力，将这三类记忆物理上分层存储，既利用了关系型数据库的事务安全，又获得了向量检索的高效性。
项目搭建与依赖配置
要开始构建这个本地记忆系统，首先需要确保环境具备TypeScript编译能力。核心依赖包括@aspect/sqlite用于数据库操作，以及sqlite-vec用于向量索引和相似度计算。在package.json中配置时，需要特别注意sqlite-vec的 native bindings（原生绑定），这意味着在构建过程中可能需要调用c-bindings编译步骤，这在Windows或macOS的不同架构下可能会有所不同，建议在CI/CD流水线中提前进行验证。
初始化数据库连接的代码片段相对 straightforward（直接）。使用TypeScript的 async/await 模式，可以轻松打开一个 SQLite 数据库文件。关键点在于加载 sqlite-vec 扩展，这通常在打开数据库连接后通过特定的 SQL 命令或 API 调用完成。这一步骤一旦成功，数据库就不再是纯粹的关系型存储，而是具备了高维向量空间的能力，可以存储嵌入向量并进行快速的最近邻搜索。
设计多层模式 schema
设计数据库 Schema 时，文章提出了一个统一的但分层的理念。并不需要三张完全独立的表，而是通过字段类型和索引策略来区分记忆的属性。例如，可以设计一张主记忆表，其中包含一个 type 字段用于区分记忆的种类：是用于短期对话上下文的“episodic”类型，还是用于长期知识的“semantic”类型，又或者是标记了特定业务逻辑的“procedural”类型。
对于语义记忆，利用 sqlite-vec 的 VECTOR 类型可以定义向量列。设置合适的嵌入模型维度至关重要，常见的有 1536 维（OpenAI embeddings）或 768 维。除了向量列，还需要为向量创建全文检索索引或 HNSW（Hierarchical Navigable Small World）图索引，以确保在数据量增长时检索速度不受影响。文章详细描述了如何在建表语句中结合普通字段（如内容、时间戳、来源）与向量字段，创建一个既能精确查询又能模糊语义匹配的混合存储结构。
构建记忆存储模块
在实际编码中，封装一套清晰的 CRUD（增删改查）接口是提高可维护性的关键。文章提供了几个核心函数的实现思路。首先是存储新记忆的函数，它需要接收原始文本、生成对应的嵌入向量（这通常需要调用外部的 embedding service，如 OpenAI 的 text-embedding-ada-002 或本地的 sentence-transformers 模型），然后将文本和向量统一插入 SQLite 数据库。
其次是检索接口。这里展示了两种典型的查询模式：一种是基于关键词的精确匹配，利用 SQLite 的 LIKE 或全文搜索功能；另一种是向量相似度搜索，通过计算余弦相似度或欧氏距离，返回最相关的几条记录。值得注意的是，文章强调了向量搜索并非万能钥匙，对于需要严格业务逻辑约束的查询，仍需结合 SQL 的 WHERE 子句进行过滤，以避免“幻觉”或无关信息的干扰。
将记忆接入代理循环
构建存储模块之后，下一步是将其无缝集成到 AI 代理的运行循环中。这不仅仅是数据的存取，更是记忆的动态调用。在每一次用户输入或代理思考之前，系统需要决定调用哪一层记忆。例如，对于当前对话的连贯性，优先查询短期的 episodic 记忆；而当用户询问“上周我们讨论过的话题”时，则需要跨越时间跨度去语义记忆中检索。
文章举了一个具体的场景：一个客服代理。当用户提出问题时，代理首先查询最近的对话记录以保持语境连贯；如果问题涉及公司政策或产品手册，代理则触发语义搜索，在长期知识库中寻找答案。这种“热冷分层”的访问模式，有效避免了将所有信息塞入有限的上下文窗口，既提高了响应速度，又降低了因上下文溢出导致的逻辑混乱风险。
性能考量与优化实践
任何本地存储方案的性能都取决于索引的质量和查询的编写。sqlite-vec 提供了丰富的配置选项，其中最关键的是 HNSW 参数的调优。HNSW 是一种基于图的近似最近邻搜索算法，它在精确度和搜索速度之间提供了可调的平衡点。在数据量较小的情况下，可以使用较低的 M 参数以减少内存占用；随着数据量的增长，增大 M 和 efSearch 参数可以保证更高的检索精度。
此外，文章还讨论了批量写入与事务处理的重要性。频繁的单条 INSERT 操作会因为 SQLite 的 WAL（写时复制）机制导致性能下降。建议在记忆录入阶段，将多条记忆打包成一个事务提交。这不仅能显著提升写入吞吐量，还能确保在系统崩溃时的数据一致性。对于嵌入向量的生成，如果是本地模型，还需要考虑模型推理的耗时，可能需要引入异步队列来解耦向量生成与数据存储的操作。
测试与验证
代码的正确性最终需要通过测试来验证。文章建议编写一套涵盖插入、向量搜索、混合查询的测试套件。在测试环境中，可以模拟不同场景的记忆查询，检查返回的结果是否符合预期。特别需要关注的是向量相似度阈值的设置，这直接影响到检索结果的相关性。通过调整阈值，可以在“漏掉重要信息”和“返回过多噪音”之间找到最佳平衡点。
实际测试中，开发者可以利用 SQLite 自带的 .schema 命令查看表结构，利用 .import 命令导入测试数据，或者编写简单的 Node.js 脚本来交互式地验证向量搜索的效果。文章还提到，监控查询执行计划是优化性能的有效手段，了解 SQLite 是如何使用索引的，可以帮助及时发现瓶颈。
未来展望与拓展方向
展望未来，这种基于 SQLite 的本地记忆方案具有广阔的应用前景。随着端侧大模型（Edge AI）的发展，越来越多的计算将在设备本地完成。利用 SQLite-vec 实现的多层记忆， perfectly（完美）契合了这种“数据不出域、计算本地化”的趋势。对于多代理协作的场景，也可以考虑在数据库层面实现分布式锁或版本控制，确保不同代理对记忆的修改不会产生冲突。
此外，随着量化技术的进步，未来有可能在 SQLite 中直接存储量化向量，进一步降低内存成本，提升检索效率。文章结尾呼吁开发者们尝试打破对云服务的依赖，利用开源工具重新定义 AI 代理的内存边界。无论是个人项目还是企业级应用，这种本地化、模块化的记忆架构都为提升 AI 系统的可控性和安全性提供了坚实的技术基础。