Prepare v0.4: reliable memory, traceable corrections and executable evaluation

[Ninadnj]

Shared project memory needs reliable identity, safe corrections and evidence that it helps real work. This candidate completes the reliability and correction implementation, adds an executable evaluation harness and demo, and prepares v0.4.0rc1 for review.

Changes

• Includes the existing UUID4 ID fix; preserves explicit and legacy IDs and rejects duplicates.
• Uses OS locks, stale-snapshot checks, atomic replacement and rollback for failed writes; validates stored data and persists embedding configuration.
• Adds revisions, source inspection, bounded history and supersession. MCP/CLI edits require the revision the caller read.
• Fixes hook prompt input, startup freshness, worklog observations, exact deduplication and complete rendered-text budgets.
• Adds 30 executable coding fixtures across three synthetic projects, an external-agent runner, and a two-process MCP handoff demo.
• Adds onboarding, migration/security/contribution notes, package checks and OS/SDK CI jobs.
• Fixes Windows executable detection and transient atomic-replacement sharing errors, with bounded retries that preserve the original file on permanent failure.

September 12 follow-up

• Adds a bundled Codex CLI adapter and --codex-model runner shortcut, with preflight before task execution.
• Records CLI version, adapter hash, requested model/settings and completion-event usage without inventing missing telemetry.
• Retains bounded failure diagnostics and kills the adapter/tool process tree on Windows timeouts.
• Adds 32 offline tests and macOS Python 3.12 CI. Production memory code and task fixtures are unchanged in this follow-up.
• Resolves the quoted-executable review thread against the existing tested fix.

Validation

• Existing baseline: 159 passed, 1 skipped.
• Fourteen new regressions failed before implementation; the first new commit preserves that state.
• Focused reliability/identity tests: 136 passed.
• Latest adapter/runner/Windows focused selection: 73 passed, 0 failed, 0 skipped.
• Latest full hashing suite: 297 passed, 0 failed, 1 skipped.
• MCP 1.30.0 and 2.2.0 focused selections: 53 passed each.
• Five additional Windows regressions failed before their fixes; the focused Windows/hooks/persistence selection then passed all 79 tests.
• All 30 graders reject their broken implementation and accept their reference fix.
• Existing retrieval results unchanged; both demos, lint, wheel/sdist build and fresh-wheel smoke passed.

Previous candidate GitHub Actions on 0c227afc6e1d8be6c31067a57cac6e7d665e6eb6: 6 jobs passed; 1 optional semantic job skipped. Linux Python 3.10/3.12 and Windows Python 3.12 each ran the full suite: 265 passed, 0 failed, 1 skipped. Both MCP SDK jobs and fresh package installation passed. CI results.

Implementation CI on f18e156c7b0c473c301a816f7f4d0544417c4868 is green: 7 jobs passed; 1 optional semantic job skipped. Linux Python 3.10/3.12, Windows Python 3.12 and macOS Python 3.12 each completed the full suite with 297 passed, 0 failed, 1 skipped. Both MCP SDK jobs and fresh package installation passed. Latest CI run.

Compatibility and remaining evidence
Format 3 requires all shared writers to upgrade together. MCP/CLI edits now require expected_revision. Python retains optional revision guards for compatibility. Existing records outside new input limits remain editable.

The optional semantic model remains untested. Linux, Windows, macOS and both supported Python versions were verified in GitHub Actions. Codex CLI 0.154.0 version/help/login preflight passed, but two 45-second connection pilots produced no completed task; the diagnostic retry recorded 401 Unauthorized. The maintainer has deferred the 18-session calibration and 216-session test comparison for this candidate. No further live evaluation or authentication is required for candidate preparation. Live client use of MCP remains unverified; fixture verification does not establish agent performance, and the README makes no new coding-performance claim. The 0.4.0rc1 wheel and sdist built successfully and passed fresh-install checks. GitHub/PyPI publication remains pending: the connected GitHub tools provide no release action, and the browser connection failed.

See docs/verification-v0.4.md and docs/verification-codex-adapter.md for commands/evidence, docs/evaluation.md for the live-run procedure, and docs/migration-v0.4.md for upgrade/rollback details.

Release-scope follow-up

• Records the deferred live evaluation in the README, evaluation guide, changelog and verification record.
• Adds reusable prerelease notes with upgrade/rollback steps and completed platform evidence.
• Keeps the release at 0.4.0rc1 with no coding-performance or whole-session token-savings claim.
• Changes documentation only; production code, tests and task fixtures are unchanged.

Local follow-up checks passed: AGENT_MEMORY_EMBEDDER=hashing python examples/handoff_demo.py, python -m build, python scripts/check_wheel.py, and git diff --check. The clean wheel check verifies installed imports, legacy-ID correction/reopen, MCP construction and CLI doctor. Current-head CI on b683504d3a5b8d52c10bfc1280f47649f1e06262 is green: 7 jobs passed; 1 optional semantic job skipped. Linux Python 3.10/3.12, Windows Python 3.12 and macOS Python 3.12 each ran AGENT_MEMORY_EMBEDDER=hashing python -m pytest -q -ra with 297 passed, 0 failed, 1 skipped. Both MCP SDK jobs and package/fresh-install verification passed. Current CI run.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ac5819d9af

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".