Memex CLI Skill | Agent Skills

Memex CLI

A CLI wrapper for AI backends (Codex, Claude, Gemini) with built-in memory and resume capabilities.

Core Concepts

memex-cli uses stdin protocol to define tasks, allowing:

Multi-backend AI execution (codex, claude, gemini)
Parallel and sequential task orchestration
Resume from previous runs with full context
File loading for context-aware tasks
Structured output (text or JSONL)

Basic Task Syntax

memex-cli run --stdin <<'EOF'
---TASK---
id: <task_id>
backend: <backend>
workdir: <working_directory>
---CONTENT---
<prompt>
---END---
EOF

Required Parameters

| Parameter | Description | Example | |-----------|-------------|---------| | id | Unique task identifier | implement-auth-20260110 | | backend | AI backend | codex, claude, gemini | | workdir | Working directory path | ./project or /home/user/app | | <prompt> | Task prompt content | Describe what to implement |

Optional Parameters

| Parameter | Description | Default | Example | |-----------|-------------|---------|---------| | model | Specific model name | Backend default | gpt-5.2, gpt-5.1-codex-max | | model-provider | Model provider | openai | For codex backend | | dependencies | Task dependencies | None | task-a or task-a,task-b | | timeout | Timeout in seconds | 300 | 600 (10 minutes) | | retry | Retry count on failure | 0 | 2 (retry twice) | | files | File paths to load | None | src/**/*.py (glob supported) | | files-mode | File handling mode | embed | ref, auto | | files-encoding | File encoding | utf-8 | base64, auto | | stream-format | Output format | text | jsonl |

Backend Selection

Codex - Code Generation

Optimized for code implementation and refactoring.

---TASK---
id: code-gen
backend: codex
workdir: ./project
model: gpt-5.2
---CONTENT---
实现用户认证模块
---END---

Best for: Code generation, refactoring, test writing

Claude - Design & Architecture

Optimized for system design and architecture planning.

---TASK---
id: design
backend: claude
workdir: ./project
---CONTENT---
设计 REST API 架构
---END---

Best for: System design, architecture, documentation

Gemini - Multimodal Tasks

Supports image and document analysis.

---TASK---
id: ux-review
backend: gemini
workdir: ./project
files: ./mockups/*.png
files-mode: embed
---CONTENT---
审查 UX 设计稿
---END---

Best for: UI/UX review, image analysis, multimodal tasks

Task ID Patterns

Recommended patterns:

# Timestamp format (unique)
task-20260110143052
implement-auth-20260110143052

# Semantic format (readable)
design-api
implement-backend
test-integration

# Hierarchical format (organized)
auth.design
auth.implement
auth.test

Avoid generic IDs like task1, task2.

Multi-Task Execution

Define multiple tasks in one stdin input:

memex-cli run --stdin <<'EOF'
---TASK---
id: task-1
backend: codex
workdir: ./project
---CONTENT---
First task
---END---

---TASK---
id: task-2
backend: codex
workdir: ./project
---CONTENT---
Second task
---END---
EOF

Execution modes:

Parallel (default) - Tasks without dependencies run simultaneously
DAG (sequential) - Tasks with dependencies: run in order

See references/advanced-usage.md for detailed multi-task documentation.

Resume Functionality

Continue from a previous run using --run-id:

# Initial run outputs Run ID
memex-cli run --stdin < task.md
# Output: Run ID: abc123-def456

# Resume from that run
memex-cli resume --run-id abc123-def456 --stdin <<'EOF'
---TASK---
id: continue
backend: codex
workdir: ./project
---CONTENT---
基于之前的实现添加功能
---END---
EOF

Context preservation:

Previous task outputs available
Conversation history maintained
File changes visible

See references/advanced-usage.md for resume strategies.

Output Formats

Text Format (Default)

Human-readable with status markers:

▶ task-id (backend/model)
[AI output content]
» 写入 file.py
✓ task-id 3.5s

Status markers: ▶ (start), ✓ (success), ✗ (failed), ⟳ (retry), » (action)

JSONL Format

Machine-readable JSON Lines for programmatic parsing:

memex-cli run --stdin --stream-format jsonl < tasks.md

Output:

{"v":1,"type":"task.start","ts":"2026-01-10T10:00:00Z","run_id":"abc","task_id":"code-gen"}
{"v":1,"type":"assistant.output","ts":"2026-01-10T10:00:01Z",...}
{"v":1,"type":"task.end","ts":"2026-01-10T10:00:03Z",...}

See references/output-formats.md for complete format specifications.

Quick Start Examples

Single task:

memex-cli run --stdin < examples/basic-task.md

Parallel tasks:

memex-cli run --stdin < examples/parallel-tasks.md

DAG workflow:

memex-cli run --stdin < examples/dag-workflow.md

All examples are in examples/ directory with full task definitions.

Additional Resources

Reference Documentation

For detailed information on advanced features:

references/output-formats.md - Complete output format specifications
- Text format status markers
- JSONL event types
- Parsing examples
references/advanced-usage.md - Advanced usage patterns
- Multi-task parallel execution
- DAG dependency configuration
- Resume strategies
- File loading modes
- Timeout and retry configuration
references/troubleshooting.md - Comprehensive troubleshooting guide
- Installation and authentication issues
- Task execution failures
- File loading problems
- Dependency and resume errors
- Performance optimization
- Advanced debugging techniques

Working Examples

Ready-to-use task files in examples/:

examples/basic-task.md - Single task implementation
examples/parallel-tasks.md - Independent parallel tasks
examples/dag-workflow.md - Complete workflow with dependencies
examples/resume-workflow.md - Iterative development with resume

Copy and customize these examples for your projects.

Common Workflows

Code Implementation

# Generate code with Codex
memex-cli run --stdin <<'EOF'
---TASK---
id: implement-feature
backend: codex
workdir: ./project
model: gpt-5.2
---CONTENT---
实现用户认证模块
---END---
EOF

Design Phase

# Design with Claude
memex-cli run --stdin <<'EOF'
---TASK---
id: design-system
backend: claude
workdir: ./project
---CONTENT---
设计系统架构
---END---
EOF

UX Review

# Review mockups with Gemini
memex-cli run --stdin <<'EOF'
---TASK---
id: review-ui
backend: gemini
workdir: ./project
files: mockups/*.png
files-mode: embed
---CONTENT---
审查 UI 设计稿
---END---
EOF

Iterative Development

# 1. Initial implementation
RUN_ID=$(memex-cli run --stdin < task.md | grep "Run ID:" | awk '{print $3}')

# 2. Add features
memex-cli resume --run-id $RUN_ID --stdin < add-features.md

# 3. Fix bugs
memex-cli resume --run-id $RUN_ID --stdin < bugfixes.md

Best Practices

Task ID naming:

Use descriptive, semantic names
Include timestamps for uniqueness
Hierarchical naming for organization

Backend selection:

Codex → Code generation
Claude → Design, architecture
Gemini → Multimodal, UI/UX

Dependency management:

Keep DAG shallow (2-3 levels)
Parallelize independent tasks
Use resume for long workflows

File loading:

Small files (<50 KB) → files-mode: embed
Large files (>50 KB) → files-mode: ref
Mixed sizes → files-mode: auto

Output format:

Interactive use → text (default)
Automation → jsonl for parsing

Troubleshooting

Common issues:

"memex-cli command not found" → Install: npm install -g memex-cli
"Backend authentication failed" → Check API keys configuration
"File not found" → Verify file paths relative to workdir:
"Circular dependency" → Restructure task dependencies (no cycles)
"Context size exceeded" → Use files-mode: ref or load fewer files

Summary

memex-cli enables AI-powered development workflows with:

Multi-backend support (codex, claude, gemini)
Parallel and sequential task execution
Resume capability for iterative development
Flexible file loading with glob patterns
Structured output (text, JSONL)

Start with examples/basic-task.md, then explore advanced patterns in references/.

Agent Skills: Memex CLI

Install this agent skill to your local

Skill Files