@laitszkin/apollo-toolkit 2.2.0 → 2.4.0

package/AGENTS.md

@@ -16,6 +16,8 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can investigate application logs and produce evidence-backed root-cause findings.
 - Users can answer repository-backed questions with additional web research when needed.
 - Users can commit and push local changes without performing version or release work.
+- Users can manage Codex user-preference memory by reviewing the last 24 hours of chats, storing categorized memory documents under `~/.codex/memory`, and syncing a memory index into `~/.codex/AGENTS.md`.
+- Users can orchestrate Codex subagents for most non-trivial tasks by reusing or creating focused custom agents under `~/.codex/agents`, then delegating exploration, review, verification, and unrelated module work while keeping tightly coupled execution in the main agent.
 - Users can research a topic deeply and produce evidence-based deliverables.
 - Users can research the latest completed market week and produce a PDF watchlist of tradeable instruments for the coming week.
 - Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.4.0] - 2026-03-19
+
+### Added
+- Add `codex-memory-manager` for reviewing the last 24 hours of Codex chats, storing durable preference memory, and syncing a managed memory index into `~/.codex/AGENTS.md`.
+- Add extractor and index-sync helper scripts plus focused tests for the new Codex memory workflow.
+
+### Changed
+- Update `codex-subagent-orchestration` guidance, prompts, and routing notes to require explicit subagent spawning language for non-trivial tasks.
+
+### Removed
+- Remove the standalone OpenAI Codex subagent summary reference from `codex-subagent-orchestration` now that the skill documentation carries the needed guidance directly.
+
+## [v2.3.0] - 2026-03-18
+
+### Added
+- Add `codex-subagent-orchestration` for default subagent routing on most non-trivial Codex tasks, including reusable custom-agent catalog inspection, creation, and persistence guidance.
+- Add OpenAI-backed subagent references, a reusable custom-agent TOML template, and a routing rubric for splitting exploration, review, verification, and isolated implementation work.
+
+### Changed
+- Restrict `codex-subagent-orchestration` starter model guidance to `gpt-5.4` and `gpt-5.3-codex`.
+- Require reusable subagents to set `model_reasoning_effort` by delegated task complexity instead of using a single fixed effort.
+
 ## [v2.2.0] - 2026-03-18
 
 ### Added

package/README.md

@@ -8,6 +8,8 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - analyse-app-logs
 - answering-questions-with-research
 - commit-and-push
+- codex-memory-manager
+- codex-subagent-orchestration
 - deep-research-topics
 - develop-new-features
 - discover-edge-cases

package/codex-memory-manager/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/codex-memory-manager/README.md

@@ -0,0 +1,54 @@
+# codex-memory-manager
+
+Persist durable user preferences from recent Codex conversations into categorized memory files and a synchronized AGENTS index.
+
+## Highlights
+
+- Reads the last 24 hours of `~/.codex/sessions` and `~/.codex/archived_sessions`
+- Stores categorized preference memory under `~/.codex/memory/*.md`
+- Keeps a normalized memory index at the end of `~/.codex/AGENTS.md`
+- Adds new index entries automatically when new preference categories appear
+- Preserves the existing language already used in `~/.codex/AGENTS.md`
+
+## Project Structure
+
+```text
+.
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── agents/
+│   └── openai.yaml
+├── scripts/
+│   ├── extract_recent_conversations.py
+│   └── sync_memory_index.py
+└── tests/
+    ├── test_extract_recent_conversations.py
+    └── test_sync_memory_index.py
+```
+
+## Requirements
+
+- Python 3.9+
+- Access to `~/.codex/sessions`
+- Access to `~/.codex/archived_sessions`
+- Write access to `~/.codex/AGENTS.md`
+- Write access to `~/.codex/memory/`
+
+## Quick Start
+
+Extract the recent conversations:
+
+```bash
+python3 scripts/extract_recent_conversations.py --lookback-minutes 1440
+```
+
+Refresh the AGENTS memory index after updating the memory files:
+
+```bash
+python3 scripts/sync_memory_index.py --agents-file ~/.codex/AGENTS.md --memory-dir ~/.codex/memory
+```
+
+## License
+
+MIT. See `LICENSE` for details.

package/codex-memory-manager/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: codex-memory-manager
+description: Manage persistent Codex user-preference memory from recent conversation history. Use when users ask to learn from the last 24 hours of chats, update `~/.codex/AGENTS.md`, maintain `~/.codex/memory/*.md`, or sync new preference categories discovered in `~/.codex/sessions` and `~/.codex/archived_sessions`.
+---
+
+# Codex Memory Manager
+
+## Dependencies
+
+- Required: none.
+- Conditional: `learn-skill-from-conversations` when the same conversation review should also evolve the skill catalog.
+- Optional: none.
+- Fallback: If `~/.codex/sessions`, `~/.codex/archived_sessions`, or `~/.codex/AGENTS.md` are unavailable, report the missing path and stop instead of guessing.
+
+## Standards
+
+- Evidence: Derive memory only from actual recent Codex conversations, and keep each stored preference tied to concrete chat evidence.
+- Execution: Extract the last 24 hours first, classify durable user preferences into memory files, then refresh the AGENTS index section.
+- Quality: Ignore one-off instructions, avoid duplicating categories, and preserve the existing language and tone already used in `~/.codex/AGENTS.md`.
+- Output: Report which sessions were reviewed, which memory categories were created or updated, and whether the AGENTS index changed.
+
+## Goal
+
+Keep a durable, categorized memory of user preferences so future agents can quickly review relevant guidance before starting work.
+
+## Required Resources
+
+- `scripts/extract_recent_conversations.py` to read the last 24 hours of Codex sessions, including archived sessions.
+- `scripts/sync_memory_index.py` to maintain a normalized memory index section at the end of `~/.codex/AGENTS.md`.
+
+## Workflow
+
+### 1) Extract the last 24 hours of Codex conversations
+
+- Run:
+
+```bash
+python3 ~/.codex/skills/codex-memory-manager/scripts/extract_recent_conversations.py --lookback-minutes 1440
+```
+
+- The extractor reads both `~/.codex/sessions` and `~/.codex/archived_sessions`.
+- If output is exactly `NO_RECENT_CONVERSATIONS`, stop immediately and report that no memory update is needed.
+- Review every returned `[USER]` and `[ASSISTANT]` block before deciding that a preference is stable.
+- The extractor also cleans up stale session files after reading, matching the existing conversation-learning workflow.
+
+### 2) Distill only stable user preferences
+
+- Focus on preferences that are durable and reusable, such as:
+  - architecture and abstraction preferences
+  - code style and naming preferences
+  - workflow preferences
+  - testing expectations
+  - language- or ecosystem-specific preferences
+  - reporting and communication format preferences
+- Ignore transient task details, secrets, and one-off requests that are not likely to generalize.
+- Prefer explicit user instructions. Use assistant behavior as supporting context only when it clearly reflects repeated user guidance.
+
+### 3) Classify preferences into memory documents
+
+- Store memory files under `~/.codex/memory/*.md`.
+- Reuse an existing category file when the new preference clearly belongs there.
+- Create a new category file when the recent chats introduce a distinct new class of preferences. Example: if the existing files are Rust-focused and recent chats introduce stable Java preferences, add a new Java-oriented category file and index it.
+- Keep filenames in kebab-case and scoped to a real category, for example:
+  - `architecture-preferences.md`
+  - `workflow-preferences.md`
+  - `java-preferences.md`
+- Use this normalized structure inside each memory file:
+
+```md
+# Architecture Preferences
+
+## Scope
+User preferences about system design, reuse, abstractions, and code organization.
+
+## Preferences
+- Prefer extending existing modules over parallel implementations.
+  - Applies when: adding adjacent behavior in an existing codebase.
+  - Evidence: repeated direction from recent Codex conversations reviewed on 2026-03-18.
+- Avoid speculative abstractions and over-engineering.
+  - Applies when: choosing between a focused edit and a broader refactor.
+  - Evidence: explicit repeated user guidance in recent sessions.
+
+## Maintenance
+- Keep entries concrete and action-guiding.
+- Merge duplicates instead of restating the same preference.
+- Replace older statements when newer evidence clearly supersedes them.
+```
+
+### 4) Refresh the AGENTS memory index at the end of `~/.codex/AGENTS.md`
+
+- First inspect `~/.codex/AGENTS.md` and mirror its existing language in the memory section instructions.
+- After updating memory files, run `scripts/sync_memory_index.py` to rewrite the managed section at the end of the file.
+- The section must do both of these things explicitly:
+  - instruct future agents to review the index before starting work
+  - instruct future agents to update the matching memory files and refresh the index when a new category appears
+- Example command in English AGENTS files:
+
+```bash
+python3 ~/.codex/skills/codex-memory-manager/scripts/sync_memory_index.py \
+  --agents-file ~/.codex/AGENTS.md \
+  --memory-dir ~/.codex/memory \
+  --section-title "## User Memory Index" \
+  --instruction-line "Before starting work, review the index below and open any relevant user preference files." \
+  --instruction-line "When a new preference category appears, create or update the matching memory file and refresh this index."
+```
+
+- The script writes a managed block with markdown links to every indexed memory file.
+- Keep the managed block at the tail of `~/.codex/AGENTS.md`; do not scatter memory links elsewhere in the file.
+
+### 5) Report the memory update
+
+- Summarize:
+  - how many sessions were reviewed
+  - which categories were created or updated
+  - whether a new category was introduced
+  - whether the AGENTS memory index changed
+- If no durable preferences were found, say so explicitly and avoid creating placeholder memory files.
+
+## Guardrails
+
+- Do not store secrets, tokens, credentials, or personal data that should not persist.
+- Do not invent preferences when the evidence is weak or ambiguous.
+- Do not create duplicate categories when a current memory document already covers the same theme.
+- Do not rewrite unrelated parts of `~/.codex/AGENTS.md`; only manage the memory index block at the end.

package/codex-memory-manager/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Memory Manager"
+  short_description: "Persist user preferences from recent Codex chats"
+  default_prompt: "Use $codex-memory-manager to review the last 24 hours of Codex sessions, update ~/.codex/memory/*.md, and refresh the memory index at the end of ~/.codex/AGENTS.md."

package/codex-memory-manager/scripts/extract_recent_conversations.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""Extract recent Codex conversation history from Codex session stores."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+DEFAULT_LOOKBACK_MINUTES = 24 * 60
+DEFAULT_RETENTION_DAYS = 7
+
+
+@dataclass
+class SessionRecord:
+    path: Path
+    timestamp_utc: datetime
+    messages: Optional[List[Tuple[str, str]]] = None
+
+
+def parse_iso_timestamp(raw: Optional[str]) -> Optional[datetime]:
+    if not raw:
+        return None
+    value = raw.strip()
+    if not value:
+        return None
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def read_session_timestamp(path: Path) -> Optional[datetime]:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            first_line = handle.readline().strip()
+    except OSError:
+        return None
+
+    if not first_line:
+        return None
+
+    try:
+        first_entry = json.loads(first_line)
+    except json.JSONDecodeError:
+        return None
+
+    if first_entry.get("type") != "session_meta":
+        return None
+
+    payload = first_entry.get("payload", {})
+    if not isinstance(payload, dict):
+        return None
+
+    return parse_iso_timestamp(payload.get("timestamp")) or parse_iso_timestamp(first_entry.get("timestamp"))
+
+
+def iter_session_paths(root: Path) -> Iterable[Path]:
+    if not root.exists() or not root.is_dir():
+        return
+    yield from root.rglob("*.jsonl")
+
+
+def find_recent_sessions(
+    session_roots: Sequence[Path],
+    cutoff_utc: datetime,
+    limit: Optional[int],
+) -> List[SessionRecord]:
+    candidates: List[SessionRecord] = []
+    seen_paths = set()
+
+    for root in session_roots:
+        for path in iter_session_paths(root):
+            resolved_path = path.resolve()
+            if resolved_path in seen_paths:
+                continue
+            seen_paths.add(resolved_path)
+
+            timestamp_utc = read_session_timestamp(path)
+            if timestamp_utc is None:
+                continue
+            if timestamp_utc < cutoff_utc:
+                continue
+            candidates.append(SessionRecord(path=path, timestamp_utc=timestamp_utc))
+
+    candidates.sort(key=lambda record: record.timestamp_utc, reverse=True)
+    if limit is None:
+        return candidates
+    return candidates[:limit]
+
+
+def sanitize_text(text: str, max_chars: int) -> str:
+    cleaned = text.replace("\r\n", "\n").replace("\r", "\n").strip()
+    if max_chars <= 0:
+        return cleaned
+    if len(cleaned) <= max_chars:
+        return cleaned
+    return cleaned[: max_chars - 1].rstrip() + "..."
+
+
+def looks_like_wrapper_message(text: str) -> bool:
+    stripped = text.strip()
+    if not stripped:
+        return True
+    lower = stripped.lower()
+    return (
+        stripped.startswith("# AGENTS.md instructions for")
+        or stripped.startswith("<environment_context>")
+        or "<collaboration_mode>" in lower
+        or stripped.startswith("<permissions instructions>")
+        or stripped.startswith("<app-context>")
+    )
+
+
+def extract_text_from_content(content: Sequence[object]) -> str:
+    texts: List[str] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        part_type = part.get("type")
+        if part_type in {"input_text", "output_text", "text"}:
+            value = part.get("text", "")
+            if isinstance(value, str) and value.strip():
+                texts.append(value)
+    return "\n".join(texts).strip()
+
+
+def extract_messages_from_event_entries(entries: Iterable[dict], max_chars: int) -> List[Tuple[str, str]]:
+    messages: List[Tuple[str, str]] = []
+    for entry in entries:
+        if entry.get("type") != "event_msg":
+            continue
+        payload = entry.get("payload", {})
+        if not isinstance(payload, dict):
+            continue
+
+        payload_type = payload.get("type")
+        if payload_type == "user_message":
+            text = payload.get("message", "")
+            if isinstance(text, str) and text.strip():
+                messages.append(("user", sanitize_text(text, max_chars)))
+        elif payload_type == "agent_message":
+            text = payload.get("message", "")
+            if isinstance(text, str) and text.strip():
+                messages.append(("assistant", sanitize_text(text, max_chars)))
+    return messages
+
+
+def extract_messages_from_response_items(entries: Iterable[dict], max_chars: int) -> List[Tuple[str, str]]:
+    messages: List[Tuple[str, str]] = []
+    for entry in entries:
+        if entry.get("type") != "response_item":
+            continue
+        payload = entry.get("payload", {})
+        if not isinstance(payload, dict):
+            continue
+        if payload.get("type") != "message":
+            continue
+
+        role = payload.get("role")
+        if role not in {"user", "assistant"}:
+            continue
+
+        text = extract_text_from_content(payload.get("content", []))
+        if not text or looks_like_wrapper_message(text):
+            continue
+        messages.append((role, sanitize_text(text, max_chars)))
+    return messages
+
+
+def extract_session_messages(path: Path, max_chars: int) -> List[Tuple[str, str]]:
+    entries: List[dict] = []
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return []
+
+    event_messages = extract_messages_from_event_entries(entries, max_chars)
+    if event_messages:
+        return event_messages
+    return extract_messages_from_response_items(entries, max_chars)
+
+
+def delete_matching_files(root: Path, predicate) -> int:
+    if not root.exists() or not root.is_dir():
+        return 0
+
+    deleted_count = 0
+    for path in root.rglob("*.jsonl"):
+        if not predicate(path):
+            continue
+        try:
+            path.unlink()
+        except OSError:
+            continue
+        deleted_count += 1
+    return deleted_count
+
+
+def path_is_same_or_nested(path: Path, root: Optional[Path]) -> bool:
+    if root is None:
+        return False
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def cleanup_session_history(
+    sessions_dir: Path,
+    archived_sessions_dir: Path,
+    retention_cutoff_utc: datetime,
+) -> Tuple[int, int]:
+    sessions_root = sessions_dir.resolve() if sessions_dir.exists() else None
+    removed_old_sessions = delete_matching_files(
+        sessions_dir,
+        lambda path: (
+            (timestamp := read_session_timestamp(path)) is not None
+            and timestamp < retention_cutoff_utc
+        ),
+    )
+    removed_archived_sessions = delete_matching_files(
+        archived_sessions_dir,
+        lambda path: not path_is_same_or_nested(path, sessions_root),
+    )
+    return removed_old_sessions, removed_archived_sessions
+
+
+def render_text_output(
+    records: Sequence[SessionRecord],
+    lookback_minutes: int,
+    max_message_chars: int,
+    removed_old_sessions: int,
+    removed_archived_sessions: int,
+) -> str:
+    if not records:
+        return "NO_RECENT_CONVERSATIONS"
+
+    lines: List[str] = [
+        f"RECENT_CONVERSATIONS_FOUND={len(records)}",
+        f"LOOKBACK_MINUTES={lookback_minutes}",
+        "ARCHIVED_SESSIONS_INCLUDED=true",
+        f"CLEANUP_REMOVED_OLD_SESSIONS={removed_old_sessions}",
+        f"CLEANUP_REMOVED_ARCHIVED_SESSIONS={removed_archived_sessions}",
+    ]
+
+    for index, record in enumerate(records, start=1):
+        lines.append(f"=== SESSION {index} ===")
+        lines.append(f"TIMESTAMP_UTC={record.timestamp_utc.isoformat()}")
+        lines.append(f"FILE={record.path}")
+
+        messages = record.messages
+        if messages is None:
+            messages = extract_session_messages(record.path, max_message_chars)
+        if not messages:
+            lines.append("MESSAGES=NONE")
+            continue
+
+        for role, message in messages:
+            tag = "USER" if role == "user" else "ASSISTANT"
+            lines.append(f"[{tag}]")
+            lines.append(message)
+            lines.append(f"[/{tag}]")
+
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Extract the latest conversation history from Codex session stores",
+    )
+    parser.add_argument(
+        "--sessions-dir",
+        default="~/.codex/sessions",
+        help="Path to the Codex sessions directory (default: ~/.codex/sessions)",
+    )
+    parser.add_argument(
+        "--archived-sessions-dir",
+        default="~/.codex/archived_sessions",
+        help="Path to archived Codex sessions (default: ~/.codex/archived_sessions)",
+    )
+    parser.add_argument(
+        "--lookback-minutes",
+        type=int,
+        default=DEFAULT_LOOKBACK_MINUTES,
+        help=f"How far back to look for sessions (default: {DEFAULT_LOOKBACK_MINUTES})",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="Maximum number of sessions to return (default: all within lookback window)",
+    )
+    parser.add_argument(
+        "--max-message-chars",
+        type=int,
+        default=1600,
+        help="Maximum characters per extracted message (default: 1600)",
+    )
+    parser.add_argument(
+        "--retention-days",
+        type=int,
+        default=DEFAULT_RETENTION_DAYS,
+        help=f"Delete sessions older than this many days after reading (default: {DEFAULT_RETENTION_DAYS})",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    sessions_dir = Path(args.sessions_dir).expanduser().resolve()
+    archived_sessions_dir = Path(args.archived_sessions_dir).expanduser().resolve()
+    lookback_minutes = max(args.lookback_minutes, 1)
+    limit = args.limit if args.limit is not None and args.limit > 0 else None
+    max_message_chars = max(args.max_message_chars, 100)
+    retention_days = max(args.retention_days, 1)
+    now_utc = datetime.now(timezone.utc)
+
+    if (
+        (not sessions_dir.exists() or not sessions_dir.is_dir())
+        and (not archived_sessions_dir.exists() or not archived_sessions_dir.is_dir())
+    ):
+        print("NO_RECENT_CONVERSATIONS")
+        return 0
+
+    cutoff_utc = now_utc - timedelta(minutes=lookback_minutes)
+    recent_records = find_recent_sessions((sessions_dir, archived_sessions_dir), cutoff_utc, limit)
+    for record in recent_records:
+        record.messages = extract_session_messages(record.path, max_message_chars)
+
+    retention_cutoff_utc = now_utc - timedelta(days=retention_days)
+    removed_old_sessions, removed_archived_sessions = cleanup_session_history(
+        sessions_dir,
+        archived_sessions_dir,
+        retention_cutoff_utc,
+    )
+
+    print(
+        render_text_output(
+            recent_records,
+            lookback_minutes,
+            max_message_chars,
+            removed_old_sessions,
+            removed_archived_sessions,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())