Codex Memory + Project Intelligence

A local-first memory, dependency-intelligence, and impact-analysis layer for Codex and other AI coding agents.

CMI helps an agent answer four questions before changing a project:

1. What has the team already learned or decided?
2. Which files, symbols, and workspaces are connected to this change?
3. Is the stored knowledge still current?
4. Which repository content should be ignored or treated as generated noise?

Everything stays in a human-reviewable .codex-memory/ directory. There is no cloud service, API key, database, or telemetry.

Codex Memory Intelligence is an independent open-source project and is not affiliated with or endorsed by OpenAI.

Current status

v0.5 is a real-world public beta, published on npm as codex-memory-intelligence. It adds incremental scanning, .cmiignore, monorepo awareness, workspace-scoped retrieval, broader parser resolution, MCP resources/prompts, reproducible benchmarks, and release-metadata validation.

Static parsing remains best effort rather than compiler-grade analysis. See Architecture, Benchmarks, and Roadmap.

Install

Install the public npm package globally:

npm install -g codex-memory-intelligence
cmi --version

Or install it in one project and run it through npx:

npm install --save-dev codex-memory-intelligence
npx cmi --version

Requires Node.js 22 or newer.

Quick start

cmi doctor
cmi init
cmi scan
cmi remember fact "Production runs on Cloudflare Pages"
cmi remember decision "Schema changes must use D1 migrations" --source wrangler.toml
cmi context "change the leaderboard migration"
cmi impact migrate
cmi stale
cmi snapshot before-refactor
cmi status

A second unchanged cmi scan reuses previously parsed source nodes. Use cmi scan --full after parser/configuration experiments or when you deliberately want a complete rebuild.

Monorepos and workspaces

CMI detects npm/pnpm workspaces, Cargo workspace members, and Go workspaces/modules.

cmi workspaces
cmi context "authentication flow" --workspace packages/web
cmi search "shared API" --workspace @company/core

Graph nodes carry workspace IDs, impact analysis reports affected workspaces, and cross-workspace edges are counted separately.

Ignore semantics

Create a root .cmiignore file using gitignore-style patterns:

# Generated code
generated/
*.snapshot.json

# Re-include one file
!important.snapshot.json

Explain any decision:

cmi explain-ignore generated --directory
cmi explain-ignore important.snapshot.json --json

Built-in dependency/generated paths and symbolic links cannot be re-included. Hidden paths such as .env are excluded by default, while root .github/ and .cmiignore remain visible for repository intelligence. See Ignore semantics.

Commands

cmi init [path]
cmi scan [path] [--full] [--json]
cmi graph [path] [--json]
cmi workspaces [path] [--json]
cmi explain-ignore <path> [--directory] [--json]
cmi search <query> [--limit N] [--workspace name-or-path] [--json]
cmi context <query> [--limit N] [--workspace name-or-path] [--json]
cmi impact <file-or-symbol> [--depth N] [--json]
cmi remember <fact|decision|mistake> <text> [--source path ...]
cmi stale [path] [--fail-on stale|review|any] [--json]
cmi refresh-memory <id|all> [--reviewed-by name] [--reason text]
cmi snapshot [label]
cmi status [path] [--json]
cmi doctor [path] [--json]
cmi mcp-config [--write] [--bulk-refresh]
cmi --version

MCP integration

Generate the safe default configuration, with durable-memory mutations disabled:

cmi mcp-config

Enable durable-memory creation and reviewed refresh explicitly:

cmi mcp-config --write

Bulk refresh requires a second opt-in:

cmi mcp-config --write --bulk-refresh

The server exposes tools, resources, and prompt templates. It supports stable MCP protocol versions from 2024-11-05 through 2025-11-25, negotiates the client version when supported, and uses newline-delimited JSON-RPC over stdio. Scanning may refresh generated cache files; durable Markdown memory remains protected by explicit write opt-in.

See MCP integration.

Security model

• Project scanning never follows symbolic links.
• Source-linked memory accepts regular files only and verifies real paths remain inside the project.
• Built-in dependency and generated paths cannot be negated through .cmiignore.
• Hidden paths are excluded by default except root .github/ and .cmiignore.
• MCP durable-memory tools are disabled by default.
• Bulk memory refresh requires a separate opt-in.
• Obvious credentials and private keys are rejected, but CMI is not a complete secret scanner.
• Repository content and memory text remain untrusted input for connected agents.

Review .codex-memory/ before publishing it. Generated project-index.json, project-graph.json, and snapshots/ are ignored by default; durable Markdown knowledge and configuration remain reviewable and commit-friendly.

Parser scope

CMI uses bounded, dependency-free static parsing for common JavaScript/TypeScript, Python, Go, Rust, and related files. v0.5 adds TypeScript paths aliases, Python absolute-package heuristics, Go module imports, and Rust mod/crate::/self::/super:: resolution.

Aliases inherited through complex extends chains, generated code, runtime imports, macros, reflection, build-system rewrites, and dependency injection may not resolve completely. Go package imports are represented by a deterministic source-file node rather than a compiler package graph.

Development

npm run verify
npm run benchmark:smoke
npm run package:smoke

CI runs on Ubuntu, macOS, and Windows with Node.js 22 and 24. A separate benchmark smoke job checks incremental reuse and release metadata. CodeQL scans JavaScript and GitHub Actions workflows.

Community documents: Contributing, Code of Conduct, Governance, Support, Security, Maintainers, and Releasing.

License

MIT