标题里“铭记的约定”这几个字，落到工程上其实是一个非常具体的问题：怎么让一个本地跑起来的模型，在几十轮对话之后、在进程重启之后、在批量任务跑完之后，还能记得住你事先跟它约定好的规则。这件事看起来像提示词技巧，实际做下来是一套完整的记忆读写链路，涉及存储结构、召回策略、冲突更新和接口封装，光靠往 system prompt 里塞几段话是撑不住的。

这篇文章不绑定某一个具体仓库，因为记忆类方案在本地部署形态下差异极大，硬套某个项目的目录结构和启动脚本反而容易误导。我们换一个更实用的角度：把“让模型记住约定”拆成可落地的模块，逐个讲清楚该准备什么环境、服务怎么起、记忆怎么写入和召回、接口怎么调、批量任务怎么跑、显存和内存占用该看哪些指标、出错之后从哪里排查。文章里给出的代码和配置都是通用模板，路径、端口、模型名需要按你自己的环境替换。

最核心的四个能力先说清楚：一是持久化写入，约定内容要落到磁盘而不是留在上下文里；二是按需召回，不能每轮把所有记忆全灌进去，否则上下文会被撑爆；三是冲突更新，用户改了规则要能覆盖旧版本而不是堆叠；四是接口化，记忆服务要能被上层应用、脚本、批处理任务统一调用。这四件事缺一件，所谓“记忆”就退化成了一次性的对话铺垫。

下面的内容按实测顺序推进：先看能力速览和边界，再准备环境、起服务、跑功能验证，然后接接口、做批量、观察资源占用，最后给排查表和工程建议。适合正在做本地 Agent、长对话助手、客服知识沉淀、个人工作流自动化的读者，如果你只是想让模型在一次对话里别跑题，前两节看完就够了，不需要往后折腾存储和接口。

1. 核心能力速览

先把这套方案的整体规格摆出来，方便你判断要不要继续往下读。需要强调的是，记忆模块本身很轻，真正吃资源的是它依赖的 embedding 模型和上层的大模型推理服务，所以“显存够不够”这个问题要分两层看。

表里有两处需要单独说明。第一是显存，很多人看到“记忆”两个字节就觉得和显卡无关，实际上向量化这一步要么走本地 embedding 模型，要么走远端接口，走本地就一定有显存或内存开销，具体多少和模型参数量、批大小、序列长度直接相关，材料里没有给出具体数值，所以这里不给数字，后面第 7 节会给观察方法。第二是批量任务，批量导入本身不难，难的是导入过程中的失败重试和幂等控制，这一点在第 6 节展开。

如果只记一句话：这是一层“可查询的规则仓库”，不是让模型变聪明的魔法。它的价值在于把“约定”从易失的上下文搬到可审计的存储里，让同一套规则能被多次调用、被不同进程复用、被人为检查和修改。

2. 适用场景与使用边界

2.1 这套方案真正解决的问题

最典型的场景是规则漂移。你和模型约定“输出一律用简体中文、代码块必须标注语言、回答不超过三段”，前五轮它还记得，二十轮之后开始慢慢走样，到了第四十轮基本回到默认风格。原因不是模型不听话，而是这些约定在上下文里被后续内容稀释了。把约定写成结构化记忆条目，每轮按当前问题检索出最相关的几条重新注入，漂移会明显收敛。

第二个场景是跨会话延续。用户今天说“我的项目用 Python 3.11，依赖用 uv 管理”，明天新开一个会话，这句话如果只存在历史聊天记录里，模型是看不到的。存成记忆条目之后，新会话第一轮就能召回。第三个场景是多任务隔离，同一个用户可能同时在做两三个项目，记忆条目要带命名空间，否则 A 项目的约定会污染 B 项目的输出。

这三个场景的共同点是：信息量不大，但必须稳定、可查、可改。这正好是记忆层擅长的事，也是大模型上下文不擅长的事。想清楚这一点，就不会把记忆层当成知识库来用，两者在写入粒度、更新频率、召回精度要求上完全不同。

2.2 不适合直接套用的场景

第一类是强实时场景。每次回答前都要做一次向量化加检索，链路上多了两跳，延迟会上去。如果业务要求百毫秒内响应，要么把记忆缓存在内存里预热，要么退化成规则表直接命中，不要走语义检索。

第二类是需要强一致性的业务。记忆层通常是最终一致，写入之后可能有短暂的索引延迟，如果你拿它存订单状态、库存数量这类数据，迟早出问题。它适合存“偏好”“约定”“背景说明”，不适合存事务型数据。

第三类是涉及他人隐私和个人信息的场景。记忆层会把内容原样落盘，一旦写进去就是长期留存，删除成本比写入高得多。涉及真实用户数据时，必须在写入前做脱敏，条目里带来源标记和过期时间，并且提供按用户、按命名空间的批量删除能力。涉及人脸、声音、聊天记录等素材时，务必确认已获得授权，只在自己的测试环境里验证，不要把来源不明的数据灌进生产库。

2.3 合规与安全边界

记忆层天然是个“数据沉淀池”，所以边界要提前划。写入侧建议做三件事：一是过滤掉明显的敏感信息，比如证件号、完整手机号、密钥字符串；二是给每条记忆打上来源标签，区分“用户明示的约定”和“模型自己总结的内容”，后者可靠性低，召回应降权；三是设置保留期限，超过期限自动清理。

读取侧同样要做控制。检索结果注入提示词之前，应该限制条数和总长度，避免把大量历史内容一次性塞进去，既浪费上下文也增加泄漏面。对外提供接口时不要默认监听公网地址，用127.0.0.1绑定本地，需要跨机访问时再加访问控制和鉴权。这些都不是可选项，一旦记忆服务对外裸奔，等于把用户的历史对话直接挂在网上。

3. 环境准备与前置条件

3.1 基础环境检查清单

动手之前先把这几项确认掉，能省掉后面一大半的报错。操作系统方面 Windows 10/11 和主流 Linux 发行版都可以，Windows 上注意路径不要带中文和空格，某些向量库的原生扩展对路径比较敏感。Python 版本建议 3.10 到 3.12，太老的版本很多依赖装不上，太新的版本轮子还不全。

显卡和驱动方面，如果要本地跑 embedding 模型，确认驱动版本和 CUDA 版本匹配，装完之后用nvidia-smi看一眼能不能正常输出。磁盘方面，向量库文件加上模型权重，留出至少十几 GB 的空间比较稳妥，具体看模型大小。端口方面，默认习惯用 8000 或 8080，起服务前先确认没被占用，方法在后面的排查表里。

还有一个容易被忽略的点是时区。记忆条目通常带创建时间和过期时间，如果容器时区和宿主机不一致，过期判断会出现偏差，表现为“明明刚写的记忆，检索却查不到”。统一用 UTC 存储、展示时再转本地时区，是最省心的做法。

3.2 依赖安装与虚拟环境

无论用哪个方案，都建议先建独立虚拟环境，别往系统 Python 里直接装。下面这段是通用流程，包名需要按你实际选用的向量库和 web 框架替换。

# 创建并激活虚拟环境（Windows 用 venv\Scripts\activate） python -m venv .venv source .venv/bin/activate # 升级基础工具 python -m pip install --upgrade pip setuptools wheel # 安装通用依赖：web 框架 + 向量检索 + 客户端 pip install fastapi uvicorn pydantic requests numpy # 下面前两个按实际方案二选一，不要同时装 pip install chromadb # 轻量方案，适合单机小规模 # pip install qdrant-client # 服务化方案，适合数据量增长后迁移

装完之后做个最小验证，确认核心库能正常导入，不要把问题留到起服务时才发现。

import fastapi, numpy print("fastapi ok:", fastapi.__version__) print("numpy ok:", numpy.__version__) try: import chromadb print("vector store ok:", chromadb.__version__) except ImportError as e: print("vector store missing:", e)

如果这一步报ImportError或者DLL load failed，基本是依赖版本冲突或缺少系统运行库，先在一个干净环境里重装，不要在已经装了几十个包的环境里硬调。

3.3 模型与配置项准备

embedding 模型需要提前下载到本地目录，避免运行时临时拉取导致首次请求超时。模型文件和业务数据分开放，比如模型放./models，向量库放./data/store，配置放./config，这样备份和迁移的时候边界清晰。

配置项建议统一到一个 JSON 或 YAML 文件里，不要散落在代码各处。下面是一份通用配置模板，字段名按你实际使用的库调整，路径和端口务必替换成本机情况。

{ "server": { "host": "127.0.0.1", "port": 8000, "workers": 1 }, "embedding": { "model_path": "./models/your-embedding-model", "device": "cuda", "batch_size": 8, "max_length": 512 }, "store": { "backend": "chromadb", "persist_dir": "./data/store", "collection": "memory", "distance": "cosine" }, "memory": { "top_k": 5, "max_chars": 1200, "default_ttl_days": 90, "namespace": "default" } }

workers先设 1，本地部署时多进程会各自加载一份模型，显存占用直接翻倍，这是很多人踩过的坑。等确认单进程稳定了，再考虑要不要加。top_k和max_chars是控制注入长度的关键，一开始设小一点，跑通之后再往上调。

4. 部署与启动方式

4.1 命令行直接启动

最省事的方式是直接用 uvicorn 起一个记忆服务，把写入、检索、删除三个接口暴露出来。下面是一个可以直接跑起来的最小示例，逻辑完整，字段名可以按需扩展。

# memory_server.py import time import uuid from fastapi import FastAPI from pydantic import BaseModel, Field app = FastAPI(title="memory-service") # 示例用内存字典，生产环境请替换为向量库 STORE = {} class MemoryIn(BaseModel): content: str = Field(..., min_length=1) namespace: str = "default" tags: list[str] = [] source: str = "user" # user / model ttl_days: int = 90 class QueryIn(BaseModel): query: str namespace: str = "default" top_k: int = 5 @app.post("/memory") def add_memory(item: MemoryIn): mid = uuid.uuid4().hex STORE[mid] = { "id": mid, "content": item.content, "namespace": item.namespace, "tags": item.tags, "source": item.source, "created_at": int(time.time()), "expire_at": int(time.time()) + item.ttl_days * 86400, } return {"ok": True, "id": mid} @app.post("/memory/search") def search(item: QueryIn): now = int(time.time()) hits = [ v for v in STORE.values() if v["namespace"] == item.namespace and v["expire_at"] > now ] # 示例只做关键词匹配，实际请替换为向量检索 hits = [h for h in hits if item.query[:6] in h["content"]] return {"ok": True, "items": hits[: item.top_k]} @app.delete("/memory/{mid}") def remove(mid: str): return {"ok": STORE.pop(mid, None) is not None}

启动命令和健康检查如下，--reload只在开发时加，生产环境去掉。

# 启动服务 uvicorn memory_server:app --host 127.0.0.1 --port 8000 # 另开一个终端做健康检查 curl -s http://127.0.0.1:8000/docs -o /dev/null -w "%{http_code}\n"

返回 200 说明服务起来了。注意示例里的检索是关键词匹配，仅用于验证链路是否通畅，真实场景要换成向量检索，否则同义表达根本召回不到。

4.2 Docker 方式启动

需要多机复用或者想固定环境时，用 Docker 更合适。写 Dockerfile 时把模型目录挂载进去，不要打进镜像，否则镜像体积会非常大，每次改模型都要重新构建。

# 构建与运行示例，镜像名和端口按实际修改 docker build -t memory-service:local . docker run -d \ --name memory-service \ -p 127.0.0.1:8000:8000 \ -v "$(pwd)/models:/app/models:ro" \ -v "$(pwd)/data:/app/data" \ -v "$(pwd)/config:/app/config:ro" \ -e MEMORY_CONFIG=/app/config/memory.json \ memory-service:local # 查看启动日志，确认没有加载失败 docker logs -f memory-service

-p 127.0.0.1:8000:8000这样写是刻意只绑本地，写成-p 8000:8000就会监听所有网卡。GPU 场景还要加--gpus all，并且宿主机的驱动和容器内的 CUDA 版本要能对上，版本不匹配时容器里nvidia-smi能跑但模型加载会失败。

4.3 作为库嵌入主程序

如果记忆只服务于一个应用，没必要单独起服务，直接当库引入更简单，少一层网络调用也少一类故障。缺点是多个应用无法共享同一份记忆，需要共享时还是回到服务形态。两种形态可以共存：本地开发用库，部署用服务，接口层保持一致的函数签名，切换成本很低。

启动方式定下来之后，建议马上固化一份“最小可运行配置”，把端口、模型路径、top_k这些固定住并提交到版本库。后面调参时另存一份实验配置，出问题时能一键回到可用状态，这个习惯在排查阶段特别有用。

5. 功能测试与效果验证

服务起来只是第一步，真正要验证的是“记得住、找得到、改得掉”。下面五组测试按顺序做，每组都有明确的成功判据，不要凭感觉判断。

5.1 基础写入与召回测试

先验证最朴素的链路：写一条约定，立刻用相近但不完全相同的表述去查，看能不能召回。写入内容选一条典型规则，比如“所有代码块必须标注语言类型，禁止裸代码块”。然后分别用“代码块要标语言”“写代码时格式要求是什么”去检索。

判断成功的标准有两条：一是能召回，二是排序靠前。如果相似表述召不回来，说明 embedding 模型选得不合适或者文本被截断；如果召回了但排在很后面，说明库里干扰项太多，需要加namespace隔离或者提高相似度阈值。这一步不过关，后面的测试都没意义。

5.2 跨进程持久化测试

停掉服务再重新启动，用同样的查询再跑一次，看记忆还在不在。这个测试专门抓“内存字典当存储”的问题，示例代码里用的就是内存字典，重启必丢，属于预期行为，换成真实向量库之后才应该通过。

如果换成向量库之后还是丢，重点查三个地方：持久化目录是否真的挂载到了容器内、写权限是否足够、persist_dir是否和读取时指向同一个路径。这三点在 Docker 场景下最容易出错，宿主机目录没挂对时，容器里的数据看着正常，一重启就回到初始状态。

5.3 冲突更新测试

写入“回答不超过三段”，确认能召回；再写入“回答不超过五段”，同一个namespace、同一个标签，然后查询“回答长度要求”。这时候库里会有两条互相冲突的记忆，正确做法是新条目覆盖旧条目，而不是两条都返回。

实现上通常用业务主键去重，比如给约定类记忆加一个key字段，写入前先按key查一次，命中就更新内容并刷新时间戳。如果不做这一步，几轮修改之后库里会堆一堆互相矛盾的条目，模型拿到之后输出会非常不稳定，而且这种不稳定很难复现，排查成本极高。

5.4 长文本与截断测试

写入一条较长的背景说明，比如三四百字的项目约定，然后检查召回时返回的内容是否完整。很多方案默认有max_length，超出部分会被直接截断，导致后半段约定实际没生效。

应对方式有两种：一是写入前做切分，把长文档拆成若干语义完整的短条目，各带相同的key前缀；二是保留长条目但在注入时做摘要。前者更可控，推荐优先用。测试时要专门造一条刚好超过阈值的内容，确认切分点没有把一句话劈成两半，否则召回的内容会读不通。

5.5 检索质量抽查

最后一组是人工抽查，从库里随机抽二三十条记忆，构造对应的自然语言问题，看命中率和排序质量。这一步没法完全自动化，但对判断“能不能用”最有价值。

抽查时重点看两类失败：一类是召回了不相关的记忆，属于误召回，通常因为阈值太低或者 embedding 模型对领域词不敏感；另一类是明显相关的没召回，属于漏召回，常见于表述差异大、专业术语多的情况。前者调阈值和加过滤条件，后者考虑混合检索，把关键词匹配和向量检索的结果做融合，能明显改善。

6. 接口 API 与批量任务

6.1 接口调用示例

服务化之后，上层应用通过 HTTP 调用，语言和技术栈都不受限。下面是最常见的三个调用：写一条记忆、检索、删除。

# 写入一条约定 curl -X POST http://127.0.0.1:8000/memory \ -H "Content-Type: application/json" \ -d '{ "content": "所有代码块必须标注语言类型", "namespace": "proj_a", "tags": ["format"], "source": "user" }' # 检索 curl -X POST http://127.0.0.1:8000/memory/search \ -H "Content-Type: application/json" \ -d '{"query": "代码格式要求", "namespace": "proj_a", "top_k": 5}'

Python 侧封装一层更实用，把重试和超时都加上，避免网络抖动导致整个流程失败。

import time import requests BASE = "http://127.0.0.1:8000" def add_memory(content, namespace="default", tags=None, retries=3): payload = { "content": content, "namespace": namespace, "tags": tags or [], "source": "user", } for i in range(retries): try: r = requests.post(f"{BASE}/memory", json=payload, timeout=10) r.raise_for_status() return r.json()["id"] except Exception as e: if i == retries - 1: raise time.sleep(1.5 ** i) def search_memory(query, namespace="default", top_k=5): r = requests.post( f"{BASE}/memory/search", json={"query": query, "namespace": namespace, "top_k": top_k}, timeout=15, ) r.raise_for_status() return r.json().get("items", [])

超时时间不要设得太短，向量检索首次请求会触发模型加载，几十秒都有可能。可以加一个预热接口，服务启动后主动跑一次空查询，把模型加载到显存里，避免第一个真实请求超时。

6.2 批量导入任务设计

批量导入的坑比单条写入多得多。第一个坑是重复导入，脚本跑两遍库里就有两份数据，所以每条记录要带业务主键，导入前先查后写。第二个坑是中途失败，跑到一半网络断了，重启之后不知道从哪继续，所以要记录进度。

import json from pathlib import Path INPUT = Path("./inputs/memories.jsonl") STATE = Path("./data/import_state.json") BATCH = 50 def load_state(): if STATE.exists(): return json.loads(STATE.read_text(encoding="utf-8")) return {"offset": 0, "done": 0, "failed": []} def save_state(state): STATE.parent.mkdir(parents=True, exist_ok=True) STATE.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8") def run(): state = load_state() lines = INPUT.read_text(encoding="utf-8").splitlines() total = len(lines) for idx in range(state["offset"], total, BATCH): chunk = lines[idx: idx + BATCH] for line in chunk: try: item = json.loads(line) except json.JSONDecodeError: state["failed"].append({"line": idx, "reason": "json_error"}) continue try: add_memory(item["content"], item.get("namespace", "default")) state["done"] += 1 except Exception as e: state["failed"].append({"line": idx, "reason": str(e)}) state["offset"] = idx + BATCH save_state(state) print(f"progress {state['offset']}/{total} done={state['done']}") if __name__ == "__main__": run()

这个脚本的核心是状态文件，失败的行集中在failed列表里，跑完之后单独处理。建议把失败行导出成单独文件人工过一遍，不要无脑重试，因为有一类失败是内容本身有问题，重试多少次都一样。

6.3 批量任务的队列与限流

批量导入和在线检索共用同一个服务时，容易出现导入把服务打满、在线请求超时的情况。简单的处理方式是给批量任务加并发上限和间隔，比如每批之间sleep一小段时间，同时把服务的workers保持为 1，让请求排队而不是把显存打爆。

如果数据量确实大，建议走异步队列：生产端把任务推进队列，消费端单线程慢慢处理，状态回写到数据库。这样在线接口和批量任务天然隔离，也不会因为一次导入把服务搞挂。队列选型不用太复杂，本地场景用个文件队列或者简单的任务表就够。

7. 资源占用与性能观察

7.1 该看哪些指标

记忆层的资源占用分四块：embedding 模型的显存、向量库的内存、进程的常驻内存、磁盘增长。很多人只盯显存，结果磁盘涨到几百 GB 才发现没做清理。

显存用nvidia-smi观察，重点看稳态值而不是启动瞬间的峰值，模型加载完之后会回落一部分。CPU 内存用top或任务管理器看，向量库全量加载进内存时峰值会比较高，配了持久化但没配内存映射的话要注意。磁盘看data目录的增长速度，按条数估算单条记忆的平均占用，再乘以每天新增量，就能判断多久需要清理一次。

# 观察显存与进程内存变化，间隔 2 秒 nvidia-smi --query-gpu=memory.used,memory.total --format=csv -l 2 # Linux 下观察进程内存与磁盘增长 ps -o rss,cmd -C python du -sh ./data/store

7.2 影响性能的四个因素

第一是批大小。写入和检索时一次处理的条数上去了，显存峰值跟着上去，吞吐提升但延迟变高。本地单卡建议从小批开始，逐步加到显存占用留出安全余量为止。

第二是序列长度。embedding 模型通常有最大长度限制，超长文本要么被截断要么分块，分块数量直接决定计算量。把长文档切成两三百字的片段，比硬塞进一条长文本更划算，召回精度通常也更好。

第三是库的规模。向量库条数上来之后，检索耗时会增长，尤其是不带索引的全量暴力检索。到了十万级就应该考虑带近似索引的后端，或者按命名空间分库，把每次检索的范围缩小。

第四是并发。单个进程处理并发请求时，模型推理是串行执行的，并发高了只会排队，不会变快。想让并发真正生效，要么多卡多进程，要么把模型换成更小的版本。本地场景通常没必要追高并发，把单次请求的稳定性做好更实际。

7.3 降低占用的几个实用做法

把 embedding 模型放到 CPU 上跑是最直接的省显存方式，代价是延迟上升，适合写入频率低、检索不密集的场景。也可以把写入和检索拆开，写入走 CPU 异步处理，检索保留 GPU，兼顾体验和占用。

定期清理过期记忆同样重要。给每条记忆设ttl_days，起一个每天跑一次的清理任务，把过期条目和长期未被召回的条目一起处理掉。清理要留日志，记录删了多少条、按什么条件删的，出问题时能回溯。最后别忘了向量库自身的压缩能力，部分后端支持手动触发整理，长期只增不删的库检索会越来越慢。

8. 常见问题与排查方法

表里最值得单独说的是“写入成功但检索查不到”。这个问题在刚上线时特别常见，因为写入接口返回 200 只代表接收成功，不代表索引已更新。排查时不要反复调检索参数，先按 id 把原始记录拉出来确认到底有没有落库，再判断是索引问题还是查询条件问题，能省掉大量无效调试。

另一个高频问题是时区。容器里默认 UTC，宿主机是东八区，计算过期时间时差八小时，表现就是刚写完的记忆偶尔查不到。统一用 UTC 存时间戳、只在展示层转换，这类问题基本可以杜绝。

9. 最佳实践与下一步

第一次搭这套东西，建议先做单条写入加检索，跑通之后再上服务化和批量导入。很多人一上来就把接口、队列、清理任务全铺开，结果出问题时不知道是哪一层的问题。链路越短，定位越快，这是所有本地部署项目通用的经验。

配置管理上坚持“最小可用配置 + 实验配置”两套并存。最小配置里只放端口、模型路径、top_k这几个必要项，实验配置用来试新的 chunk 策略和阈值。任何调参之前先确认最小配置能跑通，回滚才有意义。模型文件、输入素材、输出数据、日志分目录管理，备份时只备份配置和数据，模型目录单独同步。

数据和合规上，写入口做脱敏过滤，每条记忆带来源标签和过期时间，按用户和命名空间提供批量删除。涉及他人对话记录、人脸、声音素材时，只在获得明确授权的范围内使用，测试阶段用自己构造的脱敏样本，不要拿真实业务数据练手。

往下可以扩展的方向有三个。一是混合检索，把关键词匹配和向量检索的结果做加权融合，对专业术语多的场景提升明显。二是记忆分层，把“硬约定”和“软背景”分开存，前者每轮必注入，后者按需召回，能显著压低上下文长度。三是接入可观测，把召回命中率、注入长度、写入失败率打成指标，跑一段时间之后回头看数据，才知道哪些约定是真的被用上了，哪些只是躺在库里吃磁盘。

如果只挑一件事先做，那就是把“冲突更新”做对。它是记忆层从玩具变成可用工具的分水岭，也是后面所有扩展的地基。