1. 项目概述与核心定位

1.1 这个项目到底在解决什么问题

做过AI辅助开发的朋友大概率都遇到过这个场景：跟AI助手聊了半小时，把项目架构、命名规范、踩过的坑都交代得清清楚楚，结果关掉窗口再开一个新的对话，它就像失忆了一样，什么都不知道了。你得重新解释一遍项目背景，重新说明代码风格，重新强调哪些方案已经试过不行。这种重复劳动消耗的时间，累积起来相当可观。

claude-mem这个项目瞄准的就是这个痛点。它的核心思路很直接：给AI助手装一个持久化的记忆层，让它在不同会话之间能够记住关键信息，包括项目上下文、用户偏好、历史决策、技术栈选型等等。你可以把它理解成一个专门为AI编程助手服务的"外部大脑"，所有值得留存的信息都写进去，下次对话时自动加载。

这个项目适合几类人：一是长期用AI辅助写代码的开发者，尤其是同时维护多个项目的人；二是需要AI保持角色一致性的内容创作者；三是任何觉得"每次都要重新调教AI"很烦的效率追求者。哪怕你只是偶尔用AI写写脚本，配好记忆层之后体验提升也是立竿见影的。

1.2 为什么是"记忆"而不是"更大的上下文"

很多人第一反应是：现在模型的上下文窗口不是越来越大了吗，直接塞进去不就行了？这个想法理论上没错，但实际用起来有几个硬伤。

第一，成本问题。上下文窗口越大，每次请求消耗的token越多，费用是线性增长的。你不可能每次对话都把整个项目的所有文档、所有历史决策全部塞进去，那样单次请求的成本会高到离谱。

第二，注意力稀释。上下文里塞的东西越多，模型对关键信息的注意力就越容易被分散。你把一百页文档丢进去，它可能反而抓不住你真正想强调的那三条规则。这是目前大模型的一个普遍特性，信息过载反而导致关键信息被淹没。

第三，结构化管理。记忆不是简单的文本堆砌，它需要分类、需要优先级、需要按需加载。比如"项目技术栈"这类信息每次都要带，"上周讨论过的某个临时方案"可能只在特定话题下才需要调出来。claude-mem的价值就在于它做了这层结构化管理，而不是无脑全量注入。

所以这个项目的定位不是"替代大上下文"，而是"让上下文用得更加精准高效"。它更像是一个智能的信息调度层，在合适的时机把合适的信息喂给模型。

1.3 整体架构的选型考量

claude-mem在架构上走的是轻量路线。核心组件通常包括三块：一个本地存储层（常见的是SQLite或者JSON文件），一个检索层（基于关键词或者向量相似度），一个注入层（负责在对话开始时把相关记忆拼接到提示词里）。

为什么选本地存储而不是云端数据库？主要是隐私和延迟两个考虑。开发者的项目信息、代码片段、决策记录都属于敏感数据，放在本地最放心。而且本地读写没有网络往返，响应速度更快，不会因为网络波动影响使用体验。

检索层为什么不做成纯向量检索？纯向量检索在语义匹配上确实强，但对于"精确匹配某个函数名"、"找回某个特定配置项"这类需求反而不如关键词检索靠谱。所以实践中常见的是混合检索：先用关键词做粗筛，再用向量做精排，兼顾召回率和准确率。

注入层是最考验设计的地方。全量注入会浪费token，注入太少又起不到作用。合理的做法是分级：核心记忆（比如项目基本信息和用户明确设定的规则）每次必带，次要记忆（比如历史对话摘要）按当前话题相关性动态加载。这个分级策略直接决定了整个系统的实用价值。

2. 核心细节解析与实操要点

2.1 记忆的分类体系怎么设计

记忆分类是整个项目的地基，分得好后面用起来顺风顺水，分得乱就是给自己挖坑。根据实际使用经验，我建议至少分成四类。

第一类是身份与偏好记忆。这类信息描述"你是谁"和"你喜欢什么"。比如你习惯用TypeScript而不是JavaScript，你偏好函数式写法而不是面向对象，你的代码注释用中文。这类记忆的特点是变化频率低、适用范围广，应该每次对话都加载。

第二类是项目上下文记忆。这类信息描述"当前在做什么项目"。包括项目名称、技术栈、目录结构、核心模块职责、部署方式等。这类记忆跟项目绑定，切换项目时应该整体替换。

第三类是决策与约束记忆。这类信息记录"哪些方案已经定了"和"哪些路走不通"。比如"数据库选型已经确定为PostgreSQL"、"不要用某个已经废弃的内部库"、"API返回格式统一用这个结构"。这类记忆极其重要，能避免AI反复建议你已经否决过的方案。

第四类是会话摘要记忆。这类信息是历史对话的浓缩版。每次对话结束或者达到一定轮次后，自动生成一段摘要存起来。下次遇到相关话题时调出来作为参考。这类记忆数量最多，必须做相关性过滤，不能全量加载。

注意：分类不是越细越好。我见过有人分了十几类，结果维护成本高到根本坚持不下去。四到六类是比较舒服的区间，既能覆盖主要场景，又不至于管理不过来。

2.2 存储格式的选择与字段设计

存储格式直接决定了检索效率和扩展难度。JSON文件胜在简单直观，用文本编辑器就能改，适合记忆条数在几百条以内的场景。一旦超过这个量级，检索就开始变慢，而且并发写入容易出问题。

SQLite是更稳妥的选择。单文件、零配置、支持全文检索（FTS5扩展），对于个人使用场景完全够用。表结构设计上，我推荐至少包含这几个字段：

priority和hit_count这两个字段容易被忽略，但实际很有用。priority让你能手动标记哪些记忆是"铁律"，必须优先加载。hit_count则是自动统计哪些记忆经常被用到，用得多说明价值高，可以在检索时给更高权重。

keywords字段的设计有个小技巧：不要只存内容里出现过的词，还要存"你可能会用什么词来问"。比如一条关于数据库配置的记忆，keywords里除了"PostgreSQL"、"连接池"，还应该加上"数据库"、"DB"、"存储"这些同义表达。这样检索时命中率会高很多。

2.3 检索策略的混合实现

检索是记忆系统的核心能力。做得糙一点就是简单的LIKE查询，做得精细一点就是关键词加向量的混合检索。我建议分三步走。

第一步是关键词粗筛。把用户当前输入拆成词，跟keywords字段做匹配。这一步要求快，所以用简单的字符串包含判断就行，不需要上分词器。匹配到的记忆进入候选集。

第二步是优先级加权。候选集里的每条记忆，根据priority和hit_count算一个分数。公式可以很简单：score = priority * 2 + log(hit_count + 1)。priority权重高是因为人工标记的优先级通常比自动统计更可靠。

第三步是数量截断。不管候选集有多大，最终注入的记忆条数要有个上限。经验值是核心记忆不超过10条，次要记忆不超过5条。超过这个数，注入的文本太长反而干扰模型。

def retrieve_memories(query, project, max_core=10, max_secondary=5): # 粗筛 candidates = db.query( "SELECT * FROM memories WHERE project=? OR project IS NULL", (project,) ) # 打分 scored = [] for mem in candidates: if any(kw in query for kw in mem.keywords.split(',')): score = mem.priority * 2 + math.log(mem.hit_count + 1) scored.append((score, mem)) # 排序截断 scored.sort(key=lambda x: x[0], reverse=True) core = [m for _, m in scored if m.category in ('identity', 'constraint')][:max_core] secondary = [m for _, m in scored if m.category not in ('identity', 'constraint')][:max_secondary] return core + secondary

这段逻辑不复杂，但效果比纯向量检索稳定得多。尤其是对于代码相关的查询，精确匹配关键词的召回质量明显更高。

2.4 注入时机的把握

记忆注入不是越早越好，也不是越多越好。时机和格式都会影响最终效果。

注入时机上，我建议在系统提示词之后、用户第一条消息之前插入。这样模型在开始处理用户请求时就已经带着记忆了，不需要在中途打断。如果对话轮次很多，可以在每5到10轮之后重新评估一次，看是否需要补充加载新的相关记忆。

注入格式上，用清晰的分段标记比纯文本拼接效果好。比如：

[项目记忆] 项目名称：xxx 技术栈：TypeScript + React + PostgreSQL 核心约束：API返回统一使用 {code, data, message} 结构 [用户偏好] 代码注释使用中文 优先使用函数式写法

这种带标签的格式让模型更容易区分不同来源的信息，也方便你在调试时快速定位问题。

提示：注入的记忆内容要精简。一条记忆控制在50字以内最佳，超过100字的记忆建议拆分成多条。模型对短句的利用率明显高于长段落。

3. 实操过程与核心环节实现

3.1 环境准备与依赖安装

先把基础环境搭起来。Python 3.9以上版本是必须的，因为要用到一些较新的语法特性。数据库用SQLite，Python标准库自带，不需要额外安装。

# 创建项目目录 mkdir claude-mem && cd claude-mem # 创建虚拟环境 python -m venv venv source venv/bin/activate # Windows下用 venv\Scripts\activate # 安装依赖 pip install sqlite-utils rich

sqlite-utils是个很顺手的库，能用Python代码操作SQLite，比裸写SQL舒服很多。rich用来做终端输出美化，调试的时候看着清楚。

目录结构建议这样组织：

claude-mem/ ├── venv/ ├── memories.db # SQLite数据库文件 ├── src/ │ ├── __init__.py │ ├── db.py # 数据库操作 │ ├── retrieve.py # 检索逻辑 │ ├── inject.py # 注入逻辑 │ └── cli.py # 命令行入口 ├── config.yaml # 配置文件 └── README.md

config.yaml里放一些可调参数，比如最大注入条数、优先级权重、数据库路径等。把这些抽出来，后面调优的时候不用改代码。

3.2 数据库初始化与表结构创建

数据库初始化只做一次，但表结构设计要考虑扩展性。除了前面提到的基础字段，我建议再加一个metadata字段，用JSON格式存一些灵活信息，比如记忆的来源、关联的对话ID等。

import sqlite3 import json import time def init_db(db_path='memories.db'): conn = sqlite3.connect(db_path) conn.execute(''' CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, category TEXT NOT NULL, project TEXT, content TEXT NOT NULL, keywords TEXT DEFAULT '', priority INTEGER DEFAULT 3, metadata TEXT DEFAULT '{}', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, hit_count INTEGER DEFAULT 0 ) ''') # 创建索引加速检索 conn.execute('CREATE INDEX IF NOT EXISTS idx_category ON memories(category)') conn.execute('CREATE INDEX IF NOT EXISTS idx_project ON memories(project)') conn.execute('CREATE INDEX IF NOT EXISTS idx_priority ON memories(priority DESC)') conn.commit() return conn

索引这块别省。category和project的索引能让粗筛阶段的查询快一个数量级，priority索引则加速排序。数据量小的时候感觉不出来，上千条之后差距就很明显了。

3.3 记忆写入的完整流程

写入记忆有两种触发方式：手动写入和自动摘要。手动写入是你主动告诉系统"记住这条"，自动摘要是对话结束后系统自己提炼。

手动写入的接口设计要简单，最好一行命令搞定：

python -m src.cli add \ --category constraint \ --project my-web-app \ --content "API返回格式统一用 {code, data, message}" \ --keywords "API,返回格式,response,接口" \ --priority 5

自动摘要稍微复杂一点。基本流程是：对话结束后，把整段对话发给模型，让它提炼出值得记住的信息，然后按分类写入。这里有个关键点：摘要的prompt要明确告诉模型"只提取长期有效的信息，忽略一次性的临时讨论"。

SUMMARY_PROMPT = """请从以下对话中提取值得长期记忆的信息。 只提取以下类型： 1. 用户明确表达的偏好或习惯 2. 项目的技术选型或架构决策 3. 已经确定不采用的方案及原因 忽略：临时性的调试过程、一次性的问题排查、闲聊内容。 输出格式：每条记忆一行，格式为 [分类] 内容 """

这个prompt我调了好几版，核心就是"忽略"那部分。不明确说忽略什么，模型会把所有东西都提取出来，记忆库很快就变成垃圾场。

3.4 检索与注入的串联实现

检索和注入要串成一个完整的流程。用户发起对话时，系统先拿用户输入去检索，把相关记忆拼成一段文本，插入到系统提示词里。

def build_prompt(user_input, project, db): memories = retrieve_memories(user_input, project, db) if not memories: return user_input # 按分类分组 grouped = {} for mem in memories: grouped.setdefault(mem['category'], []).append(mem['content']) # 拼装记忆块 memory_block = [] category_names = { 'identity': '用户偏好', 'context': '项目上下文', 'constraint': '约束与决策', 'summary': '历史摘要' } for cat, items in grouped.items(): name = category_names.get(cat, cat) memory_block.append(f"[{name}]") for item in items: memory_block.append(f"- {item}") memory_text = '\n'.join(memory_block) # 更新命中计数 for mem in memories: db.execute('UPDATE memories SET hit_count = hit_count + 1 WHERE id = ?', (mem['id'],)) db.commit() return f"{memory_text}\n\n[用户输入]\n{user_input}"

这段代码里有个细节：命中计数在检索后立即更新。这样热度统计是实时的，下次检索时经常用到的记忆权重会自然上升。形成正反馈循环，越有用的记忆越容易被调出来。

3.5 与AI助手的对接方式

对接方式取决于你用的具体工具。如果是命令行工具，通常支持通过配置文件指定系统提示词模板，你把记忆注入的逻辑挂上去就行。如果是API调用，那更灵活，直接在构造messages的时候把记忆块拼进去。

以常见的API调用为例：

def chat_with_memory(user_input, project, db, client): prompt = build_prompt(user_input, project, db) response = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=4096, system="你是一个编程助手，请结合提供的记忆信息回答用户问题。", messages=[{"role": "user", "content": prompt}] ) return response.content[0].text

system提示词里明确说"结合提供的记忆信息"，这个引导很重要。不说的话，模型有时候会忽略注入的记忆，还是按自己的默认方式回答。

注意：不同工具对接方式差异较大，上面是通用思路。具体到你用的工具，查一下它的文档看怎么注入自定义上下文。大部分工具都支持这个能力，只是配置方式不同。

4. 常见问题与排查技巧实录

4.1 记忆检索不准的排查思路

检索不准是最常见的问题，表现是"明明存了这条记忆，但问的时候就是调不出来"。排查按这个顺序来。

先看keywords字段。大部分检索不准都是keywords没设好。检查一下你存记忆时填的关键词，是不是只填了内容里出现的词，没填同义表达。比如存了"用PostgreSQL做数据库"，keywords只写了"PostgreSQL"，那用户问"数据库用什么"的时候就匹配不上。补上"数据库"、"DB"、"存储"这些词就好了。

再看优先级设置。如果一条重要记忆的priority设成了默认的3，而一堆不重要的记忆也是3，那排序时就分不出主次。重要的记忆priority至少设4，铁律级别的设5。

最后看截断数量。如果max_core设得太小，比如只有3条，那候选集里排第4的重要记忆就被截掉了。适当调大这个值，或者优化打分公式让重要记忆排得更靠前。

4.2 记忆库膨胀的处理办法

用久了记忆库会越来越大，几千条之后检索变慢，而且噪音变多。这时候需要做清理。

第一种清理是合并。把内容相近的记忆合并成一条。比如"用TypeScript"、"偏好TS"、"不要用JS"这三条其实是一回事，合并成"使用TypeScript，不使用JavaScript"一条就够了。

第二种清理是降权。长期没被命中的记忆，hit_count一直是0，说明价值不高。可以把这类记忆的priority降一级，或者直接归档。归档不是删除，是移到一个单独的归档表，需要的时候还能找回来。

第三种清理是定期摘要。把某个项目下的所有summary类记忆，让模型重新提炼一遍，生成一条更精炼的总摘要，替换掉原来的一堆零散摘要。

def cleanup_memories(db, days_threshold=30): # 归档长期未命中的低优先级记忆 cutoff = int(time.time()) - days_threshold * 86400 db.execute(''' UPDATE memories SET category = 'archived' WHERE hit_count = 0 AND priority <= 2 AND created_at < ? ''', (cutoff,)) db.commit()

这个清理逻辑建议每月跑一次。跑之前先备份数据库，万一误归档了还能恢复。

4.3 注入内容干扰模型输出的问题

有时候注入的记忆反而让模型回答变差了。典型表现是模型开始生搬硬套记忆里的内容，哪怕跟当前问题不相关。

这个问题通常出在注入格式上。如果记忆块和用户输入之间没有清晰的分隔，模型会混淆哪些是背景信息、哪些是当前任务。解决办法是加明确的分隔标记，比如用[用户输入]这样的标签把用户的实际问题标出来。

另一个原因是注入了太多不相关的记忆。检索时相关性阈值设得太低，把一些勉强匹配的记忆也带进来了。这时候要收紧匹配规则，宁可少注入几条，也不要注入不相关的。

还有个隐蔽的原因是记忆内容本身有歧义。比如存了一条"不要用某个库"，但没说清楚是在什么场景下不要用。模型看到这条记忆，可能在所有场景下都避开这个库，哪怕某些场景下用它是合理的。所以存约束类记忆时，一定要把适用范围写清楚。

4.4 多项目切换时的记忆隔离

同时维护多个项目时，记忆隔离是个必须处理的问题。核心原则是：项目相关的记忆严格隔离，用户偏好类的记忆全局共享。

实现上靠project字段。写入时标记所属项目，检索时只查当前项目加上project为空的记忆。project为空的那些就是全局记忆，比如用户偏好。

def retrieve_memories(query, project, db): # 只检索当前项目和全局记忆 candidates = db.execute(''' SELECT * FROM memories WHERE (project = ? OR project IS NULL) AND category != 'archived' ''', (project,)).fetchall() # ...后续打分逻辑

有个容易踩的坑：项目重命名或者合并时，记得批量更新project字段。不然旧项目名下的记忆就变成孤儿了，新项目检索不到。

提示：项目标识建议用简短的英文slug，比如"web-app"、"data-pipeline"，不要用中文或者带空格的名称。这样在命令行里输入方便，也不容易出编码问题。

4.5 性能优化的几个实用技巧

记忆条数上千之后，检索性能会开始下降。几个不用大改架构就能见效的优化。

第一个是加缓存。把最近检索过的结果缓存起来，同样的查询直接返回缓存。开发过程中经常反复问类似的问题，缓存命中率不低。

第二个是延迟加载。summary类记忆不要一开始就全查出来，先只查identity、context、constraint这三类，如果这三类里没有匹配的，再去查summary。大部分情况下前三类就够了。

第三个是定期VACUUM。SQLite删除数据后不会自动回收空间，定期执行VACUUM能压缩数据库文件，提升读写速度。

def optimize_db(db): db.execute('VACUUM') db.execute('ANALYZE') db.commit()

这两个命令建议每周跑一次。VACUUM回收空间，ANALYZE更新查询优化器的统计信息，都能让检索更快。

4.6 记忆内容的编写规范

最后说一个容易被忽视但影响很大的点：记忆内容怎么写。同样一条信息，写法不同，模型利用的效果差别很大。

好的写法是具体、可执行、带上下文。比如"API返回格式统一用 {code, data, message}，code为0表示成功，非0表示错误"。这条记忆模型一看就知道怎么用。

差的写法是模糊、抽象、缺上下文。比如"注意API格式"。这条记忆模型看了等于没看，不知道该注意什么。

约束类记忆要写清楚"不做什么"和"为什么"。比如"不要用moment.js处理日期，因为项目已经统一用dayjs，混用会导致打包体积增大"。带上原因，模型在边缘情况下能自己判断。

偏好类记忆要写清楚适用范围。比如"代码注释用中文（仅限业务逻辑代码，工具函数和类型定义用英文）"。不写清楚范围，模型可能在不该用中文的地方也用中文。

这些规范看起来琐碎，但积累几十条记忆之后，规范性带来的效果差异非常明显。花点时间把记忆写好，比事后调检索参数管用得多。

我个人在实际使用中最大的体会是：记忆系统的价值不在于技术多复杂，而在于坚持维护。刚开始用的时候兴致勃勃存了一堆，过两周就懒得管了，那系统就废了。真正有效的用法是把它融入日常工作流，每次做完一个决策就顺手记一条，每次对话结束让系统自动摘要。坚持一个月，你会发现AI助手真的开始"懂你"了，那种感觉跟重新调教一个陌生助手完全不一样。另外一个小技巧是定期回顾记忆库，把过时的、矛盾的记忆清理掉，保持记忆库的"新鲜度"，这比不断往里加新记忆更重要。