Codex Memory MCP Server

Local stdio MCP server for long-term engineering memory.

This repository contains only the MCP service code, scripts, and tests. It does not include a user's private memory data directory, SQLite memory database, Codex config, hooks config, session logs, or API credentials.

The server is intentionally file-backed. It reads the existing Codex memory workspace and writes new ad-hoc notes only under:

%USERPROFILE%\.codex\memories\extensions\ad_hoc\notes

Tools:

• search_engineering_memory: search Markdown and JSONL memory files.
• read_engineering_memory: read a memory file by relative path.
• list_engineering_memory_files: list readable memory files.
• add_engineering_memory_note: append a timestamped note when the user has explicitly asked to save or update long-term memory.
• get_project_memory_context: build the project memory context for a cwd.
• get_project_engineering_context: build compact structured project context, including recent progress, project facts, interfaces, pin map, baud rates, and resource paths.
• search_project_memory: search memory scoped to a project cwd.
• list_memory_projects: list indexed project memory roots.
• refresh_project_resources: index matching file paths from shared project-resource folders.
• list_project_resources: list indexed project resource file locations.
• upsert_project_fact: record or update one observed project fact.
• list_project_facts: list structured project facts.
• update_project_progress: append a structured project progress entry.
• list_project_progress: list recent project progress entries.
• upsert_project_action_config: record one standard project action command for build, flash, monitor, clean, test, or reset.
• list_project_action_configs: list stored standard action commands.
• upsert_project_interface: record UART/interface details such as baud rate, TX/RX pins, protocol, and settings.
• list_project_interfaces: list structured project interfaces.
• upsert_project_pin: record one pin-map row for wiring cross-checks.
• list_project_pin_map: list structured pin mappings.
• search_troubleshooting_memory: search indexed fault patterns and reminders.
• list_troubleshooting_memory_cases: list troubleshooting cases in SQLite.

Tool responses are compact JSON. Successful calls include "ok": true; invalid arguments or blocked paths return "ok": false with an error string.

Codex starts this server through your Codex config, typically %USERPROFILE%\.codex\config.toml on Windows.

Automatic turn summaries

Codex can also run scripts\codex-turn-summary-hook.cmd from the global %USERPROFILE%\.codex\hooks.json Stop hook. The hook records each completed turn as a new global note under the same ad-hoc notes directory. It records a copy under the project memory folder only when the turn is classified as project_engineering; Codex/MCP/hook/config work is classified as global_infrastructure and stays global-only. It reads the hook payload from stdin and never modifies existing memory files.

The add_engineering_memory_note MCP tool is still explicit-only. Automatic turn summaries are written by the Stop hook, not by MCP tool calls.

Codex renders hook systemMessage output as a warning line in the CLI, so display output is disabled by default. To test the optional display path, set CODEX_TURN_SUMMARY_DISPLAY=systemMessage; the hook will then return a compact message like /* 本轮总结：... */.

Troubleshooting index

Fault-pattern reminders are stored in the same SQLite database under the troubleshooting_cases table. The search tool can return at most the top 3 matching reminders. UserPromptSubmit runs in silent mode by default so the Codex CLI does not print hook context blocks on every prompt. Set CODEX_PROJECT_CONTEXT_HOOK_MODE=alerts to inject only troubleshooting reminders, or CODEX_PROJECT_CONTEXT_HOOK_MODE=full to inject full project memory context.

Project memory

Project-scoped memory is stored under:

%USERPROFILE%\.codex\memories\projects\<project-slug>

Project metadata and turn summaries are indexed in SQLite at:

%USERPROFILE%\.codex\memories\engineering_memory.sqlite

The project root is the nearest parent containing .git; if no git repository exists, the current working directory is used. In default silent mode, UserPromptSubmit refreshes project resource indexes but does not return additionalContext, avoiding noisy CLI output. Project memory remains available through get_project_memory_context, search_project_memory, and list_project_resources. Global infrastructure work, such as changing this MCP server, Codex hooks, or Codex config, is retained in global long-term memory instead of being added to an unrelated engineering project.

First project scan

When a project is first resolved, the MCP creates or updates the project profile.md with a deterministic first-pass scan. The scan records:

• project type
• build system
• entry files
• main modules
• driver directories
• config files
• flash method
• test method
• potential risks

The scanner is intentionally conservative. It reads only small text snippets needed to detect entry points and build/test targets, ignores generated/vendor directories such as build, dist, .git, and node_modules, and stores paths plus summaries instead of copying source contents. If an existing profile already has ## First Scan, it is left unchanged. If a profile exists without that section, the scan section is inserted before ## Stable Notes so manual notes are preserved.

Structured project engineering memory

Project memory now has structured SQLite tables for data that should be retrieved precisely instead of only searched as prose:

• project_facts: project code/name, chip model, hardware revision, build and flash commands, default baud rate, source path, confidence, and verification flag.
• project_progress: compact work progress entries from the Stop hook or the update_project_progress tool, including status, completed work, blockers, next steps, and verification notes.
• project_actions: standard build/flash/monitor/clean/test/reset action commands, device IDs, framework type, config file path, timeout, risk, and verification flag.
• project_interfaces: UART/I2C/SPI/CAN/network/debug interfaces, including UART number, baud rate, TX/RX pins, protocol, and JSON settings.
• project_pin_map: board/peripheral/signal/GPIO/net/connector/direction rows for schematic, EDA netlist, and firmware wiring cross-checks.

resolve_project() automatically records identity facts for each project: project.code, project.root, and project.memory_slug. Turn summaries from project engineering work are also inserted into project_progress so the latest work state can be queried without reading every Markdown turn file.

The structured upsert tools should store only observed or explicitly confirmed facts. For engineering documents, schematic PDFs, and EDA netlists, store the file location and extracted fact rows; do not copy whole document contents into long-term memory.

Project resource path index

The project memory layer can also index file locations from shared engineering resource folders. This is configured with:

CODEX_PROJECT_RESOURCE_ROOTS=C:\path\to\shared\engineering-resources

The scanner matches files by project aliases such as repository name, nearby path segments, and git remote repository name. It indexes likely resource files only: documents, PDFs, spreadsheets, text/Markdown notes, archives, EDA netlists, and files whose names clearly look like netlists or schematics. It stores only file paths and metadata in SQLite, not file contents. Indexed metadata includes path, root, file name, extension, type, size, modified time, matched alias, and match score.

Resource paths are stored in the project_resources SQLite table and are included in auto-mounted project context under Project Resource Paths. EDA netlists and schematic PDFs are classified as eda_netlist and schematic_pdf so they appear near the top for wiring cross-check tasks.

If a turn summary mentions a file path inside the configured resource folders, the Stop hook also binds that path to the current project with matched_alias=mentioned_in_turn. This handles ambiguous files such as a generic Netlist_Schematic2_2026-03-19.tel whose name does not contain the project identifier.