IronClaw 内存原生提供方（memory-native）深度解析：MemoryService 契约实现、双通道召回与提示写入安全

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 将持久化记忆拆分为provider-neutral 契约与可插拔提供方两层memory-native扩展 idironclaw.memory是随二进制默认捆绑、基于文件系统实现的[memory]提供方负责记忆文档的读写、搜索、树形浏览、结构化用户档案以及检索前retrieve-before/记录后record-after的完整生命周期。本文以 crates/extensions/packages/memory-native/CLAUDE.md 为骨架结合该包的源码、manifest.toml、prompt 资产与测试套件讲清它拥有什么、如何实现、受哪些约束。一、包的定位契约在ironclaw_memory实现在ironclaw_memory_nativememory-native是一个完整的 self-contained 包目录本身即crate manifest prompts schemas四位一体CLAUDE.md Start Here 一节。它与mem0包是同一[memory]提供方表面的两个候选实现——每次部署恰好激活一个README.md默认就是本包。# crates/extensions/packages/memory-native/manifest.toml id ironclaw.memory name Reborn Memory trust first_party_requested [runtime] kind first_party service native_memory_provider [memory] lifecycle [read_long_term, read_short_term, record_interaction, profile_read] guidance_doc prompts/memory-guidance.md关键分层事实契约归属MemoryServicetrait、DTO、scope/path/context 值类型、prompt-safety 词汇表、审计/事件契约都定义在 crates/domains/ironclaw_memory本包只实现并 re-exportlib.rs。依赖集非常克制Cargo.toml只依赖ironclaw_memory、ironclaw_filesystem、ironclaw_safety、ironclaw_host_api四个 crate不依赖 mem0、任何 HTTP client、ironclaw_extension_host/ironclaw_extension_manager或任何 kernel/product crate。链接方式包 crate 只被二进制链接唯一例外是ironclaw_host_runtime持有普通依赖其捆绑式内存包构建器见 crates/kernel/ironclaw_host_runtime/src/memory_native_extension.rs这是契约文档中明确记录的 pending port inversion而非迁移。二、本包拥有的功能面What This Crate Owns1. 文档仓储与后端插件契约MemoryDocumentRepository有两个实现FilesystemMemoryDocumentRepository生产部署目标单层叠加在RootFilesystem之上InMemoryMemoryDocumentRepository仅测试支撑绝不用于部署CLAUDE.md Guardrails。后端层MemoryBackend/RepositoryMemoryBackend/MemoryBackendCapabilitiesbackend.rs封装仓储 索引器 能力声明。能力声明是强制执行输入声明不支持的搜索/文件行为会在后端产生任何副作用之前 fail-closed。原生后端默认声明见 service.rs 的build_native_backendfile_documents true, metadata true, versioning true, prompt_write_safety true, full_text_search true, delete true, transactions true注意不声明vector_search——本包没有 embedding-provider 端口向量检索只能针对预先提供的 embeddings 激活否则在后端 fail-closed 消息中直接拒绝这正是无向量、纯 FTS的设计取舍mem0 后端则相反。2./memory虚拟路径语法与 scopeMemoryDocumentPath以(tenant_id, user_id, agent_id, project_id, relative_path)定位一条记忆文档MemoryDocumentScopepath.rs拒绝空字符串作为提供的 id因此未指定 agent/project的存储哨兵必须用空字符串而_none只是虚拟路径哨兵、永远不得落库。唯一性约束UNIQUE (tenant_id, user_id, agent_id, project_id, path)。每一条读/列/搜索/写/版本/分块操作都按完整四元组过滤绝不从路径前缀推断 project scopeCLAUDE.md Guardrails。3. 分块、内容哈希与索引器ChunkConfig、chunk_document、content_sha256chunking.rs负责把文档切成块并做内容寻址ChunkingMemoryDocumentIndexerindexer.rs把块写入索引。写入提交语义一旦持久化成功即视为已提交之后派生索引/embedding 刷新失败不得让写入报告失败否则会把持久化已成功误报为失败。4. 混合搜索FTS 向量经 RRF 融合MemorySearchRequest/MemorySearchResult/FusionStrategysearch.rs实现了混合搜索骨架全文检索与向量检索各自产生候选集再通过 RRFReciprocal Rank Fusion融合排序。由于原生后端vector_searchfalse实际运行时走纯 FTS 路径——MemorySearchRequest::new(query).with_limit(...).with_pre_fusion_limit(limit.max(20)).with_vector(false)service.rs 的search方法。5. 文件系统适配器与显著事件 sinkMemoryBackendFilesystemAdapter/MemoryDocumentFilesystemfilesystem.rs把记忆文档映射到虚拟文件系统显著事件 sinkevents.rs记忆写入/检索的关键节点产生审计事件。6. 提示写入安全引擎PromptWriteSafetyPolicy词汇表operation、source、severity、reason code、事件 payload/sink、policy trait、protected-path registry在ironclaw_memory强制执行引擎在本包safety.rsDefaultPromptWriteSafetyPolicyPromptProtectedPathRegistryironclaw_safety::Sanitizercheck_write先做 protected-path 分类再跑 sanitizer把Severity映射到契约的PromptSafetySeverity桶Low/Medium/High/Critical。三、模型面记忆指引guidance_doc提供方自带的什么该记prompts/memory-guidance.md是[memory].guidance_doc声明的模型面指引service.rs 通过MEMORY_GUIDANCE/MEMORY_GUIDANCE_DOC_REF常量 MEMORY_ASSETS资产表捆绑要点保存时机用户给出持久偏好、事实、决定或纠正时主动用ironclaw.memory.write保存targetmemory、append: true、一行自包含简洁事实不要等被要求措辞纪律写成关于用户的陈述句User prefers concise responses绝不写成给自己的指令Always respond concisely——因为保存的文本会在每个后续回合作为上下文被重新读取祈使句会变成一条覆盖用户当前请求的常驻指令不保存清单任务进度、会话结果、已完成工作日志、临时 TODO、PR 号/issue 号/commit SHA 等短期工件一两周内会过时的事实不进持久记忆绝不保存 secrets、凭据、token去重更新写入前先 search/read更新已有条目而非追加近似重复显式忘记用append: false重写文档追加式纠错会让原始条目仍然留在原地记忆块会同时携带两者。这一指引属于提供方自有资产因为它点名本提供方的工具、描述本提供方的召回行为host 只把绑定提供方声明的指引拼进 system prompt自己不写任何一句。mem0 故意不提供 guidance无追加。四、五个模型工具面read / write / search / tree / profile_setmanifest.toml的[[tools]]数组声明了 5 个工具input/output schema 由schemas/memory/*.v1.json资产内联提供单一事实源prompt 文档在prompts/memory-native/工具 id行为effects默认权限origin gateloop_runironclaw.memory.read读当前 scope 的持久记忆文档read_filesystemallowungatedironclaw.memory.write写/追加/补丁记忆文档read_filesystemwrite_filesystemallowgated_unless_grantedironclaw.memory.search仅搜索内部持久记忆read_filesystemallowungatedironclaw.memory.tree以紧凑树列出记忆文档read_filesystemallowungatedironclaw.memory.profile_set记录 timezone/locale/location 结构化档案read_filesystemwrite_filesystemallowungated安全要点manifest 注释明确origin_gate_matrix缺失不等于无门禁——S4 授权折叠对任何带 origin 戳的调用 fail-closed 到Forbidden。Product/Automation 对全部五个工具都是forbiddendeny-by-defaultwrite 保持gated_unless_granted可写任意路径read-like 工具通过UNGATED_LOOP_RUN_CAPABILITIESallowlist 放行。write 的路径别名与解析resolve_target_pathservice.rs定义了 4 个约定别名 任意相对路径target解析结果memoryMEMORY.md常驻记忆文档heartbeatHEARTBEAT.mdbootstrapBOOTSTRAP.md清空语义daily_logdaily/YYYY-MM-DD.md按调用方 timezone 解析缺省 UTC其他原样作为相对路径profile_set 与档案路径profile_set/profile_read使用独立于 agent/project 的档案路径profile_scope_and_path把 scope 钉在(tenant_id, user_id, agentNone, projectNone)文档路径固定为context/profile.json——这是关于人类用户本人的私有本地事实与builtin.trace_commons.profile_set无关。写入用 compare-and-writeCAS 至多MAX_MEMORY_PATCH_RETRIES 8次重试并校验 timezone/locale/location 字段必须为字符串。五、生命周期钩子与双通道召回manifest 声明了完整生命周期read_long_term、read_short_term、record_interaction、profile_read未声明的钩子永远不会被调用。NativeMemoryService是纯内部实现模型只能通过工具触达生命周期钩子由 host 驱动service.rs 的MemoryServiceimpl。常驻 MEMORY.md 前缀read_long_term 的 always-on curated prefix本提供方在自己的长程通道头部、全文命中之前无条件投放常驻MEMORY.md#7185与本次查询无关理由全文搜索只有在当前消息与存储事实共享词汇时才有效——新开一个无关话题的会话已保存的偏好就不可见了而 write 指引让模型维护的正是这份常驻文档上限MAX_CURATED_SNIPPETS 4防止常驻文档吃光调用方的max_snippets配额、饿死其后的搜索命中分块CURATED_CHUNK_RAW_BYTES 400字节/块host 对模型可见 snippet 有 512 字节上限并跑 prompt denylist分块保证每个模型可见字节都经过与搜索命中相同的检查携带 denylisted 秘密的行只丢自己、不连累整份文档截断标记 (truncated)与行内分隔符; 都是明文单词——方括号等符号会被 host 的 safe-summary 规则拒绝缺失是正常态用户从未保存过任何东西此时优雅降级为空前缀而非让通道失败后端故障同样降级并打debug!——记忆是最佳努力上下文绝不让一次 turn 随它一起倒下。长/短程双通道read_long_term常驻前缀 全文命中从候选集中剔除threads/子树与短程通道保持不相交和MEMORY_PATH本身避免重复占槽read_short_term只检索活动线程的threads/thread_id/子树thread_id来自可信 host 运行上下文绝不来自模型无活动线程则降级为空两个通道共享ranked_in_scope_results先超量抓取max_snippets * 8下限 64再做 scope通道过滤最后才截断——否则全局 top-N 的普通长程命中会饿死线程限定的短程通道。record_interaction每轮转录写入threads/record_interaction把完整 turn 历史以 Markdown 转录每条消息## {role} ({name})写入每轮独立文件threads/thread_id/turn_run_id.mdappend: false覆盖写幂等性调度器重跑已Completed的 run 会覆盖同一文件而不是把对话复制进无限增长的共享log.md这是唯一合法的threads/写入口公共write对任何threads/前缀目标直接拒绝保留命名空间审计 L1——散落写入会成为检索黑洞只有可信的记录器经write_reserved_document绕过该守卫且该 helper 自身也防御性拒绝非threads/路径。六、版本控制、补丁与并发安全Patch 语义old_string/new_string都非空保留 Origin 的空 new_string 不得删除匹配文本约束支持replace_all基于 CASexpected hash 至多 8 次重试的 read-compare-write 循环append 语义每条追加条目以恰好一个换行符终止——后端 append 是字节精确的若不加换行两条受引导的正确保存likes tea 与 lives in Berlin会拼成一行likes tealives in Berlin被当成一个事实并发安全测试tests/用#[tokio::test(flavor multi_thread, worker_threads 2)]跑针对replace_document_chunks_if_current的真实抢占竞态测试Cargo.toml 注释单线程下tokio::join!协作式轮询会隐藏真实竞态因此显式依赖rt-multi-thread。七、路径安全与输入卫生reject_local_or_traversal_path拒绝三类输入service.rs含\反斜杠的路径形如文件系统绝对路径 /~/开头 / 盘符C:\、C:/的路径含..遍历片段的路径按/分段检查。八、守卫与边界Guardrails / Do Not Move In Here从 CLAUDE.md 提炼的可执行约束依赖纪律只依赖上述四个 crateironclaw_extension_contracts仅在某个表面真正需要时才允许加入scope 纪律后端是 host 解析 scope 之后的插件不得推断更宽的 tenant/user/agent/project 权限不得绕过 mount/scope 文件系统检查语义搜索、分块、embeddings、版本控制必须留在 memory 自有的 repository/indexer 抽象之后通用 mount/catalog 逻辑留在ironclaw_filesystem不迁移入本包中性MemoryService词汇表留在ironclaw_memory、通用文件系统语义、直接 provider HTTP、原始 secret 处理、loop prompt 策略输出纪律错误、事件、快照、日志、文档中不得出现 secrets、raw host 路径、后端错误细节、未脱敏的用户内容。九、验证体系契约测试套件验证分三层CLAUDE.md Validation快速本地检查cargo test -p ironclaw_memory_native——tests/下五个契约文件memory_service_contract.rs共享MemoryService一致性套件memory_backend_contract.rsmemory_filesystem_contract.rsrepo_filesystem_contract.rsrepo_in_memory_contract.rs 这些测试瞄准内存后端覆盖版本控制、chunk 替换、metadata 级联、混合搜索融合等记忆文档语义后端特定的 libSQL/Postgres 行为覆盖属于ironclaw_filesystem的后端契约测试边界检查依赖/API 变更后跑cargo test -p ironclaw_architecture_tests跨提供方一致性同一共享套件也跑在 mem0 包上——契约变动时必须让两个提供方都保持通过。测试基建注意点test-supportfeature 默认关闭避免契约测试 harness 中的.expect/.unwrap/assert!*进入生产构建并触发 scripts/check_no_panics.py 扫描本 crate 的集成测试通过自依赖ironclaw_memory_native { path ., features [test-support] }启用Cargo.toml。十、调度运维每十轮一次的记忆整理scheduled_opsmanifest 中声明了提供方自有的循环维护#7664[[memory.scheduled_ops]] trigger after_turn interval_turns 10 pass { prompt prompts/memory_curation.md, tools [ironclaw.memory.read, ironclaw.memory.search, ironclaw.memory.write], max_model_calls 10 }归属原则整理工作属于提供方——prompt 描述本提供方的文档形状、挑选本提供方的工具因此随 manifest 声明而非放在 product/loop 层host 只负责时钟、调用信封与授权预算max_model_calls 10是本轮自身预算低于 host 上限#7770 的实测显示真实模型会多花调用一次失误的 read、一次多余的 write需要余量来完成报告工具选择限制pass 的 tools 只能从同一 manifest 声明的[[tools]]中挑选且每次调用仍要过常规能力授权。整理 promptprompts/memory_curation.md与 guidance 资产一起由MEMORY_ASSETS表承载host 通过泛型解析不按包名硬编码匹配manifest 引用与资产文本由native_bundle_declares_guidance_that_resolves_to_the_bundled_asset测试保证不漂移。结语memory-native是契约中立、实现可插拔架构的完整样本ironclaw_memory定义词汇表与行为契约本包以文件系统为底座、以严格依赖集和 fail-closed 能力声明为边界提供常驻记忆前缀、长/短程双通道召回、每轮转录、结构化档案与提示写入安全并通过共享一致性套件与 mem0 提供方保持可互换。若需替换后端可参照../mem0包实现同一MemoryService契约二者在 compose 时经[memory]绑定切换五个模型工具的输入/输出 schema 完全不变。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 内存契约解析provider 无关的 MemoryService 抽象与 /memory 路径文法IronClaw 内存契约解析provider 无关的 MemoryService 抽象与 /memory 路径文法 IronClaw 将内存抽象为一个人工智能AI 应用交互助手AI AgentIronClaw 记忆契约层深度解析provider-neutral 的 MemoryService 接口、/memory 路径语法与 Prompt 写安全边界IronClaw 记忆契约层深度解析provider neutral 的 MemoryService 接口、 /memory 路径语法与 Prompt 写安全人工智能AI 应用交互助手AI AgentIronClaw 内存服务契约深度解析provider-neutral 的 MemoryService 接缝与路径/安全词汇表IronClaw 内存服务契约深度解析provider neutral 的 MemoryService 接缝与路径/安全词汇表 本文围绕 IronClaw 中人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考