Changes Memory MCP

Local MCP server for storing corrections, preferences, and reusable criteria across conversations, with a single Codex configuration and separate global + project memory files.

What It Solves

• Stores user-approved corrections in a stable format.

• Lists, searches, and retrieves relevant criteria for new tasks.

• Helps agents avoid repeating mistakes when they consult this MCP before implementation or review.

Related MCP server: Mono Memory MCP

Memory Stores

By default, memory is stored in plain Markdown files:

~/.codex/changes.md              # global memory
<project>/.codex/changes.md      # project memory

You can change this with CLI arguments or environment variables:

• --project-path=/path/to/project: default project when a tool call does not pass projectPath.

• --global-path=/path/to/changes.md: exact file path for global memory.

• CHANGES_MEMORY_PROJECT_PATH: equivalent to --project-path.

• CHANGES_MEMORY_GLOBAL_PATH: equivalent to --global-path.

Backward compatibility:

• --memory-root and CHANGES_MEMORY_ROOT still work as the default project path.

• --memory-path and CHANGES_MEMORY_PATH force an exact file path for the default project memory.

MCP Tools

• add_local: stores a new correction or criterion in project memory.

• add_global: stores a cross-project criterion in global memory.

• list_change_index: lists a compact index of entries with id, title, store, kind, tags, and paths.

• list_tag_catalog: lists the recommended tag catalog for memory entries.

• list_changes: lists project + global entries by default.

• search_changes: searches entries by free text, tags, or paths.

• get_relevant_changes: returns the most relevant project + global entries for a task.

• get_change: retrieves an exact entry by id from project + global memory.

Read tools and add_local accept projectPath to select the right project when a conversation touches multiple repositories.

Recommended Tags

Every add_local and add_global call must include tags. Prefer 2-5 tags from this catalog:

api, backend, codex, components, config, database, docker, docs, frontend,
git, i18n, json, mcp, migration, mongo, naming, opensearch, performance,
security, styles, tests

Use list_tag_catalog when unsure which tags fit. Tags are what make list_change_index useful without loading full entries.

Run From GitHub

npx -y --package github:formonkey/knowledge-memory-mcp#main knowledge-memory-mcp

Run From A Local Checkout

node /path/to/knowledge-memory-mcp/src/index.js

Codex MCP Configuration

Use one global config in ~/.codex/config.toml.

Recommended setup, directly from GitHub:

[mcp_servers.knowledge_memory]
command = "npx"
args = [
  "-y",
  "--package",
  "github:formonkey/knowledge-memory-mcp#main",
  "knowledge-memory-mcp"
]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "auto"

Local checkout:

[mcp_servers.knowledge_memory]
command = "node"
args = [
  "/absolute/path/to/knowledge-memory-mcp/src/index.js"
]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "auto"

Environment-variable alternative:

[mcp_servers.knowledge_memory.env]
CHANGES_MEMORY_GLOBAL_PATH = "/Users/nigma/.codex/changes.md"

After changing the config, restart Codex so the MCP server is reloaded.

Recommended Agent Instruction

Add a rule like this to global or repository instructions when you want agents to use this memory:

Before implementing or reviewing changes, call `list_change_index` on the `knowledge_memory` MCP server to inspect the compact index. Then call `get_change`, `search_changes`, or `get_relevant_changes` only for entries that look relevant.

When a conversation touches multiple projects, pass `projectPath` in tool calls to select the correct local memory.

Do not store memory on your own initiative. If the user confirms that a learning should be saved, use `add_local` for project-specific criteria and `add_global` only for criteria that apply across projects. Always include 2-5 tags from the catalog.

Notes

• Persistence currently uses plain changes.md files, with no database or external index.

• Search is text-based with simple ranking. It is enough to start and easy to audit.

• The model can later evolve toward richer scopes, editable confirmations, and explicit Before -> After output.