Configuration

PML configuration files and options

Environment Variables

PML behavior can be customized via environment variables:

Example

# Set custom database path
export PML_DB_PATH=/path/to/custom/db

# Enable debug logging
export LOG_LEVEL=debug

# Start PML
./pml serve --config config/mcp-servers.json

Config Files

MCP Server Configuration

The primary configuration file defines which MCP servers PML will manage.

Location: Specified via --config flag

Format:

{
  "mcpServers": {
    "<server-id>": {
      "command": "<executable>",
      "args": ["<arg1>", "<arg2>", ...],
      "env": {
        "<VAR>": "<value>"
      }
    }
  }
}

Example Configuration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/home/user/projects"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-memory"],
      "env": {}
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-fetch"],
      "env": {}
    }
  }
}

Server Configuration Fields

Claude Code Integration

To use PML with Claude Code, add it to your Claude configuration:

Linux/macOS: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pml": {
      "command": "/absolute/path/to/pml",
      "args": ["serve", "--config", "/absolute/path/to/mcp-servers.json"]
    }
  }
}

Important: Use absolute paths for both command and --config.

Database Configuration

PML uses PGlite (embedded PostgreSQL) for persistent storage.

Default Location

~/.pml/
├── db/                  # PGlite database files
│   ├── base/
│   ├── global/
│   └── ...
├── logs/                # Application logs
│   └── pml.log
└── cache/               # Execution cache

Custom Database Path

# Via environment variable
PML_DB_PATH=/custom/path/db ./pml serve --config ...

# Or in your shell profile
export PML_DB_PATH=/custom/path/db

Logging Configuration

Log Levels

Log Files

Logs are written to ~/.pml/logs/pml.log in structured JSON format:

{
  "timestamp": "2025-01-15T10:30:00.000Z",
  "level": "info",
  "message": "Tool executed",
  "tool": "filesystem:read_file",
  "duration_ms": 45
}

Grafana/Loki Integration

PML logs are compatible with Promtail for Grafana/Loki ingestion:

# promtail-config.yml
scrape_configs:
  - job_name: pml
    static_configs:
      - targets:
          - localhost
        labels:
          job: pml
          __path__: ~/.pml/logs/*.log

Algorithm Configuration

PML's intelligent algorithms can be tuned via YAML configuration files in the config/ directory.

Local Alpha Configuration

File: config/local-alpha.yaml

Controls the semantic vs graph balance per-node for DAG suggestions (ADR-048).

What is Alpha?

Alpha determines how much PML trusts the graph structure vs pure semantic similarity:

• alpha = 1.0 → Pure semantic (ignore graph structure entirely)
• alpha = 0.5 → Maximum graph influence (equal weight semantic/graph)

Four algorithms compute alpha based on context:

Alpha Bounds

Hard limits for alpha values across all algorithms. Tighter bounds = more predictable, wider = more adaptive.

Alpha Scaling Factor

Controls how aggressively alpha decreases when confidence is high.

Formula: alpha = max(alpha_min, alpha_max - confidence × alpha_scaling_factor)

Cold Start (Bayesian Algorithm)

When a node has few observations, we can't trust graph statistics. The Bayesian algorithm interpolates from prior (don't trust graph) to target (trust graph).

Formula: alpha = prior_alpha × (1 - confidence) + target_alpha × confidence where confidence = observations / threshold

Heat Diffusion (Passive Tools)

Computes "heat" for each node based on graph connectivity. Well-connected nodes get more heat → lower alpha → trust graph more.

Formula: heat = intrinsic_weight × node_heat + neighbor_weight × avg_neighbor_heat

Hierarchy Weights (Capabilities)

For capability/meta nodes, heat combines three sources:

• intrinsic: node's own graph connectivity
• neighbor: heat from graph neighbors (same level)
• hierarchy: heat from parent/children in Tool→Capability→Meta hierarchy

Important: Sum of weights MUST equal 1.0 for each node type.

Hierarchy Inheritance Factors

Controls top-down heat propagation. When computing a child's hierarchy heat, it inherits a fraction of its parent's heat.

Lower values = children are more independent. Higher values = parent reputation strongly influences children.

Structural Confidence Weights

Combines multiple heat signals into a single "structural confidence" score, then used to compute alpha via the scaling factor. Sum should equal 1.0.

See also: Hybrid Search - Local Adaptive Alpha

Speculation Configuration

File: config/speculation_config.yaml

Controls speculative execution behavior.

# Enable/disable speculation globally
enabled: true

# Minimum confidence for speculation (0.40-0.90)
confidence_threshold: 0.70

# Maximum concurrent speculations
max_concurrent_speculations: 3

# Timeout in milliseconds
speculation_timeout: 10000

# Adaptive threshold adjustment
adaptive:
  enabled: true
  min_threshold: 0.40
  max_threshold: 0.90

See also: Speculative Execution

Security Configuration

PII Protection

By default, PML protects sensitive data:

# Disable PII protection (not recommended)
PML_NO_PII_PROTECTION=1 ./pml serve --config ...

Sandbox Permissions

The code execution sandbox runs with minimal permissions by default. Additional paths can be allowed per-execution via sandbox_config.allowedReadPaths.

See Also

• CLI Reference - Command-line options
• MCP Tools Reference - API documentation
• Installation - Setup guide