lgctl - LangGraph Memory Management CLI

A Unix-style command-line tool for managing LangGraph memory stores, threads, runs, assistants, and crons.

Features

• Unix-style commands: Familiar commands like ls, get, put, rm, mv, cp
• Multiple output formats: Table (human-readable), JSON (for piping), Raw (for scripts)
• Interactive REPL: Context-aware shell with namespace navigation
• Higher-level operations: Analyze, prune, export/import, dedupe, grep
• MCP Server: Plug into AI agents via Model Context Protocol
• Flexible connectivity: Works with local dev servers and remote LangSmith deployments

Installation

# From the package directory
pip install lgctl

# With MCP server support
pip install -e "lgctl[mcp]"

Quick Start

# Set your environment (or use .env file)
export LANGSMITH_DEPLOYMENT_URL=https://your-deployment.langsmith.com
export LANGSMITH_API_KEY=your-api-key

# List namespaces
lgctl store ls

# Search items
lgctl store search user,123 "preferences"

# Get a specific item
lgctl store get user,123 settings

# Interactive mode
lgctl repl

Commands

Command Aliases

All main commands have short aliases for faster typing:

Store Commands

lgctl store ls [namespace]              # List namespaces
lgctl store ls -i user,123              # List items in namespace
lgctl store ls -d 10                    # List with max depth
lgctl store get user,123 key            # Get item
lgctl store put user,123 key "value"    # Store item
lgctl store rm user,123 key             # Delete item
lgctl store search user,123 "query"     # Semantic search
lgctl store mv src,ns key dst,ns        # Move item
lgctl store cp src,ns key dst,ns        # Copy item
lgctl store count user,123              # Count items
lgctl store tree                        # Show namespace tree

# Short alias: 's' for 'store'
lgctl s ls                              # Same as: lgctl store ls

Thread Commands

lgctl threads ls                        # List threads
lgctl threads get <thread_id>           # Get thread details
lgctl threads create                    # Create new thread
lgctl threads rm <thread_id>            # Delete thread
lgctl threads state <thread_id>         # Get thread state
lgctl threads history <thread_id>       # Get state history

# Short alias: 't' for 'threads'
lgctl t ls                              # Same as: lgctl threads ls

Run Commands

lgctl runs ls <thread_id>               # List runs
lgctl runs get <thread_id> <run_id>     # Get run details
lgctl runs cancel <thread_id> <run_id>  # Cancel run

# Short alias: 'r' for 'runs'
lgctl r ls <thread_id>                  # Same as: lgctl runs ls

Assistant Commands

lgctl assistants ls                     # List assistants
lgctl assistants get <id>               # Get assistant
lgctl assistants schema <id>            # Get schemas
lgctl assistants graph <id>             # Get graph definition

# Short alias: 'a' for 'assistants'
lgctl a ls                              # Same as: lgctl assistants ls

Cron Commands

lgctl crons ls                          # List cron jobs
lgctl crons get <cron_id>               # Get cron details
lgctl crons rm <cron_id>                # Delete cron

# Short alias: 'c' for 'crons'
lgctl c ls                              # Same as: lgctl crons ls

Memory Operations

lgctl ops analyze [namespace]           # Analyze memory usage
lgctl ops analyze -d                    # Detailed analysis
lgctl ops stats                         # Overall statistics
lgctl ops export -o backup.jsonl        # Export memories
lgctl ops export user,123 -o user.jsonl # Export specific namespace
lgctl ops export -k "pref" -o prefs.jsonl  # Export keys containing "pref"
lgctl ops export -v "pizza" -o pizza.jsonl # Export values containing "pizza"
lgctl ops export --export-format json   # Export as JSON (default: jsonl)
lgctl ops import backup.jsonl           # Import memories
lgctl ops import backup.jsonl --dry-run # Preview import
lgctl ops import backup.jsonl --overwrite  # Overwrite existing
lgctl ops import backup.jsonl --prefix archive  # Add namespace prefix
lgctl ops prune user,123 --days 30      # Remove old items (dry-run)
lgctl ops prune user,123 --days 30 --force  # Actually delete
lgctl ops dedupe user,123               # Remove duplicates (dry-run)
lgctl ops dedupe user,123 --force       # Actually remove duplicates
lgctl ops find -k pattern               # Find by key pattern
lgctl ops find -v "search"              # Find by value content
lgctl ops grep "search term"            # Search all values

# Short alias: 'o' for 'ops'
lgctl o stats                           # Same as: lgctl ops stats

Interactive REPL

lgctl repl

In the REPL:

lgctl> use user,123              # Set working namespace
[user,123]> ls -i                # List items
[user,123]> s "preferences"      # Quick search
[user,123]> get settings         # Get item (namespace implied)
[user,123]> put newkey "value"   # Store (namespace implied)
[user,123]> ..                   # Go up one level
[user]> cd /                     # Go to root
lgctl> threads                   # List threads
lgctl> analyze                   # Analyze all memory
lgctl> exit

Output Formats

# Human-readable table (default)
lgctl store ls

# JSON for piping to jq
lgctl -f json store ls | jq '.[] | .namespace'

# Raw for scripting
lgctl -f raw store ls

Configuration

Environment Variables

LANGSMITH_DEPLOYMENT_URL    # LangGraph deployment URL
LANGGRAPH_URL              # Alternative URL variable
LANGSMITH_API_KEY          # API key for authentication

.env File

LANGSMITH_DEPLOYMENT_URL=https://your-deployment.langsmith.com
LANGSMITH_API_KEY=lsv2_...

Command Line

lgctl -u http://localhost:8123 store ls
lgctl -k your-api-key store ls

Usage Patterns

Backup and Restore

# Export all memories
lgctl ops export -o backup.jsonl

# Export specific namespace
lgctl ops export user,123 -o user_backup.jsonl

# Export with filters
lgctl ops export -k "settings" -o settings.jsonl
lgctl ops export website,products -v "haltech" -o haltech.jsonl

# Export as JSON instead of JSONL
lgctl ops export --export-format json -o backup.json

# Restore (dry-run first)
lgctl ops import backup.jsonl --dry-run

# Restore (actually import)
lgctl ops import backup.jsonl

# Restore with overwrite
lgctl ops import backup.jsonl --overwrite

Cleanup Old Data

# Preview what would be deleted
lgctl ops prune user,123 --days 90 --dry-run

# Actually delete
lgctl ops prune user,123 --days 90 --force

Find Specific Data

# Find by key pattern
lgctl ops find -k "pref"

# Find by value content
lgctl ops find -v "pizza"

# Grep across all memories
lgctl ops grep "email@example.com"

Migrate Data

# Move item between namespaces
lgctl store mv old,ns key new,ns

# Copy entire namespace (via export/import)
lgctl ops export old,ns -o temp.jsonl
lgctl ops import temp.jsonl --prefix new

MCP Server (for AI Agents)

lgctl includes an MCP (Model Context Protocol) server that exposes memory management tools to AI agents.

Running the MCP Server

# Install with MCP support
pip install -e ".[mcp]"

# Run the server
lgctl-mcp

# Or via Python
python -m lgctl.mcp_server

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "lgctl": {
      "command": "lgctl-mcp",
      "env": {
        "LANGSMITH_DEPLOYMENT_URL": "https://your-deployment.langsmith.com",
        "LANGSMITH_API_KEY": "your-api-key"
      }
    }
  }
}

Or with uv:

{
  "mcpServers": {
    "lgctl": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/lgctl", "lgctl-mcp"],
      "env": {
        "LANGSMITH_DEPLOYMENT_URL": "https://your-deployment.langsmith.com",
        "LANGSMITH_API_KEY": "your-api-key"
      }
    }
  }
}

Available MCP Tools

Agent Usage Example

Once configured, an AI agent can use the tools naturally:

Agent: Let me check what memories are stored for this user.
[Uses store_list_items with namespace="user,123"]

Agent: I found 15 items. Let me search for food preferences.
[Uses store_search with namespace="user,123", query="food preferences"]

Agent: The user prefers Italian food. Let me update their profile.
[Uses store_put with namespace="user,123", key="food_pref", value="Italian cuisine"]

Python API

from lgctl import get_client
from lgctl.commands import StoreCommands
from lgctl.formatters import get_formatter

# Create client
client = get_client(url="http://localhost:8123")

# Use commands programmatically
formatter = get_formatter("json")
store = StoreCommands(client, formatter)

# Async operations
import asyncio

async def main():
    items = await store.search("user,123", "preferences")
    print(items)

asyncio.run(main())

Architecture

lgctl/
├── __init__.py          # Package exports
├── __main__.py          # python -m lgctl entry
├── client.py            # LangGraph SDK wrapper
├── cli.py               # CLI argument parser & dispatcher
├── repl.py              # Interactive REPL
├── formatters.py        # Output formatting (table/json/raw)
├── mcp_server.py        # MCP server for AI agents
└── commands/
    ├── __init__.py
    ├── store.py         # Store operations
    ├── threads.py       # Thread operations
    ├── runs.py          # Run operations
    ├── assistants.py    # Assistant operations
    ├── crons.py         # Cron operations
    └── ops.py           # Higher-level operations

License

MIT