企业官网建设流程全解析

聊一个最近在 AI 编程圈子里讨论度很高的开源项目：claude-mem。如果你用过 Claude Code、Cline 这类对话式 AI 编程工具，多半有过一种“熟悉的陌生感”——上一个会话里刚跟 AI 对齐过的项目架构、目录约定、代码风格，重启一个会话之后它全忘了，你不得不再花十分钟把上下文重新喂一遍。claude-mem 就是冲着这个痛点去的：它给 AI 助手加了一层“长期记忆”，让跨会话的记忆可以自动沉淀、自动检索、按项目隔离。这篇文章我会从原理到配置、从踩坑到实战，完完整整拆一遍。

先给还没接触过的朋友一个定位：claude-mem 是一个基于 TypeScript 开发的记忆层服务，跑在本地，通过 MCP（Model Context Protocol）协议接入 Claude Code 等支持 MCP 的 AI 客户端。它的核心价值不是“多存点对话日志”，而是把散落在会话里的有效信息，比如项目决策、用户偏好、代码约定、技术栈选型，结构化地存进 Markdown 文件，并在后续会话里以工具调用的形式让 AI 随时检索。这篇文章适合两类人：一是被 AI 失忆折磨的日常用户，想给助手装个“脑子”；二是想了解 MCP 记忆层方案选型、准备自己动手定制记忆管道的开发者，可以把它当一份很好的参考样本。

1. 先从痛点说起：对话式 AI 编程助手的“记忆综合征”

1.1 每次对话都像第一次见面，问题出在哪

我最早用 Claude Code 的时候，体验是这样的：第一个会话里，我详细交代了项目用的是 pnpm monorepo、组件库用 shadcn/ui、服务端路由全部走 tRPC，AI 理解得很到位，生成的代码像模像样。但第二天新开一个会话，它又把 web 框架猜成 Next.js 的 pages router，我也不知道该怪谁——从 AI 的角度看，它确实什么都不知道，是一个全新的开始。

这个问题的本质在于：模型本身的上下文窗口是“每会话独立”的，模型权重里固化的通用知识还在，但“你这个项目长什么样”这种个性化信息，在会话结束后就跟着上下文窗口一起被丢弃了。你唯一能做的就是把项目信息写进 CLAUDE.md 或者每次手动贴上下文。可问题在于：CLAUDE.md 是静态的，你得手动维护；手动贴上下文是随机的，漏一次就翻车一次。更现实的是，很多决定是对话过程中临时做出的，比如“改用 React Query 而不是 SWR”“错误边界统一放在 components/ErrorBoundary”，你根本不会想到要去更新 CLAUDE.md。

1.2 claude-mem 是什么：给 AI 装一个“工作笔记本”

claude-mem 的思路很直接：在 AI 和你之间加一层持久化记忆，让“这个项目怎么样”的信息不依赖上下文窗口，而是落到本地文件里。它做的事情可以概括为三件：

• 自动捕获：在会话过程中，AI 调用它提供的 MCP 工具，把关键信息写入记忆文件。
• 结构化存储：记忆不是一坨聊天记录，而是按项目、按用户、按记忆类型组织的 Markdown 文件，带时间戳、事件类型、来源会话等元数据。
• 按需检索：后续会话里，AI 可以主动搜索记忆文件，把相关内容重新拉进上下文。

用大白话讲，以前 AI 是个“每天重新入职的新员工”，现在你给它发了台笔记本，里面记了项目历史、决策记录和个人偏好，它开工前先翻笔记本，不知道的先查再问，而不是瞎猜。

1.3 原理一句话：MCP 协议 + 本地 Markdown 文件

MCP 是 Anthropic 提出的一个开放协议，全称 Model Context Protocol，大意是把 AI 与外部工具之间的交互标准化。claude-mem 就是一个 MCP 服务器：它运行在你本地，AI 客户端通过标准协议调用它暴露出来的工具，比如“写入一条记忆”“搜索记忆”“倒出记忆”。存储载体则是朴素的 Markdown 文件，放在了用户目录下的~/.claude-mem/里面。

选择 Markdown 而不是数据库，我觉得是个很聪明的决定：一来对人类可读，你可以直接用编辑器打开看 AI 到底记了什么；二来容错率高，文件坏了顶多丢一段记忆，数据库崩了整个服务都瘫；三来方便 git 化，你可以把记忆目录纳入版本管理，跟团队共享沉淀。这个设计取向很值得学习——工具可以先复杂，但存储格式一定要简单。

2. 环境准备与安装：从零跑通 claude-mem

2.1 需要准备的环境清单

claude-mem 在技术栈上依赖 Node.js，因为 npn 包本身是 TypeScript 编译出来的 CLI 程序，所以你本机至少要有 Node.js 环境。官方建议 Node 18 以上，实测下来 Node 20 和 22 都很稳。如果你用的是 Homebrew 安装的 Node，基本不用额外折腾。

其次，你需要一个支持 MCP 的 AI 客户端。目前集成度最好的是 Claude Code，配置方式是编辑项目或用户目录下的.mcp.json。Cline、Continue 这类工具也支持 MCP，配置方式大同小异，后面我会给一个通用写法。

环境要求： - Node.js 18+ - 一个支持 MCP 的 AI 编程客户端（Claude Code / Cline 等） - 一个实际的项目目录（建议先用小项目试跑）

提示：不要一上来就装到全局系统目录里做实验，可以先找个临时目录或者小项目验证，配置干净，出问题了也好排查。

2.2 安装步骤与 .mcp.json 配置

安装非常简单，一条命令搞定：

npm install -g @smithery-ai/claude-mem

装完可以用下面的命令确认版本号：

claude-mem --version

正常情况下会输出一个语义化版本号，比如0.x.x。这一步能跑通，说明 CLI 本身没问题。接下来就是接入 AI 客户端了。以 Claude Code 为例，需要在项目根目录添加一个.mcp.json文件：

{ "mcpServers": { "claude-mem": { "command": "claude-mem", "args": [] } } }

如果你担心全局命令找不到，也可以用npx方式启动：

{ "mcpServers": { "claude-mem": { "command": "npx", "args": ["-y", "@smithery-ai/claude-mem"] } } }

我个人更推荐第二种，因为npx会自动解析到最新版本，不用定期手动更新 npm 包。代价是每次冷启动会多几百毫秒的依赖检查时间，不过对于记忆层这种低频调用场景，完全感知不到。

配置好后，重启你的 Claude Code 会话，让它加载新的 MCP 配置。不同版本的 Claude Code 加载方式略有差异，新版通常在启动时自动读取，老版本可能需要输入/mcp重连或者干脆重启终端。

2.3 验证安装是否生效

配置完别急着开始干活，先花十秒钟验证一下。在对话里直接问 AI：你能看到哪些 MCP 工具？如果 claude-mem 接入成功，AI 会列出它可调用的工具，比如claude_mem_store_auto_memory、claude_mem_search、claude_mem_store_declarative_memories这一串。

另一个更直接的验证方式：聊几句项目相关的内容，然后打开~/.claude-mem/目录看看。正常情况下会生成按项目名命名的目录，里面已经有会话记录或记忆文件的雏形了。如果这两步都通过，说明记忆层已经在后台开始工作。

3. 核心配置：让记忆按你的方式存储

3.1 目录结构与记忆文件类型

跑通基本安装后，下一步是理解它到底把东西存在哪。claude-mem 的记忆根目录在用户目录下：

~/.claude-mem/

里面大致分了三类内容：

• 会话记忆（session memory）：按项目和日期存放的会话日志，是自动捕获的原始素材。
• 声明式记忆（declarative memory）：你或 AI 主动声明“这个必须记住”的信息，比如项目技术栈、代码规范、架构决策。
• 铭牌记忆（badge memory）：项目级身份标记，相当于给项目贴了个“我是谁”的标签，让 AI 一眼认出这是什么项目、用什么框架、有什么约束。

实际目录结构可能长这样：

~/.claude-mem/ └── agents/ └── claude-code/ └── projects/ └── my-web-app/ ├── output/ │ └── 2025-01-01-abc123.md ├── declarative-memory.md └── badge.md

为什么要按agents再按projects拆两层？我的理解是：同一个记忆库里可能跑着多个 AI 客户端，Claude Code、Cline、Continue 都来读写，如果混在一起会互相污染；同一个客户端也会同时打开多个项目，按项目隔离后才能保证“这个项目查到的记忆是只属于这个项目的”。

3.2 声明式记忆文件：手把手教 AI 记什么

自动记忆很省心，但有些信息你不想等它自动发现，而是要明确告诉它“这些就是事实，不许再问”。这就是声明式记忆的用途。

打开~/.claude-mem/agents/claude-code/projects/<项目名>/declarative-memory.md，你会发现它支持一个非常简洁的键值语法，核心就是key: value，换行分隔：

# declarative-memory.md 示例 project_name: MyWebApp tech_stack: Next.js 14, TypeScript, Tailwind CSS package_manager: pnpm api_pattern: tRPC, 所有服务端逻辑放在 /server/routers database: PostgreSQL + Prisma auth: NextAuth.js, 会话策略是 JWT error_handling: 全局 ErrorBoundary 在 /components/ErrorBoundary

这个文件的读取时机是每次会话开始前。也就是说，只要这个文件存在，AI 开工前就会把它当作项目背景读一遍。这比 CLAUDE.md 更强的地方在于：CLAUDE.md 是给“当前会话”的提示词，而这个声明式记忆是通过 MCP 工具主动拉取的，它可以被检索、被追加、被其他进程管理。

实际使用中我发现一个经验：声明式记忆的条目不要求多，但要求“硬”。每一条都应该是那种“你不想让 AI 猜错第二次”的事实。比如component_library: shadcn/ui这种就非常值得写；像“项目还可以”“代码风格尚可”这种模糊描述写了等于没写。

3.3 触发方式：怎么让 AI 知道“这条要记住”

除了手动编辑声明式记忆文件，你还可以在对话里让 AI 帮你存记忆。两种最常用的方式：

第一种是显式指令。直接在对话里说“记住：测试命令统一用pnpm test:unit，不要用 jest 的默认配置”。AI 识别到这是记忆指令，就会调用 MCP 工具把这条写入声明式记忆。

第二种是代码内标记。claude-mem 支持一类特殊的注释标记，比如pre-mem。你可以在代码文件里写：

// pre-mem: 此项目禁止直接修改 /legacy 目录下的代码，重构前先与负责人确认

AI 在阅读代码时看到这个标记，就会把对应内容提取为记忆。这个设计我觉得非常妙——它把记忆的写入动作从“对话时”延伸到了“写代码时”，等于让你在代码旁边贴便利贴，AI 看代码时顺手就记住了。团队协作时，这个特性尤其有用：老成员在关键文件里留几条pre-mem，新会话的 AI 读到文件就等于读到了团队约定。

3.4 ignore 与白名单：别让垃圾冲淡记忆

记忆层的最大风险不是“记不住”，而是“什么都记”。如果 AI 把每句话都当成记忆存下来，检索时噪音会淹没信号。

claude-mem 提供了 ignore 机制来控流。你可以在记忆目录或项目根目录配置忽略规则，告诉它哪些目录、哪些文件名模式不需要记忆。比如：

node_modules/ dist/ build/ *.log

实际项目中我踩过一个坑：AI 把node_modules里的包名、版本号全部提取进记忆，导致搜索“React”时返回几十条无关片段。加一行node_modules/到忽略规则后，检索质量立刻提升。这个经验分享给每个准备长期用 claude-mem 的人：忽略规则不是可选项，是必选项。

3.5 铭牌文件：让 AI 看一眼就知道在哪个项目

铭牌（badge）文件是 claude-mem 里很特别的一种记忆，它保存的是项目的“身份摘要”。不像声明式记忆那样追求全面，铭牌只回答几个基础问题：这是什么项目？主要技术栈？构建命令？测试命令？运行方式？

它的价值在于极速召回。AI 开工时如果能在几毫秒内读到铭牌，就不需要去翻一整份声明式记忆，可以更快进入状态。你可以把它看作项目的“前台名片”，声明式记忆是“档案室”。

# badge.md 示例 name: MyWebApp description: 面向 C 端用户的工具型 Web 应用 tech_stack: Next.js (App Router), TypeScript, Tailwind install_command: pnpm install build_command: pnpm build test_command: pnpm test:unit run_command: pnpm dev

注意：铭牌内容要短小精悍，只写那些“几秒内读完”的信息。如果你发现铭牌已经写了五十行，那大概率是把声明式记忆的内容混进来了。

4. 实操经验：让 claude-mem 真正为项目提效

4.1 上线初期：先让它“听”，再让它“记”

我建议任何新项目接入 claude-mem 后，不要立刻手动塞一堆声明式记忆，先以自动捕获为主，跑两三天再说。原因有两个：第一，你还没摸清 AI 在这个项目里最容易记错什么，盲目预设反而可能固化了错误认知；第二，自动捕获的记忆能反映真实的工作模式，等你回头翻看，会发现自己最常关注的是哪几类信息。

跑了两三天后，打开output/目录翻一翻会话记录，重点看两类内容：一是重复出现的项目信息，比如每次对话你都要重申一次“数据库连接串在.env.local”，这说明它没记住，需要写进声明式记忆；二是 AI 明显搞错过的点，比如把 SQLite 当成 PostgreSQL 来优化，这种也必须固化。

4.2 把项目约定“喂”给记忆层

项目约定是 claude-mem 最值得投入的信息类型。我通常会整理四类：

1. 技术选型与架构决策：用了什么框架、为什么不用另一个。比如“状态管理用 zustand，不用 redux，因为项目体量小”。
2. 目录结构与文件职责：/components只放 UI 组件，业务逻辑放/hooks。
3. 代码风格与命名规范：组件文件名用 PascalCase，工具函数用 camelCase。
4. 协作约定：CI 里跑哪些检查、提交信息格式、分支命名规则。

这些约定只要写进声明式记忆，后续会话里 AI 生成的代码就会自动贴合项目风格。实测下来，最明显的变化是：生成组件时不再出现我在别的项目里常用的 Vite + Vue 套路，而是老老实实按 Next.js + Tailwind 的项目风格来写。

4.3 多项目隔离与团队协作

如果你同时开好几个项目，claude-mem 按项目目录隔离的特性会非常有用。你不必担心 A 项目的记忆跑到 B 项目去。但有一个坑：项目名是 AI 根据目录名识别的，如果你在不同目录下开着两个同名项目（比如都叫my-app），记忆会串。解决办法很简单：在声明式记忆里加一条project_id: 自定义唯一标识，或者在启动 AI 客户端时明确项目路径，避免同名混淆。

团队协作方面，claude-mem 的记忆目录本质上是一堆磁盘文件，所以完全可以用 git 或同步盘来共享。我们团队的做法是：在项目仓库里放一个.claude-mem-shared/目录，里面存声明式记忆和铭牌文件的模板，成员拉到本地后合并到自己的记忆目录。缺点是同步靠手动，没有自动合并，但对于小团队来说完全够用。

4.4 记忆的迭代维护

记忆文件不是写一次就完事了。项目推进过程中，技术栈可能换、目录可能改、约定可能废。我最常做的维护操作有两个：

一是定期 Diff。每个月用编辑器对比一下声明式记忆文件和当前项目实际结构，删掉过时条目。别偷懒，过时记忆比没有记忆更危险——AI 会一本正经地按已废弃的约定写代码。

二是通过对话更新。当项目里推出新约定时，直接在对话里说“把这条加入项目记忆”，让 AI 自己调 MCP 工具追加。这种方式的优点是即时生效，缺点是 AI 可能把上下文里的临时内容误存成长期记忆。所以我一般每过一段时间就检查一遍记忆文件的“保质期”，不重要的删掉，不确定的留档。

5. 常见问题与排查实录

5.1 配置后不生效怎么办

这是百分之八十新手遇到的问题。装完 claude-mem，AI 却说看不到 MCP 工具，或者根本没有读取记忆。排查顺序我建议这样来：

• 第一步，确认 CLI 本身能运行。终端执行claude-mem --version，报错说明安装有问题，卸载重装。
• 第二步，确认.mcp.json位置正确。Claude Code 读取的是当前目录的.mcp.json，如果放错层级会被忽略。
• 第三步，确认 MCP 服务有没有正常拉起。Claude Code 里输入/mcp，看 claude-mem 的状态是 connected 还是 failed。
• 第四步，看日志。大多 MCP 客户端会把服务器 stderr 输出打到调试面板或日志文件里，里面有报错堆栈。

我自己遇到最多的情况是：.mcp.json里用了全局安装路径，但全局又被权限限制，导致进程启动失败。换成npx启动方式后基本没再遇到。

5.2 记忆文件没有生成，是它没在干活吗

有时候会话跑完了，~/.claude-mem/下却看不到文件。别慌，先想想：你有没有在这个会话里聊出任何“值得记”的内容？自动记忆捕获也不是无差别录音，它通常只提取那些有信息量的事件——项目声明、决策、命令、约定，纯闲聊它可能不会落盘。

如果确实聊了正经内容还是没有文件，检查一下是否被忽略规则拦了（项目名或目录名命中了 ignore 模式），或者 MCP 连接是否在会话中途掉过。我的办法是：手动在对话里发一条“请把刚才的架构决策写入记忆”，如果 AI 能执行并生成文件，说明管道是通的，剩下的只是自动捕获的触发时机问题。

5.3 记忆内容太杂或太干，怎么调教

记忆太多，检索全是噪音；记忆太少，形同虚设。这个平衡点是使用 claude-mem 的核心调校乐趣。我的经验是分两步：

第一步，先用 ignore 规则做减法。把构建产物、依赖目录、日志文件全部排除，只保留代码目录和文档目录。 第二步，再用声明式记忆做加法。把你反复重申过两遍以上的信息，手动写进declarative-memory.md，让 AI 每次开工必读。

找平衡的过程中，claude_mem_search工具是你的好帮手。你可以直接在对话里要求 AI“搜索记忆里关于数据库配置的所有内容”，看看返回结果是不是你想要的。搜索结果偏了就调规则，这个反馈闭环很快。

5.4 隐私、安全与记忆清洁

最后提醒一个使用 claude-mem 的底线问题：记忆文件是纯文本的 Markdown，放在你的磁盘上，而且可能包含对话里出现的敏感信息，比如 API 密钥、内网地址、客户名称。我强烈建议：

• 不要把你的密钥、token 这类敏感凭据交给 AI 记忆，尤其是声明式记忆。
• 如果团队同步记忆文件，先跑一遍关键词扫描，把明显的敏感内容提前清理。
• 定期清空不需要的会话记忆。你可以直接删除~/.claude-mem/agents/<客户端>/projects/下对应项目的output/目录，那里面是半成品素材，删了对核心记忆影响不大。

隐私问题上还有一点：MCP 工具调用时，记忆内容可能会被发送给 AI 模型提供商作为上下文。如果你在处理敏感项目，建议评估再使用云上模型，或启用本地模型方案。这个不是 claude-mem 特有的问题，是所有 AI 编程工具都绕不开的边界。

我个人在实际操作中的体会是：claude-mem 最舒服的用法不是把它当成一个“必须配置完美”的基建，而是先跑起来、再慢慢调。它真正改变工作流的那一刻，是你连续开了五六个会话、每个新会话 AI 都能准确说出你这个项目的技术栈和代码约定的时候。就为这一个体验，前期花出去的半小时配置成本就值回票价。如果你已经装了但还没用出感觉，按我上面说的方式先跑两天自动记忆，再手动补几条声明式记忆，大概率会回来问“怎么没早用这个”。