_{不止于代码，更记住架构演进与研发脉络。}

English · 简体中文

Coding Agent 擅长解决眼前的问题，但新会话不会自动继承此前积累的架构认知、踩坑经验、仓库规则 和协作偏好。

MemoraX Code 让 Codex、Claude Code、CodeBuddy CLI、WorkBuddy、DeepSeek Harness、OpenCode、Trae、Cursor 和 Qoder 共享一套能够持续积累的记忆。 它会沉淀代码任务中的工程经验，持续整理仓库知识，并在后续任务中找回相关的工作流程和偏好。

它追求的不是“记得更多”，而是在需要时带回与当前任务相关的 Memory，让 Agent 减少重复搜索和试错， 更快进入问题定位与事实验证。

开始前，请确保已安装 Node.js 20 或更高版本（推荐 Node.js 24 LTS），以及 Codex、Claude Code、 CodeBuddy CLI、WorkBuddy、DeepSeek Harness、OpenCode、Trae、Cursor 或 Qoder 中的至少一个。

当前 DeepSeek Harness（DSH）版本要求 Node.js ^22.19.0 || >=24.0.0。运行 setup 前， 请先安装或初始化 DSH，创建至少一个 Profile；使用 npm CLI 时，确保 pnpm 在 PATH 中可用。 使用 DSH 桌面版时，请先打开一次以初始化 Profile，再完全退出以安装插件；MemoraX Code 会调用桌面版内置的启动器和包管理器。CLI 与桌面版可以同时启用。MemoraX Code 不会安装或更新 DSH。

Linux 下，游客凭据管理需要 libsecret 提供的 /usr/bin/secret-tool，以及当前用户会话中可用的 Secret Service。使用 Remote SSH、WSL 或 Dev Container 时，请将 MemoraX Code 安装在 Coding Agent 所在的同一环境中。MemoraX 搜索和写回需要网络访问。

npm install -g @memorax/memorax-code

此命令只安装包，不会启动交互式安装引导。请勿使用 --ignore-scripts：替换包时，npm 生命周期 脚本会安全停止并恢复已有的运行中托管 Backend。

前往 MemoraX 注册账号；已有账号可直接使用，然后在正常的交互式终端中运行：

memorax-code setup --existing-account

按照安装引导，在本机终端中输入 MemoraX 用户名和 API Key。

如果 Coding Agent 无法提供交互式终端，可以通过 stdin 传入 API Key。以下示例假定调用方 已提供 MEMORAX_SETUP_API_KEY 变量；请勿将 Key 填入命令参数或项目文件。

printf '%s\n' "$MEMORAX_SETUP_API_KEY" | memorax-code setup --existing-account --non-interactive

Windows PowerShell 使用：

$env:MEMORAX_SETUP_API_KEY | memorax-code.cmd setup --existing-account --non-interactive

该显式命令会替换已保存的 Key，使用检测到的本机用户名和系统语言。 本地配置与就绪检查通过后会输出 API Key match: true，不代表云端凭据已验证。 输入要求及配置复用行为见非交互安装说明。

如果您希望先体验并稍后再接入账号，请运行：

memorax-code setup

默认 setup 会复用已有的完整连接；否则会检测本机用户名和语言，必要时询问，再创建或恢复游客凭据。 如需替换已保存的连接，游客模式使用 memorax-code setup --reconfigure， 正式账号使用 memorax-code setup --existing-account。

如果稍后注册时希望保留游客记忆，请先直接在本机终端运行：

memorax-code account --show-mark-id

两种安装引导都会自动检测受支持的 Coding Agent。完成后，请重启或刷新检测到的 Coding Agent。

Qoder 使用 ~/.qoder/settings.json 和 ~/.qoder/skills/memorax-code/， 可通过 QODER_CONFIG_DIR 指定配置根目录。当前实测目标为 Qoder Desktop 0.4.3 及其内置 runtime 1.1.64。Search 和主动 Add 通过共享 CLI 执行，自动 Add 从原生 transcript 中读取精确匹配的已完成轮次。Repo Memory 构建和整理使用 Qoder 原生后台子 Agent， 遵循正常工具权限，无需单独安装或登录 Qoder CLI。详见 Qoder 配置。

Cursor 独立安装到 ~/.cursor/hooks.json 和 ~/.cursor/skills/memorax-code/，不依赖 Claude Code，setup 会保留 Cursor 的第三方集成开关。Search 和主动 Add 通过 Skill 调用 CLI； 自动 Add 从原生数据库读取经过验证的轮次，需要带内置 SQLite 的 Node.js 22.13+（推荐 Node.js 24）。 支持普通提问、编辑重发，以及能绑定到已观测前一轮的 Continue；中断或内容归属不明确时跳过。 Prompt Hook 会在首个符合条件的轮次注入 User Profile 偏好，并按配置的提醒周期 注入 Procedure Memory。默认 Procedure 周期为第 1、6、11 轮（之后每 5 轮一次）。记录的压缩经 原生数据库验证后，会在下一个非空且成功注册的 Prompt 恢复 Profile 与个人记忆提醒；Procedure 仍遵循原有周期。缺少证据时跳过恢复，不保证在同一个持续执行的任务中立即恢复。Repo Memory 初建和按策略维护使用 Cursor 原生后台子 Agent，无需单独安装或登录 Cursor CLI；执行工具时仍遵循 Cursor 的正常授权。详见 Cursor 配置。

打开项目，新建客户端会话并发送一次 Prompt，然后在项目目录中运行：

memorax-code --version
memorax-code status
memorax-cli status

Windows PowerShell 请使用 memorax-cli.cmd status。客户端真正执行 Hook 之前，已配置好的集成 仍可能显示 hook-runtime=unverified；成功执行 Hook 后，对应客户端的 Hook runtime 应变为 observed。

memorax-code status 检查本地 Backend 和客户端集成；memorax-cli status 检查本地记忆配置 和工作区作用域。这两个命令都不会向 MemoraX 发送测试请求；实际搜索或写入才会验证远端连接与凭据。 接着按下方示例体验跨会话记忆，验证实际效果。各客户端的诊断命令见故障排查。

npm 包安装完成后不会自动启动 setup，请运行上面适合您的安装引导命令；Agent 没有交互式终端时可使用 stdin 模式。 如果 setup 未完成或记忆不可用，请先运行状态检查命令，再按故障排查处理。

两个命令均由同一个包提供。请按 Windows PATH 修复步骤 启动 setup，或修复仍使用旧环境的终端。

克隆示例仓库，并在项目目录中打开 Codex、Claude Code、CodeBuddy CLI、WorkBuddy、DeepSeek Harness、OpenCode、Trae、Cursor 或 Qoder：

git clone https://github.com/SWE-agent/test-repo.git
cd test-repo

在 Codex 中使用 $memorax-code，在 Claude Code 或 DeepSeek Harness 中使用 /memorax-code 调用该 Skill。在 OpenCode、CodeBuddy CLI、WorkBuddy、Trae、Cursor 或 Qoder 中，直接让 Agent 使用名为 memorax-code 的 Skill。 下面的指令使用产品名称，所有客户端均可直接理解。

在同一个会话中依次发送以下指令：

1. 请使用 MemoraX Code Skill 帮我构建 Repo Memory，只拉取最近 3 条 Issue、PR 和 Commit 记录。
2. Repo Memory 中最近的一条 Issue 提到，第 0 个数字曾经计算错误。请检查当前代码，避免再次出现同类问题。
3. 请使用 MemoraX Code Skill 记住这次的代码开发经验。

结束当前对话，然后在同一仓库中开启一个新会话，再发送：

请使用 MemoraX Code Skill 回忆之前的开发经验，看看有哪些建议。

此时，Agent 应能找回此前保存的经验，并结合当前仓库给出建议。

Personal Memory 和 Procedure Memory 在用户级目录 $MEMORAX_CODE_HOME/personal-memory/（默认 ~/.memorax-code/personal-memory/）下：User Profile 使用 user-profile/preferences.md，每个 Procedure 主题在 procedure-memory/ 中单独保存。适用条件可以提到仓库、工具或工作流，但仓库内没有个人记忆层。 旧 .repo_memory 中的个人记忆会被忽略，不会迁移。Agent 按意图而不是措辞决定是否保存： 你表达了希望在当前任务之后继续生效的做事规则或偏好时，不必说“记住”，Agent 也会保存并告诉你存了什么； 做事方式的规则存入 Procedure Memory，沟通和结果呈现的偏好存入 User Profile。涉及已有内容时，MemoraX Code 会先比较含义： 语义相同的请求不重复写入；长期有效的补充或冲突规则会更新匹配项，并彻底移除被替代的文字； 适用环境失效时先修正范围，只有整条记忆完全过时时才删除。用户明确要求忘记时，只删除点名的偏好、 流程主题、段落或步骤，其他记忆保持不变。一次性任务指令不会改写已保存的记忆；是否长期有效或目标不清楚时，Agent 会先询问。

云端记忆依赖 MemoraX。完成安装引导后，会启用 MemoraX 搜索/添加，以及生成配置中的自动写回； 不会再出现第二次写回确认。Search 由 Agent 通过 Skill 主动调用，或由您直接运行 CLI； Hook 继续提供本地记忆上下文与提醒，不发起 Search 请求。

可选的 Jev 配置会通过 TypeSafe 模型， 对每个符合条件的新用户请求判断是否需要 Search；需要时，Agent 先读取 memorax-code Skill 中的 Search 指引，再按照其中的规则构造查询并执行搜索。 该功能使用您配置的 Jev Key，默认关闭；开启后会将限长的本轮请求与上一轮交互文本 发送给 TypeSafe。调用失败时按原有周期提供 Skill 提醒，Search 仍由 Agent 执行。

受支持客户端的本地 trace 默认开启。根据客户端能力，MEMORAX_CODE_HOME 下保留的 trace 可能包含用户指令、Agent 回复、召回的 Memory、提醒文本和本地路径。可通过 本地 trace 配置改为仅记录元数据，或关闭对应客户端的 trace。 关闭 trace 后仍会保留必要的本地会话状态，以保证记忆操作使用正确的工作区范围。

Setup、主动 Search/Add、Backend 启动/停止/重启、客户端部署或包更新失败时，会提供错误码、恢复建议和不含内容的本地诊断记录， 详见故障恢复。Hook 执行和自动写回的已知故障也会在关闭 Debug 时尝试保留本地诊断， 不会向对话插入报错消息，也不会因此阻断编码任务。 memorax-code status 会汇总近期故障；使用 memorax-code logs --diagnostics 或 memorax-code logs --id <diagnostic-id> 查看详情，检查后即可用于问题反馈。

Coding Memory 按仓库或工作区确定范围。Codex、WorkBuddy、OpenCode、Cursor 和 Qoder 中符合识别规则的 默认聊天目录或上下文，会在相同的 MemoraX 用户 ID 配置下共享 General。Cursor 未选择文件夹的对话使用 这个共享的 @General 范围；打开仓库后则使用该仓库的正常范围。已有记忆不会自动迁移，目录规则详见 记忆范围。

游客额度提醒可能显示完整的 Mark ID；请将包含该信息的提醒文本和本地 trace 视为敏感信息。

主动记忆操作会将查询或选中的内容发送至 MemoraX。自动写回会从受信任工作区的任务中，发送经过 选择的用户指令和对应的 Agent 最终回复，并先移除最终回复中的记忆作用说明，再用于提取和保存记忆；它不会上传完整的本地客户端 trace 文件或本地 trace 路径。

QA 写回会保留可用的原生时间戳，并标明使用观测时间的回退情况，详见消息时间戳。

登录 MemoraX Console 后，可以随时查看、修改或删除已经保存的记忆。 MemoraX 云端不会接收模型服务商凭据或本地 Backend Token。

完整行为请参阅配置，网络、本地数据和保留边界请参阅 安全策略。

全局 npm 安装使用：

memorax-code update

完成 setup 后，托管 Backend 运行期间也会自动检查并更新。更新会短暂停止运行中的托管 Backend， 再按保留的客户端选择恢复。重新安装后的 setup 和更新都会保留明确的客户端选择，即使旧配置缺少 codex 或 claude 字段。发布通道、自定义状态目录、客户端选择、Backend 恢复规则和关闭后台检查 的方法见更新配置。 如果更新修改了运行中客户端已加载的集成资产，请重启或刷新客户端。 如果包替换失败，请按更新恢复步骤 使用 memorax-code update --recover。

如果较旧的 Windows 安装在升级时遇到 EBUSY 重命名错误，请按 旧版升级恢复步骤处理。

请先运行产品自身的卸载流程：

memorax-code uninstall

该命令会移除受管客户端集成和全局 npm 包，同时保留配置与已保存的记忆。 请勿先运行 npm uninstall -g，否则可能在清理客户端集成之前就移除了产品命令。 完整的保留数据清单见卸载与数据保留。

完整卸载后重新安装时，请再次运行 memorax-code setup；默认会复用保留的完整连接。 正常执行 memorax-code stop 或仅卸载部分客户端集成会保留 setup 完成状态。

• 安装与首次使用
• 配置
• 故障排查
• 参与贡献
• 安全策略

欢迎提交 Issue 和 Pull Request。修改前请阅读 CONTRIBUTING.md， 公开报告中不要包含 API Key、原始对话、私有记忆或本地 trace 文件。

MemoraX Code 基于 MIT License 开源。