企业官网建设流程全解析

Serena Memories 记忆系统与项目自动 Onboarding 实战指南

【免费下载链接】serenaA powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent项目地址: https://gitcode.com/GitHub_Trending/ser/serena

Serena 的 Memories（记忆）系统是项目长期知识的持久化层：它以人类可读、可版本化的 Markdown 文件为载体，让 Agent 在多次会话间复用项目结构、构建方式、测试约定等关键信息，并在首次接触项目时通过自动 Onboarding 流程沉淀知识。读完本文，你将掌握记忆的存储布局与设计原则、mem:引用约定与引用完整性检查、全局/项目级记忆的配置（只读与忽略）、Onboarding 全流程，以及serena memories全部 CLI 子命令的实战用法。

记忆是什么

Serena 提供了完整 Agent 的能力，而其记忆系统是其中一个非常实用的设计：Memories 是简单、人类可读的 Markdown 文件，用户和 Agent 都可以创建、读取、引用和编辑。尽管实现极简，许多用户倾向于将它与自己 Agent 的内部记忆管理（例如AGENTS.md文件）结合使用。

Serena 区分两种记忆作用域：

• 项目级记忆（project-specific memories）：存放在项目文件夹内的.serena/memories/目录中，随代码一起提交、评审和回滚。
• 全局记忆（global memories）：跨所有项目共享，默认存放在~/.serena/memories/global/。

LLM 会被告知记忆的存在，并被指示在合适的时候读取它们（根据文件名推断相关性）。当 Agent 开始处理某个项目时，它会收到可用记忆的名称列表；是否更新记忆则由用户在合适时机指示 Agent 完成。

从源码实现看，这两个作用域由 MemoryManager 统一管理：构造时接收serena_data_folder（项目.serena数据目录）以及只读/忽略正则列表，全局目录通过SerenaPaths().global_memories_path解析，项目目录则为<serena_data_folder>/memories并在初始化时自动创建（memory_manager.py）。

设计原则：为什么是纯 Markdown 文件

Serena 的记忆系统刻意保持极简，其设计目标如下：

1. 人类可读可编辑（Human-readable and editable）：记忆必须能在任何文本编辑器中直接读写。Agent 是日常消费者，但人类作者或评审者必须能随时介入，而无需经过 Agent。
2. 随项目版本化（Versionable with the project）：项目记忆与代码共存，可以像任何仓库产物一样提交、在 PR 中评审、回滚。
3. 渐进式披露（Progressive disclosure）：Agent 在初始指令中只收到完整的记忆名称列表；更深层的引用由记忆内容自身描述——通常以一个mem:core入口点指向各专题记忆。Agent 根据名称加已看到的引用来决定读什么。
4. 引用优先于搜索（Prefer references to search）：面对智能 Agent 和结构良好的引用，搜索并非必要，反而引入噪声——任何检索方法（词法或语义）都会同时产生误报和漏报。由 Agent 决定的、显式的、基于名称的引用是确定性的，可同时规避两种错误模式；必要时用 regex/grep 做基础搜索作为补充即可。
5. 主动读取而非触发注入（Prefer deliberate reads to triggers）：Agent 自己决定读什么、何时读，框架不会替 Agent 注入记忆内容。
6. 框架无关（Framework-agnostic）：存储格式就是简单目录布局下的纯 Markdown。Serena 唯一的专属约定是mem:引用前缀，这并不妨碍在 Serena 之外使用这些记忆文件。
7. 可配置可组合（Configurable and composable）：项目级与全局两个正交作用域可自由组合；在任一作用域内，全局或项目配置中的正则模式可以把部分记忆标记为只读或完全隐藏。

这些准则排除了常见的替代方案：

• 数据库记忆（SQLite、图数据库、向量存储）——被准则 1、4、6 排除；
• AGENTS.md等单一文件约定——被准则 3、5 排除；
• Hooks 与框架内置记忆系统——被准则 5、6 排除。

据项目文档所述，尚无现有系统满足这一设计目标，因此 Serena 自带记忆层而非复用现成方案；最接近的现有思路是 Markdown 类个人知识管理工具（Obsidian、Logseq、Foam）的家族。

组织记忆：Topic 与目录映射

记忆可以用名称中的/组织成topics（主题），例如modules/frontend。该结构直接映射到文件系统——topic 对应子目录。list_memories工具支持按 topic 过滤，使 Agent 能以结构化方式浏览大量记忆。

对应源码中，MemoryManager 的list_memories(topic)会在给定 topic 下遍历*.md文件（并跟随符号链接目录，支持 monorepo 通过 symlink 共享记忆目录），再依据只读/忽略模式打标。名称在写入前会经过_sanitize_name归一化：去掉误带的mem:前缀、去掉.md后缀、把操作系统路径分隔符统一为/（memory_manager.py）。

记忆间的引用：mem:约定

记忆之间可以互相引用。Serena 把记忆名称前缀mem:并用反引号包裹的形式识别为引用，例如`mem:auth/login`或`mem:suggested_commands`。这一约定有两个实际效果：

重命名时引用自动保持

当你用rename_memory工具重命名或移动记忆时，Serena 会重写所有记忆中出现的`mem:OLD_NAME`，指向新名称。未使用mem:前缀的引用不会被自动更新。

源码层面，memory_manager.py 的rename_references_to_memory用字符类[A-Za-z0-9_\-/]界定记忆名称边界，确保不会把嵌在更长名称中的片段误当作引用；rename_memory_and_propagate_references 会遍历全部记忆，仅重写确实包含旧引用的文件（避免无意义的 mtime 变化），并返回重写的引用总数。注意：只读记忆中的引用不会被更新（见 memory_tools.py 的RenameMemoryTool说明）。

完整性检查报告悬空引用

完整性检查会报告所有目标无法解析到现有记忆的`mem:NAME`，并为每个悬空引用推荐名称相似的可能目标。该检查由serena memories check触发（详见下文 CLI 章节）。

相似度排名由 memory_reference_analysis.py 中的compute_name_similarity计算，默认阈值NAME_SIMILARITY_THRESHOLD = 0.55，每个悬空引用最多推荐 3 个候选（MAX_STALE_REFERENCE_CANDIDATES）。算法会先归一化（小写 + 剥离_v2/_old/_legacy等版本后缀），再对 basename 与 topic 前缀分别做 token 化、Jaccard 相似度与序列匹配，并设有短名称下限（SHORT_NAME_FLOOR = 3）与跨 topic 误报门控（BASENAME_JACCARD_FLOOR），避免把frontend/x-subtleties和backend/y-subtleties这类仅共享通用尾词的名称误判为引用候选。

完整的引用约定——包括风格、增改阈值、以及如何围绕core记忆组织跨层引用——会在每个项目 Onboarding 时以memory_maintenance记忆的形式下发（见下文）。

全局记忆（Global Memories）

全局记忆使用顶级 topicglobal：只要记忆名称以global/开头，就存储在全局记忆目录中，跨项目共享。

默认情况下，全局记忆允许删除和编辑。若想防止 Agent 意外修改，可以在全局或项目级配置中添加read_only_memory_patterns正则。例如设置"global/.*"会把所有全局记忆标记为只读，Agent 会被告知哪些记忆是只读的。

在源码中，正则通过fullmatch精确匹配记忆名称（memory_manager.py）；在工具调用上下文中，写入只读记忆会抛出PermissionError（_check_write_access）。全局与项目级配置中的模式是合并累加的。特别地，在启用默认只读保护时，全局记忆默认允许工具写入；当配置global/.*为只读模式后，工具上下文中对全局记忆的写/删/改会被拦截。

由于全局记忆不随项目文件版本化，建议用 git 跟踪全局记忆（即把~/.serena/memories/变成一个 git 仓库），以获得变更历史并在需要时回滚。源码中的GLOBAL_TOPIC = "global"常量（memory_manager.py）与_is_global判定（名称等于global或以其为前缀）就是这一约定的实现；裸的global不是合法记忆名，必须写成global/<name>。

忽略记忆（Ignoring Memories）

积累了大量归档记忆文件的项目，可以使用ignored_memory_patterns把它们从list_memories和activate_project的输出中排除。在全局或项目级配置中添加正则：

ignored_memory_patterns: ["_archive/.*", "_episodes/.*"]

被忽略的记忆是完全排除的——无法通过read_memory、write_memory或任何其他记忆工具访问。要读取被忽略的记忆文件，请对原始文件路径使用read_file工具（例如.serena/memories/_archive/2026-03/some-topic.md）。

与read_only_memory_patterns一样，全局与项目级配置的模式是合并累加的。源码中，_check_not_ignored会在读取/写入/删除前对名称做正则fullmatch校验，命中即抛出ValueError并提示改用read_file读取原始路径（memory_manager.py）；_list_memories也会跳过被忽略的记忆，确保它们不出现在任何工具的输出中。

手动编辑记忆

你可以直接在文件系统中用任意文本编辑器或 IDE 编辑记忆。或者，在 Serena 运行期间通过 Serena Dashboard 访问它们——Dashboard 提供了查看、创建、编辑、删除记忆的图形界面。

另外，MCP 集成还提供EditMemoryTool：以 literal 或 regex 模式在记忆内做内容替换（regex 模式启用MULTILINE与DOTALL标志，默认禁止多处匹配，需显式开启allow_multiple_occurrences），见 memory_tools.py。实现上复用ContentReplacer并最终以原子写入（write_file_atomic）落盘。

自动 Onboarding 流程

默认情况下，Serena 在第一次遇到某个项目时（即该项目尚不存在任何项目记忆时）会执行一次onboarding 流程。其目标是让 Serena 熟悉项目——结构、构建系统、测试设置及其他关键方面——并把这份知识作为记忆存储下来，供未来的交互使用。

在后续的项目激活中，Serena 会通过检查是否已存在项目记忆来判断 onboarding 是否已经完成，若找到记忆则跳过该流程。

Onboarding 如何工作

1. 项目被激活时，Serena 检查 onboarding 是否已完成（通过检查是否存在任何记忆）。
2. 若未找到记忆，Serena 触发 onboarding 流程，读取关键文件和目录以理解项目。
3. 在写入任何项目记忆之前，Serena 会先生成项目本地的memory_maintenance记忆（见下文）。Agent 被指示首先阅读它并遵循其描述的约定。
4. 收集到的信息被写入项目特定的记忆文件，遵循 onboarding prompt 指令及memory_maintenance中概述的约定。

从源码看，onboarding 由 OnboardingTool 驱动——它会先检查记忆写入工具是否激活，再通过 prompt factory 渲染onboarding_prompt模板。模板（simple_tool_outputs.yml）要求 Agent 先读mem:memory_maintenance，然后按目标布局逐个写入：

• mem:core— 顶层源码地图与不归属专题记忆的项目级不变量；
• mem:tech_stack— 语言、框架、构建工具、包管理器、关键版本锁定；
• mem:suggested_commands— 用户实际会跑的项目命令（dev、test、lint、format、入口点）及与标准 Unix shell 行为不同的系统工具命令；
• mem:conventions— 代码风格、命名、类型提示、docstring 约定、本代码库特有的设计模式；
• mem:task_completion— 编码任务完成时要运行的确切命令（linter、formatter、测试运行器、类型检查器等）。

若项目有明显模块划分（如 frontend/backend），应创建各模块的mem:<module>/core并引用更细的记忆，而不是把所有内容塞进mem:core。模板特别强调：onboarding 只有真正对每个记忆调用过write_memory才算完成——在聊天里总结而不落盘是不算数的。

memory_maintenance记忆

为了让记忆约定对 LLM 和用户都可发现，Serena 在首次 onboarding 时植入一个memory_maintenance记忆。种子内容从随 Serena 包分发的模板复制而来，包含紧凑的 agent 笔记风格、mem:引用约定、围绕core记忆的引用模型、增改阈值，以及维护动作（重命名/删除/拆分）。模板原文见 resources/memory_maintenance.md，核心要点包括：渐进式引用发现模型、密集 agent 笔记风格（"Dense agent notes, not prose docs"）、只在记忆内容稳定且不易在未来重新发现时才增改的阈值，以及通过serena memories check检查悬空记忆的建议。

植入遵循严格优先级（实现见 memory_manager.py 的ensure_memory_maintenance_memory）：

1. 如果你已经维护着global/memory_maintenance记忆，Serena 使用它，不会创建项目本地副本——这是希望所有项目共享同一份约定文档的团队推荐做法；
2. 否则，如果项目已有memory_maintenance记忆，则保持不动；
3. 否则，把随包模板写入.serena/memories/memory_maintenance.md。

已有文件永远不会被覆盖，你可以自由定制项目副本；若想从随包模板刷新，先删除现有记忆即可。

Onboarding 实用提示

• 上下文占用：onboarding 会读取项目大量内容、占满上下文窗口，因此建议 onboarding 完成后开启新会话。
• LLM 失败：如果 LLM 未能完成 onboarding、未真正把相应记忆写入磁盘，你可能需要明确要求它这样做。
• 检查结果：onboarding 后建议快速浏览生成的记忆，按需编辑或补充新的记忆。

serena memoriesCLI 子命令

虽然管理记忆的推荐方式是MCP 集成，Serena 也提供记忆相关的 CLI 命令。以下命令没有 MCP 工具对应物，专为人类执行设计：

• serena memories check— 引用完整性报告。默认报告失效的`mem:NAME`引用；额外的扫描（裸出现与模糊近似）通过 flag 显式开启。运行serena memories check --help查看完整 flag 列表。
• serena memories auto-prefix-references— 启发式重写裸出现，为其添加mem:前缀；支持--dry-run。
• serena memories initialize— 为项目植入memory_maintenance记忆。

其余命令与 MCP 工具一一对应，因此你也可以在没有运行 MCP 服务器的情况下，指示 Agent 用 serena 管理记忆。完整命令面与各命令 flag 可通过以下方式发现：

serena memories --help serena memories <subcommand> --help

从 cli.py 的MemoryCommands看，命令全集如下（全部要求项目已注册为 Serena 项目，即存在.serena/project.yml，可先用serena project create创建）：

check与auto-prefix-references的精细控制

check默认只报告失效的mem:引用；--include-unmarked额外报告已有记忆名称的裸出现（即未加mem:前缀），分为高置信（名称含/或超过长度阈值）与低置信两组；--fuzzy-matching（须与--include-unmarked组合，否则被忽略）还会报告模糊近似——记忆正文中长的、特征明显的裸 token 与某个高置信记忆名相似但不完全相同。实现上，分析器会跳过memory_maintenance本身、空记忆、自引用，以及 basename 落在常见英文词（如core）范围内的候选，以控制误报（见 memory_reference_analysis.py）。

auto-prefix-references是启发式、会修改文件的操作，文档明确警告：一个恰好与记忆名同词的裸单词即使本意是普通散文也会被改写。因此：

• 只重写精确匹配的裸出现（正文文本必须与现有记忆名逐字相同）；模糊近似需要子串替换而非加前缀，永远不会被自动修复，而是归入skipped_fuzzy供人工审查；
• 默认只处理高置信发现（名称含/或超过长度阈值），并跳过全局记忆与只读记忆——默认策略刻意偏向"漏报而非误报"；
• --dry-run预览将要应用的改写而不动任何文件；--include-flat-names（显著提高误报风险）、--include-read-only、--include-global可逐步放宽范围。

MCP 记忆工具一览

与记忆相关的 MCP 工具定义在 memory_tools.py：

• write_memory— 以 md 格式写入对项目有用的信息；名称要有意义、可用/组织 topic；仅在明确指示时使用global/前缀；对其它记忆的引用要放进反引号并加mem:前缀（如`mem:auth`）。内容受max_chars长度约束（默认取default_max_tool_answer_chars）。
• read_memory— 读取记忆内容，建议根据名称推断相关性、在任务相关时读取。
• list_memories— 列出可用记忆，可按 topic 过滤；输出按记忆名排序，并区分普通记忆与只读记忆。
• delete_memory— 删除记忆；仅在用户明确指示或授予权限时调用。
• rename_memory— 重命名/移动记忆，自动更新所有mem:前缀引用（只读记忆中的引用不受影响）。
• edit_memory— 用字面量或正则替换记忆内容，默认拒绝多处匹配。

禁用记忆与 Onboarding

如果不需要本节所述功能，可以有选择地禁用它：

• 要禁用所有记忆相关工具（包括 onboarding），在 Serena 的全局配置中把no-memories加入base_modes。
• 类似地，要仅禁用 onboarding，把no-onboarding加入base_modes。

这两个模式分别对应随包配置 modes/no-memories.yml（同时排除记忆工具与依赖记忆的 onboarding 工具）和 modes/no-onboarding.yml（仅关闭 onboarding 流程，适用于记忆由外部创建的场景）。

结语

Serena 的记忆系统证明了"简单即强大"：纯 Markdown + 目录布局、mem:名称引用、渐进式披露，再加上随包下发的memory_maintenance约定与自动 Onboarding，构成了一套 Agent 可自主维护、人类可随时介入、可随代码版本化的项目知识层。结合 MemoryManager 与 MemoryReferenceAnalyzer 的源码实现，以及 test/serena/test_memories_manager.py 中的测试用例，你可以放心地把它接入自己的多会话工作流——用serena memories check守护引用健康，用--dry-run预览批量改写，再辅以 Dashboard 图形界面做日常维护。

【免费下载链接】serenaA powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent项目地址: https://gitcode.com/GitHub_Trending/ser/serena