init-simple-memorix

init-simple-memorix

Overview

本技能用于精简 Memorix hooks 和检查 Memorix MCP 配置。核心原则是先判断问题属于 hooks 噪音还是 MCP 连接/工具暴露问题，再只处理对应层面。

• hooks 目标：移除工具调用、文件编辑、命令执行等高频触发器，只保留会话生命周期事件。
• MCP 目标：确认 memorix server entry 使用 serve --mode full，并避免 WorkBuddy 注入的 Node 参数破坏 stdio MCP 启动。
• 分发视角：脚本、模板、源码索引都以技能安装目录为根，不引用仓库源码路径或开发期产物。

When to Use

• 用户明确提到 init-simple-memorix、初始化 Memorix、精简 Memorix hooks、移除记忆噪音。
• 用户完成 Memorix setup 或升级后，怀疑默认 hooks 又引入高频噪音。
• 用户需要项目级或全局级 hooks 模板参考。
• 用户反馈 Memorix MCP 工具缺失、不是 full 模式、MCP server 启动失败。
• 用户在 WorkBuddy 中看到 memorix MCP 反复断开、审批后仍不可用、NODE_OPTIONS 或 Node ABI 相关错误。

When Not to Use

• 用户只是询问如何使用已有 Memorix 工具读写记忆，且没有 hooks/MCP 配置问题。
• 用户要求记录事故、沉淀经验或同步记忆时，优先使用 record-bug-fix-memory。
• 用户要求发版、写 changeset、提交代码或生成报告时，本技能只提供背景信息，不接管这些流程。
• 现场症状是普通业务代码 bug、测试失败或构建失败，且没有 Memorix hooks/MCP 线索。

Decision Path

1. 先定性问题。
   • 记忆太多、太杂、每次工具调用都记录：处理 hooks。
   • MCP 工具缺失、full 模式不可用、server 断开：检查 MCP 配置。
   • WorkBuddy 审批、Node 参数、better-sqlite3 报错：进入 WorkBuddy Notes。
2. 再定作用域。
   • 只影响当前项目：使用 templates/ 下的项目级模板。
   • 影响用户全局 Agent：参考 templates-global/，但不要在未获明确授权时写入用户主目录配置。
3. 最后选执行方式。
   • 只需要确认脚本行为：运行帮助或 dry-run。
   • 需要真实写入：必须由用户明确要求，并在执行前说明会修改哪些用户配置文件。
4. hooks 噪音场景优先处理 hooks，不要把 WorkBuddy MCP 信任链路排查放到主路径上。

Reference Routing

本技能正文只保留判断入口和高频规则。需要细节时按场景读取对应参考文件，不要一次性加载全部 references。

参考文件	何时读取
references/hooks-reference.md	用户要求精简 hooks、检查噪音、合并项目级/全局级 hooks，或需要旧版完整 hooks 表格与模板格式细节。
references/workbuddy-mcp-notes.md	用户反馈 WorkBuddy 中 memorix MCP 连接失败、untrusted/disabled、Connection closed、Node/ABI、NODE_OPTIONS 或审批 hash 问题。
references/memorix-setup-notes.md	用户刚执行 memorix setup、全局安装、升级 Memorix 插件，或需要理解 setup 后哪些 hooks/MCP 配置可能被覆盖。

如果用户只抱怨“记忆太吵”或“每次工具调用都记录”，优先读取 references/hooks-reference.md。只有同时出现 MCP 连接、工具缺失、审批或 Node 错误时，才读取 references/workbuddy-mcp-notes.md。

Safety Rules

• 不要主动运行 Memorix setup 或 cleanup；如果需要提命令，只提供 --help 或 --dry-run / -DryRun / -d 形式。
• 不要在未获明确授权时修改用户主目录配置。
• 不要删除用户的非 Memorix 配置字段，例如 permissions、自定义 hooks、其他 MCP server entries。
• 不要承诺不存在的模板：项目级没有 Codex hooks 模板；Codex 只在全局模板中出现。
• 不要写死 full 模式的工具数量；只要求 full 模式暴露完整工具面。
• 不要在正文命令或资源索引中引用开发期路径、测试目录、CI 配置、报告目录或依赖安装目录。
• 合并配置时保留未知字段，只精确调整 Memorix 相关 entry。

Hooks Quick Reference

作用域模型：

场景	行为
项目级	用户没有要求全局配置时，只处理当前项目根目录下的 IDE hooks 配置。
全局级	用户明确要求全局、--global、setup 后全局精简时，才处理用户主目录下的全局 hooks 配置。
双作用域	用户同时需要全局和项目级时，先处理全局，再处理当前项目；不要把两类路径混在一次写入里。

支持的 hooks 配置目标：

工具	项目级目标	全局级目标
Claude Code	.claude/settings.local.json	~/.claude/plugins/cache/memorix-local/memorix/{version}/hooks/hooks.json
Codex	不提供项目级模板	~/.codex/plugins/memorix/hooks/hooks.json
Cursor	.cursor/hooks.json	~/.cursor/hooks.json
Windsurf	.windsurf/hooks.json	暂不支持
Gemini CLI	.gemini/settings.json	暂不支持
Kiro	.kiro/hooks/memorix-file-save.kiro.hook	暂不支持
WorkBuddy	.workbuddy/hooks/hooks.json（实验性，待运行时验证）	暂不支持
ZCode	.zcode/config.json 或 zcode.json	暂不支持
Antigravity	.agents/hooks.json	~/.gemini/config/plugins/memorix/hooks.json

项目级模板：

工具	模板	目标形态
Claude Code	templates/claude-code.settings.local.json	.claude/settings.local.json
Cursor	templates/cursor.hooks.json	.cursor/hooks.json
Windsurf	templates/windsurf.hooks.json	.windsurf/hooks.json
Gemini CLI	templates/gemini-cli.settings.json	.gemini/settings.json
Kiro	templates/kiro.memorix-file-save.kiro.hook	.kiro/hooks/memorix-file-save.kiro.hook
WorkBuddy	templates/workbuddy.hooks.json（实验性，待运行时验证）	.workbuddy/hooks/hooks.json
ZCode	templates/zcode.config.json	.zcode/config.json 或 zcode.json
Antigravity	templates/antigravity.hooks.json	.agents/hooks.json

全局模板：

工具	模板	说明
Claude Code	templates-global/claude.hooks.json	版本目录需动态发现
Codex	templates-global/codex.hooks.json	仅全局模板
Cursor	templates-global/cursor.hooks.json	全局 hooks
Antigravity	templates-global/antigravity.hooks.json	全局 hooks

应移除或禁用的高频事件：

工具	高频噪音事件
Claude Code	PreToolUse, PostToolUse
Codex	PostToolUse
Cursor	afterFileEdit, afterMCPExecution, beforeShellExecution
Windsurf	post_write_code, post_run_command, post_mcp_tool_use
Gemini CLI	AfterTool
Kiro	文件保存 hook 保持 enabled: false
WorkBuddy	PreToolUse, PostToolUse
ZCode	PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure
Antigravity	PreToolUse, PostToolUse

应保留的生命周期事件：

工具	生命周期事件
Claude Code	SessionStart, UserPromptSubmit, PreCompact, Stop
Codex	SessionStart, UserPromptSubmit, Stop
Cursor	sessionStart, beforeSubmitPrompt, preCompact, stop
Windsurf	pre_user_prompt, post_cascade_response
Gemini CLI	SessionStart, PreCompress, AfterAgent
WorkBuddy	SessionStart, UserPromptSubmit, PreCompact, Stop
ZCode	SessionStart, UserPromptSubmit, Stop
Antigravity	PreInvocation, PostInvocation, Stop

格式要点：

• Cursor hooks 是对象数组，例如 { "command": "memorix.cmd hook" }，不是 command 字符串数组。
• WorkBuddy hooks 使用 matcher 嵌套结构，每个事件数组内包含 { "matcher": "*", "hooks": [...] }；项目级目标和模板为实验性、待运行时验证。
• ZCode 配置文件 hooks 使用 top-level hooks.enabled: true + hooks.events，事件条目使用 matcher + hooks 嵌套，hook 命令为 memorix.cmd hook，不要写成插件 hooks 结构；matcher 是大小写敏感正则，可省略，不能写 *，匹配全部时用 .*。
• ZCode 配置文件 hooks 默认禁用；模板必须显式设置 hooks.enabled: true，可使用 hooks.timeoutMs 设置总体超时。
• ZCode 当前支持的配置文件事件是 SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop；不支持 PreCompact，生命周期模板不要包含它。
• Antigravity 项目级模板真实存在于 templates/antigravity.hooks.json。
• 项目级 Codex hooks 模板不存在；Codex 只在全局模板中说明。
• Claude Code 全局路径包含 {version}，必须动态发现已安装的最新 Memorix 插件版本目录。
• Kiro 文件保存 hook 是通过 enabled: false 禁用，而不是删除文件。

合并策略：

• 已存在配置时，不做全量覆盖；只移除明确的高频 Memorix hooks，并补齐或保留生命周期 hooks。
• 保留用户字段，例如 permissions、not-use-now-hooks、自定义 hooks、非 Memorix MCP server entries。
• WorkBuddy 配置要保留 matcher、description 等结构字段，不能用模板替换导致语义丢失。
• 同一事件已有合格 lifecycle hook 时不要重复添加。
• 用户要求清理历史噪音记忆时，先说明风险；不要主动运行 memorix cleanup。

MCP Full Mode

memorix MCP server entry 的通用核心要求是 command 与 args 指向 full 模式：

{
	"mcpServers": {
		"memorix": {
			"command": "memorix",
			"args": ["serve", "--mode", "full"]
		}
	}
}

TOML 形态：

[mcpServers.memorix]
command = "memorix"
args = ["serve", "--mode", "full"]

脚本入口只在技能安装目录下使用：

tsx scripts/install-mcp.ts --help
tsx scripts/install-mcp.ts --dry-run

Windows PowerShell 兜底：

.\fallback\install-mcp.ps1 -DryRun

Bash 兜底：

./fallback/install-mcp.sh -d

维护要点：

• scripts/install-mcp.ts 支持 dry-run 和额外配置文件参数；真实写入前先 dry-run。
• MCP 配置中已有 memorix entry 时，只检查 args 是否包含 --mode full。
• WorkBuddy 相关 MCP entry 应额外保留或建议 env.NODE_OPTIONS = ""，避免继承父进程注入的 Node 参数；当前脚本主责是校准 full args，不要声称 dry-run 一定会补齐 WorkBuddy env。

已知 MCP 配置平台：

平台	配置路径	格式
Codex	~/.codex/config.toml, ~/.codex/config-2026-6-13-bg.toml	TOML
Claude Code	~/.claude.json	JSON
Cursor	~/.cursor/mcp.json	JSON
WorkBuddy	~/.workbuddy/mcp.json, ~/.workbuddy/.mcp.json	JSON
ZCode	~/.zcode/cli/config.json	JSON
Qoder	~/AppData/Roaming/Qoder/SharedClientCache/mcp.json	JSON
Kiro	~/.kiro/settings/mcp.json	JSON

脚本输出状态：

状态	含义
created	配置文件不存在，脚本会创建新文件；dry-run 下只预览。
updated	配置文件存在，memorix entry 需要改为 full 模式；dry-run 下只预览。
skipped	配置已满足要求，或 dry-run 下跳过实际写入。
error	配置解析、读写或格式处理失败，需要先排除该文件问题。

与 memorix setup / 升级配合：

• memorix setup 可能重新安装默认 hooks；setup 后如果用户要求降噪，应再次执行 hooks 精简。
• Memorix 插件升级后，全局 hooks 文件可能被新版本目录或默认内容覆盖；尤其是 Claude Code 全局路径含版本号，需要重新动态发现。
• MCP full 模式和 hooks 精简是两条链路：工具缺失优先查 MCP，记忆噪音优先查 hooks。

WorkBuddy Notes

• WorkBuddy 可能向子进程注入 NODE_OPTIONS。旧 Node 版本不识别 --use-system-ca 时，stdio MCP 会在启动阶段退出。memorix MCP entry 中建议显式设置 env.NODE_OPTIONS = ""。
• WorkBuddy 的 MCP 信任 hash 基于 server entry 的 JSON.stringify 结果再做 SHA-256。任何 mcp.json entry 变化都可能触发重新审批。
• 修改 mcp.json 后需要完全重启 WorkBuddy；只刷新窗口或重开会话可能仍使用旧信任状态。
• Node 22.x 的 ABI 都是 127。同 major 内一般不需要重建 better-sqlite3；跨 major 升级或降级后才优先考虑 rebuild。
• trustLevel=gray 不是充分失败条件。判断重点是 server status=connected，以及 Memorix 工具是否实际暴露。
• 用户抱怨记忆噪音时，优先检查 hooks 模板和高频事件，不要先把问题归因到 MCP 信任链路。

Verification Checklist

• YAML frontmatter 合法，metadata.version 已更新。
• description 只写触发条件，不写流程说明，不使用第一人称。
• 项目级模板表包含 templates/antigravity.hooks.json。
• 项目级模板表包含 templates/zcode.config.json，目标形态是 .zcode/config.json 或 zcode.json。
• 项目级模板表没有 Codex；Codex 只出现在 templates-global/codex.hooks.json。
• ZCode 文档明确配置文件 hooks 必须 hooks.enabled: true 且事件写在 hooks.events，不包含不支持的 PreCompact。
• Cursor 格式说明是对象数组，不是 command 字符串数组。
• 文档没有写死 full 模式工具数量。
• 命令示例只有帮助或 dry-run，不会写入用户配置。
• 资源索引只列技能安装目录内的相对路径。

可建议用户或主线程运行：

tsx scripts/install-mcp.ts --help
tsx scripts/install-mcp.ts --dry-run

.\fallback\install-mcp.ps1 -DryRun

./fallback/install-mcp.sh -d

Resource Index

路径	用途
scripts/install-mcp.ts	MCP 配置检查与安装 CLI 入口
fallback/install-mcp.ps1	Windows PowerShell 兜底入口
fallback/install-mcp.sh	Bash 兜底入口
src/platforms.ts	MCP 平台注册表
src/install-mcp.ts	MCP 配置读写逻辑
templates/	项目级 hooks 模板目录
templates/claude-code.settings.local.json	Claude Code 项目级模板
templates/cursor.hooks.json	Cursor 项目级模板
templates/windsurf.hooks.json	Windsurf 项目级模板
templates/gemini-cli.settings.json	Gemini CLI 项目级模板
templates/kiro.memorix-file-save.kiro.hook	Kiro 项目级模板
templates/workbuddy.hooks.json	WorkBuddy 项目级模板
templates/zcode.config.json	ZCode 项目级配置文件 hooks 模板，可用于 .zcode/config.json 或 zcode.json
templates/antigravity.hooks.json	Antigravity 项目级模板
templates-global/	全局 hooks 模板目录
templates-global/claude.hooks.json	Claude Code 全局模板
templates-global/codex.hooks.json	Codex 全局模板
templates-global/cursor.hooks.json	Cursor 全局模板
templates-global/antigravity.hooks.json	Antigravity 全局模板
references/hooks-reference.md	hooks 作用域、噪音事件、生命周期事件、模板格式与合并策略详解
references/workbuddy-mcp-notes.md	WorkBuddy MCP 连接、信任审批、NODE_OPTIONS、Node ABI 与日志检查详解
references/memorix-setup-notes.md	memorix setup / 插件升级后的全局配置影响与重新精简策略