AI编程本地持久记忆：无需Embeddings的轻量方案

平时用 AI Coding 工具写代码最让人烦躁的往往不是模型能力不够而是“它又忘了”。改完一个文件重新开一轮对话还要把项目背景、技术栈、刚才改到哪一步重新讲一遍。如果正在用多 Agent 协作的 AI 编程工作流问题更明显每个 Agent 各干各的上下文互相不通A Agent 刚确认过的技术方案B Agent 又按自己的理解写了一遍甚至把已经否决的方案重新实现出来。最近在 Hacker News 上看到一个名为Llmem的项目标题很直接“Show HN: Llmem – Local persistent memory for AI coding, no embeddings”。核心卖点就三个词本地、持久、不使用 embeddings。这篇文章不打算只做项目介绍而是围绕“AI 编程的本地持久记忆”这个方向做一次系统拆解包括它要解决什么问题、no-embeddings 方案为什么值得关注、以及一套不依赖向量库的参考实现方便你理解这类工具的设计思路也方便你在自己的 AI 编程工作流里动手试试。阅读本文你会掌握AI Coding Agent 为什么需要“记忆”它和上下文窗口有什么区别带 embeddings 的记忆方案与不带 embeddings 的方案各自的取舍是什么如何用 SQLite 实现一个极简的本地持久记忆模块把记忆模块接入 AI 编程工作流时应该注意哪些坑和工程化建议。1. AI Coding 工具的“记忆”瓶颈1.1 什么是 AI Coding Agent 的“记忆”要理解 Llmem 这类工具的价值得先看 AI 编程工具目前的记忆方式。当前主流 AI Coding 工具包括各类 IDE 插件、CLI Agent、AutoGPT 风格的自主编程 Agent大多采用“会话式上下文”工作模式。它的工作过程可以简化成三步接收用户的自然语言指令结合当前代码库、文件内容、对话历史组成上下文调用大模型生成代码或执行终端操作。问题在于这个上下文是临时的。对话轮次一旦结束、终端会话一旦关闭、或者 Agent 上下文长度超限被截断模型就“失忆”了。下一次启动它只能重新读取代码库但无法记住项目里哪些约定是团队刚定下来的这个 bug 之前排查到哪一步、已经否定了哪些方案用户偏好用 TypeScript 还是 JavaScript、测试框架选 Vitest 还是 Jest上一次重构时哪些文件已经迁移完哪些还没动。这就是“记忆”和“上下文窗口”的本质区别上下文窗口是短时记忆容量有限对话结束就清空持久记忆是长时记忆能跨会话保留供后续请求反复读取。AI 编程要从“能写代码”进化到“能持续维护项目”缺少的就是长时记忆。1.2 现有记忆方案的两条技术路线目前业界做 AI 编程记忆大体有两条路线。第一条是无限上下文 / 超长上下文窗口。通过扩展模型的上下文长度把所有历史信息一股脑塞进去。这种方式实现简单但成本随上下文长度快速上升且检索效率不高历史信息混在一起真正关键的决定容易被淹没。第二条是外部存储 向量检索。把对话历史、代码片段、设计文档转换成 embedding 向量存入向量数据库查询时做相似度检索。这也是目前很多 AI 编程工具和 RAG 方案的主流做法。但 embedding 方案并非没有代价需要额外调用 embedding 模型可能是远程 API也可能是本地模型都会增加延迟需要维护向量数据库引入新的基础设施相似度检索的结果是“模糊的”可解释性差你很难说清楚它为什么召回这条记忆在离线环境、内网环境或者本地资源有限的开发机上部署一套 embedding 向量库链路并不轻松。正是在这种背景下Llmem提出了一种更轻的思路本地持久记忆不需要 embeddings也能解决 AI 编程中的大部分记忆需求。1.3 本地持久记忆要解决的核心问题不管用不用 embedding一个可用的本地持久记忆系统都得回答下面四个问题问题说明存什么哪些信息值得被记住哪些只是噪音什么时候写在对话的哪个节点把信息沉淀到存储中怎么读用户或 Agent 如何快速找到与当前任务相关的记忆怎么失效旧记忆怎么清理避免信息过时和堆积Llmem 这类 no-embeddings 方案的思路是把其中“怎么读”这一步从向量相似度检索替换成更轻量的结构化查询和关键词匹配。2. Llmem 的核心思路本地、持久、无 embeddings2.1 “No embeddings”到底意味着什么很多文章一提到“AI 记忆”就默认必须做向量化。但 Llmem 的标题明确把“no embeddings”当成卖点说明它刻意放弃了一条被认为“理所当然”的路线。不使用 embeddings意味着整个系统不依赖 embedding 模型也不依赖向量数据库。具体来说没有 embedding 接口调用也就没有额外的网络依赖和费用没有向量索引构建写入记忆时不需要等待向量化完成没有相似度计算的抽象黑盒记忆的匹配逻辑直接可见、可调试整个系统可以完全跑在本地甚至跑在一台非常低配的开发机上。它的取舍也很明确放弃了语义相似检索的强大能力换取了简单、可控、离线可用。2.2 无 embedding 的本地记忆如何工作如果不用 embedding记忆检索怎么实现答案是用结构化数据 关键词匹配 元信息过滤。举个例子。假设 AI 编程 Agent 完成了一次“修复用户登录时 token 过期导致 401”的任务它可以把下面这段记忆写入本地存储{ id: 1024, content: 用户登录 token 过期时后端返回 401前端需要拦截并跳转 /login, source: auth_module_fix, tags: [auth, token, login, 401], importance: 0.8, created_at: 1718000000 }下次用户提问“登录又 401 了怎么回事”Agent 检索记忆时可以做两件事用关键词登录、401、token在记忆库里做匹配根据匹配度、创建时间、重要程度给候选记忆排序挑出最相关的几条注入提示词。这种方案检索不到“用户认证失败”这种完全不同的表述但对于编程场景里大量明确、可枚举的专业术语来说关键词匹配已经能解决很大一部分问题。这就是 Llmem 这类工具敢于去掉 embeddings 的底气。2.3 从 Show HN 看 Llmem 的项目定位“Show HN”是 Hacker News 上专门展示个人项目、开源作品的一个板块。作者把自己的工具发布上去接受社区反馈。这通常意味着项目处于早期阶段文档和 API 可能变化较快但它代表了一个明确的产品趋势AI 编程的记忆机制正在从“云端、重量级”走向“本地、轻量级”。从标题提供的信息看Llmem 面向的是 AI 编码场景强调 local本地和 persistent持久。如果你想实际使用它建议直接查看项目仓库的 README 和示例代码重点确认三件事支持哪些编程语言或框架接入记忆条目如何定义和存储与其他工具如 Claude Code、Cline、Continue 等的集成方式。因为项目仍可能快速迭代本文后面给出的示例不直接绑定 Llmem 的 API而是实现一个与它同思路的迷你版本地持久记忆模块。理解了这个模块你再去看 Llmem 的源码或文档会轻松很多。3. 环境准备与演示项目结构在开始写代码前先明确一下环境。下面这个参考实现只使用 Python 标准库不依赖第三方包。它的核心存储引擎是 SQLite所以只需确认本机 Python 版本在 3.9 以上即可。如果你的电脑上还没有 Python去官网下载安装后通过下面命令验证python --version # 建议输出 Python 3.9 或更高版本SQLite 是 Python 内置支持的轻量级数据库不需要单独安装服务端非常适合做本地开发工具的记忆存储。3.1 项目目录结构为了演示清晰我们创建一个简单的项目结构local-memory-demo/ ├── memory_store.py # 记忆存储核心模块 ├── cli_demo.py # 命令行演示脚本 ├── memories.db # SQLite 数据库文件运行时自动生成 └── README.md # 说明文档可选当然实际项目中你完全可以把memory_store.py改名为llmem_client.py或者嵌入到你自己的 Agent 工具代码库里。4. 参考实现no-embeddings 本地持久记忆模块4.1 初始化数据库首先实现存储模块的骨架。它的职责是创建数据库表、支持写入记忆、按关键词检索记忆、清理过期记忆。下面是memory_store.py的完整代码# memory_store.py import json import math import sqlite3 import time from pathlib import Path from typing import Dict, List, Optional class LocalMemoryStore: 一个极简的本地持久记忆存储模块。 不使用 embedding使用 SQLite 关键词匹配实现记忆读写。 def __init__(self, db_path: str memories.db): self.db_path Path(db_path) self._init_db() def _get_connection(self) - sqlite3.Connection: conn sqlite3.connect(self.db_path) conn.row_factory sqlite3.Row return conn def _init_db(self) - None: conn self._get_connection() try: conn.execute( CREATE TABLE IF NOT EXISTS memory_entries ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, source TEXT DEFAULT , tags TEXT DEFAULT [], importance REAL DEFAULT 0.5, created_at REAL NOT NULL, last_accessed_at REAL, access_count INTEGER DEFAULT 0 ) ) conn.commit() finally: conn.close()这里有几处设计值得注意tags字段用 JSON 数组存储标签方便后续做精确匹配importance是人工或 Agent 写入记忆时标记的重要程度取值范围建议 0 到 1created_at存 Unix 时间戳体现“创建时间”last_accessed_at和access_count用于记录记忆被访问的情况后续可以做热度衰减。4.2 写入记忆写入记忆的方法如下def add_memory( self, content: str, source: str , tags: Optional[List[str]] None, importance: float 0.5, ttl: Optional[int] None, ) - int: 写入一条记忆。 :param content: 记忆内容 :param source: 来源例如模块名、Agent 名称 :param tags: 标签列表 :param importance: 重要程度 0~1 :param ttl: 生存时间秒超过后检索时自动忽略 :return: 新记忆 id if not content or not content.strip(): raise ValueError(content 不能为空) conn self._get_connection() try: cur conn.execute( INSERT INTO memory_entries (content, source, tags, importance, created_at) VALUES (?, ?, ?, ?, ?) , ( content.strip(), source, json.dumps(tags or [], ensure_asciiFalse), float(importance), time.time(), ), ) conn.commit() return cur.lastrowid finally: conn.close()注意ttl参数暂时还没有落到表结构里。要支持过期逻辑有两种方式在表中增加expire_at字段写入时计算过期时间在查询时用created_at和ttl一起判断。为了简化演示我们采用第二种方式在检索时传入ttl_filter参数由调用方决定多长时间以内的记忆才算有效。4.3 关键词检索与排序这就是 no-embeddings 方案的关键部分。我们不用向量相似度而是把候选记忆取出来在 Python 中计算一个简单的相关分。def search_memory( self, query: str, limit: int 5, ttl_filter: Optional[int] None, ) - List[Dict]: 按关键词检索记忆。 匹配规则content 包含任意查询词或 tags 包含任意查询词。 # 把查询拆成关键词 words [w.strip() for w in query.replace(, ).replace(,, ).split()] words [w for w in words if w] if not words: return [] conn self._get_connection() try: # 先从数据库里挑出候选 conditions [] params [] for word in words: conditions.append((content LIKE ? OR tags LIKE ?)) pattern f%{word}% params.append(pattern) params.append(pattern) where_clause OR .join(conditions) rows conn.execute( f SELECT * FROM memory_entries WHERE {where_clause} ORDER BY created_at DESC LIMIT ? , [*params, limit * 5], ).fetchall() # 在 Python 里做二次打分排序 now time.time() scored [] for row in rows: content row[content] tags json.loads(row[tags] or []) created_at row[created_at] importance row[importance] # TTL 过滤 if ttl_filter is not None and (now - created_at) ttl_filter: continue # 基础分内容命中多少词 hit_count sum(1 for w in words if w in content) tag_hit sum(1 for w in words if w in tags) if hit_count 0 and tag_hit 0: continue # 时间衰减系数24 小时为半衰期 age_hours (now - created_at) / 3600 time_decay math.exp(-age_hours / 24) score (hit_count * 2 tag_hit * 1.5) * importance * time_decay scored.append( { id: row[id], content: content, source: row[source], tags: tags, importance: importance, created_at: created_at, score: round(score, 4), } ) scored.sort(keylambda x: x[score], reverseTrue) return scored[:limit] finally: conn.close()这段代码体现了三个关键思路先粗筛再精排。先用 SQL 的 LIKE 减少数据量再用 Python 计算排序分避免在数据库里写复杂函数时间衰减。math.exp(-age_hours / 24)让记忆在 24 小时后相关度减半避免很久以前的碎片长期占据高位重要程度参与排序。同样命中的记忆人工标记为高优先级的会更先被读取。4.4 清理与统计记忆系统不能只进不出。我们提供一个简单的清理方法def cleanup_expired(self, max_age_hours: float 24 * 30) - int: 清理超过指定小时数且从未被再次访问的旧记忆。 返回删除条数。 deadline time.time() - max_age_hours * 3600 conn self._get_connection() try: cur conn.execute( DELETE FROM memory_entries WHERE created_at ? AND access_count 0 , (deadline,), ) conn.commit() return cur.rowcount finally: conn.close() def stats(self) - Dict: conn self._get_connection() try: total conn.execute(SELECT COUNT(*) AS c FROM memory_entries).fetchone()[c] return {total: total} finally: conn.close()这里的清理策略是“超过 30 天且从未被访问过的记忆直接删除”。如果一个记忆被多次读取说明它仍然活跃即使旧一些也值得保留。更复杂一点的系统可以根据记忆的access_count做热度分级这里为了保持代码简洁不做过度设计。4.5 命令行演示为了让上面的模块可以直接运行我们再写一个简单的cli_demo.py# cli_demo.py from memory_store import LocalMemoryStore def main(): store LocalMemoryStore(memories.db) # 写入几条示例记忆 store.add_memory( content用户登录 token 过期时后端返回 401前端需要拦截并跳转 /login, sourceauth_module_fix, tags[auth, token, login, 401], importance0.9, ) store.add_memory( content项目测试框架使用 Vitest不使用 Jest, sourceteam_standard, tags[test, vitest, standard], importance0.8, ) store.add_memory( content订单状态变更后需要发送 WebSocket 通知, sourceorder_service, tags[order, websocket], importance0.6, ) print(当前记忆量, store.stats()[total]) # 检索测试 print(\n--- 查询登录 401 ---) for item in store.search_memory(登录 401, limit3): print(item[score], item[content]) print(\n--- 查询测试框架 ---) for item in store.search_memory(测试框架, limit3): print(item[score], item[content]) if __name__ __main__: main()运行结果期望类似这样当前记忆量 3 --- 查询登录 401 --- 1.7951 用户登录 token 过期时后端返回 401前端需要拦截并跳转 /login 0.0 项目测试框架使用 Vitest不使用 Jest --- 查询测试框架 --- 0.799 项目测试框架使用 Vitest不使用 Jest不同的机器、不同时间的运行结果会因时间衰减稍有差异但排序逻辑直观可见。4.6 如何与 AI Coding 工作流结合上面的LocalMemoryStore只是存储与检索基础模块。真正接入 AI 编程工作流时还需要一个“调度层”负责决定何时读取记忆、何时写入记忆。一个可参考的接入流程用户发起新任务Agent 先从本地记忆库中检索与任务描述最相关的 3~5 条记忆将这 3~5 条记忆追加到系统提示词中再调用大模型任务结束后Agent 把本次任务中值得沉淀的信息关键决策、踩坑结论、用户偏好写入记忆库定期运行cleanup_expired防止记忆库无限膨胀。关键点在第 2 步记忆检索应该发生在模型调用之前而不是之后。你可以把它理解为“给模型开场前塞小抄”而不是“让模型自己翻笔记本”。在具体实现上如果接入的是 Claude Code、Cline 这类已有 Agent 框架的项目通常可以通过自定义插件或工具调用的方式实现上述流程。Llmem 这类项目很可能就是在扮演这个“记忆底座”的角色。5. embeddings 方案与 no-embeddings 方案对比5.1 一张表看清差异关于 Llmem 出现的背景最好用一个表格对比两种方案在不同维度上的差异对比维度Embeddings 向量库No-embeddingsLlmem 思路数据存储向量数据库 元数据存储本地数据库 / JSON / 文本文件写入成本需要调用 embedding 模型生成向量直接写入零额外计算检索能力语义相似检索能处理近义表述关键词/标签匹配依赖术语一致性可解释性较差向量相似度难以解释较好可明确看到命中词和排序规则离线支持依赖 embedding 模型和向量库部署天然离线可用维护复杂度中等偏高低隐私保护取决于 embedding 服务部署位置数据完全本地适用项目规模中大型、记忆量大、语义模糊场景个人开发机、中小项目、术语固定场景5.2 什么时候选 no-embeddings 方案结合 AI 编程的实际场景下面这些情况更适合 Llmem 这类轻量方案本地开发环境。开发者电脑上资源有限不想为了一个记忆功能再启一个向量数据库容器。离线或内网环境。不允许把代码片段、业务信息发送到外部 embedding 服务。记忆以“明确术语”为主。编程场景中的关键词通常很固定函数名、文件名、框架名、报错信息、接口路径这些内容用关键词匹配效果不差。希望记忆行为可控、可调试。开发过程中如果发现记忆检索不准向量方案往往要调 embedding 模型、调向量库参数很玄学而关键词方案可以直接查看排序逻辑改起来明确。5.3 什么时候还是要用 embeddings当然no-embeddings 并不是万能的。如果遇到下面这些情况还是建议考虑 embedding 方案记忆条目非常多比如上万条关键词检索很难覆盖所有表述用户提问方式高度口语化和存储的术语相差很远需要跨语言的语义匹配例如英文文档、中文提问混合需要根据语义聚类、推荐而不只是精确检索。实际工程中两种思路并不互斥。你完全可以用一个混合方案关键词检索作为第一层快速过滤语义检索作为第二层兜底两条路径的结果做加权融合。Llmem 提供的 no-embeddings 思路正好可以作为这套混合方案里最轻量的前置通道。6. 常见问题与排查思路6.1 记忆写入并发冲突SQLite 同一时刻只允许一个写事务。如果多个 Agent 或 IDE 插件进程同时写入记忆库可能出现database is locked报错。排查和解决思路用WAL模式可以减少读写锁冲突写入逻辑尽量集中到一个进程如果并发写入频繁可以加一层带重试机制的写入封装。6.2 关键词检索召回率低用户提问“用户认证失败”但存进去的记忆写的是“登录 token 过期”。两者语义一致表述不同关键词匹配就不灵了。解决这个问题不一定要上 embedding可以先尝试两个简单手段在写入时增加同义词标签例如“登录”和“认证”都写成标签在读取时做查询改写先让大模型把用户问题改写成多个可能的关键词组合再用这些组合做检索。第二种方式比全量 embedding 成本低很多效果提升也很明显。6.3 记忆噪音太多随着使用时间变长记忆库会积累大量低价值记录比如“今天把按钮颜色改成蓝色”。这类一次性信息对后续任务没有帮助。建议的做法是写入时降低importance定期执行cleanup_expired或者人工把重要的记忆固定为“置顶知识”。从实现上说可以在表里加一个pinned字段置顶记忆不参与时间衰减。6.4 数据隐私和误用本地记忆库保存的是开发过程中的对话和代码结论。如果电脑被多人使用或者代码仓库被同步到第三方平台这些记忆可能被泄露。建议遵守以下边界不要写入任何密码、Token、密钥不要把客户敏感数据写进记忆库如果记忆库文件放在项目目录下记得加入.gitignore对记忆库文件设置较严格的文件系统权限。问题现象常见原因解决思路database is locked多进程并发写开启 WAL、集中写入、加重试检索不到相关记忆表述不一致增加同义词标签、查询改写记忆越积越多缺少过期机制设置 TTL、定期清理敏感信息泄露风险把密钥写入记忆禁止写入凭据、加 .gitignore7. 最佳实践给本地记忆系统加工程化护栏如果你准备把 no-embeddings 本地记忆方案用到真实项目中下面这些建议值得参考。7.1 记忆条目要“原子化”一条记忆只保存一个结论。不要把“今天完成了登录模块、修了 401、顺便调整了按钮样式”写成一条。拆成三条独立记忆检索时才能精确命中。原子化也让去重和更新变得更加容易。7.2 给记忆带上来源和可信度记忆库会同时保存 Agent 自动生成的记录和人工手动整理的知识它们的可信度不同。建议在表结构中增加source和confidence两个字段source记录来源比如agent_auto、user_manual、code_reviewconfidence可信度比如 0~1。检索时如果结果条数过多可以优先返回人工知识标记的记录。7.3 设计“更新”而不是“追加”同一个主题的记忆可能会更新。比如项目一开始定下“用 Jest 做测试框架”两周后改成“用 Vitest”。如果只追加不更新检索时会同时出现两条相反结论。建议在写入前做一次检索如果发现相似记忆已经存在就更新旧记录的内容而不是插入新记录。可以用(source, tags)作为去重键也可以由调用方传入replace_id。7.4 记忆库文件必须纳入版本管理范围之外如果记忆库文件放在代码仓库内部务必将它加入.gitignore# .gitignore 示例 memories.db memories.db-journal memories.db-wal memories.db-shm记忆是开发者的私密上下文不应被同步到公共仓库。7.5 检索逻辑要可测试、可回放记忆系统的难点不在写入而在“检索准确性”。建议给检索模块编写确定性测试准备一份固定的测试记忆集写一批固定的查询词断言排序结果是否符合预期修改排序算法后能通过回归测试验证效果没变差。这套测试能把记忆系统的行为“锁住”避免以后优化时误伤已有场景。7.6 在 Agent 工作流中明确记忆读取位置记忆不是万能的也不是所有任务都必须读记忆。建议按任务类型区分涉及项目整体架构、既有实现时优先读记忆纯算法写作、一次性脚本生成可以不读记忆节省 token超过一定轮次的对话在每轮开始前重新检索一次记忆避免信息过期。把记忆读取设计成“按需注入”而不是“全部塞入”信息密度更高模型专注度也会更好。8. 总结与后续学习路线本文从一个开源项目标题出发拆解了 AI 编程场景下“本地持久记忆”的需求背景也解释了 Llmem 为什么把“no embeddings”当作卖点。随后用 Python 标准库实现了一个迷你版本地记忆模块覆盖了写入、关键词检索、时间衰减排序和过期清理并探讨了它与 embedding 方案的边界和取舍。核心收获可以归纳为三点AI 编程工具的长时记忆不一定要靠向量数据库才能实现结构化字段、关键词匹配、时间衰减足以覆盖大量编程语境下的记忆场景老工具、老思路在 AI 时代仍然有实用价值关键是你理解业务约束是什么。如果你对这个方向感兴趣下一步可以沿着三条线继续深入读 Llmem 的源码看你能否找到与本文实现对应的设计决策把LocalMemoryStore接入一个开源 Agent 工具做一个“带记忆的代码审查助手”练手在检索层做一次升级加入查询改写和 TF-IDF 加权看看在不引入 embedding 的情况下检索精度能提升多少。记忆系统没有银弹最合适的方案永远是结合你的数据量、硬件条件、离线需求和隐私约束综合权衡的结果。希望这篇文章能给你一条新的思考路径也欢迎在评论区聊聊你正在使用的 AI 编程记忆方案。