# codex-memory

**English** | [简体中文](README.zh-CN.md)

Curated long-term memory for [Codex CLI](https://github.com/openai/codex), delivered as an MCP server. It stores atomic facts as plain Markdown files, deduplicates on write, retrieves via a lightweight index, and — crucially — **forgets**: entries decay by type-aware half-life and are archived after human review.

Core idea: raw experience accumulates, but knowledge is what survives distillation — so forgetting is treated as a feature on equal footing with remembering.

- 4 MCP tools: `memory_index` / `memory_search` / `memory_write` / `memory_revise`
- One memory per Markdown file, git-versioned, human-auditable — no database
- Built-in dedup (weighted token overlap, CJK-aware), source ranking (`user-correction` wins)
- Global/project scopes prevent repository-specific knowledge from leaking into unrelated tasks; optional provenance points back to supporting sessions
- Development schema is strict: `cwd`, `scope`, counters, dates, type, and source must satisfy the current contract; no legacy defaults or migrations
- Decay scoring, an archive buffer with 90-day expiry, driven by a small CLI
- Explicit memory graduation promotes proven global preferences/lessons into a managed AGENTS.md region and retains a permanent audit copy
- Weekly `consolidate` job — semantic dedup, pattern promotion, and an episodic bridge from Codex's built-in memories, powered by `codex exec` (no extra LLM dependency), one git commit per run
- Built-in evals: repeat-mistake rate, write-burst and project-coverage signals (`eval`), plus the index growth curve (`growth`)

## Documentation

| English | 简体中文 |
|---|---|
| [Getting Started](docs/en/getting-started.md) | [快速开始](docs/zh-CN/getting-started.md) |
| [Design](docs/en/design.md) | [设计](docs/zh-CN/design.md) |
| [Reference](docs/en/reference.md) | [参考手册](docs/zh-CN/reference.md) |

Agent instruction templates (append to `~/.codex/AGENTS.md`): [English](templates/AGENTS.en.md) · [中文](templates/AGENTS.zh-CN.md)

## License

[MIT](LICENSE) © Xiandong Liu (刘宪东)