# EverOS Codex

[简体中文](./README.zh-CN.md)

Use a local [EverOS](https://github.com/EverMind-AI/EverOS) instance as long-term memory for Codex through MCP.

`everos-codex` provides:

- an MCP bridge for local EverOS
- repo-scoped default `project_id` inference
- `memory_search`, `memory_get`, `memory_save_turn`, `memory_flush`
- a bundled Codex skill: `everos-local-memory`

## Why

This project keeps EverOS in its native local shape:

- EverOS stays a local HTTP service, usually `http://127.0.0.1:8000`
- Codex connects through MCP over stdio
- memory stays local-first

## Install

Verify EverOS is running:

```bash
curl http://127.0.0.1:8000/health
```

Install the bundled Codex skill:

```bash
npx -y everos-codex install-skill
```

Add this MCP config to `~/.codex/config.toml`:

```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"
```

Restart Codex or open a fresh thread.

## Quick checks

```bash
npx -y everos-codex doctor
npx -y everos-codex smoke
```

## CLI

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

## How project IDs work

If `project_id` is omitted and `EVEROS_DEFAULT_PROJECT_ID` is empty, `everos-codex` infers it from the current repo root name.

Examples:

- `water` -> `project_id=water`
- `store-ops-suite` -> `project_id=store-ops-suite`
- `EverOS-Codex` -> `project_id=everos-codex`

Explicit `project_id` still wins.

## Bundled skill

This repo bundles `skills/everos-local-memory`.

Its job is simple:

- search before repeating work
- save only high-value summaries
- verify new memory with `memory_get`
- avoid dumping whole conversations into memory

## Acknowledgement

This project is built on top of the open-source [EverMind-AI/EverOS](https://github.com/EverMind-AI/EverOS) project.

Thanks to the EverOS maintainers and contributors for making a local-first memory system available to the community.

## License

Apache-2.0