Seamless

The coding agent that remembers why a bug was hard.

Seamless is a global MCP integration for Codex. It turns a resolved debugging session into a schema-validated, evidence-grounded trace, then makes relevant past traces available when a similar failure appears in another repo. The useful output is not a generic summary: it preserves what was ruled out, why it was ruled out, the root cause, and constraints that still matter.

What it does

resolved debugging session
  -> structured extraction
  -> schema validation + evidence grounding
  -> shared SQLite memory
  -> fixed-threshold semantic retrieval
  -> focused guidance for the next investigation

The MCP server exposes three small operations:

• extract_trace stores one validated debugging trace.
• query_traces returns only strong prior matches; otherwise it says there is no strong match.
• get_trace retrieves a stored trace by ID.

Grounding is enforced before storage. A ruled-out cause without support in the source evidence is marked ungrounded and is not presented as confirmed fact.

Supported platform

The one-command installers support Windows 10/11 and macOS, with Python 3.11 or newer and Codex installed. Windows uses PowerShell; macOS uses the system Bash shell. Linux is not yet packaged with an installer.

Install for a judge

Clone this repository, then run the command for your platform.

Windows

powershell -ExecutionPolicy Bypass -File .\install.ps1

macOS

bash ./install.sh

The installer creates a local virtual environment, installs dependencies, caches the local retrieval model, registers the MCP server globally with Codex, and installs the save and retrieval skills globally. It stores shared memory at ~\.debug-memory\traces.db, while retaining project identity so a project is searched first before strong cross-project matches are considered.

Open a new Codex task in any repository after installation. No manual MCP server process is needed: Codex starts the stdio server when it needs it.

To include verification during installation, append -Verify on Windows or --verify on macOS:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Verify

bash ./install.sh --verify

Fast, reproducible judge test

This is deliberately designed to work in a judge's own repositories.

1. In a disposable repository, use Codex to investigate and fix a real or small intentionally introduced bug.
2. After the fix, invoke /remember-debugging-trace and confirm the save. Codex submits only the evidence from that resolved session.
3. In another repository, reproduce a related symptom and invoke /query-trace. Codex returns a strong prior match with grounded ruled-out causes and constraints, or honestly reports that no strong match exists.

The skills invoke MCP tools behind the scenes; judges never need to construct JSON or operate the SQLite database. The first semantic request may briefly report that the local model is warming. Retry once after about 30 seconds; the local embedding worker then stays available for later Codex tasks.

Built with Codex and GPT-5.6

I used Codex as the engineering environment for the project, not merely as a code generator. I used it to turn product rules into durable AGENTS.md guidance, implement the FastMCP and SQLite pipeline, create the global installer and reusable skills, reproduce stdio and retrieval-latency failures, and add focused regression coverage for those integration paths.

To accelerate that work, I configured reusable Codex slash-command skills that mirrored the workflow categories in my Claude Code plugin setup: project setup, AGENTS.md management, code review, code simplification, current documentation lookup, frontend work, and disciplined implementation. That made repeatable engineering activities explicit, inspectable commands instead of one-off prompts, while keeping the product and architecture decisions mine.

The key product decisions were mine: extraction is explicit and user-confirmed; raw model output is never stored; grounding is deterministic; weak matches are not forced; and projects retain separate identities even when a strong prior match can be useful across repositories.

GPT-5.6 is the configured live extraction model when OPENAI_API_KEY is available (DEBUG_MEMORY_MODEL defaults to gpt-5.6). It produces the candidate structured trace from a resolved transcript. The agent then validates the required schema and grounds ruled-out reasons against the transcript before anything is saved. Fixture-based tests remain deterministic and do not pretend to be live model output.

Development and verification

python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
.venv\Scripts\python -m pytest tests -q

For direct MCP protocol troubleshooting only:

.venv\Scripts\python debug_memory_agent\mcp_server.py

The server will appear idle until an MCP client connects; that is expected.

Privacy and scope

Only save traces you are permitted to retain. The tool asks for confirmation before saving; it does not automatically capture every debugging session.

License

This project is licensed under the MIT License.