context-mode 知识库清除指南深入解析 ctx_purge 的双范围安全删除机制【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode导读在 context-mode 项目中AI 编码 Agent 的会话上下文通过沙箱化工具输出、持久化会话记忆与 FTS5 索引被压缩进一个本地知识库中以此降低上下文窗口消耗。当索引内容过期、被污染或需要彻底重置时ctx_purge是唯一的删除通道。skills/ctx-purge/SKILL.md 定义了该能力的完整使用契约支持项目级与单会话级两种范围confirm: true强制确认且删除操作不可撤销。本文将以该技能文档为骨架结合 src/server.ts 中的 MCP 工具注册实现与 src/session/purge.ts 的底层清理逻辑完整讲解 ctx_purge 的触发方式、参数规则、删除范围与底层实现原理帮助你安全、精准地维护 context-mode 的本地知识库。ctx_purge 是什么ctx_purge是 context-mode 暴露的一个 MCP 工具mcp__context-mode__ctx_purge用于永久删除当前项目的索引化会话数据。它与只读的ctx_stats形成互补ctx_stats只负责展示统计信息不具备任何重置能力而ctx_purge是项目中唯一可以删除会话数据的机制没有任何其他删除入口。/clear与/compact等常规会话命令都不会影响任何 context-mode 数据。触发方式有两种在支持斜杠命令的客户端中直接使用/context-mode:ctx-purge该技能文件在 frontmatter 中声明了user-invocable: true或由 Agent 在符合使用场景时直接调用mcp__context-mode__ctx_purgeMCP 工具。从源码实现看该工具注册于 src/server.ts其输入 schema 是一个纯z.object——这一点是刻意为之。开发注释对应 issue #563明确指出MCP SDK 的normalizeObjectSchema()会读取.shape来生成 JSON Schema如果使用ZodEffects如.refine()包装则没有.shapeSDK 会静默输出properties: {}导致 Claude Code 的严格输入校验直接拒绝所有调用。因此跨字段的歧义检查被移入 handler 函数体而非 schema 层。两种删除范围project 与 sessionctx_purge 支持两种范围对应 issue #520 引入的分级清除能力范围参数形式删除内容保留内容Project项目级{ confirm: true, scope: project }FTS5 知识库ctx_index、ctx_fetch_and_index、ctx_batch_execute索引的全部内容、项目内所有会话的 Session DB 行、events markdown 文件、内存会话统计与持久化统计文件无全部清除Session会话级{ confirm: true, sessionId: id }仅匹配sessionId的会话事件行 对应的 FTS5 chunks同项目其他会话、项目统计、FTS5 store 文件Project 范围完整重置项目级清除是传统且默认的破坏性行为。当 scope 为project时以下内容将被全部删除FTS5 知识库通过ctx_index、ctx_fetch_and_index、ctx_batch_execute索引进来的所有内容存于chunks与chunks_trigram表会话事件 DB项目中所有会话的分析数据、元数据与恢复快照session_events、session_meta、session_resume表会话事件 markdown 文件hashsuffix-events.md内存会话统计 持久化统计文件sessionStats内存对象被重置统计文件也被删除。从 src/server.ts 的实现看统计重置仅在effectiveScope project时发生内存中的calls、bytesReturned、bytesIndexed、bytesSandboxed、cacheHits、cacheBytesSaved全部清零sessionStart重置为当前时间并删除持久化统计文件。Session 范围精准清除会话级清除只影响指定的一个会话其底层实现src/session/purge.ts分为两部分Session DB 行删除通过SessionDB.deleteSession(sessionId)事务性地删除该会话的session_events、session_resume、session_meta三张表的行见 src/session/db.ts。注意这里调用的是db.close()而非db.cleanup()——close()释放句柄但保留文件这正是会话级清除在文件系统层面不破坏 DB 文件的关键cleanup()会连主文件与 WAL/SHM 一起抹掉反而违背了单会话范围的设计。FTS5 chunks 删除针对chunks与chunks_trigram表执行DELETE FROM ... WHERE session_id ?。chunks表带有session_id UNINDEXED列schema 定义见 src/store.ts。需要说明的是当前公开的index()路径插入的session_id为 NULL因此这一 SQL 契约目前对存量数据是安全的空操作但为未来按会话打标的索引路径提前建立了正确性测试 tests/session/purge-session.test.ts 验证了删除目标会话 chunks 而保留兄弟会话 chunks 的行为。会话级清除后FTS5 store 文件仍然存在项目统计也原样保留——因为统计是项目级的每个项目一个统计文件汇总所有会话单会话清除不能动它们。调用方式与参数规则标准调用形式// 会话级推荐用于精准清除 { confirm: true, sessionId: 7c8a-1234-5678-9abc-def012345678 } // 项目级显式破坏性形式 { confirm: true, scope: project } // 兼容旧形式已弃用会输出 deprecation 警告 { confirm: true }Schema 规则ctx_purge 的输入参数src/server.tsconfirm必填布尔必须为true才能执行删除false会返回Purge cancelled. Pass confirm: true to proceed.。该字段经coerceBoolean预处理以兼容 OpenCode 原生插件桥可能以字符串true/false传递的情况对应 issue #627。sessionId可选UUID 字符串配合confirm: true只清除该会话的事件与 per-session FTS5 chunks不得与scope: project组合。scope可选枚举session/project显式范围选择器。session必须搭配sessionId省略时走兼容旧行为的裸{confirm: true}路径。三条强制校验规则confirm: true始终必需——这是不可撤销操作的第一道闸门sessionId与scope: project组合会被拒绝歧义sessionId本身就隐含了会话范围与项目范围组合语义矛盾。handler 会返回错误Ambiguous purge: sessionId implies scope:session, cannot combine with scope:project. Use scope:project WITHOUT sessionId for the legacy whole-project wipe.scope: session不携带sessionId会抛错——purgeSession在底层会直接throw new TypeErrorsrc/session/purge.ts。有效范围解析逻辑有效范围的解析遵循优先级src/server.ts显式scope优先否则给出了sessionId就推断为session只给 sessionId 不可能意味着清除整个项目两者都没有则推断为project兼容旧 handler 的破坏性默认行为并输出 stderr 弃用警告提示迁移到显式形式。使用场景与前置判断何时使用会话级清除临时验收场景、演练回放drill replays之后清理临时的 scratch 会话隔离某个被污染的会话而不影响主工作会话的统计会话中包含错误的决策记录、拒绝的方案、无效的计划等需要单独抹掉。何时使用项目级清除知识库中包含陈旧或错误内容正在污染搜索结果在同一会话中切换到无关项目需要彻底重置归属想要一个完全干净的初始状态。何时不要清除src/server.ts 中的工具描述给出了明确的反向指引用户只说 reset、clear、wipe 但没有指明范围时先询问范围再调用绝不默认执行用户想释放内存或提升性能时推荐先看ctx_stats而不是直接 purge——ctx_stats是只读的可以先用它预览分类计数项目级清除前尤其建议如此操作见工具描述中的 Use ctx_stats first to preview category counts before purging。底层实现purgeSession 的删除清单项目级清除的底层实现是 src/session/purge.ts 的purgeSession()函数。它被设计为深度模块deep module将所有会话相关的磁盘产物清理集中到一处。按删除顺序其覆盖的产物如下顺序产物文件形态用户可见标签1FTS5 知识库contentDir/hash.db含-wal/-shmsidecarknowledge base (FTS5)2旧版共享内容库~/.context-mode/content/hash.db静默清理无标签—3会话事件 DBsessionsDir/hashsuffix.db含 sidecarsession events DB4会话事件 markdownsessionsDir/hashsuffix-events.mdsession events markdown5cleanup 标记sessionsDir/hashsuffix.cleanup静默清理无标签—几个值得注意的实现细节SQLite 三元组删除每个.db文件可能伴随-wal预写日志与-shm共享内存索引sidecartryUnlinkSqliteTriple会无条件一并删除src/session/purge.ts缺失的 sidecar 不视为错误双哈希清扫dual-hash sweep在 macOS/Windows 这类大小写不敏感的文件系统上同时清扫 canonical小写化与 legacy原始大小写两种 project-dir 哈希变体src/session/purge.ts。这修复了历史 bug旧的 handler 只对.db文件做双哈希events.md与.cleanup单哈希导致大小写漂移的项目在部分升级后残留孤儿文件Linux 上两种哈希重合双清扫自动坍缩为单次遍历worktree 隔离保证模块触及的每个路径都由输入的projectDir确定性推导没有readdirSync glob 过滤循环。不同 worktree → 不同物理路径 → 不同哈希 → 不同文件名因此磁盘上不可能发生 worktree 折叠。测试 tests/session/purge-session.test.ts 明确断言清除 wt1 时 wt2 的 DB、WAL、SHM、events、cleanup 全部原封不动幂等与容错purgeSession对缺失文件从不抛错全新安装是安全的空操作deleted与wipedPaths均为空数组只在参数非法时抛TypeError如legacyContentDir未配contentHashWindows 文件锁handler 在委托purgeSession之前会先_store?.cleanup()关闭持久 FTS5 store 句柄并置空引用src/server.tsstore 会在下次getStore()调用时按需重建从而避免 Windows 上的文件占用问题。触发前的注意事项ctx_purge 是唯一的删除通道。没有其他机制能删除会话数据ctx_stats 是只读的只展示统计不提供重置能力/clear与/compact不影响任何 context-mode 数据没有撤销。如果之后还需要索引内容必须重新索引ctx_index/ctx_fetch_and_indexpurge 已清除过的范围是幂等的——对已清空范围再次调用不会有额外效果工具注解中idempotentHint: true且整个过程不发起网络请求。使用流程示例以技能文档 skills/ctx-purge/SKILL.md 定义的流程为例一个规范的清除流程是先决定范围并与用户确认只清除一个会话 → 向用户索取sessionId清除整个项目 → 确认scope: project这是破坏性、不可逆的默认行为。向用户警告 project 级清除的后果FTS5 知识库、所有会话的 Session DB、events markdown、内存与持久化统计都会被删除。按选定范围调用 MCP 工具会话级{ confirm: true, sessionId: id }隐含scope: session项目级{ confirm: true, scope: project }显式破坏性形式裸{ confirm: true }仍可用但会发出弃用警告优先使用显式形式。向用户报告结果响应会列出实际删除了哪些内容如 knowledge base (FTS5)、session events DB、session events markdown会话级清除还会确认其他会话与项目统计已保留响应格式如Purged session id: ... Other sessions and project-wide stats preserved.。与 ctx-stats 的配合作为删除前的预览手段ctx_stats是 ctx_purge 的最佳搭档skills/ctx-stats/SKILL.md 明确指出ctx_purge(confirm: true)用于永久删除知识库中所有索引内容并建议通过/context-mode:ctx-purge触发。工具描述中同样强调项目级清除前先调用ctx_stats预览各类别计数确认无误后再执行删除。这种先统计、后清除的节奏可以显著降低误删风险。总结ctx_purge 是 context-mode 知识库生命周期管理的收尾环节项目级清除负责完整重置FTS5 知识库 全部会话 统计会话级清除负责精准隔离单个污染会话。其安全设计体现在三个层面——confirm: true强制确认、范围歧义显式拒绝、不可撤销操作前的明确警告其工程实现则通过深度模块purgeSession、SQLite 三元组删除、双哈希清扫与 worktree 隔离保证了跨平台的一致性与数据安全。掌握它的正确用法你就能在索引污染、项目切换或完全重置等场景下对 context-mode 的本地数据做精准、安全的清理。【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 context-mode 知识库清除指南：深入解析 ctx_purge 的双范围安全删除机制
context-mode 知识库清除指南深入解析 ctx_purge 的双范围安全删除机制【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode导读在 context-mode 项目中AI 编码 Agent 的会话上下文通过沙箱化工具输出、持久化会话记忆与 FTS5 索引被压缩进一个本地知识库中以此降低上下文窗口消耗。当索引内容过期、被污染或需要彻底重置时ctx_purge是唯一的删除通道。skills/ctx-purge/SKILL.md 定义了该能力的完整使用契约支持项目级与单会话级两种范围confirm: true强制确认且删除操作不可撤销。本文将以该技能文档为骨架结合 src/server.ts 中的 MCP 工具注册实现与 src/session/purge.ts 的底层清理逻辑完整讲解 ctx_purge 的触发方式、参数规则、删除范围与底层实现原理帮助你安全、精准地维护 context-mode 的本地知识库。ctx_purge 是什么ctx_purge是 context-mode 暴露的一个 MCP 工具mcp__context-mode__ctx_purge用于永久删除当前项目的索引化会话数据。它与只读的ctx_stats形成互补ctx_stats只负责展示统计信息不具备任何重置能力而ctx_purge是项目中唯一可以删除会话数据的机制没有任何其他删除入口。/clear与/compact等常规会话命令都不会影响任何 context-mode 数据。触发方式有两种在支持斜杠命令的客户端中直接使用/context-mode:ctx-purge该技能文件在 frontmatter 中声明了user-invocable: true或由 Agent 在符合使用场景时直接调用mcp__context-mode__ctx_purgeMCP 工具。从源码实现看该工具注册于 src/server.ts其输入 schema 是一个纯z.object——这一点是刻意为之。开发注释对应 issue #563明确指出MCP SDK 的normalizeObjectSchema()会读取.shape来生成 JSON Schema如果使用ZodEffects如.refine()包装则没有.shapeSDK 会静默输出properties: {}导致 Claude Code 的严格输入校验直接拒绝所有调用。因此跨字段的歧义检查被移入 handler 函数体而非 schema 层。两种删除范围project 与 sessionctx_purge 支持两种范围对应 issue #520 引入的分级清除能力范围参数形式删除内容保留内容Project项目级{ confirm: true, scope: project }FTS5 知识库ctx_index、ctx_fetch_and_index、ctx_batch_execute索引的全部内容、项目内所有会话的 Session DB 行、events markdown 文件、内存会话统计与持久化统计文件无全部清除Session会话级{ confirm: true, sessionId: id }仅匹配sessionId的会话事件行 对应的 FTS5 chunks同项目其他会话、项目统计、FTS5 store 文件Project 范围完整重置项目级清除是传统且默认的破坏性行为。当 scope 为project时以下内容将被全部删除FTS5 知识库通过ctx_index、ctx_fetch_and_index、ctx_batch_execute索引进来的所有内容存于chunks与chunks_trigram表会话事件 DB项目中所有会话的分析数据、元数据与恢复快照session_events、session_meta、session_resume表会话事件 markdown 文件hashsuffix-events.md内存会话统计 持久化统计文件sessionStats内存对象被重置统计文件也被删除。从 src/server.ts 的实现看统计重置仅在effectiveScope project时发生内存中的calls、bytesReturned、bytesIndexed、bytesSandboxed、cacheHits、cacheBytesSaved全部清零sessionStart重置为当前时间并删除持久化统计文件。Session 范围精准清除会话级清除只影响指定的一个会话其底层实现src/session/purge.ts分为两部分Session DB 行删除通过SessionDB.deleteSession(sessionId)事务性地删除该会话的session_events、session_resume、session_meta三张表的行见 src/session/db.ts。注意这里调用的是db.close()而非db.cleanup()——close()释放句柄但保留文件这正是会话级清除在文件系统层面不破坏 DB 文件的关键cleanup()会连主文件与 WAL/SHM 一起抹掉反而违背了单会话范围的设计。FTS5 chunks 删除针对chunks与chunks_trigram表执行DELETE FROM ... WHERE session_id ?。chunks表带有session_id UNINDEXED列schema 定义见 src/store.ts。需要说明的是当前公开的index()路径插入的session_id为 NULL因此这一 SQL 契约目前对存量数据是安全的空操作但为未来按会话打标的索引路径提前建立了正确性测试 tests/session/purge-session.test.ts 验证了删除目标会话 chunks 而保留兄弟会话 chunks 的行为。会话级清除后FTS5 store 文件仍然存在项目统计也原样保留——因为统计是项目级的每个项目一个统计文件汇总所有会话单会话清除不能动它们。调用方式与参数规则标准调用形式// 会话级推荐用于精准清除 { confirm: true, sessionId: 7c8a-1234-5678-9abc-def012345678 } // 项目级显式破坏性形式 { confirm: true, scope: project } // 兼容旧形式已弃用会输出 deprecation 警告 { confirm: true }Schema 规则ctx_purge 的输入参数src/server.tsconfirm必填布尔必须为true才能执行删除false会返回Purge cancelled. Pass confirm: true to proceed.。该字段经coerceBoolean预处理以兼容 OpenCode 原生插件桥可能以字符串true/false传递的情况对应 issue #627。sessionId可选UUID 字符串配合confirm: true只清除该会话的事件与 per-session FTS5 chunks不得与scope: project组合。scope可选枚举session/project显式范围选择器。session必须搭配sessionId省略时走兼容旧行为的裸{confirm: true}路径。三条强制校验规则confirm: true始终必需——这是不可撤销操作的第一道闸门sessionId与scope: project组合会被拒绝歧义sessionId本身就隐含了会话范围与项目范围组合语义矛盾。handler 会返回错误Ambiguous purge: sessionId implies scope:session, cannot combine with scope:project. Use scope:project WITHOUT sessionId for the legacy whole-project wipe.scope: session不携带sessionId会抛错——purgeSession在底层会直接throw new TypeErrorsrc/session/purge.ts。有效范围解析逻辑有效范围的解析遵循优先级src/server.ts显式scope优先否则给出了sessionId就推断为session只给 sessionId 不可能意味着清除整个项目两者都没有则推断为project兼容旧 handler 的破坏性默认行为并输出 stderr 弃用警告提示迁移到显式形式。使用场景与前置判断何时使用会话级清除临时验收场景、演练回放drill replays之后清理临时的 scratch 会话隔离某个被污染的会话而不影响主工作会话的统计会话中包含错误的决策记录、拒绝的方案、无效的计划等需要单独抹掉。何时使用项目级清除知识库中包含陈旧或错误内容正在污染搜索结果在同一会话中切换到无关项目需要彻底重置归属想要一个完全干净的初始状态。何时不要清除src/server.ts 中的工具描述给出了明确的反向指引用户只说 reset、clear、wipe 但没有指明范围时先询问范围再调用绝不默认执行用户想释放内存或提升性能时推荐先看ctx_stats而不是直接 purge——ctx_stats是只读的可以先用它预览分类计数项目级清除前尤其建议如此操作见工具描述中的 Use ctx_stats first to preview category counts before purging。底层实现purgeSession 的删除清单项目级清除的底层实现是 src/session/purge.ts 的purgeSession()函数。它被设计为深度模块deep module将所有会话相关的磁盘产物清理集中到一处。按删除顺序其覆盖的产物如下顺序产物文件形态用户可见标签1FTS5 知识库contentDir/hash.db含-wal/-shmsidecarknowledge base (FTS5)2旧版共享内容库~/.context-mode/content/hash.db静默清理无标签—3会话事件 DBsessionsDir/hashsuffix.db含 sidecarsession events DB4会话事件 markdownsessionsDir/hashsuffix-events.mdsession events markdown5cleanup 标记sessionsDir/hashsuffix.cleanup静默清理无标签—几个值得注意的实现细节SQLite 三元组删除每个.db文件可能伴随-wal预写日志与-shm共享内存索引sidecartryUnlinkSqliteTriple会无条件一并删除src/session/purge.ts缺失的 sidecar 不视为错误双哈希清扫dual-hash sweep在 macOS/Windows 这类大小写不敏感的文件系统上同时清扫 canonical小写化与 legacy原始大小写两种 project-dir 哈希变体src/session/purge.ts。这修复了历史 bug旧的 handler 只对.db文件做双哈希events.md与.cleanup单哈希导致大小写漂移的项目在部分升级后残留孤儿文件Linux 上两种哈希重合双清扫自动坍缩为单次遍历worktree 隔离保证模块触及的每个路径都由输入的projectDir确定性推导没有readdirSync glob 过滤循环。不同 worktree → 不同物理路径 → 不同哈希 → 不同文件名因此磁盘上不可能发生 worktree 折叠。测试 tests/session/purge-session.test.ts 明确断言清除 wt1 时 wt2 的 DB、WAL、SHM、events、cleanup 全部原封不动幂等与容错purgeSession对缺失文件从不抛错全新安装是安全的空操作deleted与wipedPaths均为空数组只在参数非法时抛TypeError如legacyContentDir未配contentHashWindows 文件锁handler 在委托purgeSession之前会先_store?.cleanup()关闭持久 FTS5 store 句柄并置空引用src/server.tsstore 会在下次getStore()调用时按需重建从而避免 Windows 上的文件占用问题。触发前的注意事项ctx_purge 是唯一的删除通道。没有其他机制能删除会话数据ctx_stats 是只读的只展示统计不提供重置能力/clear与/compact不影响任何 context-mode 数据没有撤销。如果之后还需要索引内容必须重新索引ctx_index/ctx_fetch_and_indexpurge 已清除过的范围是幂等的——对已清空范围再次调用不会有额外效果工具注解中idempotentHint: true且整个过程不发起网络请求。使用流程示例以技能文档 skills/ctx-purge/SKILL.md 定义的流程为例一个规范的清除流程是先决定范围并与用户确认只清除一个会话 → 向用户索取sessionId清除整个项目 → 确认scope: project这是破坏性、不可逆的默认行为。向用户警告 project 级清除的后果FTS5 知识库、所有会话的 Session DB、events markdown、内存与持久化统计都会被删除。按选定范围调用 MCP 工具会话级{ confirm: true, sessionId: id }隐含scope: session项目级{ confirm: true, scope: project }显式破坏性形式裸{ confirm: true }仍可用但会发出弃用警告优先使用显式形式。向用户报告结果响应会列出实际删除了哪些内容如 knowledge base (FTS5)、session events DB、session events markdown会话级清除还会确认其他会话与项目统计已保留响应格式如Purged session id: ... Other sessions and project-wide stats preserved.。与 ctx-stats 的配合作为删除前的预览手段ctx_stats是 ctx_purge 的最佳搭档skills/ctx-stats/SKILL.md 明确指出ctx_purge(confirm: true)用于永久删除知识库中所有索引内容并建议通过/context-mode:ctx-purge触发。工具描述中同样强调项目级清除前先调用ctx_stats预览各类别计数确认无误后再执行删除。这种先统计、后清除的节奏可以显著降低误删风险。总结ctx_purge 是 context-mode 知识库生命周期管理的收尾环节项目级清除负责完整重置FTS5 知识库 全部会话 统计会话级清除负责精准隔离单个污染会话。其安全设计体现在三个层面——confirm: true强制确认、范围歧义显式拒绝、不可撤销操作前的明确警告其工程实现则通过深度模块purgeSession、SQLite 三元组删除、双哈希清扫与 worktree 隔离保证了跨平台的一致性与数据安全。掌握它的正确用法你就能在索引污染、项目切换或完全重置等场景下对 context-mode 的本地数据做精准、安全的清理。【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考