Pamie command-line reference

Install

Use Homebrew for the simplest local install:

brew install kurocho/tap/pamie
pamie --version

Run pamie start to start the local background server. The first run prints a generated Bearer token once:

pamie start
pamie status

Run with Docker when you want an isolated container and persistent `/data` volume. Containers usually receive a bootstrap token from the environment:

docker volume create pamie-data
export PAMIE_TOKEN="$(openssl rand -hex 32)"

docker run --rm \
  --name pamie \
  -p 127.0.0.1:17683:8080 \
  -v pamie-data:/data \
  -e PAMIE_TOKEN="$PAMIE_TOKEN" \
  -e PAMIE_TOKEN_ID=local \
  -e PAMIE_TOKEN_SCOPES=all \
  kurocho/pamie:latest

Server quickstart

pamie start
pamie status

Use pamie token when you need a new default token. Existing raw tokens cannot be recovered because Pamie stores only hashes.

Check the server:

curl http://127.0.0.1:17683/health
curl http://127.0.0.1:17683/ready

Server options

Top-level command help

Usage:
  pamie
  pamie start [server options]
  pamie serve [server options]
  pamie status
  pamie stop
  pamie token [rotate|create|list|revoke]
  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] [--embedding-scope title_keywords] [--reindex]

Commands:
  start       Start Pamie in the background.
  serve       Run Pamie in the foreground for Docker, systemd, and development.
  status      Show background process and health status.
  stop        Stop the background Pamie process.
  token       Create, rotate, list, or revoke persistent tokens.
  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.

Tokens

Persistent tokens are stored as salted hashes. Raw generated tokens are printed once.

pamie token
pamie token list
pamie token create --id readonly --scopes memory:read,stats:read
pamie token rotate --id readonly
pamie token revoke --id readonly

Connect MCP clients

Start Pamie, then create a dedicated token for each MCP client so access can be rotated or revoked independently. Add memory:delete only for clients that should be able to delete memories.

pamie start
pamie token create --id copilot --scopes memory:read,memory:write,stats:read

GitHub Copilot in VS Code

Create .vscode/mcp.json in your workspace. VS Code will prompt for the token without storing it in the file.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pamie-token",
      "description": "Pamie Bearer token",
      "password": true
    }
  ],
  "servers": {
    "pamie": {
      "type": "http",
      "url": "http://127.0.0.1:17683/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pamie-token}"
      }
    }
  }
}

Open Copilot Chat, switch to Agent mode, enable the Pamie server in the tools picker, then ask it to search or save memory.

Codex CLI or IDE extension

Codex shares MCP configuration between the CLI and IDE extension.

export PAMIE_MCP_TOKEN="<token printed by pamie>"
codex mcp add pamie \
  --url http://127.0.0.1:17683/mcp \
  --bearer-token-env-var PAMIE_MCP_TOKEN
codex mcp list

[mcp_servers.pamie]
url = "http://127.0.0.1:17683/mcp"
bearer_token_env_var = "PAMIE_MCP_TOKEN"

Claude Code

Claude Code can connect to Pamie as an HTTP MCP server.

export PAMIE_MCP_TOKEN="<token printed by pamie>"
claude mcp add --transport http pamie http://127.0.0.1:17683/mcp \
  --header "Authorization: Bearer $PAMIE_MCP_TOKEN"
claude mcp list

Claude.ai custom connectors connect from Anthropic infrastructure, so 127.0.0.1 will not work there. Put Pamie behind HTTPS and keep Bearer authentication enabled before using it as a remote connector.

v1.1.0 highlights

Pamie now starts as a local background server with pamie start, prints a first-use token once, and can be managed with pamie status, pamie token, and pamie stop.

Vector search is enabled by default with local local-hash embeddings. Switch to Ollama with pamie start --vector-provider ollama. Embeddings use memory titles and explicit keywords only; full bodies remain searchable through SQLite FTS5.

Operator commands now follow the running daemon database path, so token and backup commands use the same database as a daemon started with --db-path.

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

Vector search is enabled by default with local hash embeddings. Pamie embeds only memory titles and explicit keywords; full bodies stay durably stored and searchable through FTS5. Provide keywords for long notes with people names, project names, aliases, technologies, decisions, ticket IDs, dates, error messages, and domain-specific terms.

ollama serve
ollama pull embeddinggemma

pamie start --vector-provider ollama

pamie embeddings backfill --provider ollama --limit 500

Usage:
  pamie embeddings backfill [options]

Subcommands:
  backfill  Index missing title/keywords 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)
  -embedding-scope string
        embedding scope: title_keywords (default "title_keywords")
  -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"