ai-memory 作用域标记文件.ai-memory.toml完全指南workspace/project 声明、捕获排除与 Allowlist 模式【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory.ai-memory.toml是 ai-memory 的仓库级标记文件marker file它让一个 Agent 的cwd无需依赖目录 basename 即可声明自己属于哪个 workspace、哪个 project。本文以 docs/marker-file.md 为骨架结合仓库内 POSIX hook 脚本hooks/_lib.sh、原生 hook 捕获实现hook_capture.rs与 marker 解析模块marker.rs的源码证据完整讲解 marker 文件的 Schema、目录查找规则、[capture]排除、Allowlist 模式、repo-root项目推导以及与会话中途路由、CLI 作用域解析的配合方式。读完你将掌握多客户端隔离、monorepo 分组、git worktree 合并、敏感路径捕获排除等场景的落地方案并能独立排查marker 不生效类问题。为什么需要 marker 文件ai-memory 用(workspace, project)二元组为每一张 wiki 页面做命名空间。默认情况下workspace defaultproject basename($cwd)——这套默认对~/projects/repo这种单人目录足够但对以下场景会错桶多客户咨询团队~/projects/client/repo结构下每个客户都应该落入独立的 workspace而不是全部挤在default工作 / 个人 / 开源分离单人开发者希望按生活语境隔离记忆Monorepo希望所有包统一归到一个 project而不是按每个包的 basename 各自成桶或者反过来每个包独立成 project——完全由你决定。marker 文件的意义在于不必 fork ai-memory也不必为每个目录手工运行 CLI 命令就能声明这些映射关系。它在仓库内repository-owned随代码库一起提交/分发。此外静态 MCP 客户端把 marker 当作仓库自持的显式 scope 参数来源因为这类客户端无法挂载真实的 lifecycle-hook session id托管路由managed routing要求它们在每次 project 级工具调用时都带上(workspace, project)二元组若二者缺一Agent 必须从操作者或服务器配置处获取而不能从 checkout 目录猜测。会话感知的桥接session-aware bridges则继续使用自动的 current-project 路由。放在哪里从cwd向上查找的规则.ai-memory.toml必须放在cwd的任意允许的祖先目录中。lifecycle hooks 从cwd逐级向上走到$HOME$HOME未设置时走到/采用第一个找到的marker。边界规则如下cwd 在$HOME内时向上走到$HOME为止cwd 在$HOME外时向上走到最近的 checkout 根存在.git文件或目录为止cwd 在$HOME外且不在任何 git checkout 内时只检查 cwd 自身更近的 marker 覆盖更外层 markerclosest wins找到 marker 后hook 脚本还会转发当前的cwd因此只有workspace的 marker 依然能以project basename(cwd)完成 handoff 查询。从源码看这条向上查找逻辑同时存在于两条实现路径且行为保持一致POSIX shell 版hooks/_lib.sh 中的ai_memory_find_marker先判定边界$HOME或最近的.git根再逐级检查dir/.ai-memory.tomlRust 原生版marker.rs 中的find_marker_with_home/find_marker_matching使用checkout_root找到边界absolute_normalized做纯词法路径规范化不解析符号链接、不加 Windows\\?\前缀避免 macOS/var - /private/var符号链接与 Windows verbatim 前缀导致 marker 目录和运行时 candidate 路径不在同一命名空间而匹配失败对应测试absolute_normalized_does_not_resolve_a_real_symlink。捕获专用 marker 的透明性capture-only transparency一个只包含[capture]段的 marker 对作用域查找是透明的workspace、project、project_strategy以及其余转发设置drop_subagent_captures、[recall] default_global、[briefing]各键都从最近的、至少声明了其中一项的祖先 marker解析跳过那些只声明了[capture]的更近 marker。这样一个仅为排除某些路径而新增的子目录 marker不会再把这个子树的作用域重置回default/ basename。[capture]/ignore_paths本身不受此影响永远取自最近 marker哪怕它是 capture-only 的。实现上shell 的ai_memory_find_settings_marker与 Rust 的find_settings_marker/declares_more_than_capture使用同一套设置键清单判定workspace、project、project_strategy、drop_subagent_captures、default_global、inject_on_session_start、max_chars。marker.rs中read_scope_skips_a_nested_capture_only_marker测试验证内层只写[capture]时外层acme/infra依然生效而read_scope_treats_a_briefing_only_marker_as_a_settings_boundary验证只声明[briefing]的 marker 是一个设置边界会停止查找但本身不声明作用域。统一的查询参数转发marker 路径由 POSIX/PowerShell hook 脚本与生成的 OpenCode / OMP / Pi / OpenClaw TypeScript 集成共享。marker 声明了cwd、workspace、project、project_strategy、drop_subagent、default_global、briefing、briefing_budget时hook 捕获与 handoff 查找都会把这些参数发给服务器handoff 查找在无 marker 时也会发送cwd保证默认project basename(cwd)路由一致工作。原生侧由 hook_capture.rs 的marker_query_suffix/marker_query_suffix_without_briefing构建后者供 kimi-code 在首次用户提示词后不再重复组合 brief。Schema完整配置参考以下为 marker 文件完整 schema继承自原文档并按源码补全取值细节# 必填。声明该目录树所属的 workspace。 workspace movvia # 可选。存在时强制该 marker 树内所有 cwd 的 project pe-portais。 # 省略时由 basename(cwd) 决定 project 名。 project pe-portais # 可选。省略时保持 project basename(cwd)。设为 repo-root 时 # project 从主 git 仓库根推导使关联 worktree 与子目录共享同一 project。 # 当 project 存在时被忽略。 project_strategy repo-root # 可选。为该项目启用 drop_subagent_captures设为 true 后服务器接受但 # 不存储该项目的 subagent-session 捕获。多 Agent harness 会把一个目标 # 扇出到大量 subagent 会话其逐事件捕获可能淹没小实例在此按项目 opt-in # 不会影响同一服务器上其他项目。默认关闭缺省 / false。 drop_subagent_captures true # 可选。把本仓库的默认记忆召回DEFAULT memory recall扩大到所有项目 # 本树中未指定范围的 memory_query 行为等同于 globaltrue # 未指定范围的 memory_recent 返回跨所有项目的最新页面每条命中标注 # workspace project。面向持续需要兄弟项目上下文的 meta-repos。 # 显式参数永远优先——为该次调用传入 workspace/project/scopes/ # global 会覆盖此项。默认关闭。注意激活期间未指定范围的查询返回 # 跨项目 global_hits 而非项目 hits global_scope_hits # _global 偏好页仍会出现在标注过的全局结果中。 [recall] default_global true # 可选。在会话开始以及上下文清除后——Claude Code 会在 /clear 时重放 # SessionStart注入编译好的项目简报session-start handoff 抓取还会返回 # 该项目 pinned / _rules/ / _slots/ wiki 页面含正文以及最近更新的 # 页面标题让 Agent 带着架构上下文开始而不是重新探索代码库。 # 追加在待处理 handoff 之后且不像 handoff 那样被消费——每个 opted-in # 会话开始都会重新组合。只有 session-start hook 会把 stdout 注入上下文的 # Agent 受益Claude Code、Codex、OpenCode……。默认关闭简报在每次 # 会话开始都会消耗 token所以按仓库 opt-in。 # Kimi Code 注意kimi 会丢弃 SessionStart hook stdout因此那里改在 # 会话首次用户提示词时投递简报每会话一次与 Claude 相同。其本地 # 投递标记只为 opted-in 仓库创建并限制在最近 512 个会话v1 不支持 # /clear 后重新简报。 [briefing] inject_on_session_start true # 可选。整个简报的字符预算约 4 字符/token含页眉页脚。 # 超出预算的正文被截断并附可见提示被挤掉的 core 页面按路径列出 # 让 Agent 可以 memory_query 它们连路径都放不下时退化为计数。 # 页面正文优先然后才用剩余空间放指针段安全通知与不受信任历史标记 # 永不因内容而牺牲。服务端钳制到 [1500, 20000]默认 4000。 max_chars 4000命名规则服务端校验workspace与project的命名规则在get_or_create_workspace/get_or_create_project时校验只允许小写 ASCII 字母、数字、点、短横线、下划线正则^[a-z0-9][a-z0-9._-]*$。任何不符的值都会在创建时报错并以 hook warning 形式浮出。shell 助手会防御性地做 URL 编码但服务端的正则才是最终真相。另注意 hook_capture.rs 的url_encode是 RFC 3986 unreserved 集合的白名单A-Z a-z 0-9 - _ . ~逐字节编码 UTF-8测试url_encode_is_an_unreserved_allow_list验证了C:\dev\myproject这类 Windows 路径能完整百分号编码、可被reqwest::Url::parse解析#188 回归。取值宽容度lenient parsingproject_strategy只接受repo-root或repo_root。未知值被忽略行为等同默认basename(cwd)策略default_global与inject_on_session_start接受真值true/1/yes/on可带引号也可裸写——节式键按宽松方式解析其他值视为缺席。max_chars是纯整数drop_subagent_captures接受真值字符串true/1/yes/on其他值或缺省表示照常存储该项目的 subagent 捕获。顶层非 subagent会话无论如何都照常存储。这是刻意的按项目设计没有服务器级全局开关所以一个嘈杂项目 opt-in 不会连累共享实例上其他项目的 subagent 捕获。解析器的 shell 版与 Rust 版刻意保持逐行镜像ai_memory_parse_toml_key只匹配key ...与ai_memory_parse_toml_flag额外接受裸值key true/key 6000剥离行尾# 注释Rust 侧对应 marker.rs 的parse_key_in/parse_flag_in/is_truthy。测试parse_toml_flag_accepts_bare_and_quoted_tokens与is_truthy_matches_shell_parity_tokens固定了这套契约含TRUE、yes等大小写与空白变体。session-start 简报是 project 级且不可信session-start 简报严格按 project 限定只取材于会话解析出的(workspace, project)预留的_globalscope刻意不并入。因此放在_global/_rules/的常设规则不会进入简报——它仍可通过memory_query确实并入_global按需触达真正要每轮都生效的常设规则应放在 Agent 自己的规则文件CLAUDE.md/AGENTS.md中详见 docs/usage.md 的 Rules vs facts 指引。简报按不受信任历史编译所以它刻意不是承载Agent 每轮必须遵守的指令的通道。Allowlist 模式把 marker 变成 opt-in默认情况下 marker 文件是可选的——没有 marker 的仓库依然会被捕获marker 只会收窄采集范围。但安装可以反转这个方向ai-memory install-hooks --apply --capture-mode allowlist在 allowlist 模式下.ai-memory.toml的存在本身就是 opt-in。没有 marker 的仓库完全不发出任何 lifecycle 事件——提示词、工具调用与会话边界一律在 hook 进程内、到达本地 spool 或网络之前被丢弃。无需额外键已有 marker 无论还配置了什么都自动把它的仓库纳入。这改变了忘记放文件的代价方向默认模式下忘记 采集了本不想采集的仓库allowlist 模式下忘记 仓库保持静默即使你本想要。请选择你更愿意向别人解释的那一种失败方向。模式是按安装存储而非按 Agent 存储之后一次裸install-hooks --apply包括升级刷新会保留它。从 install_hooks.rs 看persist_capture_mode把模式写入data_dir下的模式文件resolve_capture_mode遵循显式--capture-mode优先否则读持久化值否则默认 denylist测试bare_apply_preserves_an_existing_allowlist_optin验证了裸 apply 不覆盖已有 allowlist。允许名单由两条路径强制执行原生ai-memory hook命令见 hook.rs 的repository_admits_capture——先按find_marker的同一向上查找解析marker_presentallowlist 下marker_present false时直接短路连UserPromptSubmit/SessionStart/Stop这类非工具事件也不落 spool#446生成的 TypeScript 集成pi、omp、opencode、opencode2、openclaw每个插件把所选模式烘焙进代码POST 之前执行同样的 marker 存在性门如 install_hooks.rs 中的const markerPresent !!findMarker(cwd); if (CAPTURE_MODE allowlist !markerPresent) return { disposition: drop, payload };对应测试opencode_plugin_bakes_allowlist_admit_gate等逐一断言插件内CAPTURE_MODE常量。例外仅有的原始脚本回退路径AI_MEMORY_HOOK_PLATFORM覆盖、Docker 宿主包装、setup-agent片段会绕过这两个强制点直接 POST因此 allowlist 模式对它们不设门。Capture exclusions[capture] ignore_paths要阻止被识别的文件工具活动在匹配路径下进入捕获使用这个精确的按仓库形态[capture] ignore_paths [private/**, ~/personal-notes/**]把决策记录放在仓库内的仓库也适合这里——ADR 目录、Keep the Why 的context/树ignore_paths [docs/adr/**]或[context/**]。因为这些记录归仓库所有不排除的话Agent 对它的读取会被捕获并被 consolidation 编译进不跟随仓库的 wiki 页面记录一旦被取代副本立刻过期见 docs/usage.md 的 Repo-native decision records 一节。语义与限制最近的.ai-memory.toml是权威marker 的段不合并。缺失[capture]段或ignore_paths []视为未激活保持现状[capture]只接受ignore_paths未知键、非法类型/glob/根、不可读 marker、或超过 64 KiB 的 marker都会使整个捕获策略失效而不是部分应用。从 hook_capture.rs 的read_capture_config看读取被MAX_MARKER_BYTES上限约束[capture]段用严格的 TOML 解析器解析表中出现ignore_paths以外的键即返回错误测试capture_section_is_strict_and_marker_read_is_bounded覆盖了未知键、畸形 TOML、超限三种失效路径模式匹配整个词法规范化路径不是子串。只允许*、?、**相对模式以 marker 目录为根相对文件工具路径从事件的实际cwd解析~/展开到主目录。所有平台尽量用正斜杠。POSIX 匹配区分大小写Windows 驱动器/UNC 匹配按 ASCII 不区分大小写上限128 条模式、每条模式 1,024 字符、32 个直接候选、每个候选 4,096 字符、100 万次有界模式/候选比较。对 fixture 验证过的直接文件工具ai-memory只读取显式路径字段与多文件调用的文档化直接数组。任一候选匹配整个事件在 spool、队列、网络、传输日志或服务器存储之前就被本地丢弃。策略激活时被识别的搜索/列出工具被保守丢弃缺失或畸形的已识别文件候选、不支持的已识别 schema、或非法策略则降级为metadata-only——该形态只含受限的路由/工具/决策元数据绝不包含路径、模式、参数、输出、错误、标题或嵌套载荷。已知的非文件工具与未知工具保持原行为。在传输前排除很关键否则内容可能进入 observations/FTS、会话页面、handoffs、reviewer 请求、proposals 或日志。这是词法捕获边界不是完整 DLP不解析符号链接、junction、bind mount 或 Windows 8.3 别名不解析 shell 命令与自由格式 patch提示词、助手文本、通知与引号内容无法归因到路径。请显式添加每个相关可见别名不要指望它检测私有内容被提及的所有方式。支持的集成与刷新Capture policy v1 由以下路径强制执行原生ai-memory hook命令含原生 POSIX/Windows hook 命令生成的 OpenCode、OMP、Pi、OpenClaw 集成。本地安装器在支持处默认使用原生命令。旧版.sh/.ps1hook 与仅远程/Docker 脚本包不强制执行。升级后请重装 hooks 或刷新/重装生成的插件已有 hooks/插件保持旧行为。安装器的能力输出会描述所选集成。新客户端 旧服务器是安全的因为剥离与丢弃发生在客户端旧客户端 新服务器保持旧行为无法强制仅宿主侧的 marker 策略——服务器无法警告它从未见过的策略。该策略不新增 MCP 工具也不需要数据库迁移。本地检查一次决策--check-captureai-memory hook --event ... --agent ... --check-capture从 stdin 读取一条 JSON 载荷不执行任何 spool、队列、drain、网络或 handoff 工作。它只打印受限的决策元数据协议版本、策略状态、工具族、路径数、处置与提取状态绝不打印路径、模式或载荷内容printf %s\n {session_id:demo,cwd:/example/workspace,tool_name:Edit,tool_input:{path:docs/example.md}} \ | ai-memory hook --event post-tool-use --agent claude-code \ --server-url http://127.0.0.1:49374 --check-capture对应实现见 hook.rs--check-capture分支输出含capture_mode、marker_present、admits_capture、version、policy_state、tool_family、path_count、disposition、extraction_state的 JSON 后立即返回测试check_capture_has_no_spool_side_effects钉死了这套键集。正常捕获契约有多窄正常捕获契约刻意收窄受支持的 Claude Code、OpenCode、Pi、Antigravity 工具事件只保留规范工具族、Agent 提供并经其文档化 schema 证明的校验过的调用 ID以及一个 PostToolUse 结果类别。PreToolUse永不保留命令、参数、路径、输入体或任意工具名PostToolUse追加其现有的工具响应/错误摘录并把完整渲染体封顶在 2,000 UTF-8 安全字节Antigravity 的成功文件编辑事件回退到toolCall.args中有界的替换/写入内容字段其 hook 载荷没有输出字段失败编辑保留错误。该回退仅限 Antigravity并随任何被排除规则拒绝的事件一起丢弃不支持的工具信封不会获得 PreToolUse 体关联只靠匹配 Agent 提供的调用 IDUser-prompt 存储提示词文本除非以--no-capture-prompts安装 Claude Code hooksnotification 存储消息/文本post-compaction 存储摘要其他事件体当前为空除非显式支持Stop / assistant-message 捕获默认禁用且从不持久化只能通过安装指南描述的双重显式 opt-in 启用客户端install-hooks --capture-assistant加服务器capture_assistant摘录在两侧消毒并封顶。它不受 marker 文件门控——assistant 文本无法归因路径.ai-memory.toml收窄不了它元数据头是封闭的PostToolUse 响应/错误摘录仍是现有的有界内容捕获。捕获排除只在路径有被证明 schema 的地方求值所以它们不声称过滤其他那些体。四个经典示例多客户端~/projects/movvia/.ai-memory.toml → workspace movvia ~/projects/cliente-x/.ai-memory.toml → workspace cliente-x ~/personal/.ai-memory.toml → workspace personal结果~/projects/movvia/pe-api-core→ workspace movviaproject pe-api-core~/projects/cliente-x/api→ workspace cliente-xproject api~/personal/blog→ workspace personalproject blog带分组包的 Monorepo~/projects/movvia/.ai-memory.toml → workspace movvia ~/projects/movvia/pe-portais/.ai-memory.toml → workspace movvia project pe-portais结果~/projects/movvia/pe/pe-api-core→ workspace movviaproject pe-api-core~/projects/movvia/pe-portais/apps/web→ workspace movviaproject pe-portais更近 marker 胜出Git worktrees / repo-root 身份~/projects/.ai-memory.toml → workspace oss → project_strategy repo-root结果~/projects/ai-memory→ workspace ossproject ai-memory~/projects/ai-memory/crates/cli→ workspace ossproject ai-memory~/projects/ai-memory-feature-branch→ workspace ossproject ai-memory如果 marker 在主 checkout 内例如~/projects/ai-memory/.ai-memory.toml请把它复制/提交到每个树外 worktree或像上面这样在 worktree 父目录上方放一个共享 marker。没有project_strategy repo-root时同样的路径保持默认行为按当前目录 basename 解析。解析发生在宿主侧lifecycle hooks 与生成的 TypeScript 插件跟随 worktree 的 commondir 指针git rev-parse --git-common-dir原生 hooks 用等价的 Rust/libgit2 助手到达主仓库并把解析出的名字作为显式project发送。因此即使 worktree 目录位于主仓库树之外一些工具把 worktree 放在独立目录使 worktree 自身没有任何.ai-memory.toml祖先也有效即使服务器跑在看不到宿主 checkout 的容器里也有效。把 marker 放在从 worktree 向上的任何路径——通常一个~/.ai-memory.toml——即可选择该策略。对应实现hooks/_lib.sh 的ai_memory_repo_root_project先确认--is-inside-work-tree为 true再取--git-common-dir的父目录 basenameRust 侧是 marker.rs 的repo_root_project复用 ai-memory-consolidate 的discover_main_repo_root。hook_capture.rs 的marker_query_suffix_repo_root_collapses_out_of_tree_worktree测试真实地git initgit worktree add断言树外 worktree 的 cwd 解析出主仓库名acme-api。单一 workspace无每仓库覆盖~/.ai-memory.toml → workspace home$HOME下每个 cwd 都落在 workspacehomeproject basename(cwd)。适合只想完全退出default桶的场景。迁移已有项目已经在 workspacedefault下创建的项目留在原地。用 CLI 把它移到别的 workspaceai-memory move-project \ --from-workspace default --project foo \ --to-workspace movvia --confirm安装级默认无 marker 的 repo-rootproject_strategy repo-root通常住在 marker 里意味着要在或要在每个仓库放一个.ai-memory.toml。要在不写每个仓库 marker的情况下给整个安装启用同样的 repo-root 解析就在安装时把它烘焙进生成的 hooksai-memory install-hooks --apply --agent claude-code --project-strategy repo-root这样该安装的每个会话都从主 git 仓库根解析 project——Agent 运行mkdir sub cd sub并留在那里不会再将会话的其余部分分叉成一个名为sub的幻影项目。这是安装时配置写入 Agent 的 hook 命令以及生成的 OpenCode / OMP / Pi / OpenClaw 插件地位与旁边的AI_MEMORY_AUTH_TOKEN/AI_MEMORY_HOOK_URL相同不是用户可设的运行时覆盖后者在 #16 中被刻意否决。flag 接受basename新安装默认——什么都不烘焙或repo-root。之后的install-hooks --apply不带 flag 会保留已烘焙进 ai-memory hooks 的值显式传--project-strategy basename才移除它。优先级不变marker 显式的project_strategy或project仍然胜过安装默认。源码上hook_capture.rs 的marker_query_suffix_impl先读 marker 的 strategy仅在 marker 未钉时用default_strategy填充marker_query_suffix_marker_strategy_overrides_default与marker_query_suffix_marker_project_overrides_default_repo_root测试分别钉住这两种优先级。会话中途导航[routing] mid_session以上都决定会话从哪开始。长会话还会移动Agentcd进 scratch 目录或进兄弟 checkout 去 grep 参考。config.toml中的[routing] mid_session决定这些中途事件如何归因。它是服务器端运行时配置不是 marker 键[routing] mid_session follow-cwd # default # mid_session stickyfollow-cwd默认历史行为从每个中途事件自己的 cwd 重新解析。cd进兄弟 checkout 会把那些 observation 记在该 checkout 的 project 下于是一条会话的原始记录被拆到两个 project而其会话行与编译页留在第一个sticky把会话的 project 固定无论 Agent 游走到哪。这与系统其余部分已使用的模型一致sessions.project_id恰好持有一个值consolidation 按session_id读取并在会话的 project 里写一页。当一个 Agent 会话 一个 project时选它。两种模式下都有两条保证marker 仍然优先。.ai-memory.toml命名 project 是刻意的 rescope 而非漂移永不被否决。hook 会告诉服务器它发送的是哪种覆盖project_srcmarker与project_srcrepo-root这正是sticky能否决派生名、同时尊重声明名的机制。低于 v1.27 的客户端不发送 provenance其覆盖保持权威宽锚点永不粘滞。根在/或$HOME的会话不是有意义的锚点所以它永不捕获其下事件——否则一个误在$HOME开启的会话会把所有项目折进一个桶。会话创建事件在两种模式下都不受影响在普通非 git 文件夹打开会话仍以该文件夹命名 project。与此设置独立的是在project_strategy repo-root下cwd 位于任何 git 仓库和任何 marker 之外的中途事件Agent scratch 目录、/tmp、数据文件夹已经继承会话的 project而不是铸造名为scratchpad或data的幻影项目。宿主 hook 自行解析 repo-root所以缺失覆盖已经证明了 cwd 解析为空。谁读取 marker自 v1.20 起有两条入口Lifecycle hooks在每次事件上把 marker 的字段转发给服务器使会话捕获落入声明的 scope客户端 CLI 命令在调用服务器之前本地解析(workspace, project)——run、bootstrap、search、read-page、write-page、lint、curator、embed、pending-writes、forget-sweep、auto-improve、purge-project、rename-project、move-project以及move-session --from-project源侧等等。v1.20 之前只有 hooks 读它。因此一个声明workspace acme的 checkout 会让捕获落在acme而每条 CLI 命令解析进default——同一仓库被拆到两个 scopeai-memory run的托管 workstream 还落在拆分错误的一侧。这个缺陷正是 marker.rs 模块注释所述两入口共享一个读取器设计的原因。每个字段独立解析三级优先级显式 flag--workspace/--project最近 markerworkspace以及project——或只设project_strategy repo-root时主仓库根的 basename旧回退default以及 cwd 派生的 project 名。对应实现见 commands/mod.rs 的resolve_scopeAI_MEMORY_IGNORE_MARKER1跳过第 2 级两级都被 flag 钉住时连文件都不读直接短路。当第 2 级决定了某字段时命令会向 stderr 打印一行说明解析出的 scope、marker 决定了哪一半或两半以及是哪个 marker$ ai-memory search scope resolver ai-memory: scope acme/api (workspace project from /Users/dev/projects/acme/.ai-memory.toml)AI_MEMORY_IGNORE_MARKER1跳过第 2 级一次调用恢复 v1.20 前的解析而无需编辑或离开 marker 树。它只作用于客户端命令——lifecycle hooks 仍在每次事件转发 marker 字段所以设了它的一次调用解析出的 scope 与会话捕获不同。用于一次性读取而不是把仓库的记忆搬家。ai-memory serve被刻意排除服务器没有可向上查找的调用方 cwd它的--workspace/--project是到达的无可用 cwd 的 hook 事件的烘焙回退。marker 文件不做的事❌无 glob 模式。只按字面祖先关系向上查找。❌无祖先 marker 合并。最近者胜。❌无defaultworkspace 项目的自动迁移。❌无自动 repo-root 折叠。worktree 与子目录只在显式设置project_strategy repo-root时共享 project按 marker或按上文烘焙为安装级。❌无用户可设的 env / auth / hook-url 覆盖。这些请用现有环境变量AI_MEMORY_AUTH_TOKEN、AI_MEMORY_HOOK_URL。repo-root默认仍可不写 marker 地烘焙进安装——install-hooks --project-strategy repo-root——但那是安装时配置不是用户在 shell 里设的运行时覆盖。❌不越信任边界。查找在$HOME停止其外的 checkout 在该 checkout 根停止且需要 marker 在 checkout 内。$HOME外的非 git 目录需要 marker 在它精确的 cwd 里。Troubleshootingmarker 没生效按序排查文件名精确为.ai-memory.toml注意前导点文件在 cwd 的祖先里——不是兄弟不是后代没有更近的 marker 覆盖它。运行find ~/projects -maxdepth 5 -name .ai-memory.toml查看树内所有 markerworkspace / project 值匹配上面的正则小写字母数字、点、短横线、下划线若用project_strategy它精确是repo-root。hook 脚本按设计 fire-and-forget成功时不记录日志。想看实际发送了什么手工运行一条 hook 脚本printf {cwd:%s} $PWD \ | sh ~/.local/share/ai-memory/hooks/claude-code/post-tool-use.sh如果 marker 被读取curl 行用set -x或服务器日志可见会包含workspace...于 URL 中。对应的原生调试路径则是上文的--check-capture它直接输出marker_present与admits_capture无需任何网络或 spool 副作用。源码地图一文看全向上查找、解析与透明性判定crates/ai-memory-cli/src/marker.rsfind_marker/find_settings_marker/read_scope/parse_toml_key/parse_toml_flag/is_truthy原生 hook 的查询串构建与[capture]严格解析crates/ai-memory-cli/src/commands/hook_capture.rsmarker_query_suffix_impl/capture_policy/read_capture_config/url_encode/canonical_contextallowlist 门与--check-capture决策输出crates/ai-memory-cli/src/commands/hook.rsrepository_admits_capture/persisted_capture_modeCLI 三级 scope 解析与 stderr 提示crates/ai-memory-cli/src/commands/mod.rsresolve_scope/resolve_scope_for_path安装时--capture-mode/--project-strategy烘焙crates/ai-memory-cli/src/commands/install_hooks.rspersist_capture_mode/resolve_capture_mode/ TypeScript 插件CAPTURE_MODE常量与findMarker门POSIX/PowerShell 脚本侧的全部镜像逻辑hooks/_lib.shai_memory_find_marker/ai_memory_find_settings_marker/ai_memory_marker_qs/ai_memory_briefing_qs/ai_memory_repo_root_project。所有 hook 集成claude-code、codex、cursor、gemini-cli、kimi-code、kiro-cli、antigravity-cli、opencode、omp、pool 等共享 hooks/_lib.sh 同一份实现原生二进制与 shell 侧对 marker 的语义保持一致——这正是[capture]段用严格 TOML 解析、而 scope 键用逐行镜像解析的原因让两条路径对marker 意味着什么达成完全一致。【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考