Documentation

Pamie command-line reference

Pamie runs as a server process and also includes local operator commands for backups, restores, and embedding backfill. This page collects the current command-line options, environment variables, and command help in one place.

CLI help Server options Operator commands

Install

Use Homebrew for the simplest local install:

brew install kurocho/tap/pamie
pamie --version

Create one local token file and reuse it for the binary, Docker, and MCP client configuration:

if [ ! -f .pamie.env ]; then
  umask 077
  printf "PAMIE_TOKEN=%s\nPAMIE_TOKEN_ID=local\nPAMIE_TOKEN_SCOPES=all\n" \
    "$(openssl rand -hex 32)" > .pamie.env
fi

set -a
. ./.pamie.env
set +a
printf "MCP endpoint: http://127.0.0.1:8080/mcp\nBearer token: %s\n" "$PAMIE_TOKEN"

Keep `.pamie.env` local and out of version control. For production, put these values in your service manager or secret store instead of printing tokens to logs.

Run with Docker when you want an isolated container and persistent `/data` volume. Docker can read the same token file:

docker volume create pamie-data

docker run --rm \
  --name pamie \
  -p 127.0.0.1:8080:8080 \
  -v pamie-data:/data \
  --env-file .pamie.env \
  kurocho/pamie:latest

Server quickstart

if [ ! -f .pamie.env ]; then
  umask 077
  printf "PAMIE_TOKEN=%s\nPAMIE_TOKEN_ID=local\nPAMIE_TOKEN_SCOPES=all\n" \
    "$(openssl rand -hex 32)" > .pamie.env
fi

set -a
. ./.pamie.env
set +a
printf "MCP endpoint: http://127.0.0.1:8080/mcp\nBearer token: %s\n" "$PAMIE_TOKEN"

pamie \
  --addr 127.0.0.1:8080 \
  --data-dir ./data

Check the server:

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/ready

Server options

Flag	Environment	Description
`--version`	n/a	Print version and exit.
`--addr`	`PAMIE_ADDR`	HTTP listen address. Default: `127.0.0.1:8080`.
`--token`	`PAMIE_TOKEN`	Bearer token for the protected MCP endpoint.
`--token-id`	`PAMIE_TOKEN_ID`	Identifier used for the configured Bearer token in audit logs. Default: `default`.
`--token-scopes`	`PAMIE_TOKEN_SCOPES`	Comma-separated scopes or `all`. Default: `all`.
`--data-dir`	`PAMIE_DATA_DIR`	Directory for local Pamie data. Default: `data`.
`--db-path`	`PAMIE_DB_PATH`	SQLite database path. Default: `data/pamie.db`.
`--log-level`	`PAMIE_LOG_LEVEL`	Log level: `debug`, `info`, `warn`, or `error`. Default: `info`.
`--read-header-timeout`	`PAMIE_READ_HEADER_TIMEOUT`	HTTP read header timeout. Default: `5s`.
`--shutdown-timeout`	`PAMIE_SHUTDOWN_TIMEOUT`	Graceful shutdown timeout. Default: `10s`.
`--mcp-rate-limit`	`PAMIE_MCP_RATE_LIMIT`	Per-client `/mcp` requests per minute. `0` disables rate limiting. Default: `120`.
`--mcp-rate-burst`	`PAMIE_MCP_RATE_BURST`	Per-client `/mcp` rate limit burst. Default: `30`.
`--lifecycle-worker`	`PAMIE_LIFECYCLE_WORKER_ENABLED`	Enable scheduled lifecycle evaluation. Default: disabled.
`--lifecycle-interval`	`PAMIE_LIFECYCLE_INTERVAL`	Interval between scheduled lifecycle evaluations. Default: `1h`.
`--lifecycle-batch-size`	`PAMIE_LIFECYCLE_BATCH_SIZE`	Maximum memories evaluated per lifecycle run. Default: `500`.
`--lifecycle-run-on-start`	`PAMIE_LIFECYCLE_RUN_ON_START`	Run lifecycle evaluation as soon as the worker starts. Default: false.
`--lifecycle-startup-delay`	`PAMIE_LIFECYCLE_STARTUP_DELAY`	Delay before first lifecycle run when run-on-start is false. Default: `0s`.
`--vector-search`	`PAMIE_VECTOR_SEARCH_ENABLED`	Enable local vector embedding storage and hybrid search. Default: disabled.
`--vector-backend`	`PAMIE_VECTOR_BACKEND`	Local vector backend: `auto`, `sqlite-json`, or `sqlite-vec`. Default: `auto`.
`--vector-provider`	`PAMIE_VECTOR_PROVIDER`	Local embedding provider: `local-hash` or `ollama`. Default: `local-hash`.
`--vector-model`	`PAMIE_VECTOR_MODEL`	Embedding model name for providers that require one. Default: `embeddinggemma`.
`--vector-dimensions`	`PAMIE_VECTOR_DIMENSIONS`	Embedding dimensions for the local vector provider. Default: `384`.
`--vector-ollama-url`	`PAMIE_VECTOR_OLLAMA_URL`	Base URL for a local Ollama server. Default: `http://127.0.0.1:11434`.
`--vector-ollama-keep-alive`	`PAMIE_VECTOR_OLLAMA_KEEP_ALIVE`	Ollama `keep_alive` value for loaded embedding models.

Top-level command help

Usage:
  pamie [server options]
  pamie backup --db-path PATH --out PATH [--format sqlite|ndjson]
  pamie restore --db-path PATH --in PATH [--format sqlite|ndjson] (--dry-run|--confirm)
  pamie embeddings backfill [--db-path PATH] [--limit N] [--reindex]

Commands:
  backup      Create a SQLite backup, or NDJSON with --format ndjson.
  restore     Validate or restore a SQLite backup, or NDJSON with --format ndjson.
  embeddings  Manage local embedding indexes.

Use "pamie <command> -h" for command-specific options.

Backup

Create a SQLite backup, or a portable NDJSON export with --format ndjson.

pamie backup --db-path data/pamie.db --out backup.db
pamie backup --format ndjson --db-path data/pamie.db --out backup.ndjson

Usage of backup:
  -db-path string
        SQLite database path (default "data/pamie.db")
  -format string
        backup format: sqlite or ndjson (default "sqlite")
  -log-level string
        log level: debug, info, warn, or error (default "info")
  -out string
        backup destination path, or - for NDJSON stdout; must not already exist

Restore

Validate with --dry-run before committing a restore with --confirm.

pamie restore --db-path restored.db --in backup.db --dry-run
pamie restore --format ndjson --db-path restored.db --in backup.ndjson --confirm

Usage of restore:
  -confirm
        commit the restore
  -db-path string
        SQLite target database path (default "data/pamie.db")
  -dry-run
        validate the restore without committing rows
  -format string
        restore format: sqlite or ndjson (default "sqlite")
  -in string
        restore source path, or - for NDJSON stdin
  -log-level string
        log level: debug, info, warn, or error (default "info")

Embedding backfill

Index missing embeddings, or recompute existing embeddings with --reindex.

pamie embeddings backfill --db-path data/pamie.db --provider ollama --model embeddinggemma --dimensions 384 --backend auto --limit 500

Usage:
  pamie embeddings backfill [options]

Subcommands:
  backfill  Index missing embeddings, or all embeddings with --reindex.

Usage of embeddings backfill:
  -backend string
        vector backend: auto, sqlite-json, or sqlite-vec (default "auto")
  -db-path string
        SQLite database path (default "data/pamie.db")
  -dimensions int
        embedding vector dimensions (default 384)
  -limit int
        maximum chunks to index in this run (default 500)
  -log-level string
        log level: debug, info, warn, or error (default "info")
  -model string
        embedding model for providers that require one (default "embeddinggemma")
  -ollama-keep-alive string
        Ollama keep_alive value
  -ollama-url string
        base URL for a local Ollama server (default "http://127.0.0.1:11434")
  -provider string
        embedding provider: local-hash or ollama (default "local-hash")
  -reindex
        recompute embeddings even when rows already exist

Source install script

Use this path when developing from a clone of the repository.

Usage: scripts/install-local.sh [options]

Build Pamie and install it as a local `pamie` command.

Options:
  --install-dir DIR   Install directory (default: $PAMIE_INSTALL_DIR or $HOME/.local/bin)
  --profile FILE      Shell profile to update (default: $PAMIE_SHELL_PROFILE or auto-detect)
  --version VERSION   Version embedded into the binary (default: $VERSION or dev)
  --no-path           Do not update a shell profile
  -h, --help          Show this help

Examples:
  scripts/install-local.sh
  scripts/install-local.sh --version v0.1.0
  scripts/install-local.sh --install-dir "$HOME/bin"

Install Pamie View source