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。

1. 再定作用域。

• 只影响当前项目：使用 templates/ 下的项目级模板。
• 影响用户全局 Agent：参考 templates-global/，但不要在未获明确授权时写入用户主目录配置。

1. 最后选执行方式。

• 只需要确认脚本行为：运行帮助或 dry-run。
• 需要真实写入：必须由用户明确要求，并在执行前说明会修改哪些用户配置文件。

1. hooks 噪音场景优先处理 hooks，不要把 WorkBuddy MCP 信任链路排查放到主路径上。

Reference Routing

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

如果用户只抱怨“记忆太吵”或“每次工具调用都记录”，优先读取 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

作用域模型：

支持的 hooks 配置目标：

项目级模板：

全局模板：

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

应保留的生命周期事件：

格式要点：

• 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 配置平台：

脚本输出状态：

与 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