EverOS Codex

English

everos-codex 是一个本地 MCP 桥接和配套 Codex skill，用来把本机运行的 EverOS 接成 Codex 的长期记忆层。

它保持 EverOS 的原生边界不变：

• EverOS 继续作为本机 HTTP 服务运行，通常是 http://127.0.0.1:8000
• Codex 通过 MCP stdio 和 EverOS 通信
• 记忆完全本地化，不依赖 EverMe 托管服务

功能

• memory_search
  • 用于召回历史项目上下文、过去修复记录和决策
• memory_get
  • 用于按 session_id 做确定性回读和验真
• memory_save_turn
  • 用于写入高价值任务总结，推荐结构为 问题 / 根因 / 修复 / 验证
• memory_flush
  • 用于手动触发单个 session 的提取
• 内置 Codex skill：everos-local-memory
  • 用来约束使用口径，避免记忆库被写脏

默认行为

• 默认召回路径是 owner_type=user
• 当未传 project_id 且 EVEROS_DEFAULT_PROJECT_ID 为空时，MCP 会按当前仓库根目录名自动推导 project_id
• 显式传入的 project_id 永远优先于自动推导

依赖要求

• Node.js 20+
• 本机已安装并运行 EverOS
• 支持 MCP 的 Codex

快速开始

1. 先确认 EverOS 正常运行：

curl http://127.0.0.1:8000/health

2. 运行快速检查：

npx everos-codex doctor
npx everos-codex smoke

3. 把内置 skill 安装到 Codex：

npx everos-codex install-skill

4. 把下面这段加到 ~/.codex/config.toml：

[mcp_servers.everos]
command = "npx"
args = ["-y", "everos-codex"]

[mcp_servers.everos.env]
EVEROS_BASE_URL = "http://127.0.0.1:8000"
EVEROS_APP_ID = "codex"
EVEROS_DEFAULT_PROJECT_ID = ""
EVEROS_AGENT_ID = "codex"
EVEROS_AGENT_NAME = "Codex"
EVEROS_USER_ID = "your-user-id"
EVEROS_USER_NAME = "Your Name"
EVEROS_TIMEOUT_MS = "60000"

如果没有显式设置 EVEROS_USER_ID，这个包会回退到本机系统用户名，并自动归一化成安全的 EverOS 标识符。

5. 重启 Codex，或者新开一个线程。

本地开发

npm install
npm run doctor
npm run smoke
npm run smoke:e2e
npm run install-skill

直接启动 MCP stdio server：

npm start

CLI 命令

everos-codex start
everos-codex doctor
everos-codex smoke
everos-codex smoke-e2e
everos-codex install-skill

Skill

仓库内置了 skills/everos-local-memory。

它不是再造一层存储或传输，而是固定使用纪律：

• 开场优先 memory_search
• 只保存高价值总结
• 优先显式传 project_id
• 验真优先用 memory_get
• 不把整段聊天直接灌进记忆库

安装后路径：

~/.codex/skills/everos-local-memory

按仓库隔离的 project_id

如果你不传 project_id，everos-codex 会尝试按当前仓库根目录名自动推导。

例如：

• 仓库 water -> project_id=water
• 仓库 store-ops-suite -> project_id=store-ops-suite
• 仓库 EverOS-Codex -> project_id=everos-codex

以下场景仍建议显式传 project_id：

• 一个仓库里要拆多个长期记忆桶
• 多个仓库要共用一个记忆桶
• 你在跑 smoke / scratch / 临时测试

致谢

这个项目建立在开源项目 EverMind-AI/EverOS 之上。

感谢 EverOS 的维护者和贡献者把本地优先的记忆系统带给社区。

发布建议

推荐发布形态：

• GitHub 仓库：gix9303/EverOS-Codex
• npm 包：everos-codex

发布后，用户只需要：

npx -y everos-codex doctor
npx -y everos-codex install-skill

发布检查清单

1. 推送仓库到 [email protected]:gix9303/EverOS-Codex.git
2. 检查 examples/codex-config.toml
3. 运行：

npm run doctor
npm run smoke
npm run smoke:e2e
npm pack --dry-run

4. 登录 npm：

npm login

5. 发布：

npm publish

6. 做公网安装验证：

npx -y everos-codex doctor
npx -y everos-codex install-skill

License

Apache-2.0