feat: add codex repository adapter

Alexxigang · Alexxigang · commit aeb3dd008f99 · 2026-04-06T10:25:15.000+08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 ﻿# Changelog
 
+## 0.29.0 - 2026-04-06
+
+- added a codex-repo adapter for recursive AGENTS.md and AGENTS.override.md repository scopes
+- added fixtures and roundtrip coverage for Codex repository instruction layouts
+
 ## 0.28.0 - 2026-03-29
 
 - added a claude-code-memory adapter for recursive CLAUDE.md layouts, local overrides, and @path imports
@@ -170,3 +175,4 @@
 - added baseline tests
 
 
+
diff --git a/README.md b/README.md
@@ -36,12 +36,14 @@ This project solves that with a portable canonical memory package plus adapter-b
 - scaffold new adapter integrations with a generated starter template
 - run a local web UI for interactive migration workflows
 - migrate OpenHands repository customizations, scripts, skills, and microagents
+- migrate Codex repository-scoped AGENTS instructions and overrides
 
 ## Supported formats
 
 - `generic-json`
 - `markdown-bundle`
-- `codex-memories`
+- codex-memories
+- codex-repo
 - `cline-memory-bank`
 - `cursor-rules`
 - `claude-code-memory`
@@ -161,3 +163,4 @@ See `CONTRIBUTING.md`.
 
 MIT
 
+
diff --git a/fixtures/README.md b/fixtures/README.md
@@ -21,3 +21,6 @@ Available sample sets:
 
 - claude-code-memory/: Modern Claude Code memory sample with imports, local overrides, and nested CLAUDE.md files
 
+
+- codex-repo/: Codex repository instructions sample with recursive AGENTS.md and AGENTS.override.md scopes
+
diff --git a/fixtures/codex-repo/AGENTS.md b/fixtures/codex-repo/AGENTS.md
@@ -0,0 +1,3 @@
+﻿# Root Agent Instructions
+
+Use small commits and keep migration artifacts deterministic.
diff --git a/fixtures/codex-repo/apps/api/AGENTS.md b/fixtures/codex-repo/apps/api/AGENTS.md
@@ -0,0 +1,3 @@
+﻿# API Scope
+
+Prefer stable JSON outputs and explicit validation.
diff --git a/fixtures/codex-repo/apps/web/AGENTS.md b/fixtures/codex-repo/apps/web/AGENTS.md
@@ -0,0 +1,3 @@
+﻿# Web Scope
+
+Favor simple UI interactions and local-first workflows.
diff --git a/fixtures/codex-repo/apps/web/AGENTS.override.md b/fixtures/codex-repo/apps/web/AGENTS.override.md
@@ -0,0 +1,3 @@
+﻿# Web Override
+
+When touching the web console, preserve download and history behavior.
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memory-migrate-plugin"
-version = "0.28.0"
+version = "0.29.0"
 description = "Open-source toolkit for migrating memories across AI agent systems."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,3 +32,4 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+
diff --git a/src/memory_migrate_plugin/__init__.py b/src/memory_migrate_plugin/__init__.py
@@ -1,4 +1,5 @@
 ﻿__all__ = ["__version__"]
 
-__version__ = "0.28.0"
+__version__ = "0.29.0"
+
 
diff --git a/src/memory_migrate_plugin/adapters/__init__.py b/src/memory_migrate_plugin/adapters/__init__.py
@@ -4,6 +4,7 @@
 from .claude_code_memory import ClaudeCodeMemoryAdapter
 from .cline_memory_bank import ClineMemoryBankAdapter
 from .codex_memories import CodexMemoriesAdapter
+from .codex_repo import CodexRepoAdapter
 from .cursor_rules import CursorRulesAdapter
 from .generic_json import GenericJsonAdapter
 from .markdown_bundle import MarkdownBundleAdapter
@@ -14,6 +15,7 @@
     "GenericJsonAdapter",
     "MarkdownBundleAdapter",
     "CodexMemoriesAdapter",
+    "CodexRepoAdapter",
     "ClineMemoryBankAdapter",
     "CursorRulesAdapter",
     "ClaudeProjectAdapter",
diff --git a/src/memory_migrate_plugin/adapters/claude_code_memory.py b/src/memory_migrate_plugin/adapters/claude_code_memory.py
@@ -21,7 +21,7 @@ def probe(self, path: Path) -> bool:
             return path.name in MEMORY_FILENAMES
         if not path.is_dir():
             return False
-        return any(path.rglob(filename) for filename in MEMORY_FILENAMES)
+        return any(any(path.rglob(filename)) for filename in MEMORY_FILENAMES)
 
     def detect_confidence(self, path: Path) -> int:
         if not self.probe(path):
diff --git a/src/memory_migrate_plugin/adapters/codex_repo.py b/src/memory_migrate_plugin/adapters/codex_repo.py
@@ -0,0 +1,98 @@
+﻿from __future__ import annotations
+
+from pathlib import Path
+
+from memory_migrate_plugin.adapters.base import BaseAdapter
+from memory_migrate_plugin.models import CanonicalMemoryPackage, MemoryEntry
+from memory_migrate_plugin.utils import read_text, slugify, write_text
+
+
+DOC_FILENAMES = ("AGENTS.override.md", "AGENTS.md")
+
+
+class CodexRepoAdapter(BaseAdapter):
+    name = "codex-repo"
+    description = "Codex repository instructions using recursive AGENTS.md and AGENTS.override.md files."
+
+    def probe(self, path: Path) -> bool:
+        if path.is_file():
+            return path.name in DOC_FILENAMES
+        if not path.is_dir():
+            return False
+        return any(any(path.rglob(filename)) for filename in DOC_FILENAMES)
+
+    def detect_confidence(self, path: Path) -> int:
+        if not self.probe(path):
+            return 0
+        if path.is_file():
+            return 96 if path.name == "AGENTS.override.md" else 92
+        files = self._discover_docs(path)
+        score = 90
+        if any(file_path.name == "AGENTS.override.md" for file_path in files):
+            score += 5
+        if len(files) > 1:
+            score += 3
+        if any(len(file_path.relative_to(path).parts) > 1 for file_path in files):
+            score += 1
+        return min(score, 99)
+
+    def read(self, path: Path) -> CanonicalMemoryPackage:
+        root = (path.parent if path.is_file() else path).resolve()
+        docs = [path.resolve()] if path.is_file() else self._discover_docs(root)
+        package = CanonicalMemoryPackage(package_id=root.name or self.name, source_formats=[self.name])
+
+        for doc_path in docs:
+            relative_path = doc_path.relative_to(root).as_posix()
+            role = "override" if doc_path.name == "AGENTS.override.md" else "agents"
+            scope_dir = doc_path.parent.relative_to(root).as_posix() if doc_path.parent != root else "."
+            title = "Codex Override Instructions" if role == "override" else "Codex Repository Instructions"
+            if scope_dir != ".":
+                title = f"{title} ({scope_dir})"
+            package.add_entry(
+                MemoryEntry(
+                    id=slugify(relative_path.replace("/", "-")),
+                    kind="instruction",
+                    title=title,
+                    content=read_text(doc_path).strip(),
+                    tags=["codex", "agents", role],
+                    source_format=self.name,
+                    metadata={
+                        "filename": doc_path.name,
+                        "relative_path": relative_path,
+                        "codex_role": role,
+                        "scope_dir": scope_dir,
+                    },
+                )
+            )
+
+        return package
+
+    def write(self, package: CanonicalMemoryPackage, path: Path) -> None:
+        path.mkdir(parents=True, exist_ok=True)
+        entries = sorted(
+            package.entries,
+            key=lambda entry: (
+                0 if entry.metadata.get("codex_role") == "agents" else 1,
+                str(entry.metadata.get("relative_path", entry.id)),
+            ),
+        )
+        for entry in entries:
+            relative_path = str(entry.metadata.get("relative_path", "")).strip()
+            role = str(entry.metadata.get("codex_role", "agents"))
+            scope_dir = str(entry.metadata.get("scope_dir", ".")).strip()
+            target = self._resolve_output_path(path, relative_path, role, scope_dir)
+            write_text(target, entry.content.rstrip() + "\n")
+
+    def _discover_docs(self, root: Path) -> list[Path]:
+        files: list[Path] = []
+        for filename in DOC_FILENAMES:
+            files.extend(root.rglob(filename))
+        return sorted(set(files), key=lambda file_path: (len(file_path.relative_to(root).parts), file_path.as_posix()))
+
+    def _resolve_output_path(self, root: Path, relative_path: str, role: str, scope_dir: str) -> Path:
+        if relative_path and not Path(relative_path).is_absolute() and ".." not in Path(relative_path).parts:
+            return root / Path(relative_path)
+        filename = "AGENTS.override.md" if role == "override" else "AGENTS.md"
+        if scope_dir and scope_dir != ".":
+            return root / Path(scope_dir) / filename
+        return root / filename
diff --git a/src/memory_migrate_plugin/registry.py b/src/memory_migrate_plugin/registry.py
@@ -9,6 +9,7 @@
     ClaudeProjectAdapter,
     ClineMemoryBankAdapter,
     CodexMemoriesAdapter,
+    CodexRepoAdapter,
     CursorRulesAdapter,
     GenericJsonAdapter,
     MarkdownBundleAdapter,
@@ -20,6 +21,7 @@ def build_registry() -> dict[str, BaseAdapter]:
     adapters = [
         GenericJsonAdapter(),
         OpenHandsRepoAdapter(),
+        CodexRepoAdapter(),
         AgentsMdAdapter(),
         ClaudeCodeMemoryAdapter(),
         ClaudeProjectAdapter(),
diff --git a/tests/test_roundtrip.py b/tests/test_roundtrip.py
@@ -133,6 +133,7 @@ def test_official_fixtures_are_detectable(self) -> None:
             "fixtures/cline-memory-bank": "cline-memory-bank",
             "fixtures/agents-md": "agents-md",
             "fixtures/cursor-rules": "cursor-rules",
+            "fixtures/codex-repo": "codex-repo",
             "fixtures/claude-code-memory": "claude-code-memory",
             "fixtures/claude-project": "claude-project",
             "fixtures/openhands-repo": "openhands-repo",
@@ -152,6 +153,29 @@ def test_agents_md_adapter_reads_main_and_notes(self) -> None:
             self.assertEqual(len(package.entries), 2)
             self.assertEqual(package.entries[0].title, "AGENTS Instructions")
 
+    def test_detect_format_prefers_codex_repo(self) -> None:
+        matches = detect_format(Path("fixtures/codex-repo"))
+        self.assertEqual(matches[0][0], "codex-repo")
+
+    def test_codex_repo_reads_recursive_agents_documents(self) -> None:
+        package = normalize("codex-repo", Path("fixtures/codex-repo"))
+        self.assertEqual(len(package.entries), 4)
+        override_entry = next(entry for entry in package.entries if entry.metadata.get("codex_role") == "override")
+        self.assertEqual(override_entry.metadata["scope_dir"], "apps/web")
+        root_entry = next(entry for entry in package.entries if entry.metadata.get("relative_path") == "AGENTS.md")
+        self.assertEqual(root_entry.metadata["scope_dir"], ".")
+
+    def test_codex_repo_writes_expected_layout(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            from memory_migrate_plugin.core import convert
+
+            target = Path(tmpdir) / "codex-repo-out"
+            convert("codex-repo", Path("fixtures/codex-repo"), "codex-repo", target)
+            self.assertTrue((target / "AGENTS.md").exists())
+            self.assertTrue((target / "apps" / "web" / "AGENTS.md").exists())
+            self.assertTrue((target / "apps" / "web" / "AGENTS.override.md").exists())
+            self.assertTrue((target / "apps" / "api" / "AGENTS.md").exists())
+
     def test_detect_format_prefers_claude_project(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Root Agent Instructions`
	`2`	`+`
	`3`	`+Use small commits and keep migration artifacts deterministic.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# API Scope`
	`2`	`+`
	`3`	`+Prefer stable JSON outputs and explicit validation.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Web Scope`
	`2`	`+`
	`3`	`+Favor simple UI interactions and local-first workflows.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Web Override`
	`2`	`+`
	`3`	`+When touching the web console, preserve download and history behavior.`