企业官网建设流程全解析

前阵子有个朋友跟我抱怨：他让 AI Agent 帮他整理了项目文档、梳理了接口规范、还写了好几页开发笔记，结果第二天打开新会话，Agent 像是失忆了一样，又问他“你们的项目背景是什么”。这几乎是所有用过 AI Agent 的人都会撞上的墙：同一段对话里它能记住很多内容，换一个会话、过一天、换一个客户端，它就把你忘得一干二净。

这个问题的本质不是模型变笨了，而是它缺少一套真正属于自己的长期记忆系统。市场上有不少记忆方案，但 Basic Memory 的思路和大多数不太一样：它把记忆落成本地 Markdown 文件，通过 MCP 协议暴露给 Agent，用 SQLite 和语义检索完成召回。换句话说，它不是把记忆塞进一个黑盒数据库，而是让“记住什么”“忘掉什么”变成你可以直接查看、编辑、维护的工程资产。

这篇文章我会从问题本质讲起，带你完整走一遍 Basic Memory 的搭建、配置、使用和维护流程，并且把那些容易踩坑的地方单独拎出来说。

1. 先想明白：AI Agent 为什么会“失忆”

很多人把 AI Agent 当成一个“越用越懂你”的工具，但现实是，绝大多数 Agent 根本不具备跨会话记忆。它每次面对你的时候，唯一的依赖就是当前上下文窗口里的内容。

1.1 上下文窗口不是记忆，而是工作台

你可以把上下文窗口理解成一张工作台：模型能看到什么，完全取决于工作台上摆了什么东西。你粘贴的文档、之前的对话、工具返回的结果，都在这个台面上。但工作台的空间是有限的，而且一旦会话结束，桌子就被收走了，第二天重新给你一张空桌子。

所以，模型不是“忘了你”，而是它从来没有机会把信息从一次会话搬运到另一次会话。这就像一个新同事每天上班都失忆，只靠当天邮件和聊天记录工作，你对他的所有了解都留在了前一天。

长期记忆要解决的，就是给这张工作台配一个“外置硬盘”：能写入、能读取、能检索，而且不随会话结束而消失。

1.2 会话隔离造成“每次从头认识你”

在真实工作流里，AI Agent 通常以会话为单位工作。开会话 A 的时候，它记得你在 A 里说过的偏好；开会话 B 的时候，它完全不知道 A 的存在。这对个人助手、代码助手、内容创作助手来说都是很大的限制。

最典型的场景是：

• 你让 Agent 在会话 A 里确定了“项目的后端用 Python，接口文档放在 docs/api.md”；
• 换到会话 B，想让它继续开发新功能，它又从头问起项目结构，甚至可能推荐一套和之前完全冲突的技术方案。

更麻烦的是，这种“失忆”不只是信息丢失，还会带来一致性破坏。你花了很多时间建立的偏好和规范，一旦 Agent 记不住，每次都是重新磨合。长期记忆系统存在的意义，不只是“多存点东西”，而是让 Agent 的行为表现具有连续性。

1.3 长期记忆真正要解决的是“可复用、可检索、可修正”

长期记忆如果只是“能存能读”，还远远不够。它必须具备三个能力：

1. 可复用：过去在一次会话里沉淀的信息，能被未来的任何会话复用，而不是只对当前场景有效。
2. 可检索：记忆量变大后，Agent 要能快速找到相关内容，而不是把所有历史记录强行塞进上下文。
3. 可修正：记忆出错或过时时，你能直接改、直接删，而不是让 Agent 自己猜。

Basic Memory 的核心设计，刚好就是围绕这三个能力展开的。这也是我要推荐先去理解它的原因：它不是单纯给你一个“记忆更大的箱子”，而是重新定义了记忆在 AI Agent 工作流里的形态。

2. Basic Memory 用一套什么思路解决长期记忆

Basic Memory 表面上是一个记忆工具，实际上的设计取舍很值得琢磨。它没有走常见的“向量数据库 + 检索增强生成”路线，而是选了一条更工程化、更可维护的路径。

2.1 把记忆落成 Markdown：可读、可改、可版本控制

Basic Memory 最鲜明的特点，是记忆的载体是本地 Markdown 文件。每条记忆就是一个 Markdown 笔记，文件名、标题、标签、正文都清清楚楚。你可以用任何编辑器打开，直接修改，甚至丢进 Git 仓库里做版本管理。

这种设计有个很实际的好处：记忆系统不再是“黑盒”。当你发现 Agent 记住了一个错误信息，你可以直接打开对应文件改掉，而不是在数据库里做不知道会影响到什么的 update。这一点对长期使用非常重要。

一个典型的记忆文件可能是这样的：

--- title: 技术栈偏好 tags: [preference, project] date: 2025-01-01 --- 用户的后端技术栈是 Python + FastAPI，缓存使用 Redis。 接口文档统一放在 docs/api.md 下。

frontmatter 里的字段可以灵活扩。你可以自己定义 tag、project、status 等元数据，Basic Memory 会把这些信息作为检索和归类的依据。

2.2 用 SQLite 和语义检索解决“怎么找回来”

存储只是第一步，关键是“怎么找回来”。Basic Memory 的思路是：在 Markdown 文件基础上建立索引，同时利用 SQLite 做结构化查询，配合嵌入模型生成向量表示做语义检索。

这里要区分两种检索方式：

实际使用时，Agent 会先根据用户的问题，自己判断是走精确搜索还是语义搜索。你可以把这两层理解成一个同事先翻你整理的笔记目录，再按语义扫一遍相关主题，最后挑出最相关的几张卡片放到当前会话里。

2.3 通过 MCP 把记忆变成 Agent 的工具

Basic Memory 不是以一个单独的程序让你手动操作，而是作为 MCP 服务器接入 AI Agent。MCP（Model Context Protocol）是当前 AI Agent 生态里比较通用的工具接入协议，你可以把它理解成“AI 世界的 USB 接口”：Agent 通过这个协议调用外部工具，读写外部数据。

接入 MCP 后，Basic Memory 会把记忆操作变成一组 Agent 可以直接调用的工具，通常包括：

• 写入新记忆（创建一条笔记）
• 读取指定记忆（按 ID 或路径读取文件）
• 搜索记忆（关键词搜索或语义搜索）
• 列出记忆（按标签、日期、目录列出相关笔记）

Agent 在对话过程中，如果判断当前信息需要长期保留，就会调用“写入记忆”工具；如果用户提问涉及历史信息，它就会调用“搜索记忆”工具。这个过程对用户来说是自动的，但你又可以通过日志看到它的每一步动作。

2.4 和向量数据库、RAG 方案的核心差异

很多人会问：这和搞一个向量数据库做 RAG 有什么区别？

最本质的区别在于记忆的管理权。传统 RAG 方案里，文本被切块、向量化、存进向量库，用户看到的是“知识库”，但很难直接干预“哪些内容会被记住、按什么逻辑组织”。Basic Memory 则把记忆还原成“笔记”，格式是人类可读的，结构是由你定义的，检索逻辑也尽量透明。

另外，向量数据库方案通常是为了解决“超大语料知识库”的召回问题，而 AI Agent 的长期记忆更像“个人外脑”，规模不一定大，但对可读性、可维护性要求更高。用记笔记的方式做记忆，比用切块入库的方式更贴合 Agent 的实际使用场景。

3. 从 0 搭建：安装、配置、验证

下面进入实操部分。这里我给出一套相对稳妥的搭建路径，覆盖从环境准备到验证连接。因为 Basic Memory 依赖 MCP 客户端，所以不同客户端的配置入口会略有差异，但整体思路是一致的。

3.1 环境准备：需要哪些前置条件

搭建之前，建议先确认好以下几项：

• Node.js：因为 Basic Memory 一般通过 npx 方式启动，建议使用 Node.js 18 或更高版本，常见版本即可，不需要特意追求最新版。
• 一个支持 MCP 的 AI 客户端：Claude Desktop、Claude Code、Cursor 等都是常见选择，具体看你自己日常用哪个。
• 可用的数据目录：建议先规划一个专门存放记忆文件的目录，比如~/basic-memory或项目内的basic-memory-data。
• 网络环境：第一次通过 npx 启动时会拉取包，需要能正常访问 npm 源。

这些前置条件里，最容易出问题的是 MCP 客户端版本。有些客户端版本不支持自定义 MCP 服务器，有些则改了配置入口。如果你在配置界面找不到“MCP”相关选项，建议先升级客户端到最新稳定版。

3.2 以 MCP 服务方式启动

Basic Memory 的常规启动方式不是执行一个前台脚本，而是作为一个 MCP 服务器，由客户端自动拉起。常见写法是：

{ "mcpServers": { "basic-memory": { "command": "npx", "args": ["-y", "basic-memory"], "env": { "BASIC_MEMORY_PATH": "/绝对路径/basic-memory-data" } } } }

这段配置的意思是：客户端启动时，自动通过 npx 运行basic-memory包，并指定数据目录。BASIC_MEMORY_PATH这个环境变量不是每个版本都必须，但建议显式设置，避免记忆文件被写到默认位置后你找不到。

注意：这里给出的是常见的 MCP 配置结构。不同客户端对配置文件的字段、放置位置要求可能不同，落地前先确认你所用客户端的 MCP 配置格式。

3.3 在客户端里配置 MCP 服务器

具体到不同客户端，操作入口有差异。以桌面类客户端为例，通常是在设置里找到 MCP 或开发者选项，然后编辑 JSON 配置；以命令行类客户端为例，通常在项目根目录下维护一个.mcp.json文件，或者在用户级配置目录里维护全局 MCP 配置。

配置成功后，客户端一般会显示“已连接”或列出可用的 MCP 工具。如果启动时报错，优先检查 npx 是否能正常执行、网络是否通畅、Node 版本是否符合要求。

有一个容易被忽略的点：很多客户端在修改 MCP 配置后不会热加载，需要重启客户端进程。如果你改完配置发现工具没出现，先重启一次再验证。

3.4 验证连接和目录结构

配置完成后，首先要做的不是让 Agent 写大量记忆，而是做一次最小验证。

可以先在数据目录里手动创建一个测试笔记，然后问 Agent：“你还记得我之前创建的测试笔记吗？帮我看看它的内容。”如果 Agent 能读取并正确回答，说明 MCP 连接和读取链路是通的。

接着，可以尝试让 Agent 写一条新记忆，比如：“记住：我的博客平台是 CSDN，写作主题是 AI 工程实践。”然后去数据目录里检查是否生成了对应的 Markdown 文件。如果文件存在且内容正确，说明写入链路也通了。

到这里，Basic Memory 的基础搭建就算完成。你会发现它本身不复杂，真正值得花时间的是后续怎么设计记忆结构、怎么引导 Agent 正确使用记忆。

4. 让 Agent 真正记住：写入、检索、修改

搭建完成后，很多人会急着让 Agent 往记忆库里塞东西。我建议你先慢一点，把“写入、检索、修改”这三类操作都跑一遍，形成手感，再投入正式使用。

4.1 第一条记忆怎么写

写入记忆最简单的方式，就是在对话里直接告诉 Agent“记住什么”。比如你可以在新会话里说：

“请记住，我的项目使用 TypeScript，前端框架是 React，后端是 Node.js + PostgreSQL。”

正常情况下，Agent 会判断这些信息属于长期偏好，然后调用 Basic Memory 的写入工具，生成一条笔记。你不需要手动选择工具，但你可以通过客户端的日志或工具调用面板看到它做了什么。

为了让 Agent 更稳定地写入，你可以给一条相对明确的指令。例如：

“把这条信息记录到长期记忆里：项目的构建命令是 npm run build，测试命令是 npm test。”

这样做的价值是降低 Agent 的判断成本，让它明确知道“这条信息要长期保留”。日常使用中，不是每句话都值得记住，但凡是项目规范、用户偏好、关键决策，都应该主动让 Agent 写入。

4.2 怎么让 Agent 主动调用记忆

很多用户遇到的问题是：记忆已经写进去了，但新会话里 Agent 还是不主动用。

这个问题的原因通常有两个。第一个是 Agent 在新会话里不知道你有记忆库，或者不知道应该在什么时机去查记忆；第二个是记忆文件内容不完整、检索出来不匹配，Agent 宁可不用。

解决办法是在对话指令里把“先查记忆”这个动作变成惯例。比如：

“先查阅你的长期记忆，看看我之前的项目技术栈，再回答这个问题。”

这种命令式触发在前期很有用。等 Agent 熟练了，再加上合适的系统提示词，它会更自觉地在遇到相关问题时先检索记忆库。

从工程实践看，比较可靠的模式是：

• 每次启动任务前，先问一句：“根据我的长期记忆，这个项目的技术栈和约定是什么？”
• 让 Agent 明确汇报它读取了哪些记忆文件，方便你确认它没有乱猜。
• 如果发现某个信息没被读取，检查是否是因为标题、标签不匹配导致检索漏掉。

4.3 记忆的更新和删除

记忆不是写一次就永远不变。项目会改技术栈，偏好会变，过期信息会误导 Agent。Basic Memory 的优势在于，你可以直接修改 Markdown 文件，或者让 Agent 更新指定笔记。

更新时，最好明确告诉 Agent 要修改哪条记忆以及改成什么，避免它新建一条重复笔记。删除也一样，直接指定“删除关于 XX 的记录”。

尤其要注意的是重复记忆问题。如果 Agent 反复把相似内容写成新笔记，时间一长记忆库会膨胀和混乱。建议每隔一段时间就整理一次，合并重复笔记、清理过时信息，并把常用决策沉淀成稳定条目。

4.4 一个完整的工作流示例

我把一个典型工作流串起来，方便你理解：

1. 新接手一个项目，先让 Agent 建立项目笔记：技术栈、目录结构、构建命令、部署方式。
2. 日常开发中，每当确定一个关键约定，就让 Agent 追加到对应笔记里。
3. 新会话开始，先让 Agent 读项目记忆，再开始写代码。
4. 代码评审后，把评审结论和常见陷阱记录到记忆库，避免下次踩同一个坑。
5. 每周做一次记忆库清理：合并重复、删除过时、优化标签。

这样一来，Agent 不再是从零认识项目，而是一打开会话就带着你过去积累的所有上下文。这也是长期记忆最直接的价值：它把一个“每次都像刚认识”的助手，慢慢变成一个“了解项目历史”的协作者。

5. 记忆库要能长期用，关键在维护

搭建和基本使用只是开始。真正决定长期记忆系统能不能持续发挥价值的，不是存储容量，而是记忆库的组织方式和维护频率。

5.1 先建立项目笔记、个人偏好、通用背景三层结构

建议在记忆库中规划三类笔记，避免什么信息都堆在一起：

• 项目笔记：以项目为单位，记录技术栈、目录结构、命令、部署流程、常见坑点。
• 个人偏好笔记：记录使用者的写作风格、代码风格、工具偏好、常用平台。
• 通用背景笔记：记录与具体任务无关，但会长期复用的行业知识或方法论。

这个分层不一定要靠目录实现，也可以通过标签来管理。比如给笔记打上project/xxx、preference、knowledge等标签。检索时按标签缩小范围，准确率会高很多。

5.2 目录结构和命名规范

虽然长期记忆系统能通过语义搜索找内容，但命名和目录规范依然重要。原因有两个：一是你自己要能看懂记忆库，二是 Agent 的搜索排序会受标题和路径影响。

常见做法是：

• 按笔记类型建目录：/projects/、/preferences/、/knowledge/。
• 文件名尽量简洁、有辨识度，比如project-fe-tech-stack.md，而不是note-001.md。
• 每条笔记的标题要能描述核心内容，方便快速扫描。

如果你不确定怎么组织，可以先从“一个项目一个文件”开始。等记忆量大了，再按主题拆分。刻意追求复杂的目录结构，反而会让维护成本变高。

5.3 定期整理与版本控制

因为记忆文件是 Markdown，你可以很自然地把整个记忆库纳入 Git 管理。这样每次改动都有记录，万一 Agent 写坏了或者你改错了，还能回滚。

我建议的整理节奏是：

1. 每周检查一次记忆库，看看有没有重复、过期、文件名混乱的笔记。
2. 每次项目关键节点后，更新对应的项目笔记，删掉不再适用的旧约定。
3. 每次更新完记忆库，提交一次 Git commit，形成历史记录。

这个习惯看起来简单，但能显著提高长期记忆系统的可信度。否则，Agent 记住的内容越多，里面的错误也越多，最后你会变得不再信任它。

5.4 避免把“记忆库”变成“垃圾场”

长期记忆系统的最大风险，不是记不住，而是记住太多无价值信息。如果 Agent 事无巨细都往记忆库里写，检索质量会直线下降，因为真正重要信息被淹没在大量过时、重复、琐碎的内容里。

所以，需要给 Agent 设定写入标准。比如：

• 只有跨会话复用的信息才需要写入。
• 临时任务细节不要写入。
• 同一主题的增量信息，优先更新已有笔记，而不是新建笔记。

遇到记忆库变得混乱时，不要试图靠 Agent 自动整理，直接手动干预更高效。毕竟它能自动写入，但不一定理解你的组织逻辑。

6. 常见问题排查与适用边界

最后聊一聊实际使用中容易遇到的问题，以及这套方案适合谁、不适合谁。

6.1 从现象到原因的排查链路

如果你遇到“Agent 不调用记忆”“读写失败”“检索结果不对”等问题，别急着怀疑工具不行，按下面顺序排查：

1. 看现象：是完全没有调用工具、调用了但报错、还是读了但答非所问。
2. 看输入：记忆文件是否存在、标题和正文是否清晰、Agent 是否能从对话中判断“该查记忆”。
3. 看环境：npx 能否正常运行、Node 版本是否符合要求、数据目录是否能读写、MCP 进程是否启动。
4. 看客户端配置：MCP 配置是否被正确加载，修改配置后是否重启客户端。
5. 看检索条件：标签、关键词、日期范围是否设置合理；语义搜索的嵌入模型是否正常。
6. 看工具边界：当前客户端是否真的暴露了 Basic Memory 的工具；是否被其他工具抢占调用；版本兼容性是否有问题。

这个顺序基本能覆盖 90% 的场景。最常见的坑是看似配置好了，但客户端加载的是旧配置，或者 npx 拉包失败导致 MCP 进程没有真正启动。

6.2 适合谁、不适合谁

适合人群：

• 喜欢把记忆掌握在自己手里，希望记忆是可读、可改、可版本控制的开发者。
• 经常和 AI Agent 协作，希望跨会话保留代码规范、项目上下文、写作偏好的用户。
• 愿意花时间维护记忆结构，不追求“开箱即用”的人。

不太适合的场景：

• 如果你希望“全自动记忆”，完全不想干预 Agent 记住了什么，Basic Memory 可能不够省心。
• 如果你的记忆库规模达到海量文档级别，需要的是完整知识库方案，而不是个人外脑式的笔记系统。
• 如果你用的客户端不支持 MCP，或者对 MCP 支持不完善，落地成本会高不少。

6.3 回到主判断：长期记忆的真正价值

回到开头那个问题：AI Agent 为什么会失忆？因为它默认没有长期记忆。Basic Memory 给出的答案不是“塞一个更大的上下文池”，而是把记忆做成一组可检索、可读、可改的本地 Markdown 文件，再通过 MCP 交给 Agent 使用。

这个方案的真正价值，不是帮 AI 记住更多内容，而是让“记忆”从不可控的黑盒，变成你可以直接管理的工作流资产。它也提醒了我们一件事：在使用 AI Agent 时，最值得花时间的往往不是调一个更聪明的模型，而是建立一套能让它持续复用经验的基础设施。

如果你正准备给自己常用的 Agent 加一个长期记忆，我建议第一步先别追求功能完整，而是搭一个最小可用配置：一个数据目录、一条测试笔记、一次成功的写入和搜索。跑通之后，再慢慢把项目规范、个人偏好沉淀进去。长期记忆系统的价值，是靠一次一次认真维护积累出来的，不是靠一次配置完成的。