MemOS memos-local-plugin 配置系统深度解析：config.yaml 的加载、校验与安全写入

人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载memos-local-plugin 是 MemOS 为 OpenClaw / Hermes 等 Agent 宿主提供的本地记忆插件其配置体系高度收敛每个 Agent 安装只有一份config.yaml由统一的加载器、Typebox 校验器和保留注释的写入器协同管理。本文以core/config/模块为骨架结合 defaults.ts、schema.ts、writer.ts 等源码与单元测试系统讲解配置文件的位置约定、环境变量覆盖、加载/合并/校验全流程、全量配置项说明以及安全写入与容错机制。读完本文你将能定位任意 Agent 的配置文件、按需覆盖任意高级参数并理解为什么改 YAML schema 而不是引入 .env是这个插件的设计铁律。配置文件在哪里每个 Agent 恰好一份core/config/README.md给出的核心约定是每个 Agent 安装有且仅有一个配置文件。Agent配置文件路径OpenClaw~/.openclaw/memos-plugin/config.yamlHermes~/.hermes/memos-plugin/config.yaml这两个文件都不是手写的而是由安装脚本从仓库模板生成install.shLinux/macOS与install.ps1Windows在ensure_runtime_home()中把templates/config.openclaw.yaml/templates/config.hermes.yaml复制到对应 Agent 的运行时目录并立即执行chmod 600如果目标config.yaml已存在则原样保留config.yaml exists — kept as-is只有缺失时才从模板生成避免覆盖用户已有配置。从源码层面看配置文件在哪由 paths.ts 这一唯一的事实来源single source of truth决定。ResolvedHome接口不仅给出配置文件路径还一次性解析出整个运行时目录树export interface ResolvedHome { root: string; // 运行时根目录如 ~/.openclaw/memos-plugin configFile: string; // config.yaml 的绝对路径 dataDir: string; // SQLite 数据库目录 dbFile: string; // data/memos.db skillsDir: string; // 固化技能包目录 logsDir: string; // 日志目录app/error/audit/llm/perf/events… daemonDir: string; // 守护进程 pid/port 文件目录 }其余任何模块都不自己拼接路径而是统一调用resolveHome(agent)这样当约定变化或MEMOS_HOME覆盖时只需改动这一个文件。环境变量覆盖MEMOS_HOME 与 MEMOS_CONFIG_FILE测试或 CI 场景下可以在不触碰用户主目录的前提下重定向运行时位置环境变量覆盖范围MEMOS_HOME整个运行时根目录。读取MEMOS_HOME/config.yamldata/skills/logs 全部由此推导MEMOS_CONFIG_FILE仅覆盖配置文件路径data/skills/logs 仍从同一父目录推导如果两者同时设置MEMOS_HOME优先。这一点在 paths.ts 的resolveHome()中被实现为五级优先级从高到低MEMOS_HOME环境变量覆盖一切MEMOS_CONFIG_FILE环境变量仅覆盖配置文件路径defaultHome函数参数适配器以代码方式传入Windows 下 Hermes 的运行时标记/既有数据选择内置默认值~/.openclaw/memos-plugin/、~/.hermes/memos-plugin/等。路径中的~与{HOME}占位符由expandHome()显式替换为homedir()而不是依赖 shell 展开从而保证跨平台行为一致。tests/unit/config/load.test.ts与tests/helpers/tmp-home.ts正是利用MEMOS_HOME把测试隔离到临时目录mkdtemp再通过cleanup()恢复环境变量。为什么只认 YAML且只有 YAMLcore/config/README.md明确列出了三条理由人类可读YAML 是运维人员、Agent 与 LLM 都能顺畅读写的格式注释可存活写入器基于 YAML 的 CST具体语法树做修改用户手写的注释与字段顺序会被完整保留模板升级不会冲掉用户的自定义说明敏感字段集中管理API key、token 与其他配置同处一个文件用户只需编辑一处该文件权限为chmod 600仅属主可读写。因此插件没有.env文件——模板头注释里写得很直白Sensitive fields (apiKey, teamToken) live HERE — there is no .env file. 如果你发现自己在找.env正确的做法是修改 YAML schema 本身。公共 API加载、解析与写回core/config/对外暴露的入口集中在 index.ts。加载配置的典型用法import { loadConfig } from ./index.js; import { resolveHome } from ./paths.js; const home resolveHome(openclaw); // {root, configFile, dataDir, …} const config await loadConfig(home); // ResolvedConfigloadConfig的内部流程分四步见 index.ts读取home.configFile若文件缺失ENOENT不崩溃——返回defaults并追加一条 warning保证 Agent 首轮对话照常启动把 YAML 深度合并到 defaults.ts 的默认配置树之上用 schema.ts 的 Typebox schema 做校验失败时抛出MemosError(config_invalid)返回**冻结frozen**的ResolvedConfig任何运行时都无法意外修改配置。loadConfig的返回类型LoadConfigResult携带四个字段config最终配置、fromDisk文件是否真实存在、warnings校验告警、source实际读取的路径。写入是对称的走 writer.ts 的patchConfigimport { patchConfig } from ./writer.js; await patchConfig(home, { llm: { temperature: 0.2 } }); // 写回 home.configFile保留注释 字段顺序patchConfig接受任意嵌套的局部 patch缺省键不动深度合并写回前先用合并后的 JS 视图做一次 schema 校验——绝不写出一个非法文件。resolveConfig不走磁盘的同一套合并校验除loadConfig外index.ts还导出resolveConfig(raw, warnings, agent)它接受任意原始对象完成相同的合并与校验。这一入口被两类场景使用测试直接构造配置对象见tests/unit/config/load.test.ts的resolveConfig({ viewer: { port: 1234 } })断言适配器在代码中拼装配置适配层不落盘也能拿到完整 ResolvedConfig。对 Agent 宿主还有一步到位的loadConfigForAgent(agent)先resolveHome(agent)再loadConfig自动处理MEMOS_HOME覆盖与按 Agent 的默认值。内部模块布局core/config/目录的职责划分与core/config/README.md的内部布局表一致并补充实现细节文件职责paths.ts解析~/.agent/memos-plugin/及所有子路径是运行时路径的唯一事实来源含 Windows Hermes 运行时选址defaults.ts完整默认配置树与 schema 严格对齐YAML 深度合并的基座导出SECRET_FIELD_PATHS密钥路径清单schema.tsTypebox schema → JSON Schema既是运行时校验器也可发布到templates/供编辑器自动补全yaml.ts读取 YAML把语法错误包装成带行号列号的MemosError(config_invalid)提供保留注释的 Document 解析writer.ts深度合并 原子写回保留注释与顺序每次写回重设chmod 600index.tsloadConfig/resolveConfig/loadConfigForAgent及类型导出此外还有 migrations.ts——运行时配置的迁移器目前承载hermes-viewer-port-v1迁移把 Hermes 旧版 viewer 端口 18799 迁移为 18800详见下文边界情况。Typebox schema 与配置项全解schema.ts 用sinclair/typebox定义了从viewer到logging的完整配置树Statictypeof ConfigSchema即ResolvedConfig类型。schema 的三重用途加载时校验用户文件loadConfig提供 JSON Schema 供编辑器自动补全writer 可将其导出在代码评审期间生成templates/config.agent.yaml的默认值基线。schema 与 defaults 的约定是加字段必须在defaults.ts提供默认值旧配置自动升级删字段只在加载时打 warning绝不崩溃。下面是各配置块的核心字段、默认值与取值范围的汇总依据 defaults.ts 与 schema.tsviewerWeb 面板port默认 18799范围 1–65535、bindHost默认127.0.0.1官方建议不要改动、openOnFirstTurn默认 false。注意每个 Agent 有固定端口defaults.ts中的FIXED_VIEWER_PORTS规定openclaw → 18799hermes → 18800即使旧 YAML 写的是别的值运行期也会以 Agent 固定端口为准。bridge宿主桥接port默认 18911、modestdio|tcp默认stdio。embedding嵌入providerlocal|openai_compatible|gemini默认local、endpoint、model默认Xenova/all-MiniLM-L6-v2、apiKey、OpenRouter 路由providerIgnore/providerOrder/openRouter、cache.enabled默认 true/cache.maxItems默认 20000。没有dimensions字段——向量维度在运行期由 provider/model 推导schema 与 writer 会主动剔除手写的embedding.dimensions防止陈旧的dimensions: 384截断 bge-m3 的 1024 维向量。llm主 LLMprovider|local_only|openai_compatible|gemini|anthropic|bedrock|host、endpoint、model、temperature0–2默认 0、fallbackToHost默认 trueprovider 失败时回退到宿主 LLM、apiKey、timeoutMs默认 45000、maxRetries默认 3上限 10、OpenRouter 路由三件套、可选reasoning块enabled/effortminimal…max /maxTokens。l3Llm 与 skillEvolver专用模型槽结构相同、全部可选provider/endpoint/model/apiKey/temperature/timeoutMs/providerIgnore/providerOrder/openRouter/reasoning。语义不同skillEvolver服务于 L2 归纳与技能结晶skill crystallization生成的代码会被 Agent 实际调用常配置更强的模型如 claude-sonnet / gpt-5-thinkingl3Llm服务于 L3 世界模型抽象运行在回合响应路径之外慢而稳的模型不影响对话延迟。两者model为空时都回退到主llm.*全新安装零配置。storage存储ftsTokenizertrigram默认保留历史 FTS5 行为|cjk保留中文短词与混合 ASCIICJK token改善早报、配置、API配置等查询的召回。algorithmV7 算法参数共 9 个子块直接对应 V7 论文规范γ、support、gain、top-K 等注释中标注了公式出处如 γ 对应 §0.6 eq.4/5。关键子块与默认值lightweightMemory.enabled默认 true低开销模式只保留 summarize embedding retrieval filter跳过 task/reward/L2/L3/skill 进化capturemaxTextChars4000、maxToolOutputChars2000、embedTracestrue、alphaScoringtrue、synthReflectionstrueOpenClaw 工具消息无显式 reflection 块默认合成以维持 α 信号、llmConcurrency4、maxReflectLlmCalls128、batchModeauto短 episode 把 N 次逐步骤 LLM 调用折叠为 1 次批处理、batchThreshold12、reflectionContextModetask_downstream、longEpisodeReflectModeper_step_downstream、downstreamStepCount3rewardgamma0.9、tauSoftmax0.5、decayHalfLifeDays30、llmScoringtrue、implicitThreshold0.2、feedbackWindowSec30为交互式聊天从 10 分钟下调、minExchangesForCompletion1、minContentCharsForCompletion40支持hermes chat -q …这类单轮 CLI 模式、toolHeavyRatio0.7l2InductionminSimilarity0.65、candidateTtlDays30、minEpisodesForInduction1、minTraceValue0.005、useLlmtrue、traceCharCap3000、gainEmaAlpha0.4、archiveGain-0.05l3AbstractionminPolicies1、minPolicyGain0.02、minPolicySupport1、clusterMinSimilarity0.3、cooldownDays0、confidenceDelta0.05、minConfidenceForRetrieval0.2skillminSupport1、minGain0.02、candidateTrials1、cooldownMs0、evidenceLimit6、etaDelta0.1、archiveEta0.1、minEtaForRetrieval0.1feedbackfailureThreshold3、failureWindow5、valueDelta0.5、minLowValueThreshold0.01、useLlmtrue、cooldownMs60000sessionfollowUpModemerge_follow_ups同主题追问并入前一 episode、mergeMaxGapMs2 小时、maxTurnsPerEpisode30、classifyTimeoutMs5000、bgLlmConcurrency2retrievaltier1TopK3 /tier2TopK5 /tier3TopK2、candidatePoolFactor4、weightCosine0.6 /weightPriority0.4、mmrLambda0.7、rrfConstant60、minSkillEta0.1、minTraceSim0.25、episodeGoalMinSim0.45、tagFilterauto、keywordTopK20、relativeThresholdFloor0.2、skillEtaBlend0.15、smartSeedtrue、skillInjectionModesummary、llmFilterEnabledtrue、llmFilterMaxKeep4、llmFilterMinCandidates2、vectorScanMaxAgeMs0默认无时间窗上限超过 5 万条 trace 的部署建议设为86400000即 24 小时。这些默认值不是拍脑袋定的defaults.ts中逐条记录了调参动机例如synthReflections默认开启是因为 OpenClaw 工具消息缺乏显式 reflection 块不合成会令 α 恒为 0、使反射加权反向传播退化为纯 γ 折扣feedbackWindowSec从 600 降到 30 是因为 10 分钟窗口太长用户早已进入下一个任务导致 R_human 永不触发。hub记忆中心互联enabled默认 false、rolehub|client默认client、port18912、address、teamName、teamToken、userToken、nickname。telemetry 与 loggingtelemetry.enabled默认 true匿名用量事件可随时关闭loggingleveltrace…fatal默认 info、detailedViewfalse、timezoneIANA 时区默认 UTC非法值会在加载时被拒绝、console、fileformatjson|compact、rotate.maxSizeMb50 /maxFiles14 /gzip、retentionDays30、audit按月轮转、gzip、永不删除、llmLog/perfLog/eventsLog、redact.extraKeys与extraPatterns、channels按通道覆盖级别如core.l2.cross-task: debug。安装模板与真实配置示例templates/目录是安装脚本的配置源注意它们只在安装时被复制运行期插件始终读取用户实际文件见 templates/README.md模板复制到重装时是否覆盖config.openclaw.yaml~/.openclaw/memos-plugin/config.yaml否除非--force-configconfig.hermes.yaml~/.hermes/memos-plugin/config.yaml否除非--force-configREADME.user.md~/.agent/memos-plugin/README.md是纯文档config.demo.yaml不自动安装不适用config.openclaw.yaml 的实际内容很精简——设计哲学是短小 默认值兜底version: 1 viewer: port: 18799 # OpenClaw 独占 :18799Hermes 用 :18800互不共享 embedding: provider: local # local | openai_compatible | gemini | cohere | voyage | mistral apiKey: # 云 provider 必填 llm: provider: host # host | local_only | openai_compatible | anthropic | gemini | bedrock apiKey: # 除 host / local_only 外必填 model: # 留空 让 provider 选默认 storage: ftsTokenizer: trigram # trigram | cjk algorithm: lightweightMemory: enabled: true # true 仅低成本摘要false 开启记忆自我进化 hub: enabled: false address: # 如 http://10.0.0.12:18912enabledtrue 且 roleclient 时必填 teamToken: telemetry: enabled: true # 匿名用量事件随时可关闭 logging: level: info # trace | debug | info | warn | error | fatal detailedView: false而 config.hermes.yaml 的关键差异在于Hermes 没有宿主 LLM所以llm.provider默认openai_compatible、apiKey标注REQUIRED — fill in before runningviewer 端口为 18800。config.demo.yaml 是一份演示专用的algorithm.*覆盖层install.sh刻意不安装它。演示脚本TaskCLI 走查会用yq把它合并进真实配置把 reward 门槛、minTraceSim、minTraceValue、clusterMinSimilarity、candidateTrials等阈值进一步放宽让 L1/L2/L3/Skill 全链路在约 9 个回合内跑完演示结束后恢复备份并重启 gateway。生产环境绝不能照抄这些值——这正是文档反复强调的边界。需要调优模板未暴露的高级参数时直接向config.yaml追加对应块即可。例如 OpenRouter 路线下的 provider 路由llm: provider: openai_compatible endpoint: https://openrouter.ai/api/v1 model: google/gemini-2.5-flash-lite apiKey: sk-or-v1-... providerIgnore: - together - deepinfra - novitaproviderIgnore/providerOrder同样适用于skillEvolver、l3Llm、embedding对应 OpenRouter 请求的provider.ignore与provider.order反向代理或 CNAME 场景需在这些块上显式设openRouter: true。写入器的安全设计原子写、保注释、chmod 600writer.ts 的写入流程体现了三个工程目标保留用户注释与字段顺序——用parseDocument(text, { keepSourceTokens: true })得到 YAML Document修改后doc.toString()落盘模板升级带来的字段变化不会清掉用户的注解绝不写坏文件——写回前把合并后的 JS 视图再过一次resolveConfigschema 不过则抛出MemosError(config_invalid)磁盘上的旧文件保持原样原子写——先写临时文件mode: 0o600再rename覆盖目标即使进程中途崩溃也不会留下半截配置。rename 后还会再补一次chmod 600防止某些文件系统上 rename 继承了错误权限配置文件永远不会意外变成世界可读。applyPatch还有一个针对真实事故的修复当用户配置里出现skillEvolver:裸 null或skillEvolver: 半截手写/老安装遗留时doc.setIn(path, {})不会把标量节点替换成YAMLMap后续嵌套setIn会抛Expected YAML collection。修复方式是先用doc.getIn(path, true)keepScalar取到 AST 节点只要不是 Map 就显式替换为new YAMLMap()见 writer.ts。相应地index.ts 的deepMerge也做了非对象容忍默认值是对象槽位而用户写入标量时保留默认树避免 Typebox 在加载期报 Expected object 导致整个守护进程启动失败。migrations.ts展示了另一种安全模式Hermes viewer 端口迁移。当检测到 Hermes 配置中的viewer.port仍是旧值 18799 时迁移器会在.migrations/目录先写一份*.config.yaml.bak备份mode: 0o600flag: wx防覆盖再改写端口为 18800最后写 JSON 标记文件整个流程由目录锁mkdir原子性防并发锁超时或备份内容不一致都会显式报错而非静默处理。密钥脱敏viewer 永远拿不到明文defaults.ts导出的SECRET_FIELD_PATHS是一份明文字段的点路径清单覆盖embedding.apiKey、llm.apiKey、skillEvolver.apiKey、l3Llm.apiKey、hub.teamToken、hub.userToken。GET /api/v1/configserver/routes/config.ts返回前memory-core.ts 的maskSecrets()会按这份清单把非空密钥替换为 ASCII 哨兵__memos_secret__——早期版本用 Unicode 圆点••••但浏览器在 HTTPAuthorization头中拒绝非 ASCIIByteString 规则导致 viewer 把占位符回传测试连接时 fetch 抛错故改用 ASCII 哨兵PATCH /api/v1/config的stripEmptySecrets()会丢弃值为空串或占位符的密钥字段viewer 表单回填后直接保存不会误清已配置的 key只有磁盘上的 YAML 才有明文密钥浏览器端永远只能看到掩码。PATCH端点还有一个健壮性约定客户端提交的非法 body类型不匹配、数值越界由resolveConfig抛出config_invalid被映射为 HTTP 400invalid_argument而服务端自身的故障如磁盘满导致原子 rename 失败继续冒泡到全局 500 处理器——这样一次坏的 PATCH 永远不会用 500 污染并发的搜索/onTurnStart 请求见 server/routes/config.ts。边界情况与容错gotchascore/config/README.md归纳的四个关键边界情况全部有源码与测试支撑首次启动没有配置文件——loadConfig捕获ENOENT记录 warning config file not found … using defaultsAgent 首轮照常工作之后可通过 viewer 的Settings页PATCH /api/config创建文件。对应测试returns defaults with a warning when no config file existstests/unit/config/load.test.ts。升级后的 schema drift——未知键原样保留向前兼容并打 warning被删除的键同样打 warning 并回落到默认值。pruneUnknown()的注释明确写着likely from a removed schema测试keeps unknown keys (forward-compatible) and emits a warning验证mysteryFutureField: 42会被保留且告警tests/unit/config/load.test.ts。chmod 600——写入器每次写回都重新应用文件永不意外变成全局可读。密钥不出现在 viewer——GET /api/config返回前按SECRET_FIELD_PATHS脱敏。tests/unit/config/load.test.ts还覆盖了大量恶意/手滑输入非数字端口viewer.port: not a number触发 schema validation 失败非法时区Not/AZone抛config_invalidvectorScanMaxAgeMs必须落在[0, 31_536_000_000]一年负数、超一年、字符串、null、布尔全部被拒——这是 Issue #1929 的契约测试确保一次脏PATCH 不可能污染磁盘上的 YAML。tests/unit/config/hermes-migration.test.ts则验证端口迁移的幂等性与并发安全三次并发loadConfig(home, hermes)只有一次执行迁移。调优速查症状到参数的映射当你想调节检索与进化行为时docs/CONFIG-ADVANCED.md 提供了一张症状 → 参数对照表这里摘录高频项症状建议调整注入包被陈旧、离题的 trace 占据调低weightPriority、调高minTraceSim相似 trace 反复出现调低mmrLambda0.5–0.6换取更多多样性重启/新装后技能浮出太少调低minSkillEta0.3——技能默认从 η0.5 起步排位过慢看 perf 日志调低candidatePoolFactor如 3L2 归纳在单 episode 循环上误触发调高l2Induction.minEpisodesForInduction如 3有用的 L2 策略始终不转 active调低algorithm.skill.minGain或minSupport大流量涌入期 LLM 成本过高设l2Induction.useLlm: false候选照常收集L3 世界模型从未创建确认至少 2 条 active 策略共享 domain key异构域下调低clusterMinSimilarity0.5–0.55技能卡在 candidate 不毕业调低skill.candidateTrials如 2或minEtaForRetrieval如 0.4Agent 无视明显的失败循环≥3 次重试调低feedback.failureThreshold2或failureWindow3决策修复表堆满近重复项调高feedback.cooldownMs如 300000 5 分钟注意 2026-04 的默认值调优V7 论文原始阈值minGain0.1、minPolicies3、candidateTrials5对真实交互场景过严——真实用户几乎不产生显式失败对照集对比式增益公式会坍缩到 0。配合core/memory/l2/gain.ts的 Beta-binomial 收缩增益以中性 0.5 为先验minGain已下调到 0.02、minPolicies到 1让聚焦用户约一周内即可到达 L3 世界模型 首个毕业技能而非几乎永远等不到。回归到默认值要恢复某个配置项的默认值直接删除config.yaml中对应块即可——下次加载时 schema 的默认值自动生效docs/CONFIG-ADVANCED.md 明确说明。由于写入器保留注释与顺序部分覆盖永远安全模板只是安装时的起点运行期的唯一权威是用户主目录下那份真实的config.yaml。小结core/config/模块用约七个文件解决了一个看似简单实则布满陷阱的问题为每个 Agent 维护一份人类可读、机器可校验、升级不破坏、密钥不外泄的 YAML 配置。从paths.ts的路径单一事实来源到defaults.tsschema.ts的默认值即 schema双向对齐再到writer.ts的 CST 级注释保留与原子写最后以SECRET_FIELD_PATHS脱敏和migrations.ts平滑升级收尾——这套设计让插件既能零配置开箱即用也能承受长时间运行后的 schema 演进是理解 MemOS 插件体系配置治理思路的最佳入口。赞分享人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载相关推荐MemOS memos-local-plugin 持久化层深度解析基于 better-sqlite3 的 core/storage 存储引擎设计MemOS memos local plugin 持久化层深度解析基于 better sqlite3 的 core/storage 存储引擎设计 导读 app人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginMemOS Local Plugin 结构化日志系统全解析core/logger 架构、通道体系与配置实战MemOS Local Plugin 结构化日志系统全解析core/logger 架构、通道体系与配置实战 本文以 core/logger 模块 https:人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginmemos-local-plugin 模板体系详解config.yaml 如何从模板落地到运行时目录memos local plugin 模板体系详解config.yaml 如何从模板落地到运行时目录 本文以 apps/memos local plugin/人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考