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/serenaSerena 的 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 的记忆系统刻意保持极简其设计目标如下人类可读可编辑Human-readable and editable记忆必须能在任何文本编辑器中直接读写。Agent 是日常消费者但人类作者或评审者必须能随时介入而无需经过 Agent。随项目版本化Versionable with the project项目记忆与代码共存可以像任何仓库产物一样提交、在 PR 中评审、回滚。渐进式披露Progressive disclosureAgent 在初始指令中只收到完整的记忆名称列表更深层的引用由记忆内容自身描述——通常以一个mem:core入口点指向各专题记忆。Agent 根据名称加已看到的引用来决定读什么。引用优先于搜索Prefer references to search面对智能 Agent 和结构良好的引用搜索并非必要反而引入噪声——任何检索方法词法或语义都会同时产生误报和漏报。由 Agent 决定的、显式的、基于名称的引用是确定性的可同时规避两种错误模式必要时用 regex/grep 做基础搜索作为补充即可。主动读取而非触发注入Prefer deliberate reads to triggersAgent 自己决定读什么、何时读框架不会替 Agent 注入记忆内容。框架无关Framework-agnostic存储格式就是简单目录布局下的纯 Markdown。Serena 唯一的专属约定是mem:引用前缀这并不妨碍在 Serena 之外使用这些记忆文件。可配置可组合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 如何工作项目被激活时Serena 检查 onboarding 是否已完成通过检查是否存在任何记忆。若未找到记忆Serena 触发 onboarding 流程读取关键文件和目录以理解项目。在写入任何项目记忆之前Serena 会先生成项目本地的memory_maintenance记忆见下文。Agent 被指示首先阅读它并遵循其描述的约定。收集到的信息被写入项目特定的记忆文件遵循 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如果你已经维护着global/memory_maintenance记忆Serena 使用它不会创建项目本地副本——这是希望所有项目共享同一份约定文档的团队推荐做法否则如果项目已有memory_maintenance记忆则保持不动否则把随包模板写入.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创建命令对应 MCP 工具说明serena memories initialize [PROJECT]—无植入memory_maintenance全局版优先serena memories list [PROJECT] -t TOPIClist_memories列出项目与全局记忆可按 topic 过滤serena memories read NAME [PROJECT]read_memory把记忆内容打印到 stdoutserena memories write NAME [PROJECT] --content/--file/stdinwrite_memory写入记忆内容按--content、--file、stdin 的优先级读取serena memories delete NAME [PROJECT]delete_memory删除记忆用global/前缀寻址全局记忆serena memories rename OLD NEW [PROJECT]rename_memory重命名/移动并更新所有mem:引用serena memories edit NAME [PROJECT] --needle --repl [--mode] [--allow-multiple-occurrences]edit_memory按字面量或正则替换记忆内容serena memories check [PROJECT] [--include-unmarked] [--fuzzy-matching]—无引用完整性检查只读不改写始终以 0 退出serena memories auto-prefix-references [PROJECT] [--dry-run] [--include-flat-names] [--include-read-only] [--include-global]—无把裸出现重写为mem:前缀引用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.pywrite_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Serena Memories 记忆系统与项目自动 Onboarding 实战指南
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/serenaSerena 的 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 的记忆系统刻意保持极简其设计目标如下人类可读可编辑Human-readable and editable记忆必须能在任何文本编辑器中直接读写。Agent 是日常消费者但人类作者或评审者必须能随时介入而无需经过 Agent。随项目版本化Versionable with the project项目记忆与代码共存可以像任何仓库产物一样提交、在 PR 中评审、回滚。渐进式披露Progressive disclosureAgent 在初始指令中只收到完整的记忆名称列表更深层的引用由记忆内容自身描述——通常以一个mem:core入口点指向各专题记忆。Agent 根据名称加已看到的引用来决定读什么。引用优先于搜索Prefer references to search面对智能 Agent 和结构良好的引用搜索并非必要反而引入噪声——任何检索方法词法或语义都会同时产生误报和漏报。由 Agent 决定的、显式的、基于名称的引用是确定性的可同时规避两种错误模式必要时用 regex/grep 做基础搜索作为补充即可。主动读取而非触发注入Prefer deliberate reads to triggersAgent 自己决定读什么、何时读框架不会替 Agent 注入记忆内容。框架无关Framework-agnostic存储格式就是简单目录布局下的纯 Markdown。Serena 唯一的专属约定是mem:引用前缀这并不妨碍在 Serena 之外使用这些记忆文件。可配置可组合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 如何工作项目被激活时Serena 检查 onboarding 是否已完成通过检查是否存在任何记忆。若未找到记忆Serena 触发 onboarding 流程读取关键文件和目录以理解项目。在写入任何项目记忆之前Serena 会先生成项目本地的memory_maintenance记忆见下文。Agent 被指示首先阅读它并遵循其描述的约定。收集到的信息被写入项目特定的记忆文件遵循 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如果你已经维护着global/memory_maintenance记忆Serena 使用它不会创建项目本地副本——这是希望所有项目共享同一份约定文档的团队推荐做法否则如果项目已有memory_maintenance记忆则保持不动否则把随包模板写入.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创建命令对应 MCP 工具说明serena memories initialize [PROJECT]—无植入memory_maintenance全局版优先serena memories list [PROJECT] -t TOPIClist_memories列出项目与全局记忆可按 topic 过滤serena memories read NAME [PROJECT]read_memory把记忆内容打印到 stdoutserena memories write NAME [PROJECT] --content/--file/stdinwrite_memory写入记忆内容按--content、--file、stdin 的优先级读取serena memories delete NAME [PROJECT]delete_memory删除记忆用global/前缀寻址全局记忆serena memories rename OLD NEW [PROJECT]rename_memory重命名/移动并更新所有mem:引用serena memories edit NAME [PROJECT] --needle --repl [--mode] [--allow-multiple-occurrences]edit_memory按字面量或正则替换记忆内容serena memories check [PROJECT] [--include-unmarked] [--fuzzy-matching]—无引用完整性检查只读不改写始终以 0 退出serena memories auto-prefix-references [PROJECT] [--dry-run] [--include-flat-names] [--include-read-only] [--include-global]—无把裸出现重写为mem:前缀引用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.pywrite_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考