ai-memory 准入 Webhook 指南如何在页面持久化前挂入自己的 HTTP 钩子【免费下载链接】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-memoryai-memory是一个为 AI 编程 AgentClaude Code、Codex 等 CLI提供长期记忆系统的开源引擎它把会话观察编译成 Markdown 知识页存入 SQLite 索引并支持跨 Agent 交接。而准入 Webhookadmission webhook正是它暴露给运维者的持久化大门——在每页知识落盘之前引擎会同步调用你配置的 HTTP 钩子允许你改写页面内容、拒绝违规写入或在删除/清除事件发生时做镜像同步。这套机制的设计哲学非常克制引擎对修改保持封闭。任何新行为富化、审计、镜像、合规校验都不写进引擎而是作为一个独立 HTTP 服务挂在链上——这就是典型的开闭原则OCP落地。准入 Webhook 是什么不是什么一句话定位它是引擎写入路径上唯一的持久化前拦截点。✅ 你能做的❌ 做不到的给页面追加规范 frontmatter如contributors字段直接对话引擎的 writer 或 store——链每次只看到一页且原地改写把写入镜像到外部系统git 仓库、搜索索引、审计日志让引擎自动发现钩子——钩子由运维在配置中显式声明拒绝不符合策略的写入如validate-no-secrets保密钥校验器跨页编排——链是逐页串行的如果某个需求不属于改写页面或观察写入那它应该走别的扩展点/hook入口、/admin/*管理接口或带外定时任务。触发时机链在写入流程的哪一步执行阻断式链blocking chain在Wiki::write_page内部触发位置非常精确Markdown 已解析并完成初始净化sanitise然后按配置顺序串行调用每个 Webhook——后一个钩子看到的是前一个钩子改完之后的页面Webhook 返回的修改会再次被净化最后原子写入磁盘上的 Markdown 文件与 SQLite 索引行在同一步原子操作中同时更新。这种先净化 → 链式改写 → 再净化 → 原子落盘的顺序保证了无论外部钩子返回什么都不会破坏 wiki 的数据完整性。哪些事件会触发 Webhook引擎目前定义了一个可扩展的事件枚举AdmissionOpWebhook 通过配置中的events字段按需订阅事件含义载荷特点write_page直接写入MCP 工具、CLI、管理接口、钩子合成等带页面路径 完整 frontmatter/bodyconsolidateLLM 整合写入会话结束、PreCompact、手动整合可能在 LLM 调用前以空 body 触发一次预检真正写入时再触发一次delete单页删除只有路径、无 body在文件被删前触发purge_project/purge_session/purge_workspace项目/会话/工作区清除无页面路径携带ctx中的作用域move_project/move_session跨工作区迁移携带源与目标工作区/项目名handoff_begin/handoff_accept/handoff_cancel跨 Agent 交接的生命周期交接记录存于 SQLite 独立表无页面路径几个值得记住的细节拒绝reject语义删除/清除/迁移类事件本身没有可改写的 body但一个reject策略的钩子仍然能中止整个操作——因为准入检查发生在 SQL 销毁之前拒绝后源数据完好无损。交接事件是决策器模式能拒绝的钩子在操作前被同步等待其余观察者只在操作成功发生之后才收到通知所以不会有人被告知一个实际没发生的交接。部分失败标记若 SQL 清除已提交但文件系统清理随后失败最终通知会带上partial_failure: true提醒你的 git 镜像别急着删自己那份副本。线协议引擎发什么、你回什么引擎向每个钩子发送一个POST请求请求头携带X-Memory-Op事件名请求体形如{ page: { path: gotchas/example.md, frontmatter: { title: ... }, body: ... }, ctx: { workspace: default, project: ai-memory-ops, actor: { agent: claude-code, user: djalmajr }, op: write_page } }其中workspace/project是引擎已解析好的人类可读名称镜像服务无需自己再查 UUID。你的服务只需三选一回复响应引擎行为200 OK{page: {frontmatter: ..., body: ...}}用返回值替换对应字段缺省字段保持不变再继续链或落盘204 No Content纯观察者/副作用——不改页、不解析链继续4xx/5xx按该钩子的失败策略处理见下节响应体上限为1 MiB超出的部分直接按无操作丢弃并打warn日志——钩子没有正当理由返回比页面信封更大的东西。失败策略ignore 还是 reject每个钩子独立选择一条策略在引擎连不上它或它返回非 2xx 时生效ignore默认推荐——记一条warn日志用未修改的页面继续写。页面写入永远不会被一个有 bug 或宕机的钩子卡住。reject——中止写入并把错误抛回调用方。只应给安全关键钩子用例如密钥校验器因为它是持久化的硬前置条件。选择口诀除了必须拦安全关口的钩子其他一律ignore让备份、镜像、统计类服务永远不影响写入可用性。三步配置上手第 1 步写一个最小的钩子服务任何语言都行实现上节的线协议。第 2 步在config.toml里声明钩子配置模式定义见 crates/ai-memory-cli/src/config.rs[[admission_webhooks]] name contributors # 稳定标识用于日志与跳过清单 url http://contributors.memory.svc:8080/enrich timeout_ms 2000 # 单请求超时 failure_policy ignore # ignore | reject events [write_page, consolidate] # 订阅的事件 blocking true # 同步执行可改写/拒绝第 3 步重启服务链即生效。服务端接线逻辑在 crates/ai-memory-cli/src/commands/serve.rs——空配置意味着不挂链每次写入零额外开销不建 HTTP 客户端、不走任何分支。两个补充开关blocking false钩子在持久化操作完成之后以发射后不管方式派发引擎不等它、忽略其响应因此它不能改写也不能拒绝只观察/镜像最终状态。给 git-mirror 这类慢速后备系统用宕机也不会给写入加延迟。环境变量覆盖AI_MEMORY_ADMISSION_WEBHOOKS_JSON可用一段 JSON 直接覆盖整个钩子列表适合 K8s 等环境注入。防循环避免钩子写引擎 → 引擎再调钩子如果钩子收到事件后要回写引擎比如经/admin/write-page写入派生页面必须在这次重入请求头里带上X-Memory-Skip-Admission-Chain: hook-name[,hook-name...]引擎会对该次写入短路指定名称的钩子仅限受信任的重入否则就是无限递归。普通 DB 用户无法用这个头绕过reject策略钩子。内置安全护栏速查所有常量从ai-memory-wikicrate 根导出核心实现在 crates/ai-memory-wiki/src/admission.rs常量值管住什么MAX_ADMISSION_WEBHOOKS16链长度。超出直接构造报错——防止 helm 模板循环之类误配把几百个钩子串行压进写路径L251MAX_WEBHOOK_TIMEOUT_MS30000单钩子超时上限配置更大也会被钳制MAX_RESPONSE_BYTES1 MiB响应体大小超出按无操作处理MAX_ASYNC_ADMISSION_IN_FLIGHT256进程内发射后不管请求在途上限超出丢弃并记日志绝不阻塞调用方链是串行的所以最坏写入延迟 ≈ 所有blocking钩子的timeout_ms之和非阻塞钩子不贡献任何延迟。两个典型用例富化mutatingcontributors钩子收到页面后把当前actoragent user追加进frontmatter.contributors返回 200 与新的 frontmatter——引擎落盘时直接采用。镜像side-effectgit-mirror钩子把页面物化到外部 git 仓库的本地 clone批量提交、异步推送立即返回204——引擎不等 push 完成只有本地入队在timeout_ms内进行。两者可以串在同一条链上先contributors富化后git-mirror镜像到的正是富化后的页面。延伸阅读相关文件索引官方机制文档docs/admission-webhooks.md——含完整线协议、生命周期与限额说明核心实现AdmissionChain::run热循环、WebhookConfig、失败策略crates/ai-memory-wiki/src/admission.rs写入路径接线write_page中解析作用域名 → 调链 → 原子写crates/ai-memory-wiki/src/wiki.rs配置模式crates/ai-memory-cli/src/config.rs端到端 HTTP 契约测试真实 axum loopback 服务器验证改写、204、ignore/reject、链序、跳过清单crates/ai-memory-wiki/tests/suite/admission.rs小结ai-memory 的准入 Webhook 用一个极小的 HTTP 契约把页面落盘前的一票否决权完整地交到了你的服务手里——引擎保持封闭扩展无限生长。先配一个ignore策略的观察者跑通镜像再按需给安全关口加reject就是最稳妥的落地路径。【免费下载链接】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），仅供参考 ai-memory 准入 Webhook 指南：如何在页面持久化前挂入自己的 HTTP 钩子
ai-memory 准入 Webhook 指南如何在页面持久化前挂入自己的 HTTP 钩子【免费下载链接】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-memoryai-memory是一个为 AI 编程 AgentClaude Code、Codex 等 CLI提供长期记忆系统的开源引擎它把会话观察编译成 Markdown 知识页存入 SQLite 索引并支持跨 Agent 交接。而准入 Webhookadmission webhook正是它暴露给运维者的持久化大门——在每页知识落盘之前引擎会同步调用你配置的 HTTP 钩子允许你改写页面内容、拒绝违规写入或在删除/清除事件发生时做镜像同步。这套机制的设计哲学非常克制引擎对修改保持封闭。任何新行为富化、审计、镜像、合规校验都不写进引擎而是作为一个独立 HTTP 服务挂在链上——这就是典型的开闭原则OCP落地。准入 Webhook 是什么不是什么一句话定位它是引擎写入路径上唯一的持久化前拦截点。✅ 你能做的❌ 做不到的给页面追加规范 frontmatter如contributors字段直接对话引擎的 writer 或 store——链每次只看到一页且原地改写把写入镜像到外部系统git 仓库、搜索索引、审计日志让引擎自动发现钩子——钩子由运维在配置中显式声明拒绝不符合策略的写入如validate-no-secrets保密钥校验器跨页编排——链是逐页串行的如果某个需求不属于改写页面或观察写入那它应该走别的扩展点/hook入口、/admin/*管理接口或带外定时任务。触发时机链在写入流程的哪一步执行阻断式链blocking chain在Wiki::write_page内部触发位置非常精确Markdown 已解析并完成初始净化sanitise然后按配置顺序串行调用每个 Webhook——后一个钩子看到的是前一个钩子改完之后的页面Webhook 返回的修改会再次被净化最后原子写入磁盘上的 Markdown 文件与 SQLite 索引行在同一步原子操作中同时更新。这种先净化 → 链式改写 → 再净化 → 原子落盘的顺序保证了无论外部钩子返回什么都不会破坏 wiki 的数据完整性。哪些事件会触发 Webhook引擎目前定义了一个可扩展的事件枚举AdmissionOpWebhook 通过配置中的events字段按需订阅事件含义载荷特点write_page直接写入MCP 工具、CLI、管理接口、钩子合成等带页面路径 完整 frontmatter/bodyconsolidateLLM 整合写入会话结束、PreCompact、手动整合可能在 LLM 调用前以空 body 触发一次预检真正写入时再触发一次delete单页删除只有路径、无 body在文件被删前触发purge_project/purge_session/purge_workspace项目/会话/工作区清除无页面路径携带ctx中的作用域move_project/move_session跨工作区迁移携带源与目标工作区/项目名handoff_begin/handoff_accept/handoff_cancel跨 Agent 交接的生命周期交接记录存于 SQLite 独立表无页面路径几个值得记住的细节拒绝reject语义删除/清除/迁移类事件本身没有可改写的 body但一个reject策略的钩子仍然能中止整个操作——因为准入检查发生在 SQL 销毁之前拒绝后源数据完好无损。交接事件是决策器模式能拒绝的钩子在操作前被同步等待其余观察者只在操作成功发生之后才收到通知所以不会有人被告知一个实际没发生的交接。部分失败标记若 SQL 清除已提交但文件系统清理随后失败最终通知会带上partial_failure: true提醒你的 git 镜像别急着删自己那份副本。线协议引擎发什么、你回什么引擎向每个钩子发送一个POST请求请求头携带X-Memory-Op事件名请求体形如{ page: { path: gotchas/example.md, frontmatter: { title: ... }, body: ... }, ctx: { workspace: default, project: ai-memory-ops, actor: { agent: claude-code, user: djalmajr }, op: write_page } }其中workspace/project是引擎已解析好的人类可读名称镜像服务无需自己再查 UUID。你的服务只需三选一回复响应引擎行为200 OK{page: {frontmatter: ..., body: ...}}用返回值替换对应字段缺省字段保持不变再继续链或落盘204 No Content纯观察者/副作用——不改页、不解析链继续4xx/5xx按该钩子的失败策略处理见下节响应体上限为1 MiB超出的部分直接按无操作丢弃并打warn日志——钩子没有正当理由返回比页面信封更大的东西。失败策略ignore 还是 reject每个钩子独立选择一条策略在引擎连不上它或它返回非 2xx 时生效ignore默认推荐——记一条warn日志用未修改的页面继续写。页面写入永远不会被一个有 bug 或宕机的钩子卡住。reject——中止写入并把错误抛回调用方。只应给安全关键钩子用例如密钥校验器因为它是持久化的硬前置条件。选择口诀除了必须拦安全关口的钩子其他一律ignore让备份、镜像、统计类服务永远不影响写入可用性。三步配置上手第 1 步写一个最小的钩子服务任何语言都行实现上节的线协议。第 2 步在config.toml里声明钩子配置模式定义见 crates/ai-memory-cli/src/config.rs[[admission_webhooks]] name contributors # 稳定标识用于日志与跳过清单 url http://contributors.memory.svc:8080/enrich timeout_ms 2000 # 单请求超时 failure_policy ignore # ignore | reject events [write_page, consolidate] # 订阅的事件 blocking true # 同步执行可改写/拒绝第 3 步重启服务链即生效。服务端接线逻辑在 crates/ai-memory-cli/src/commands/serve.rs——空配置意味着不挂链每次写入零额外开销不建 HTTP 客户端、不走任何分支。两个补充开关blocking false钩子在持久化操作完成之后以发射后不管方式派发引擎不等它、忽略其响应因此它不能改写也不能拒绝只观察/镜像最终状态。给 git-mirror 这类慢速后备系统用宕机也不会给写入加延迟。环境变量覆盖AI_MEMORY_ADMISSION_WEBHOOKS_JSON可用一段 JSON 直接覆盖整个钩子列表适合 K8s 等环境注入。防循环避免钩子写引擎 → 引擎再调钩子如果钩子收到事件后要回写引擎比如经/admin/write-page写入派生页面必须在这次重入请求头里带上X-Memory-Skip-Admission-Chain: hook-name[,hook-name...]引擎会对该次写入短路指定名称的钩子仅限受信任的重入否则就是无限递归。普通 DB 用户无法用这个头绕过reject策略钩子。内置安全护栏速查所有常量从ai-memory-wikicrate 根导出核心实现在 crates/ai-memory-wiki/src/admission.rs常量值管住什么MAX_ADMISSION_WEBHOOKS16链长度。超出直接构造报错——防止 helm 模板循环之类误配把几百个钩子串行压进写路径L251MAX_WEBHOOK_TIMEOUT_MS30000单钩子超时上限配置更大也会被钳制MAX_RESPONSE_BYTES1 MiB响应体大小超出按无操作处理MAX_ASYNC_ADMISSION_IN_FLIGHT256进程内发射后不管请求在途上限超出丢弃并记日志绝不阻塞调用方链是串行的所以最坏写入延迟 ≈ 所有blocking钩子的timeout_ms之和非阻塞钩子不贡献任何延迟。两个典型用例富化mutatingcontributors钩子收到页面后把当前actoragent user追加进frontmatter.contributors返回 200 与新的 frontmatter——引擎落盘时直接采用。镜像side-effectgit-mirror钩子把页面物化到外部 git 仓库的本地 clone批量提交、异步推送立即返回204——引擎不等 push 完成只有本地入队在timeout_ms内进行。两者可以串在同一条链上先contributors富化后git-mirror镜像到的正是富化后的页面。延伸阅读相关文件索引官方机制文档docs/admission-webhooks.md——含完整线协议、生命周期与限额说明核心实现AdmissionChain::run热循环、WebhookConfig、失败策略crates/ai-memory-wiki/src/admission.rs写入路径接线write_page中解析作用域名 → 调链 → 原子写crates/ai-memory-wiki/src/wiki.rs配置模式crates/ai-memory-cli/src/config.rs端到端 HTTP 契约测试真实 axum loopback 服务器验证改写、204、ignore/reject、链序、跳过清单crates/ai-memory-wiki/tests/suite/admission.rs小结ai-memory 的准入 Webhook 用一个极小的 HTTP 契约把页面落盘前的一票否决权完整地交到了你的服务手里——引擎保持封闭扩展无限生长。先配一个ignore策略的观察者跑通镜像再按需给安全关口加reject就是最稳妥的落地路径。【免费下载链接】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），仅供参考