人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文围绕 IronClaw 开源仓库中的crates/extensions/packages/memory-native包展开该包是 IronClaw一款聚焦隐私、安全与可扩展性的 Agent OS内置的默认[memory]提供者以文件系统为后端完整实现了跨会话的持久记忆能力。读完本文你将掌握 memory-native 的整体架构契约层与实现层的边界、/memory虚拟路径与四元组作用域规则、读写/搜索/树形浏览/档案设置五个模型工具的配置语义、混合搜索与提示词写入安全引擎的实现原理以及如何用cargo test -p ironclaw_memory_native验证这套内存系统的契约一致性。一、包定位为什么需要内置的 memory 提供者IronClaw 把记忆抽象为 provider-neutral 的契约ironclaw_memory::MemoryService而memory-native是随二进制默认捆绑、默认激活的实现扩展 ID 为ironclaw.memory保证记忆能力开箱即用无需任何安装/启用步骤。从 crates/extensions/packages/memory-native/README.md 可以看到它的关键定位Surfaces[memory]提供者 5 个模型工具ironclaw.memory.read/.write/.search/.tree/.profile_setVendor凭据权威无——不声明任何[auth.*]配方因为它是 first-party 原生实现不需要第三方凭据Runtimefirst_party与保留的ironclaw.*ID 一起只有在宿主注册了对应的native_memory_provider服务时才被接受见 manifest.toml 的注释部署约束每个部署同时只激活一个[memory]提供者备选实现是../mem0包切换后端不需要改动任何工具。值得一提的依赖反转例外crates/kernel/ironclaw_host_runtime/src/memory_native_extension.rs持有一个常规依赖其捆绑内存包的构建器README 明确记录这是 §8.2只有提供者包与二进制可以命名 memory 提供者规则的例外并被 PROPOSAL §6.8.4 记录为待迁移的端口反转而非迁移本身。二、分层架构契约在 ironclaw_memory实现在 memory-nativeAGENTS.mdcrates/extensions/packages/memory-native/AGENTS.md是本文档的核心骨架它首先强调provider-neutral 契约的归属MemoryServicetrait、DTO、scope/path/context 值类型、prompt-safety 词汇、审计/事件契约都住在 crates/domains/ironclaw_memory本 crate 只负责实现并再导出。这种契约下沉、实现外置的结构带来两个直接好处提供者可替换mem0 包同样实现同一套MemoryService契约共享的契约一致性测试套件同时跑两个提供者契约一旦变动两边都必须保持通过AGENTS.mdValidation一节依赖面收窄本 crate 只依赖ironclaw_memory、ironclaw_filesystem、ironclaw_safety、ironclaw_host_api四个包见 Cargo.toml明确禁止依赖 mem0 包、任何 HTTP 客户端、ironclaw_extension_host、ironclaw_extension_manager以及任何 kernel/product crate——这是 AGENTS.mdGuardrails的硬性边界。从 src/lib.rs 的公开导出可以看到本 crate 真正拥有的组件面领域关键类型文档仓库MemoryDocumentRepository、FilesystemMemoryDocumentRepository、InMemoryMemoryDocumentRepository后端适配MemoryBackend、RepositoryMemoryBackend、MemoryBackendCapabilities分块与哈希ChunkConfig、chunk_document、MemoryChunkWrite索引器MemoryDocumentIndexer、ChunkingMemoryDocumentIndexer、MemoryChunkReplaceOutcome搜索MemorySearchRequest、MemorySearchResult、FusionStrategy安全DefaultPromptWriteSafetyPolicy服务门面NativeMemoryService、MEMORY_GUIDANCE、MEMORY_CURATION_PASS_PROMPT等资产常量三、/memory 虚拟路径语法与四元组作用域memory-native 在宿主解析好的作用域之上工作。/memory是 crates/extensions/packages/memory-native/src/path.rs 中注册的VIRTUAL_ROOT路径语法为/memory/tenants/{tenant}/users/{user}/agents/{agent}/projects/{project}/{path}解析逻辑ParsedMemoryPath::from_virtual_path要求至少 7 段支持两种合法形态见 src/path.rs带 agent.../agents/{agent}/projects/{project}/{path...}不带 agentagent 为 None.../projects/{project}/{path...}。关键语义点_none是虚拟路径层哨兵路径段中的_none会被转换为Noneagent_id/project_id但它永远不被持久化存储——存储层用空字符串作为 agent/project 的缺席哨兵因为MemoryDocumentScope会拒绝空字符串 ID所以空串作为存储哨兵是安全的AGENTS.mdGuardrails保留后缀命名空间用户文档路径不得以.meta、.chunks、.versions结尾避免与仓库的 sidecar 后缀命名空间冲突见 src/path.rs 的rejects_path_segments_ending_in_reserved_sidecar_suffixes测试作用域过滤不可绕过每一次 read/list/search/write/version/chunk 操作都按完整(tenant_id, user_id, agent_id, project_id)四元组过滤禁止从路径前缀推断项目作用域文档唯一性约束为UNIQUE (tenant_id, user_id, agent_id, project_id, path)。此外path.rs 中还有一层防泄漏设计sanitize_memory_backend_reason当后端错误信息包含 SQL 关键字sql、sqlite、libsql、主机端口host、port、绝对路径/tmp/、/home/等敏感标记时统一替换为 memory backend operation failed避免把后端内部细节泄露到外部错误面。四、文档仓库与后端插件化存储fail-closed 能力声明4.1 双层抽象Repository 与 BackendMemoryDocumentRepositorysrc/repo/mod.rs定义文档的读写/原子追加/原子替换/元数据/列表/搜索原语并提供默认的 fail-closed 实现不支持的操作返回memory backend does not support ...错误RepositoryMemoryBackendsrc/backend.rs把仓库包装成宿主可调用的MemoryBackend在其上叠加作用域守卫、prompt-write 安全、元数据解析、schema 校验、事件上报与索引器联动。MemoryBackendCapabilities是一组布尔能力声明file_documents、metadata、versioning、prompt_write_safety、full_text_search、vector_search、embeddings、graph_memory、delete、transactionsAGENTS.md 强调它是强制输入不支持的 file/search 行为在产生后端副作用之前就 fail closed。例如RepositoryMemoryBackend::search在请求 full-text 而能力未声明、请求 vector 而能力未声明时都会先返回错误再触碰仓库见 src/backend.rs。4.2 持久化策略Filesystem 是唯一部署目标AGENTS.md 明确持久化是单一的FilesystemMemoryDocumentRepository叠在RootFilesystem之上InMemoryMemoryDocumentRepository只是测试支撑绝不是部署目标。libSQL/Postgres 等后端特有的行为覆盖属于ironclaw_filesystem的后端契约测试本 crate 的测试只针对内存后端来验证内存文档语义版本化、chunk 替换、元数据级联、混合搜索融合。4.3 原子追加与乐观并发写入路径上有多层并发控制compare_and_append_document_with_options/compare_and_write_document_with_options返回Appended/Conflict、Written/Conflict结果append_document_with_backend_options采用读-算哈希-比较追加的乐观循环最多重试 8 次超限报 memory document changed during append; retry limit exceededprofile_set与patch_document同样在最多MAX_MEMORY_PATCH_RETRIES 8次内做 read-modify-write 的哈希比对。这保证了对同一文档的并发写不会静默覆盖冲突会显式暴露并由调用方重试。五、分块、内容哈希与索引器5.1 分块配置src/chunking.rs 中的ChunkConfig移植自工作区现有 chunker以保证记忆索引保持既有搜索召回行为参数默认值说明chunk_size800以词为单位的块大小with_chunk_size强制 1overlap_percent0.15相邻块重叠比例with_overlap收敛到[0.0, 0.5]min_chunk_size50尾块不足此词数时与上一块合并chunk_document按空白切词不足chunk_size时整体返回超过时按步长chunk_size - overlap滑动切块末尾不足min_chunk_size的残块会与前一块合并避免产生无意义碎片。5.2 内容哈希content_sha256/content_bytes_sha256从ironclaw_memory再导出是原子追加/写入的乐观锁基础也是版本化与chunk 替换的比对依据。5.3 向量搜索诚实的能力边界AGENTS.md 特别强调本 crate 不存在 embedding-provider 端口向量搜索只在预先提供的 embeddings下激活。RepositoryMemoryBackend::search保留了 fail-closed 信息请求向量搜索但后端未声明vector_search→ memory backend does not support vector search声明了vector_search但请求未携带query_embedding→ 若embeddings能力为 false 则 memory backend does not support embedding generation否则 memory backend cannot generate query embeddings。也就是说搜索路径是full-text only原生后端的build_native_backend只声明full_text_search true任何向量请求都会在触碰仓库前失败。这是源码注释明确记录的端口曾有零实现而被删除的事实。六、混合搜索FTS 向量经 RRF 融合src/search.rs 定义了搜索请求/结果与融合逻辑MemorySearchRequest关键参数与默认值limit 20上限MAX_LIMIT 1000、pre_fusion_limit 50上限MAX_PRE_FUSION_LIMIT 5000、full_text true、vector true、fusion_strategy Rrf、rrf_k 60、min_score 0.0、full_text_weight 0.5、vector_weight 0.5。with_limit会联动重夹取pre_fusion_limit保证不变式pre_fusion_limit limitFusionStrategyRrf倒数排名融合工作区默认与WeightedScore加权排名分融合融合细节同一文档路径的 FTS 命中与向量命中会合并为一个结果槽full_text_rank/vector_rank各取最小排名先归一化再过滤——原始 RRF 分很小k60 时榜首约 0.016若直接拿调用方给的min_score 0.5过滤会把所有结果清空因此实现先除以最大分归一化到 [0,1] 再按min_score保留测试rrf_min_score_filters_normalized_scores_not_raw_rrf_values专门锁定了这个契约src/search.rs确定性排序同分结果按相对路径升序打破平局保证跨运行结果顺序可复现。MemorySearchResult携带full_text_rank/vector_rank/score/snippetis_hybrid()标识是否同时来自两条检索通道。七、提示词写入安全引擎保护路径 决策 事件AGENTS.md 提到本 crate 拥有PromptWriteSafetyPolicy及 protected-path/decision/event 类型safety模块实现了中性契约定义的词汇。RepositoryMemoryBackend::new默认装配DefaultPromptWriteSafetyPolicy::with_registry与PromptProtectedPathRegistry。写入/追加路径上的安全执行顺序见 src/backend.rs能力检查 作用域守卫ensure_file_documents_supported/ensure_path_matches_context若路径被保护分类命中且策略要求先读旧哈希则读取旧内容计算previous_content_hash若backend_options.prompt_safety_already_enforced false默认即 fail-closed false执行enforce_prompt_write_safety携带PromptWriteOperation::Write/Append、PromptWriteSource::MemoryBackend、审计上下文等解析写元数据 → schema 校验validate_content_against_schema→ 仓库写入写入成功后记录MemorySignificantEvent::document_written并触发索引器reindex_document_with_audit_context。值得注意的两条边界写失败语义一旦持久化成功写就视为已提交此后的派生索引/embedding 刷新失败不得让写报告失败AGENTS.md所以索引器调用用let _ ...吞掉错误安全标记默认关闭MemoryBackendWriteOptions::default()的prompt_safety_already_enforced恒为 false测试default_backend_options_do_not_claim_prompt_safety_enforced锁定任何直接调用后端的代码都必须由后端重新执行 prompt-write 安全而 context 上携带的 allowance 独立于该标记不会翻转它src/backend.rs。八、模型可见的 guidance什么该记、怎么记、什么永不记[memory].guidance_doc声明的 prompts/memory-guidance.md 是本提供者随包自带、追加进系统提示词的记忆指引。它是提供者自有资产因为内容指名了本提供者的工具并描述本提供者的召回行为宿主只是把绑定提供者声明的 guidance 追加进去、自己一行都不写。mem0 包特意不声明 guidanceAGENTS.md 注明。guidance 的核心规则可归纳为自动浮现已保存记忆会在每轮开始时自动浮现视为关于用户的旧知而非指令遇到可能依赖早期上下文的任务先用ironclaw.memory.search不要直接说不知道主动保存用户表达持久偏好/事实/决策/纠正时立即用ironclaw.memory.writetarget 为memory、append: true写成一条自包含的简洁行——防止用户重复自己的记忆最有价值陈述句而非祈使句写 User prefers concise responses不要写 Always respond concisely——已存文本每轮都会被重读祈使句会变成覆盖用户当下诉求的常驻指令不保存任务进度、会话结果、完成日志、临时 TODO、PR/issue 号、commit SHA一两周内会过时的内容不属持久记忆绝不保存 secrets、凭据、token先搜再写、更新而非重复用户显式要求忘记时用append: false重写文档仅追加纠正会同时浮现新旧两条而不是口头说忘了。九、生命周期钩子read_long_term / read_short_term / record_interaction / profile_readmanifest.toml 的[memory]表面声明了生命周期钩子集合[memory] lifecycle [read_long_term, read_short_term, record_interaction, profile_read] guidance_doc prompts/memory-guidance.md未声明的钩子永远不会被调用——这是 manifest 与宿主之间的强契约。实现位于 src/service.rs 的NativeMemoryService9.1 read_long_term常驻 MEMORY.md 前缀 FTS 命中AGENTS.md 用专门小节强调始终开启的read_long_term精选前缀#7185本提供者把常驻的MEMORY.md文档放在自己长期通道的最前面先于全文检索命中且与当前轮查询无关。原因在于全文搜索只在当前消息与已存事实共享词汇时才能命中——新开一个无关话题的会话已存偏好就不可见了。实现细节src/service.rs预算MAX_CURATED_SNIPPETS 4防止常驻文档吃掉调用方全部max_snippets额度、饿死后面的搜索命中每个精选块原始字节上限CURATED_CHUNK_RAW_BYTES 400因为宿主把模型可见 snippet 上限设为 512 字节并跑 prompt 黑名单块内切分保证模型看到的每个字节都经过与搜索命中相同的检查——携带黑名单秘密的行单独被丢弃而不是连累整个文档截断标记为纯文字 (truncated)括号与分隔符会被宿主的 safe-summary 规则拒绝块内行用; 连接原始换行是控制字符会被宿主净化剥掉精选前缀之后FTS 命中会排除threads/子树保持两通道不相交与MEMORY.md自身它已在通道头部避免同一文档占用第二个槽位。9.2 read_short_term线程作用域的 run-local 通道短程通道只检索活动线程的记忆子树thread_id由可信宿主运行上下文携带在 invocation scope 上永远不由模型提供没有活动线程就降级为空。检索用ranked_in_scope_results先过量抓取fetch_limit max_snippets * 8且至少 64再按线程前缀过滤防止全局 top-N 挤掉线程局部命中。9.3 record_interaction逐轮转录的幂等记录after-turn 记录器把完整轮次历史逐字写入threads/thread_id/turn_run_id.mdoverwrite 模式路径以turn_run_idprovenance命名使重跑已Completed的 run 覆盖同一文件而非无限追加——幂等。threads/命名空间是保留的公开write工具拒绝任何threads/前缀目标否则会成为长期通道不可见 非活动线程的短程通道也不可见的检索黑洞只有受信任的记录器通过write_reserved_document写入。9.4 profile_read / profile_set私密本地档案档案键控在人类用户上agentNone, projectNone落在context/profile.json。profile_set只接受timezoneIANA 名、localeBCP-47、location自由标签三个字符串字段且是私有本地写入与builtin.trace_commons.profile_set无关见 manifest.toml 的工具描述。十、工具表面与 origin 门控manifest 声明 5 个模型工具输入/输出 schema 内联服务自捆绑资产文件单一事实源origin_gate_matrix保留了它们作为builtin.memory_*时的门控工具effectsdefault_permissionloop_run 门控说明ironclaw.memory.readread_filesystemallowungated读当前作用域记忆文档ironclaw.memory.writeread_filesystem,write_filesystemallowgated_unless_granted任意路径写入需门控授权ironclaw.memory.searchread_filesystemallowungated仅搜内部持久记忆ironclaw.memory.treeread_filesystemallowungated树形列出记忆文档ironclaw.memory.profile_setread_filesystem,write_filesystemallowungated记录时区/语言/位置关键安全语义缺失矩阵不等于无门控——S4 authorize fold 对每个带 origin 标记的调用 fail-closed 为 Forbiddenproduct与automation对全部工具默认forbidden。也就是说这些工具只对 LoopRun模型驱动回合开放产品/自动化通道默认拒绝。十一、自声明的定期整理memory curation passmanifest 中还有一个值得展开的设计#7664提供者为自己声明 recurring upkeep——每完成 10 轮interval_turns 10按所有者执行一次整理[[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 }整理工作流为重读常驻文档 → 合并表达相同内容的条目 → 解决已被取代的条目 → 输出报告。它声明在 manifest 里是因为这份工作属于本提供者prompt 描述的是本提供者的文档形态、选用的是本提供者的工具。宿主只拥有时钟、调用信封与权威工具 ID 是从本 manifest 的[[tools]]中选择的且每次调用仍走正常的能力授权。max_model_calls 10是本 pass 自身预算低于宿主上限——#7770 实测显示真实模型会额外消耗调用一次失误的读、一次多余的写需要余量才能发出报告。十二、测试与验证共享契约套件AGENTS.md 的Validation给出三层验证路径快速本地检查cargo test -p ironclaw_memory_native——契约套件位于tests/memory_service/memory_backend/memory_filesystem/repo_*实际文件为 tests/memory_service_contract.rs、tests/memory_backend_contract.rs、tests/memory_filesystem_contract.rs、tests/repo_filesystem_contract.rs、tests/repo_in_memory_contract.rs边界检查依赖/API 变更后cargo test -p ironclaw_architecture_tests共享一致性MemoryService一致性套件同时也跑在 mem0 包上——契约变化时两个提供者必须同时保持通过。Cargo.toml 中test-supportfeature 的设计细节值得注意契约测试脚手架src/contract_tests.rs含有.expect/.unwrap/assert*!调用属于有意的测试代码必须通过 feature 门控关闭避免出现在生产构建里触发 scripts/check_no_panics.py 扫描器本 crate 的集成测试通过自 dev-dependency 开启该 feature。同时rt-multi-threadfeature 是竞态安全测试#[tokio::test(flavor multi_thread, worker_threads 2)]所必需的——没有它宏会静默回退到 current-thread 调度器tokio::join!协作式轮询将掩盖对replace_document_chunks_if_current的真实抢占式竞争PR #3180 invariant 6。十三、开发边界与契约变更流程AGENTS.md 最后给出协作规则对想为该项目贡献的读者有直接指导意义编辑边界保持编辑在本 crate 内除非契约明确要求改动相邻 crate测试偏好当 helper 门控 dispatch、持久化、网络、secrets、审批、资源、事件或进程副作用时优先写调用方级测试契约冲突处理如果契约与代码不一致停下来把任务当作契约变更请求处理而不是静默改变所有权——这条规则同时保护了契约层的权威性和实现层的自由度。结语memory-native 是一个小而克制的参考实现契约全部下沉到ironclaw_memory本 crate 只保留文件系统文档系统、路径语法、分块/索引、混合搜索、提示词写入安全与模型 guidance 这些真正属于自己的部分能力声明 fail-closed、作用域四元组全过滤、错误信息脱敏、写提交与索引刷新解耦共同构成了它的安全与一致性底座。对于想理解 IronClaw 记忆体系或移植一个自研记忆后端的读者从 AGENTS.md 出发对照 manifest.toml 的工具表面与 src/service.rs 的生命周期实现再跑一遍 tests/ 下的契约套件即可完整还原这套持久记忆架构的运作全貌。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw memory-native 详解默认 [memory] 提供者的文件系统记忆后端实现IronClaw memory native 详解默认 memory 提供者的文件系统记忆后端实现 导读 memory native 是 IronClawA人工智能AI 应用交互助手AI Agentomo-senpi Memory 组件深度解析Letta-Code 风格持久化 Agent 记忆的架构、配置与实现omo senpi Memory 组件深度解析Letta Code 风格持久化 Agent 记忆的架构、配置与实现 导读 本文以 omo senpi pac人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排IronClaw 记忆契约层深度解析provider-neutral 的 MemoryService 接口、/memory 路径语法与 Prompt 写安全边界IronClaw 记忆契约层深度解析provider neutral 的 MemoryService 接口、 /memory 路径语法与 Prompt 写安全人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
