IronClaw 记忆目录树工具 `ironclaw.memory.tree` 完全指南：作用域、参数、输出格式与源码解析

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文围绕 IronClaw 开源仓库中 memory-native 记忆扩展包扩展 IDironclaw.memory提供的ironclaw.memory.tree模型工具展开它用于将当前租户/用户/Agent/项目作用域内的持久化记忆文档以紧凑的树形结构列出帮助模型在读取或写入之前快速发现已有记忆文档。读完本文你将掌握该工具的调用参数path与depth、输出格式约定、作用域解析与路径安全校验的底层实现以及它与read、search、write、profile_set四个兄弟工具配合的完整记忆工作流。一、工具定位记忆工具族里的目录浏览入口memory-native 是 IronClaw 内置的默认[memory]提供方以文件系统为后端实现 provider 无关的ironclaw_memory::MemoryService契约扩展 ID 为ironclaw.memory。它的包说明文档README.md明确指出该扩展提供 5 个记忆工具工具 ID职责ironclaw.memory.read按相对路径读取持久化记忆文档返回内容与词数ironclaw.memory.write写入、追加或就地补丁持久化记忆文档ironclaw.memory.search用自然语言查询在记忆文档中检索最佳匹配片段ironclaw.memory.tree将记忆文档列出为紧凑树本文主角ironclaw.memory.profile_set记录时区 / 区域 / 位置的私有本地用户事实tree在工具族中承担先浏览、后操作的发现职能。其模型提示词文档tree.md原文定义了它的核心行为将持久化记忆文档列出为紧凑的树形结构作用域限定在当前 tenant/user/agent/project 内。可选传入path列出某个子目录传入depth限制遍历深度。在读取或写入之前用它发现存在哪些记忆文档。与search不知道确切路径时用自然语言找和read知道路径后按路径取内容不同tree解决的是我不知道记忆里有什么的问题——它是记忆命名空间的根目录浏览工具。二、输入参数详解path与depthtree的输入契约由 JSON Schema 文件 tree.input.v1.json 定义仅有path和depth两个可选参数且additionalProperties: false不接受任何额外字段。2.1path要列出的相对记忆目录路径类型字符串默认值为空字符串。语义相对记忆目录路径。省略或传空字符串时列出记忆根目录传入路径时列出对应子目录。硬性约束Schema 中的not正则与描述双重声明不能是绝对路径不允许前导/不能包含..路径穿越不能使用反斜杠\作为分隔符。二次校验描述中说明宿主文件系统额外将路径解析到作用域内的/memory挂载点内意味着即使通过了 Schema 层校验底层文件系统挂载仍然会约束路径不能逃逸出当前作用域的/memory虚拟根。2.2depth最大遍历深度类型整数minimum: 1maximum: 10默认值1。语义要包含的最大目录深度。默认只列出一层需要深入子目录时逐级调大。2.3 参数校验的源码层印证服务层service.rs的tree()方法对参数做了与 Schema 一致的运行时防御pub async fn tree(self, invocation, request) - ResultMemoryServiceTreeResponse, ... { if !request.path.is_empty() { reject_local_or_traversal_path(request.path)?; } let (scope, context) self.scoped_context(invocation)?; // ... }其中reject_local_or_traversal_path会在以下三种情况直接返回Input错误路径包含反斜杠\路径看起来像本地文件系统路径——以/或~/开头或形如C:\、C:/的盘符形式任一路径段为..contains_traversal按/分段逐一比对。这构成了Schema 层正则 服务层逻辑的双重防线保证tree永远不会把作用域之外的目录暴露给模型。三、输出格式紧凑树的结构约定tree的输出由 tree.output.v1.json 定义一个字符串数组每个元素是一个记忆文档路径或带尾部/的目录路径。Schema 层面的格式约定文档条目直接输出相对路径字符串例如notes/alpha.md目录条目路径末尾带/用于与文档区分例如daily/输出是无序数组但从源码实现看服务层会对底层返回的全部路径做一次字典序排序paths.sort()再渲染保证输出稳定、可预测。3.1 从源码看嵌套结构需要补充说明的是从实现函数tree_for_paths位于 service.rs的代码结构可以推断当depth 1时实际渲染结果比 Schema 描述更丰富——目录节点会递归展开为嵌套对象形如{ daily/: [ ... ] }子目录内部再嵌套其下的目录与文件而当depth 1默认值时子目录只输出为daily/这样的带斜杠字符串不再展开。测试 memory_service_contract.rs 中也是通过serde_json::to_string(tree.entries)对输出做 JSON 序列化后断言其包含目标文件名印证了输出的 JSON 数组性质。tree_for_paths的核心算法如下按源码结构还原以root参数即请求的path空串代表记忆根为前缀过滤出相关路径将剩余路径按是否含/分为两类含/的归入子目录分组用BTreeMap按首段目录名聚合不含/的直接作为文件条目若max_depth 1每个子目录仅输出dir/字符串否则递归调用自身渲染子目录树递归深度逐级减一目录条目在前、文件条目在后最终拼成完整数组。四、作用域解析tenant/user/agent/project 四级隔离tree与所有记忆工具一样只列出当前调用作用域内的文档。作用域由MemoryDocumentScope建模其虚拟路径语法定义在 path.rs/memory/tenants/{tenant}/users/{user}/agents/{agent}/projects/{project}/{path}从ParsedMemoryPath::from_virtual_path的解析逻辑可以看到tenant_id、user_id为必填段支持两种书写形态带 agent 的完整形态.../agents/{agent}/projects/{project}/...与省略 agent 的.../projects/{project}/...agent 段或 project 段为字面量_none时解析为None即无该层级绑定否则为具体的 ID第 7 个段之后的所有剩余段拼接为相对文档路径并经过validated_memory_relative_path校验——该校验会拒绝以.meta、.chunks、.versions等保留副产物后缀结尾的路径段防止用户文档与存储层内部元数据文件命名空间冲突见path_validation_tests中的rejects_path_segments_ending_in_reserved_sidecar_suffixes测试。服务层tree()通过scoped_context()从调用方传入的MemoryInvocation.scope重建MemoryDocumentScope与MemoryContext再调用后端list_documents(context, scope)获取该作用域下的全部文档路径。因此不同租户、不同用户、不同 Agent、不同项目之间的记忆目录互不可见tree天然是隔离的。五、安全与权限边界tree的权限与安全属性同样定义在包清单 manifest.toml 中[[tools]] id ironclaw.memory.tree description List Reborn persistent memory documents as a compact tree. effects [read_filesystem] default_permission allow visibility model origin_gate_matrix { loop_run ungated, product forbidden, automation forbidden }几点值得注意效果声明为只读effects [read_filesystem]tree不会产生任何写副作用来源门控origin gateloop_run为ungated循环运行上下文免审批属于受审的UNGATED_LOOP_RUN_CAPABILITIES白名单语义而product与automation来源默认forbidden——清单注释明确说明缺失的门控矩阵并不是无门控而是 S4 authorize 折叠对所有来源标记的调用默认失败关闭Forbidden。这与read、search保持一致而写路径的ironclaw.memory.write则保持gated_unless_granted任意路径写入需授权读/列目录与写入的信任等级被有意区分开路径逃逸防护除第二节介绍的输入校验外宿主文件系统还会把解析后的路径限制在作用域内的/memory挂载点内双重保证tree只能看到该看的记忆目录。六、测试验证与调用示例memory-native 的契约测试 memory_service_contract.rs 覆盖了tree与write、read、search的联动场景其流程对理解tree的典型用法很有帮助// 1. 先写入一条记忆 write(invocation, MemoryServiceWriteRequest { target: notes/alpha.md.into(), ... }) .expect(write through IronClaw memory service); assert_eq!(write.path, notes/alpha.md); // 2. 按路径读取确认内容与词数 let read service.read(invocation.clone(), MemoryServiceReadRequest { path: notes/alpha.md.into(), ... }).await; assert_eq!(read.content, alpha native IronClaw memory marker); // 3. 用 tree 从根目录发现该文档depth2 let tree service.tree(invocation.clone(), MemoryServiceTreeRequest { path: String::new(), depth: 2 }).await; assert!(serde_json::to_string(tree.entries).unwrap().contains(alpha.md));一个完整的模型侧调用示例以 JSON 参数形式描述{ name: ironclaw.memory.tree, arguments: { path: , depth: 2 } }预期返回示意[ daily/, MEMORY.md, notes/alpha.md ]典型使用节奏发现会话开始时先tree或带path定位到某个子目录了解当前作用域记忆里有什么定位不确定路径时用search做自然语言检索读取用read取回某个文档全文写入用write目标memoryappend模式最合适保存单行事实沉淀新的持久化偏好或调用profile_set记录时区/区域/位置等结构化用户事实。tree的先浏览再读写定位也与其兄弟工具read、search的提示词read.md、search.md互为呼应read强调在行动前回忆已记录的笔记、日志或画像事实search强调不知道确切文档路径时找到相关笔记而tree正是这两者之前的第一步——先把记忆目录的全貌呈现在模型面前。七、适用前提与注意事项提供方绑定tree由 memory-native 提供方实现且每次部署只有一个[memory]提供方处于激活状态默认 memory-native可替换为 mem0 后端而不改变这些工具形态见 README.md。使用前提是当前部署绑定的是该提供方。深度上限depth最大为 10避免无界遍历默认 1 意味着不深入子目录。路径合法性path必须是相对路径、不含..与反斜杠根目录浏览直接省略path即可。内容边界tree只返回路径与目录结构不返回文档内容需要内容请用read需要语义检索请用search。结语ironclaw.memory.tree是 IronClaw 记忆系统发现层的关键入口它以紧凑树形把当前租户/用户/Agent/项目作用域内的持久化记忆文档呈现在模型面前配合严格的路径校验、只读效果声明与来源门控保证安全性并通过path/depth两个参数提供灵活的浏览粒度。无论是作为模型在行动前的记忆盘点工具还是作为排查记忆存在但检索不到问题的目录索引它都是理解 IronClaw 记忆子系统时值得掌握的第一个工具。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐终极Arjun参数发现工具输出格式完全指南JSON、文本和BurpSuite格式详解终极Arjun参数发现工具输出格式完全指南JSON、文本和BurpSuite格式详解 Arjun是一款强大的HTTP参数发现工具能够帮助安全测试人员和开发人网络安全应用安全渗透测试broot 目录树导出指南使用 :print_tree 与命令行参数输出剪枝后的树broot 目录树导出指南使用 :print_tree 与命令行参数输出剪枝后的树 Broot 是一款以树状结构浏览、过滤和导航目录的工具。当你在 broot开发工具Hydra 工作目录定制指南run 与 multirun 输出目录模式全解析Hydra 工作目录定制指南run 与 multirun 输出目录模式全解析 本指南围绕 Hydra 的 hydra.run.dir 、 hydra.swee开发工具后端CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考