企业官网建设流程全解析

每次打开一个新的 AI 对话框，都要重新介绍自己的身份、项目背景、代码规范、常用偏好，这种感觉做过实际开发的人再熟悉不过了。明明上次对话里已经交代过“这个仓库用 pnpm 管理依赖，不要往 package.json 里加 npm 的 lock 文件”，这次对话却像第一次见面一样，把同样的问题再问一遍，然后给出一个不符合项目规范的答案。这种体验背后的核心问题，就是大模型的“无状态”本质：模型本身不具备跨会话的记忆能力，每次对话都是从零开始推理。

AGENTS.md 的出现，就是为了解决这个尴尬的现状。它不是大模型本身的功能，而是一种工程化的约定：在项目仓库里放一个专门的 Markdown 文件，让 AI 编码助手、智能代理在开始任务前先读取它，理解项目约定、构建方式、目录结构和工作流程。如果说传统 Prompt 是“每一句话都要反复嘱咐”，那么 AGENTS.md 就是把那些需要反复嘱咐的话，固化成一份 AI 长期可以读取的“项目说明书”。

这篇文章会从几个层面展开：先解释 AGENTS.md 是什么、解决什么问题，然后对比几种长期记忆落地的技术方案，再给出一套完整的、可运行的 Python 代码示例，演示如何用 SQLite 给 AI 助手做记忆存储，接着谈向量检索方案，最后整理常见坑点和工程建议。无论你是正在做智能对话应用，还是想让代码仓库里的 AI 助手更懂你的项目，这篇文章都适用。

1. 背景：为什么 AI 总像“失忆”一样？

1.1 大模型的“一次性对话”本质

先看一个很典型的场景。你在一个大型项目里使用 AI 编程助手，第一次对话里告诉它“前端代码在web/目录，后端在server/目录，接口文档在docs/”，它在那次对话里表现很好。可当你新建一个对话，重新问它“项目结构是什么”时，它要么猜，要么等你再介绍一遍。

这背后的原因在于，目前主流的大模型接口都是无状态的。调用一次模型接口，相当于把“当前对话的全部内容”都拼进上下文窗口里发送过去。上下文窗口是有限的，一旦关闭页面、开启新会话，上一段历史就不存在了。模型本身没有“记住你上次说了什么”的机制。

这就带来了两个问题：

• 重复沟通成本高：每次新会话都要把项目背景、代码规范、业务规则重新说一遍。
• 结果不一致：不同会话中，AI 对同一问题的理解可能完全不同，因为每次它看到的上下文不一样。

很多人在团队中推广 AI 编码工具时，最大的阻力也来自这里。大家并不是觉得 AI 能力不行，而是觉得“它太健忘”，用起来像在带新人，天天讲一样的注意事项。

1.2 AGENTS.md 是什么

AGENTS.md 是一种约定俗成的项目级指令文件，通常放在仓库根目录下。它向 AI 编码代理（例如 GitHub Copilot 的 Agent 模式、Codex CLI、Cursor 等）提供项目背景和操作规范。当 AI 代理开始与你协作时，它会优先读取这个文件，从而做到“不用你重新解释，就知道项目怎么跑、代码怎么组织、约定是什么”。

你可以把它理解成“给 AI 看的 README”。README 主要给人类开发者看，介绍项目是什么、怎么安装、怎么使用；而 AGENTS.md 是给 AI 代理看，重点在于：这个项目的目录结构是什么、构建测试命令是什么、代码风格有哪些硬性约束、哪些操作必须避免。

这在本质上就是一种静态的、人工维护的长期记忆。项目的重要信息沉淀在文件里，AI 每次开始工作都会读取，不需要依赖模型自身具备记忆功能。

1.3 持久记忆的两条技术路线

理解 AGENTS.md 后，再把视角拉远一些。想让 AI“长期读懂你”，目前在工程上有两条路线：

实际项目中，两者通常是结合使用的。AGENTS.md 负责显式的项目级规范，动态记忆负责自动沉淀的用户级偏好。下面第二个例子，就是演示动态记忆这一路线的具体实现。

2. AGENTS.md 的核心写法与设计要点

2.1 AGENTS.md 与 README.md 的区别

很多人第一次接触 AGENTS.md 时会问：这和 README.md 有什么区别？

简单说：

• README.md 面向人类开发者，重点是“项目是什么、怎么安装、怎么使用”，内容可以偏向介绍性。
• AGENTS.md 面向 AI 代理，重点是“项目怎么构建、AI 应该如何表现、有哪些限制”，内容要偏向指令性。

举例来说，README 里可能写着“本项目使用 Poetry 管理依赖，安装命令为poetry install”。AGENTS.md 里则会进一步写清楚：“AI 在执行命令时，不要手动修改pyproject.toml中的依赖版本；新增依赖必须使用poetry add命令；测试命令是poetry run pytest，不要直接用pytest，因为虚拟环境中可能没有安装 pytest。”

2.2 一份可用的 AGENTS.md 示例

下面是实践中比较有效的一份 AGENTS.md 写法，可以直接复制到项目根目录根据实际情况修改：

# AGENTS.md ## 项目简介 这是一个面向数据分析场景的 Python Web 服务，提供数据上传、清洗、可视化接口。 ## 技术栈 - Python 3.11+ - FastAPI - SQLAlchemy 2.0 - PostgreSQL 15 - Poetry 依赖管理 ## 常用命令 - 安装依赖：poetry install - 启动服务：poetry run uvicorn app.main:app --reload - 运行测试：poetry run pytest - 代码检查：poetry run ruff check . ## 目录结构 - app/api：路由接口层 - app/service：业务逻辑层 - app/repository：数据访问层 - tests：单元测试与集成测试 ## AI 操作规范 1. 新增依赖时使用 poetry add，禁止直接修改 pyproject.toml 的 [tool.poetry.dependencies] 区块。 2. 数据库表结构变更必须编写 Alembic 迁移脚本，禁止直接 create_all。 3. 所有接口返回值统一包装为 {"code": 0, "data": ..., "message": "success"}。 4. 测试文件命名必须以 test_ 开头，否则不会被收集。 5. 禁止把秘钥、数据库连接串写入代码或配置文件，统一读取环境变量。 ## 项目约束 - 不要修改 app/models 下的模型类来兼容前端字段名。 - 涉及用户数据导出的接口必须增加分页参数。

你可以注意到，这份文件里的内容基本都是“AI 容易犯错”的地方。这就是 AGENTS.md 最核心的价值：把过去的返工教训沉淀成每一次对话都可见的规范。

2.3 什么样的 AGENTS.md 才是好用的

从实际使用反馈来看，好的 AGENTS.md 通常具备以下特征：

• 指令明确：说清楚“做什么”和“不做什么”，而不是模棱两可的提示。
• 命令可复现：给出的命令是当前仓库真实能用的，AI 会真的去执行。
• 信息分层：项目简介、技术栈、常用命令、目录结构、规范约束分节展示，方便 AI 快速定位。
• 持续维护：当项目结构变化或出现新的“坑”时，会同步更新文件。

这里也想多说一句：AGENTS.md 不是写了就一劳永逸。项目迭代后，依赖、目录、命令都会变化，如果文件长期不更新，反而会误导 AI，效果比没有文件还差。

3. 动态记忆的技术架构：从对话历史到记忆库

AGENTS.md 解决的是“项目级静态记忆”，但在真实的 AI 应用开发中，我们往往还需要让 AI 记住用户的偏好和重要事实。以个人助理、智能客服、对话式 Agent 为例，用户可能在上周说过“我偏好简洁回答”“我在做跨境电商，主要市场是东南亚”，我们希望这周的新会话里 AI 依然记得。

这就是动态记忆的范畴。下面先把技术架构拆开来讲。

3.1 记忆处理四阶段

一个完整的记忆模块通常包含以下四个阶段：

• 感知：从对话消息中提取需要记忆的信息。常见做法是设定规则关键词，或者调用大模型对消息做信息抽取。
• 编码：将提取出的信息结构化成文本记录，或者做向量化嵌入。
• 存储：把记忆数据写入存储介质，常见的有 JSON 文件、SQLite、Redis、PostgreSQL、专门的向量数据库。
• 检索：在新对话到达时，根据当前用户的问题召回相关的历史记忆，注入到大模型提示词中。

这个过程可以理解成一套微型 RAG（检索增强生成）系统。区别在于，RAG 通常检索企业文档，而记忆系统检索的是用户本身的历史信息。

3.2 存储方案怎么选

在实战演示中，我们会选择 SQLite + JSON 字段的方式，原因是它零部署、单文件、易调试，而且对新手非常友好。

3.3 记忆如何融入对话

记忆注入到模型提示词时，常用的模板思路是这样的：

你是用户的长期 AI 助手。以下是关于用户的长期记忆： 1. 用户偏好：回答尽量简洁，控制在 100 字内。 2. 用户背景：正在开发一个电商数据分析平台，后端使用 FastAPI。 当前用户消息：...

这样，模型看到的不再是孤零零的一句话，而是带着历史记忆的问题。这也解释了为什么“记忆”的本质其实不是模型变聪明了，而是你的应用层简单粗暴地把相关历史信息塞进了上下文。

4. 实战：用 SQLite 给 AI 助手实现长期记忆

接下来进入代码部分。这里选用的技术栈很简单：Python 3 + SQLite + OpenAI 兼容接口。考虑到不同读者的网络环境和账号情况不同，这里先实现一个不依赖外部大模型的记忆管理模块，再用一个模拟的大模型调用函数来演示完整流程。

4.1 设计目标

我们要实现这样的效果：

• 第一次会话中，用户告诉 AI：“我喜欢简洁回答，每次回复不超过 100 字。”
• 第二次会话（模拟重新打开页面）中，AI 回答问题时自动回想起这条偏好，并说“根据你的长期偏好，我会尽量简洁地回复”。
• 记忆可以追加、查询、更新，并且按关键词召回相关条目。

4.2 文件结构

memory_demo/ ├── memory.py # 记忆存储与检索模块 ├── chatbot.py # 模拟带记忆的 AI 助手 └── demo.db # 运行时自动生成

4.3 记忆存储模块

这个模块负责把记忆文本写入 SQLite，并支持按关键词查询。

# 文件路径：memory_demo/memory.py import sqlite3 from datetime import datetime from typing import List, Dict DB_PATH = "demo.db" def get_connection(): """获取数据库连接，自动建表""" conn = sqlite3.connect(DB_PATH) conn.row_factory = sqlite3.Row conn.execute( """ CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ) """ ) return conn def add_memory(content: str) -> int: """新增一条记忆，返回记忆 id""" now = datetime.now().isoformat() conn = get_connection() cursor = conn.execute( "INSERT INTO memories (content, created_at, updated_at) VALUES (?, ?, ?)", (content, now, now), ) conn.commit() memory_id = cursor.lastrowid conn.close() return memory_id def get_all_memories() -> List[Dict]: """获取全部记忆，按更新时间倒序""" conn = get_connection() rows = conn.execute( "SELECT id, content, created_at, updated_at FROM memories ORDER BY updated_at DESC" ).fetchall() conn.close() return [dict(row) for row in rows] def search_memories(keyword: str) -> List[Dict]: """按关键词模糊检索记忆""" conn = get_connection() rows = conn.execute( "SELECT id, content, created_at, updated_at FROM memories WHERE content LIKE ?", (f"%{keyword}%",), ).fetchall() conn.close() return [dict(row) for row in rows] def update_memory(memory_id: int, new_content: str) -> bool: """更新记忆内容""" now = datetime.now().isoformat() conn = get_connection() cursor = conn.execute( "UPDATE memories SET content = ?, updated_at = ? WHERE id = ?", (new_content, now, memory_id), ) conn.commit() success = cursor.rowcount > 0 conn.close() return success def delete_memory(memory_id: int) -> bool: """删除记忆""" conn = get_connection() cursor = conn.execute("DELETE FROM memories WHERE id = ?", (memory_id,)) conn.commit() success = cursor.rowcount > 0 conn.close() return success

这里用到的 SQL 都很直接，需要注意两点：

• created_at和updated_at分开存，是为了后续做记忆更新时能看出用户最常确认的偏好是什么。
• LIKE模糊查询只适合少量数据和简单关键词场景，生产环境中建议换成全文检索或向量检索。

4.4 从对话中提取记忆

记忆内容不会自己从对话里蹦出来，需要从用户消息里抽取。这里做一个简化版的抽取函数，重点处理“我喜欢 / 我偏好 / 记住 / 以后都”这类表达。真正的生产实现可以换成调用大模型来做信息抽取，准确率会高很多。

# 在 memory.py 中追加以下函数 PREFERENCE_MARKERS = ["我喜欢", "我偏好", "记住", "以后都", "我的习惯", "请记住"] def extract_memory_from_message(message: str): """从用户消息中尝试提取记忆点，返回记忆文本或 None""" for marker in PREFERENCE_MARKERS: if marker in message: # 以标记为分界，取后半句作为记忆内容 memory_text = message.split(marker, 1)[1].strip() if memory_text: return f"用户偏好：{memory_text}" return None

这个函数虽然简单，但表现很直观：消息里包含“请记住回复不要超过 100 字”，提取结果就是“用户偏好：回复不要超过 100 字”。

4.5 模拟带记忆的 AI 助手

下面实现chatbot.py。这里不用真实的大模型接口，而是模拟一个大模型函数，同时展示记忆的读取和注入流程。你可以把fake_llm_reply替换成任何你实际使用的大模型接口。

# 文件路径：memory_demo/chatbot.py from memory import ( add_memory, get_all_memories, search_memories, extract_memory_from_message, ) def fake_llm_reply(user_message: str, memories: list) -> str: """模拟大模型回答。真实项目中这里调用 OpenAI/Claude/本地模型接口， 把 user_message 和 memories 一起拼入提示词即可。""" if not memories: return f"（模型没有找到相关记忆）你好！我收到了你的消息：{user_message}。请问需要我做什么？" memory_text = "；".join(m["content"] for m in memories) return f"（模型注入了记忆：{memory_text}）好的，我明白了。关于你说的“{user_message}”，我会结合你的偏好来处理。" def chat_once(session_id: str, user_message: str): """单次对话流程：提取记忆 -> 检索记忆 -> 生成回复""" # 1. 尝试从当前消息中提取新记忆 new_memory = extract_memory_from_message(user_message) if new_memory: add_memory(new_memory) print(f"[记忆系统] 已保存新记忆：{new_memory}") # 2. 检索与当前消息相关的旧记忆 related_memories = search_memories(user_message[:6]) # 3. 如果没有关键词命中，则把用户最近一条记忆作为上下文（简化演示） if not related_memories: all_mems = get_all_memories() if all_mems: related_memories = [all_mems[0]] # 4. 调用模型生成回复 reply = fake_llm_reply(user_message, related_memories) return reply if __name__ == "__main__": print("===== 第一次会话 =====") reply1 = chat_once("session-1", "请记住回复不要超过 100 字") print(reply1) print("\n===== 模拟新会话 =====") reply2 = chat_once("session-2", "以后回答我的问题时长话短说") print(reply2)

运行这段代码会看到类似输出：

===== 第一次会话 ===== [记忆系统] 已保存新记忆：用户偏好：回复不要超过 100 字 （模型注入了记忆：用户偏好：回复不要超过 100 字）好的，我明白了。关于你说的“请记住回复不要超过 100 字”，我会结合你的偏好来处理。 ===== 模拟新会话 ===== [记忆系统] 已保存新记忆：用户偏好：回答我的问题时长话短说 （模型注入记忆：用户偏好：回复不要超过 100 字；用户偏好：回答我的问题时长话短说）好的，我明白了。

注意第二次会话时，search_memories用消息前 6 个字“以后回答我的问题”去搜索，并没有直接命中“回复不要超过 100 字”，这时演示代码会退化成最近一条记忆。这个退化逻辑只是为了演示，实际项目中不能这么草率。

4.6 如何接入真实的大模型

把fake_llm_reply替换成真实模型调用时，推荐的做法是把检索到的记忆作为 system prompt 的一部分。以 OpenAI 兼容接口为例：

import os from openai import OpenAI client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_BASE_URL")) def real_llm_reply(user_message: str, memories: list) -> str: memory_block = "\n".join(f"- {m['content']}" for m in memories) system_prompt = f"""你是用户的长期 AI 助手。 以下是关于用户的长期记忆： {memory_block} 回答用户问题时，请优先遵循这些记忆中的偏好。""" response = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_message}, ], temperature=0.3, ) return response.choices[0].message.content

这里的核心思路是：记忆不依赖模型自己记住，而是应用层主动注入。只要检索准确，模型表现就会像“记得你”一样。

5. 进阶：向量检索与语义记忆

5.1 关键词检索的局限

上面的 SQLite 示例用LIKE做关键词匹配，存在一个明显的短板：语义泛化能力差。用户第一次说“我喜欢简洁回复”，第二次问“你能不能别讲那么多废话”，关键词之间完全不一样，但语义上是同一个意思。如果只做关键词匹配，很难把这两条记忆关联起来。

解决这个问题的关键就是向量检索。把记忆文本转成向量（embedding），把用户当前问题也转成向量，然后在向量空间里计算相似度，找出语义上最接近的记忆。

5.2 简化实现思路

完整的向量检索涉及 embedding 接口、向量库索引、相似度计算。这里给出一个轻量级的示例，展示核心流程。

假设我们安装了两个库：

pip install openai chromadb

示例代码：

# 文件路径：vector_memory_demo/vector_memory.py from openai import OpenAI client = OpenAI() # 需配置 API Key def get_embedding(text: str) -> list: """调用 embedding 接口生成向量""" resp = client.embeddings.create( model="text-embedding-3-small", input=text, ) return resp.data[0].embedding def semantic_search(query: str, memories: list, top_k: int = 2) -> list: """在记忆列表中做语义检索""" query_vec = get_embedding(query) scored = [] for mem in memories: mem_vec = get_embedding(mem["content"]) # 简化版余弦相似度 dot = sum(q * m for q, m in zip(query_vec, mem_vec)) norm_q = sum(q * q for q in query_vec) ** 0.5 norm_m = sum(m * m for m in mem_vec) ** 0.5 score = dot / (norm_q * norm_m) scored.append({"memory": mem, "score": score}) scored.sort(key=lambda x: x["score"], reverse=True) return scored[:top_k]

这份代码在真实使用中需要注意一点：每一条记忆每次检索都实时调用 embedding 接口，开销很大。生产环境应该在记忆写入时就提前算好向量并存起来，检索时只对问题做一次 embedding，再和库里已有的向量做相似度计算。这也是为什么很多项目会直接用 Chroma、Milvus、pgvector 这类专用存储。

5.3 记忆更新的工程策略

有了向量检索后，新的问题出现了：记忆会不断增长，如果不管不顾地往里塞，一段时间后发现模型把它当成“上下文垃圾场”，反而降低回答质量。这时候就需要设计记忆更新策略，常见的有：

• 去重合并：新记忆和旧记忆语义相似度很高时，用新内容更新旧内容，而不是新增一条。
• 遗忘机制：超过一定时间未命中的记忆自动降级或删除。Redis 的 TTL 就是一个直观例子。
• 手动确认：用户明确表示“记住”的信息优先级，高于系统自动抽取的信息。
• 重要性分层：身份背景、技术栈、偏好这些长期稳定的信息放高位，临时任务相关记忆放低位，上下文紧张时优先截断低位内容。

在项目实践中，比较推荐的做法是引入“记忆置信度”概念：用户在多个会话中重复表达的偏好，置信度不断提高；只出现过一次且没有主动确认的，置信度较低。这样既可以保留关键记忆，又不会积累太多噪声。

6. 常见问题与排查思路

动手实现记忆系统时，一定会碰到这些问题。按下表排查，绝大多数都能快速定位。

针对最后一点要特别说一下：AGENTS.md 是团队资产。如果谁都可以随手改而且不经过评审，很快会变成一堆互相矛盾的指令。建议像维护 README 一样维护它，改动时在 MR/PR 中说明原因。

7. 最佳实践与工程建议

7.1 记忆写入要克制

并不是所有对话内容都值得变成记忆。“今天天气不错”这种寒暄没必要存；“我负责的微服务模块是订单服务”这种关键事实才值得存。建议在提取记忆前加一道门槛：只有用户主动强调、带有明确偏好或身份信息的内容才写入。

7.2 记忆读取要带时间感知

用户半年前的偏好可能已经变化了。检索到历史记忆后，最好把记忆的updated_at一并注入，让模型知道这条记忆是“三个月前确认的”，在时间敏感性场景下提醒用户确认。这样做能明显减少“AI 拿着旧偏好给新建议”的问题。

7.3 隐私与数据边界

记忆数据往往包含用户隐私。实际开发中要做到至少以下几点：

• 敏感字段加密存储，Full Memory 备份时避免明文泄漏。
• 支持用户查看、导出、删除自己的记忆。
• 不要将记忆内容发送到第三方大模型，除非已经在用户协议中说明并获得授权。
• 测试环境使用假数据，不用产品库里的真实用户记忆来调 bug。

7.4 AGENTS.md 要团队共建

AGENTS.md 不应该是某个人的个人笔记，而是团队协作的产物。落地时可以考虑：

• 初始化模板由架构师或 Tech Lead 起草。
• 构建命令、测试命令、编码规范，务必从真实的 CI/CD 配置里复制，而不是手写。
• 每次 AI 代理给出不符合预期的结果后，反思是不是 AGENTS.md 里少了约束，然后补充进去。
• 不要写得过长。理想状态是 50~150 行，超过 300 行后 AI 代理聚焦关键指令的效果会下降。

7.5 监控记忆效果

如果记忆系统上了生产，最怕的是“看起来有记忆，实际上变成噪声”。建议在日志中记录每次检索命中情况、记忆注入的 token 数量、用户对回答的反馈（点赞/点踩）。用这些数据定期清理低质量记忆，并调整抽取策略。没有反馈闭环的记忆系统，本质上是在盲目堆数据。

8. 总结与下一步

这篇文章围绕“让 AI 长期读懂你”做了比较完整的拆解：先从 AGENTS.md 讲清楚静态项目记忆怎么落地，再从动态记忆讲清楚对话偏好如何沉淀到 SQLite、如何引入向量检索语义召回。代码示例可以直接运行，也可以作为基础改造成生产级方案。

如果接下来要继续深入，建议按这个路线走：

• 先给你的项目写一份 AGENTS.md，坚持用一周，观察 AI 编码助手的表现变化。
• 然后动手把文中 SQLite 示例跑通，理解记忆插入、检索、更新的完整链路。
• 再深入向量检索，学习 embedding 模型的选择和向量数据库的基本使用。
• 最后把记忆模块接入真实模型，从小流量用户开始灰度验证。

记忆是 AI 应用走向“个性化”的关键一环。它不像模型调参那样有那么多炫技空间，但恰恰是这些笨功夫，决定了用户觉得 AI“懂我”还是“像初次见面”。建议你从今天起，先把项目里的 AGENTS.md 写起来，再逐步把动态记忆加上去，一步步做出真正能读懂用户的 AI 助手。