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/.