Project Memory CLI

Developer context in your terminal — a Python CLI client for projectmemory.app.

Installation

pip install projectmemory-cli

Or from source:

git clone https://github.com/your-org/projectmemory-cli
cd projectmemory-cli
pip install -e ".[dev]"

Both pm and projectmemory are registered as executable names.

Quick Start

# Authenticate (opens browser)
pm login

# Create a project and start its first session
pm project create

# Or resume an existing project/session
pm resume "My App"

# See your current context
pm memory show

# Work with tasks
pm task list
pm task add "Implement login"
pm task done 42      # completes task, then optionally links a commit
pm done              # interactive task completion shortcut

# Capture notes
pm capture "Don't forget to update the Stripe webhook URL"

# Report an issue
pm issue add "Login fails on mobile Safari"

# End your session with the shared backend review
pm session end

Commands

Authentication

Command	Description
pm login	Authenticate via browser
pm logout	Revoke token
pm whoami	Show current user
pm auth status	Check auth status
pm doctor	Diagnose CLI config, auth, backend, project, session, and Git state

Projects

Command	Description
pm project list	List all projects
pm project create	Create a project (interactive)
pm project current	Show current project + session
pm project link	Link this directory to a project
pm project unlink	Remove directory mapping
pm web	Open project in browser

Work Sessions

Command	Description
pm resume [project]	Start or resume a session
pm session status	Show all active sessions
pm session end	End the current session

Project Memory

Command	Description
pm memory show	Display all memory fields
pm memory status set [text]	Update Current Status
pm memory context set [text]	Update Important Context
pm memory update	Interactive memory update, including open issues

Next Action

Command	Description
pm next	Show current Next Action
pm next set [text]	Set Next Action (interactive menu)
pm next task <id>	Link a task as Next Action
pm next issue <id>	Link an issue as Next Action
pm next clear	Clear Next Action

Tasks

Command	Description
pm task list	List tasks; supports --open, --completed, --snoozed, --all
pm task add [title]	Create a task
pm task done <id>	Complete task + optional commit link
pm done	Interactive task completion shortcut
pm task snooze <id>	Snooze task
pm task reopen <id>	Reopen task
pm task edit <id>	Edit task
pm task delete <id>	Delete task

Notes

Command	Description
pm note list	List notes
pm note add [content]	Create a note; supports --title, --editor, --stdin
pm note search <query>	Search notes
pm capture [text]	Quick note shortcut
pm note edit <id>	Edit a note
pm note delete <id>	Delete a note

Issues

Command	Description
pm issue list	List issues; supports --open, --resolved, --all
pm issue add [description]	Report an issue
pm issue resolve <id>	Mark issue as resolved
pm issue reopen <id>	Reopen issue
pm issue edit <id>	Edit issue
pm issue delete <id>	Delete issue

Commits

Command	Description
pm commit link	Interactive recovery flow for linking a commit to a completed task
pm commit link HEAD --task 24	Directly link a commit/ref to a completed task

Configuration

Configuration is stored at ~/.config/projectmemory/config.toml.

The default api_url is the Project Memory site root, for example https://projectmemory.app. The CLI adds API paths such as /api/cli/... internally.

pm config show         # show all settings
pm config set api_url https://your-instance.example.com
pm config reset        # restore defaults

Environment variables

Variable	Description
PROJECTMEMORY_API_URL	API base URL
PROJECTMEMORY_TOKEN	Token override (skip keyring)
PROJECTMEMORY_PROJECT	Current project ID override
PROJECTMEMORY_NO_COLOR	Disable color output

Diagnostics

Run a read-only diagnostic report when troubleshooting local configuration or support issues:

pm doctor
pm doctor --json
pm doctor --verbose
pm doctor --no-network

pm doctor never prints authentication tokens, refresh tokens, passwords, private keys, or OAuth secrets. It exits with 0 when healthy, 1 when warnings are present, and 2 when critical issues prevent normal CLI use.

Directory Linking

Link the current git repository to a project so pm knows which project to use automatically:

cd ~/code/my-app
pm project link "My App"

# Now pm commands in this directory use "My App" automatically
pm task list    # no --project needed

How Sessions Work

The CLI shares the session model with the web app. Sessions must be active for write operations (creating tasks, notes, issues, updating memory).

• pm resume starts or resumes the backend session for the selected project
• pm resume can offer an optional Smart Resume when meaningful work changed while you were away; generation always requires confirmation and uses 1 AI Assist
• pm session end shows the shared factual Session Review and finalizes that exact session
• After finalization, the deterministic Project Memory Review may offer an optional Smart Handoff draft; generation and every regeneration require confirmation and use 1 AI Assist
• Smart Resume is informational. Smart Handoff remains a draft until you explicitly publish selected fields through the shared Project Memory service
• If the web app ends your session, the CLI will show a clear error and ask you to pm resume again
• A user can have active sessions in multiple projects, but the CLI has one current project
• Switching projects can end the current project session, keep it active, or cancel

The Web app and CLI use the same backend sessions, review snapshots, Project Memory operations, permissions, and AI Assist accounting. Presentation differs, but saved outcomes stay synchronized.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=projectmemory_cli --cov-report=term-missing

# Lint
ruff check projectmemory_cli/

# Type check
mypy projectmemory_cli/

Security

• Tokens are stored in the OS keyring (or ~/.config/projectmemory/credentials.json with chmod 600 as fallback)
• Passwords are never stored
• The PROJECTMEMORY_TOKEN environment variable overrides stored credentials (read-only)
• Tokens can be revoked remotely via pm logout or from the web app at projectmemory.app/settings

project_memory_cli