Workbuddy持久记忆配置指南：打造懂你的专属AI项目助手

1. 先搞清楚 Workbuddy 的“持久记忆”到底解决什么问题

如果你正在用 Workbuddy 处理一些重复性高、上下文关联强的任务，比如写代码、整理文档、分析数据，那你肯定遇到过这个麻烦：每次开启新对话，它都像一张白纸，你得把项目背景、你的编码习惯、常用的工具链、甚至之前讨论过的关键结论，再重新说一遍。这太浪费时间了。

Workbuddy 的Memory.md功能，就是为了解决这个“健忘症”问题。它不是简单的聊天记录，而是一个可以被 Workbuddy 主动读取和更新的持久化知识库文件。你可以把它理解为一个放在项目根目录下的“项目大脑”或“工作手册”。一旦配置好，Workbuddy 在分析你的需求、生成代码或给出建议时，会优先参考这个文件里的信息，从而让它的输出更符合你的长期工作习惯和项目上下文。

这个功能最核心的价值，不是让 Workbuddy 变得更“聪明”，而是让它变得更“懂你”和“懂这个项目”。对于程序员、数据分析师、文档工程师等需要长期维护特定项目上下文的人来说，这是把 Workbuddy 从一个通用聊天工具，升级为专属项目助手的关键一步。

2. 配置 Memory.md 前，先理清你的环境和需求

在动手修改任何配置文件之前，我建议你先停下来，明确两件事：你的 Workbuddy 运行环境，以及你希望 Memory.md 记录什么。

2.1 确认你的 Workbuddy 运行模式

Workbuddy 有多种使用形态，这决定了你配置 Memory.md 的方式：

1. 本地命令行/桌面版：这是最常见的方式。你通过命令行启动一个本地服务，或者在桌面应用中操作。Memory.md 文件通常就放在你指定的“工作空间”或项目根目录下。配置是直接修改本地文件。
2. 服务器部署版：你可能将 Workbuddy 部署在了公司内网或自己的云服务器上，通过 Web 界面访问。这时，Memory.md 的路径是相对于服务器上 Workbuddy 的工作目录。你需要通过服务器的文件系统或 Workbuddy 管理后台来编辑它。
3. 容器化部署（如 Docker）：如果你用 Docker 运行 Workbuddy，那么 Memory.md 需要挂载到容器内的特定路径。重点在于确保宿主机上的文件修改能同步到容器内。

关键动作：打开你的 Workbuddy，随便问它一个问题，比如“你当前的工作目录是什么？”或者“列出根目录文件”。根据它的回答，你就能判断出它当前“眼中”的根目录在哪里，这就是你后续创建或修改Memory.md的位置。

2.2 规划 Memory.md 里应该写什么

不要试图把整个项目的代码都塞进去。Memory.md 应该存放元信息和工作共识。我一般会按这几个模块来组织内容：

• 项目概述：用一两句话说明这个项目是做什么的（例如：“这是一个基于 Spring Boot 的用户管理系统后端项目，使用 MySQL 数据库”）。
• 技术栈与版本：明确记录核心框架、语言、数据库、中间件的名称和版本号（例如：“Java 17, Spring Boot 3.1.5, MyBatis-Plus 3.5.4, MySQL 8.0”）。
• 代码规范与约定：
  • 命名风格（如：Controller 用XxxController，Service 接口用IXxxService，实现类用XxxServiceImpl）。
  • 包结构说明（如：controller,service/impl,mapper,entity,dto）。
  • 特定的工具类或自定义注解（如：“我们使用@BusinessLog注解记录操作日志”）。
• 常用命令与脚本：项目启动命令、数据库迁移脚本、测试命令、打包命令等。
• 当前工作焦点与待办：例如：“本周重点开发用户权限模块。TODO：完成角色与菜单的关联接口。”
• 过往决策与踩坑记录：例如：“2024-05-10：决定使用Jackson而非Fastjson进行 JSON 序列化，原因是对新版本 JDK 兼容性更好。”，“注意：application.yml中数据源配置的timezone必须设置为Asia/Shanghai，否则时间字段会出错。”

把这些想清楚，你等下写Memory.md时就不会东一榔头西一棒子，内容也会对 Workbuddy 真正有用。

3. 创建并配置你的第一个 Memory.md 文件

现在进入实操环节。我们以最常见的本地命令行模式为例，假设你的项目根目录是/Users/yourname/projects/my-awesome-project。

3.1 创建 Memory.md 文件

在你的项目根目录下，直接创建一个名为Memory.md的文件。注意，文件名是固定的，大小写敏感。

cd /Users/yourname/projects/my-awesome-project touch Memory.md

然后，用你喜欢的文本编辑器（VSCode, Sublime, Vim 等）打开它，把你在 2.2 节规划好的内容填进去。下面是一个给 Java 后端项目的简化示例：

# 项目工作记忆 (Memory.md) ## 项目简介 这是一个用于内部员工管理的微服务后端系统，核心模块包括用户、部门、考勤和审批。 ## 技术栈 - **后端框架**: Spring Boot 3.1.5 - **Java版本**: JDK 17 - **数据库**: MySQL 8.0.33 - **ORM**: MyBatis-Plus 3.5.4 - **构建工具**: Maven 3.8.6 - **API文档**: Knife4j (基于 SpringDoc) ## 代码规范与目录结构 - 项目采用标准 Maven 多模块结构：`parent-pom`, `common-module`, `user-service`, `attendance-service`。 - `Controller` 类统一放在 `*.controller` 包下，使用 `@RestController`。 - `Service` 接口放在 `*.service` 包，实现在 `*.service.impl` 包。 - 实体类使用 `@Data` (Lombok)，表名映射通过 `@TableName` 注解指定。 - 所有 RESTful API 路径前缀为 `/api/v1/`。 ## 常用命令 - 启动全部服务: `mvn spring-boot:run` (在各模块目录下) - 运行单元测试: `mvn test` - 打包: `mvn clean package -DskipTests` - 数据库迁移: 使用 `db/migration` 下的 Flyway 脚本。 ## 当前工作上下文 - **当前焦点**: 开发 `attendance-service` 中的“请假审批流程”功能。 - **待办事项**: 1. 实现 `LeaveApplicationController` 的提交和撤回接口。 2. 在 `LeaveApplicationService` 中集成工作流引擎回调。 3. 编写相关单元测试。 - **注意事项**: 审批状态枚举为 `PENDING, APPROVED, REJECTED, CANCELLED`。 ## 历史决策与备忘 - 2024-05-01: 选择 MySQL 而非 PostgreSQL，因为运维团队更熟悉前者。 - 2024-05-08: 统一使用 `LocalDateTime` 处理时间，前端传参格式为 `yyyy-MM-dd HH:mm:ss`。 - 踩坑记录: 在 `application.yml` 中配置 `spring.jackson.time-zone: GMT+8`，否则序列化时间会差8小时。

保存这个文件。

3.2 在 Workbuddy 中启用并指向 Memory.md

仅仅创建文件是不够的，你需要告诉 Workbuddy 去读取它。具体方法取决于你启动 Workbuddy 的方式。

方式一：通过启动参数或配置文件指定工作空间（推荐）

很多 Workbuddy 的启动命令或配置项允许你设置一个--workspace或-w参数。直接将这个参数指向你的项目根目录。

例如，假设你的启动命令原本是：

workbuddy --model gpt-4

现在改为：

workbuddy --model gpt-4 --workspace /Users/yourname/projects/my-awesome-project

这样启动后，Workbuddy 会自动在其工作空间（即你的项目目录）下寻找并加载Memory.md文件。

方式二：在对话中手动引导（临时性）

如果找不到明确的配置项，你可以在开启 Workbuddy 后，在第一次对话中明确告诉它：

“请读取当前目录下的Memory.md文件，并以此作为本项目的工作记忆。然后，基于其中的信息，帮我看看当前attendance-service的请假审批接口应该怎么设计。”

一个设计良好的 Workbuddy 技能（Skill）会解析这条指令，并去加载同目录下的Memory.md。

关键验证点：配置完成后，问 Workbuddy 一个只有Memory.md里才有的信息。例如：“我们这个项目用的 MyBatis-Plus 版本是多少？” 或者 “我们约定的 API 路径前缀是什么？” 如果它能正确回答，说明Memory.md加载成功了。

4. 让 Memory.md “活”起来：动态更新与维护策略

Memory.md不应该是一个创建后就束之高阁的文件。它的威力在于动态更新，让 Workbuddy 的记忆与你项目的进展同步。

4.1 如何更新 Memory.md

你有两种主要方式：

1. 手动维护（基础但有效）：当你做出一个重要的技术决策、添加了一个新的工具库、或者项目进入新阶段时，手动打开Memory.md文件，在相应的章节（如“历史决策”或“当前工作上下文”）添加一条记录。养成“大事记一笔”的习惯。

2. 引导 Workbuddy 帮你更新（进阶用法）：这是更高效的方式。你可以在对话中要求 Workbuddy 根据你们的讨论，总结并更新Memory.md。例如：

   “我们刚才决定将日志框架从 Logback 切换到 Log4j2，以提升异步日志性能。请将这条决策记录到Memory.md的‘历史决策与备忘’部分。” “接下来两周，我的工作重点是优化数据库查询。请将‘当前工作上下文’下的‘焦点’更新为‘数据库性能优化’。”

   一个具备文件写入权限或相应技能的 Workbuddy，可以执行这个操作。但注意：首次尝试时，最好先让它“建议”更新内容，你审核后再手动粘贴进去，避免自动写入出错。

4.2 维护的最佳实践与避坑指南

• 保持简洁与结构：Memory.md是给 AI 和未来的你快速查阅的，不是详细设计文档。用清晰的 Markdown 标题和列表来组织内容。避免大段冗长的叙述。
• 信息优先级：把最常用、最关键的共识放在前面（如技术栈、规范）。动态变化的“当前上下文”可以放在后面。
• 版本控制：务必把Memory.md纳入你的 Git 版本控制。这样，任何更改都有迹可循，团队成员也能同步这份“集体记忆”。
• 定期回顾与清理：每隔一两周，快速浏览一下Memory.md。将已经完成的“待办”移走或删除，将过时的“当前焦点”更新。把“历史决策”中特别重要的提炼出来，形成项目的“最佳实践”文档。
• 不要存放敏感信息：绝对不要在Memory.md里写数据库密码、API密钥、服务器IP等敏感信息。这些应该放在.env或配置中心。
• 注意文件编码：确保Memory.md使用 UTF-8 编码保存，避免中文或其他特殊字符变成乱码，导致 Workbuddy 读取错误。

5. 结合 Skills 与自定义指令，打造超级工作流

Memory.md是 Workbuddy 的“长期记忆”，而Skills（技能）和自定义指令则是它的“专业技能”和“工作习惯”。三者结合，才能发挥最大效力。

5.1 定义与Memory.md联动的自定义指令

你可以在 Workbuddy 中设置一些全局的自定义指令，让它每次分析问题时都自动结合Memory.md。例如，创建一个名为“代码审查助手”的指令：

你是一个经验丰富的Java后端代码审查助手。在回答任何关于代码、架构或调试的问题前，请先主动读取并理解当前项目根目录下的 `Memory.md` 文件，掌握本项目的技术栈、代码规范和当前工作重点。你的所有建议都必须基于该记忆文件中的约束和上下文，确保与项目现有实践保持一致。如果记忆文件中的信息与你的通用知识冲突，以记忆文件为准。

这样，每当你提出代码相关的问题，Workbuddy 都会先“复习”一遍Memory.md，给出的建议会高度贴合你的项目现状。

5.2 开发或使用与 Memory 相关的 Skills

一些高级的 Workbuddy Skills 可以更智能地处理Memory.md。例如：

• 记忆提取技能：你可以问：“根据我们的工作记忆，我们项目里处理日期时间转换的工具类是什么？” Skill 会去解析Memory.md并给出答案。
• 记忆总结/报告技能：命令 Workbuddy：“请根据Memory.md，生成一份本周项目状态简报，包括技术栈、当前焦点和主要待办。”
• 记忆对比技能：当你切换分支或查看历史版本时，可以让 Skill 分析当前Memory.md和某个历史版本的差异，快速了解上下文变化。

查找与安装：在你的 Workbuddy 技能商店或社区中，搜索 “memory”、“context”、“project” 等关键词，寻找现成的相关 Skills。如果找不到，而这又是你的核心需求，那么按照 Workbuddy 的 Skill 开发指南，自己动手写一个也是一个很好的学习过程。

5.3 工作流示例：从需求到代码

假设你配置好了Memory.md和相关指令，一个高效的工作流是这样的：

1. 启动：在项目目录下，用--workspace参数启动 Workbuddy。
2. 提问：“我需要给attendance-service添加一个查询员工本月请假记录的接口。”
3. Workbuddy 的思考过程（背后）：
   • 读取Memory.md，得知：项目是 Spring Boot + MyBatis-Plus，API 前缀是/api/v1/，当前焦点是请假审批，实体类用 Lombok。
   • 结合其编程知识，生成建议：“可以在LeaveRecordController中创建GET /api/v1/leave-records/monthly/{employeeId}接口。需要先创建LeaveRecordMapper和LeaveRecordService，查询条件应包含员工ID和当前月份。记得参考已有的LeaveApplication实体风格。”
4. 你得到的结果：不是一个通用的、可能不符合你项目规范的代码片段，而是一个直接可落地的建议，甚至它生成的代码骨架都符合你Memory.md里定义的包结构和命名规范。

6. 常见问题排查与效能边界

即使配置正确，你可能还是会遇到Memory.md不生效的情况。别急着怀疑功能，按以下顺序排查：

6.1 问题排查清单

1. 文件未找到：
   • 检查路径：再次确认Memory.md是否在 Workbuddy 的当前工作目录下。在对话中让 Workbuddy “列出当前目录文件”来验证。
   • 检查文件名：确认是Memory.md而不是memory.md、Memory.txt或memory.MD。
2. 文件已加载但信息未被使用：
   • 检查指令：你是否在提问时，明确要求 Workbuddy “参考Memory.md”？或者你是否配置了相关的自定义指令？没有明确指引，它可能不会主动使用。
   • 检查文件内容格式：确保是纯文本的 Markdown 格式，没有奇怪的字符或编码问题。内容是否过于冗长杂乱，导致关键信息被淹没？
   • 检查 Workbuddy 技能：你使用的 Workbuddy 版本或激活的 Skill 是否支持Memory.md功能？有些基础版本可能不具备此能力。
3. 信息过时或冲突：
   • 手动验证：直接问一个Memory.md里有明确答案的问题（如“本项目用的 Spring Boot 版本？”）。如果回答错误，说明它没读；如果回答正确但给的建议却不符合，可能是你的问题描述引入了冲突信息，或者它的知识库权重更高。这时需要你在提问时更强调“以Memory.md为准”。

6.2 理解 Memory.md 的能力边界

Memory.md是一个强大的上下文工具，但它不是万能的，理解其边界能让你更好地使用它：

• 它不是版本历史：它记录的是“当前共识”和“近期上下文”，不适合存放完整的项目变更日志（那是 Git 的事）。
• 它有容量限制：虽然可以写很多内容，但 Workbuddy 的上下文窗口（Token 数）是有限的。如果Memory.md过于庞大，可能会挤占你当前对话的可用空间，导致它无法记住你们刚讨论的内容。保持精炼。
• 它是静态参考：Memory.md被加载后，在单次对话会话中通常是静态的。如果你在对话中途修改了Memory.md文件，Workbuddy 可能不会自动重新加载，需要你提醒它或开启新会话。
• 它不替代沟通：在团队中，Memory.md是辅助工具，不能替代团队成员之间的直接技术讨论和文档同步。它更像是团队知识的“AI 可读快照”。

最后一点建议：不要试图在第一天就建立一个完美的Memory.md。从最简单的项目描述和技术栈开始，在每天的工作中，遇到需要反复向 Workbuddy 解释的事情时，就把它记进去。几周下来，你就会拥有一个高度定制化、能极大提升沟通效率的“项目伴侣”。它的价值，会在你不再需要重复说“我们这个项目用的是……”的那一刻，完全显现出来。