Content
AI Parallelration MCP
- A local MCP server that automatically saves Codex work history and helps you find important results later.
### Background
- AI conversations make it difficult to accumulate and reuse work context, tasks in one session make it inconvenient to review results.
- This project separates memory, execution, and result collection to create a repeatable development and operation flow.
### Idea Presentation
- Obsidian vault is a human-readable memory document storage.
- QMD indexes and searches stored documents.
- Codex CLI is an independent work executor, and the MCP server provides these functions as a single toolset.
### What Can You Do?
- Save important work decisions or notes and search them later.
- Run independent Codex tasks and check their progress and final results.
- Divide large tasks into dependent tasks or handle multiple issues in parallel.
- When starting a Codex task, automatically find related memories and reference them, and automatically remember the result summary upon success.
### Easiest Way to Use
Connect to the deployed service with Codex or MCP client and request in natural language. General users do not need to know server installation, QMD, or storage file structure.
#### Code Example Prompts
You can request the MCP tool by entering the following sentences intox conversation.session-id>` and the the previous response or actual project environment.
| Tool | Example Prompt |
| --- | --- |
health_check` | `Call_check of orchestration check Codex, Q vault, session root settings tools.` |
|` | `Save "" with orchestration MCP. The content is "Maintain a file-based session store for," and automatically classify the |
| `recall`Search for up to 5 "file-based session store decisions" with orchestration MCP's recall.` |
| `spawn_session `Run the test failure cause modification in C:\\Users\\you\\project with orchestration MCP's spawn_session. The verification command is npm test.` |
| `check_inbox` | `Call check_inbox of orchestration MCP to summarize running, successful, and failed sessions.` |
| `get_session` | `Show the status, last message, result, and recent of the <session-id> session with orchestration MCP's get_session.` |
| `close_session` | `Close the completed <session-id> session with orchestration MCP's close_session.` |
| `send_message` | `Save the follow-up instruction "Review changes again and run npm test next time" tosession-id> session with orchestration MCP's send_message.` |
| `run_task_dag` | `Run inspect and fix tasks in C:\\Users\\you with orchestration MCP_task_dag. Inspect cause, fix modifies after inspection, and both tasks' verification command is npm test.` |
| `run_branch_hunt` | `Explore C:\\Users\\you\\project with orchestration MCP's run_branch_hunt to find up to 3 reproducible errors and fix each. Each task's verification command is npm test.` |
- `<session-id>` in `get_session`, `close_session`,_message` can be found response of `spawn_sessionrun_task_dag`, `run_branch_hunt`, or `check_inbox`.
- `send_message` does not deliver messages to running sessions immediately but stores them in a queue for the next re-run or resume.
- `run_task_dag` and `run_branch_hunt` must specify verification commands.
### Limitations
- Codex sessions executed by this MCP search memories before starting without a separate `recall` request and store a summary in RAG after success without a separate ` request.
- Original conversationL execution logs are not stored in RAG. Only task summaries, result summaries, event counts, and verification commands are stored.
- Conversations outside this MCP, like regular Codex screen conversations, are not automatically remembered.
- No real-time messages are injected into running tasks. Follow-up instructions are stored in a queue for re-execution.
### Core Concepts
- `remember`: Stores knowledge documents and requests QMD indexing.
- `recall`: Finds stored knowledge with QMD search and returns it in standard JSON.
- `spawn_session`: Starts a separate Codex session and stores execution results.
- Automatic memory: Searches QMD for related memories before session start and adds them to the prompt, and stores a summary in the vault upon success.
- `Task DAG`: Runs tasks in parallel based on dependencies.
- `Branch Hunt`: Divides code exploration results into independent tasks.
- `Ralph Loop`: Requests modification and re-verification until a specified verification command passes.
### Structure/Architecturetext
MCP client
├─ remember / recall ───────────────> Obsidian vault + QMD
└─ session / DAG / Branch Hunt ────> Codex CLI
├─ Automatic QMD search before execution
└─ Automatic result summary storage after success
└─ session_root/<session_id>/
metadata, events, result, last message
```
- MCP Interfaceates input and returns tool results.
- Execution Layer:x and QMD commands.
- Storage Layer: Stores session metadata, logs, results, and follow-up instructions as files.
- For detailed structure, see [ARCHITECTURE.md](ARCHITECTURE.md), data flow in [DATA_FLOW.md](DATA_FLOW.md), and document purposes in [DOC_INDEX.md](DOC_INDEX.md).
### Technical Configuration
- Written in Node.js 24 and TypeScript.
- Providesio tool server with MCP SDK, YAML configuration, and Zod input validation.
- External integrations are with Codex CLI and QMD CLI, with detailed behavior implemented by the respective projects.
### Quick Start
1. Install dependencies and build.
```powershell
& 'C:\Program Files\nodejs\npm.cmd' install
& 'C:\Program Files\nodejs\npm.cmd' run build
```
2. Copy example settings and fill in paths and execution policies according to your environment.
```powershell
Copy-Item .\config.example.yaml .\config.yaml
```
3. Register the std server with Codex. An example `.codex\config.toml` is shown below.
```toml
[mcp_servers.orchestration]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Users\you\MCP_Orchestration\dist\src\server.js']
cwd = 'C:\Users\you\MCP_Orchestration'
env = { ORCHESTRATION_CONFIG =:\Users\you\MCP_Orchestration\config.yaml' }
startup_timeout_sec = 15
tool_timeout_sec = 600
```
4. Restart Codex. Codex will automatically start the stdio server; you do not need the server window separately.
### Configuration
- Copy `.yaml` to `config.yaml`.
- All settings are required; no implicit defaults are used.
- Key settings:
- `codex_executable`: Absolute path to `codex.cmd`
- `workspace_root`: Root path for Codex to work in
- `session_root`: Path to store session outputs
- `obsidian_vault_path`: Path to store memory Markdown files
- `qmd_executable`, `qmd_search_command`, `qmd_index_command`: QMD execution information
- `codex_model`, `codex_sandbox`, `codex_approval_policy`: Codex execution policies
max_parallel_sessions`,ph_max_consecutive_failures`, `session_timeout_seconds`: Execution limits
- `auto_remember_on_success`: Automatically save summaries of successful MCP Codex sessions
- `auto_recall_before_session`: Automatically search memories before Codex sessions start
- `auto_recall_limit`: Number of automatic search results
- `auto_summary_max_chars`: Maximum characters for automatic summaries
### Tool Invocation Examples
MCP clients can directly display tool inputs in the following JSON format. In regular Codex conversations, you can also request using natural language examples above.
```json
{
"title": "Deployment Decision",
"body": "Maintain a file-based session store for this deployment."
}
```
This input is a `remember` call. The `memory` default tag and title/body-derived tags are automatically stored. You can also pass `tags` directly to add to automatic tags.
### Tool List
| Tool | Purpose |
| --- | --- |
| `health_check` | Checks execution path and registered tools. |
| `remember`, `recall` | Stores and retrieves memories. |
| `spawn_session` | Runs independent Codex tasks. |
| `check_inbox`, `get_session`, `close_session` | Manages task results and statuses. |
| `send_message` follow-up instructions for next execution. |
| `run_task_dag` | Runs parallel tasks based on dependencies. |
| `run_branch_hunt` | Explores code, divides issues into tasks, and executes them. |
### Operation
- Start connection confirmation with `health_check`.
- Check session results with `check_inbox` or `get_session`.
- When the server starts, it automatically marks remaining sessions previous server instance as ` if they were `queued` or `running`.
- Recovered sessions can be confirmedget_session`'recovery`, `result.json`'s `recovered`, and `events.jsonl`'s `startup_recovery` event.
### Differences from Existing Methods
- Separates knowledge and execution, making it reusable and reviewable.
- Leaves each execution result in file for later confirmation.
- Automatically searches related memories session and accumulates successful results in limited-length summaries.
### Future Plans
- Implement control and automatic resume of queued messages for running sessions.
- Expand to SQLite storage and session dashboards.
### Conclusion
- This project enhances the orchestration of AI tools, making task management and result tracking more efficient.
