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

id

implement-auth-20260110

backend

codex

claude

gemini

workdir

./project

/home/user/app

<prompt>

Optional Parameters

model

gpt-5.2

gpt-5.1-codex-max

model-provider

openai

dependencies

task-a

task-a,task-b

timeout

600

retry

2

files

src/**/*.py

files-mode

embed

ref

auto

files-encoding

utf-8

base64

auto

stream-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

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

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:

▶

✓

✗

⟳

»

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

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/

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

references/