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

bash

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.

bash

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

bash

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

bash

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

code

# 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:

bash

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:

bash

# 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:

code

▶ 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:

bash

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

Output:

jsonl

{"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:

bash

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

Parallel tasks:

bash

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

DAG workflow:

bash

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

bash

# 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

bash

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

UX Review

bash

# 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

bash

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