pfmem

curl -fsSL https://pfmem-api.packagefactory.dk/install.sh | sh
pfmem init

It needs curl, Node 22 or newer, mktemp and sed, and says which one is missing rather than failing later with a syntax error.

Two environment variables move the installation: one relocates the whole thing, the other points it at a different deployment.

PFMEM_HOME="$HOME/.local/pfmem"
PFMEM_ORIGIN="https://pfmem-api.packagefactory.dk"

{"ok":true,"request_id":"…","data":{…}}
{"ok":false,"error":{"code":"…","message":"…","request_id":"…"}}

Check the success flag first. On a failure, switch on the error code and never on the message; messages are written for people and change between releases.

Three invocations are exempt, because a human is the reader: the reference page prints markdown, help prints help text, and the version flag prints a bare version string. Nothing else puts anything but one JSON document on stdout.

One flag indents the JSON. It changes the whitespace and nothing else.

Exit codes

Scripts switch on these numbers, so they are part of the interface.

cat key.txt | pfmem init
pfmem init --origin https://api.example.com

The read from standard input is bounded at 8 KB and ten seconds, so a harness that leaves the pipe open but idle gets a usage error naming its alternatives rather than hanging forever.

The key is read from the environment first, then from the config file, which is created readable only by its owner. It is never printed, never logged, and never echoed back by the diagnostic command.

A key read from that file is only ever sent to an https origin or to loopback. A stored credential rides along on every later invocation without anyone thinking about it, so an origin naming a plaintext host is refused rather than obeyed.

Overriding the origin for one call never repoints where the client fetches its own code. A per-invocation flag must not be able to nominate an installer.

Setup asks the server first. A key issued against one subject already carries it, and that answer is recorded without asking, because a write as anyone else is refused anyway. Otherwise it asks you, offering an address it finds in your git configuration, then your account name on the machine.

pfmem init
#  Whose memories is this machine writing? [user/agent] (user)
#  Which user id? ([email protected])

# or, with no terminal to ask at:
pfmem init --mode user --subject-id [email protected]

An id only has to be stable and spelled the same way everywhere you call from. An email address is a fine choice, and is usually the one offered.

With no terminal nothing is asked, because a question nobody is there to answer waits forever. Give the mode and the id as flags instead; with neither, setup still stores the key, records no subject, and says so, and each call then names its own.

Afterwards the kind and the subject are both filled in for you when you leave them out. Anything you pass wins over what was recorded, and on a read there is a flag that widens back out to every subject the key is allowed to see. The diagnostic command reports what was recorded.

# the kind and the subject are filled in from what init recorded
pfmem search --query "how do they prefer to travel"

# widen back out to every subject this key may see
pfmem search --memory-type user --all-subjects --query "billing"

Two scope flags exist, and they only ever narrow within the workspace the key already resolved to. Omitting them spans everything that key can already see; neither can widen anything.

pfmem search --memory-type user --user-id u_42 --query "retry policy" --app-id support-bot
pfmem delete --created-before 1735689600000 --project-id billing

{
  "ok": true,
  "request_id": "9130cb814f654e1ea042497d6362b08d",
  "data": {
    "hits": [
      {
        "record": {
          "id": "a1b2c3",
          "memory_type": "user",
          "subject_id": "[email protected]",
          "content": "[unverified] Prefers the night train to Berlin.",
          "verification": "unverified",
          "availability": "served"
        },
        "score": 0.0328,
        "rank": 1
      }
    ],
    "method": "hybrid",
    "embedding_version": "external_v1",
    "took_ms": 41,
    "withheld_count": 2
  }
}

The marker on unapproved content

[unverified]

Content no person has approved comes back with this prefix in front of its text. The prefix is added to the answer and never stored, so the same memory read by a signed-in person carries no prefix.

What was withheld, as a count

withheld_count

When a search or a listing leaves something out because it is withheld from this key, the count is in the JSON, and pfmem also writes it to stderr in human mode. A result set that quietly shrank is a model reading a smaller truth than the one that exists, and the count is the only warning it gets.

A procedure serves the version a person approved, when there is one

pending_version

A key is served the newest version a person has approved. When a key has written a newer version and nobody has approved it yet, the read answers with the approved version and names the waiting one in this field, so an agent follows a runbook somebody stood behind. When no version has ever been approved, the newest version is served with the marker instead: a procedure that only ever a key wrote is still usable, and nothing is held back until there is an approved version for it to fall behind.

Where an approval happens

Approving happens in the dashboard, on the page under Review — Flagged for review. Nothing a key sends can make an item trusted, and that is what keeps "a person vouched for this" a fact rather than a claim.

There is no command that stores raw text without extraction, and none that recalls a transcript. Reading before an edit is a listing, because an edit needs the memory's id and its version.

pfmem logs --lines 50

Credentials are redacted on the way in: field names like authorization, api_key and token; any key string anywhere in a message, a URL or a nested value; and any bearer header.

Quote the request id from a failure. The service records the same id, which is what makes a problem traceable from your terminal to our logs.

pfmem update
pfmem update --check

An update downloads, verifies the sha256, and replaces the bundle atomically. A check reports what is published and installs nothing.

Update and skill downloads require https, and the installer pins the protocol across redirects. A checksum published beside an artifact only proves the bytes match what that same server sent; over plaintext an attacker on the path supplies both, so it is the transport that makes the checksum mean anything. A plaintext origin is refused before any request is made.

One environment variable disables the check entirely.

PFMEM_NO_UPDATE_CHECK=1

pfmem procedure-list --name-prefix release --limit 20
pfmem procedure-search --query "release freeze" --top-k 5
pfmem procedure-get --procedure-id pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15

# that read came back at version 3, so append the next one conditionally
pfmem procedure-update --procedure-id pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15 \
  --content "Freeze at seven now." --expected-version 3 --reason "the freeze moved an hour"
pfmem procedure-versions --procedure-id pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15

# the history lists versions without their text; read the one before the append
pfmem procedure-versions --procedure-id pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15 --procedure-version 3
pfmem procedure-archive --procedure-id pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15 --reason "replaced by a new runbook"

# retiring is one-way, so the way of working that replaces it is a new procedure
pfmem procedure-create --name nightly-release --visibility team \
  --description "how we ship at night" \
  --content "Freeze at seven, then {{shared:deploy-checks}}" \
  --reason "replaces the retired nightly runbook"

Search when you know a procedure probably exists and not what it was called; list when you want everything this key can reach. Both answer with summaries; only the search adds the passage that matched, with the matching words marked, and the text itself comes from the read.

An update appends a new version and never edits in place, so an old runbook is never lost under a new one. Pass the version you read and a change somebody else made first fails loudly instead of being buried. Retiring one takes it out of listing and search while its text and every version stay readable to anyone holding the id. Nothing here deletes, and nothing un-retires: a retired procedure takes no further version, so a replacement is a new procedure.

A procedure is private by default — its owning agent, and any key that reads the whole workspace. Sharing it with everyone in the workspace is a decision, not a default, and an update can move it either way. A key bound to no agent has nobody to keep a procedure private from, so it must share the ones it writes.

Only the subject that owns a procedure, or a key bound to no subject at all, may append to it or retire it. To everyone else it answers as one that does not exist — so a refusal on a procedure you can see in the listing means it is not yours to change, not that the id is wrong. A master key is not such a key here: it answers for an account rather than for one workspace, and this client never sends a workspace name, so every procedure command made with one is refused. Mint a workspace key and give the client that.

These have nothing to do with the skill commands below. The skill is one published file that teaches your assistant how to drive this client; a procedure is content your workspace owns and versions. Installing the skill stores no memory, and writing a procedure installs nothing.

pfmem skill install
pfmem skill install --dir DIR
pfmem skill status
pfmem skill update

With no directory given, a project-level configuration found by walking up from the current directory wins over the user-level one — standing in a repository means that repository. When neither exists it reports both places it looked and asks for a directory rather than guessing.