Kommandolinje

pfmem

En klient i én fil til hukommelses-API'et, skrevet til at blive styret af en AI-harness. Den holder én nøgle og kalder hukommelsesendpointsene. Den kan ikke udstede, rotere eller tilbagekalde en nøgle, oprette et arbejdsområde eller konfigurere en udbyder — det er administration, og det ligger bag admin-API'et med vilje.

Installation

Installationsprogrammet henter det offentliggjorte manifest, downloader bundtet, verificerer det mod manifestets sha256 og installerer en launcher. Der kompileres intet, og der kræves ingen root.

install.sh

curl -fsSL https://pfmem-api.packagefactory.dk/install.sh | sh
export PATH="$HOME/.pfmem/bin:$PATH"
pfmem init

Det kræver curl, Node 22 eller nyere, mktemp og sed, og det siger hvilket af dem, der mangler, frem for at fejle senere med en syntaksfejl.

To miljøvariabler flytter installationen: den ene flytter det hele, den anden peger den mod et andet deployment.

environment

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

Kontrakten om stdout

Den primære kalder er en model, så standard output er altid præcis ét JSON-dokument. Alt, der er skrevet til et menneske — prompts, advarsler, opdateringsbeskeder — går til standard error, hvor en parser aldrig ser det.

stdout

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

Se på ok-flaget først. Ved en fejl skal du forgrene på fejlkoden og aldrig på beskeden; beskeder er skrevet til mennesker og ændrer sig mellem udgivelser.

Tre kald er undtaget, fordi et menneske er læseren: referencesiden udskriver markdown, hjælp udskriver hjælpetekst, og version-flaget udskriver en ren versionsstreng. Intet andet lægger andet end ét JSON-dokument på stdout.

Ét flag indrykker JSON'en. Det ændrer whitespace og intet andet.

Exit-koder

Scripts forgrener på disse tal, så de er en del af grænsefladen.

Exit-koder og hvad de betyder
Kode	Betydning
`0`	Kaldet lykkedes.
`1`	Alt andet.
`2`	Argumenterne var forkerte. Intet blev sendt.
`3`	Nøglen manglede eller blev ikke accepteret.
`4`	Nøglen mangler verbet, eller målet ligger uden for dens rækkevidde.
`5`	Kaldet var velformet, men fejlede valideringen.
`6`	En kvote eller en rate limit blev ramt.
`7`	Tjenesten kunne ikke betjene kaldet. Kan prøves igen.
`8`	Kaldet nåede aldrig frem til tjenesten.
`9`	Det, der blev adresseret, findes ikke.

Nøglen, og hvor den ligger

Send nøglen på standard input, eller lad den spørge, når der er en terminal. Begge dele holder hemmeligheden ude af proceslisten, hvor ps viser den til hver bruger på maskinen, og ude af din shell-historik. Flaget, der tager en nøgle som argument, findes, og det er det dårligste af de tre.

pfmem init

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

Læsningen fra standard input er begrænset til 8 KB og ti sekunder, så en harness, der efterlader røret åbent men tomt, får en brugsfejl med alternativerne nævnt frem for at hænge i det uendelige.

Nøglen læses først fra miljøet og derefter fra konfigurationsfilen, som oprettes læsbar kun for ejeren. Den udskrives aldrig, logges aldrig og gentages aldrig af diagnosekommandoen.

En nøgle læst fra den fil sendes kun til et https-origin eller til loopback. En gemt legitimation følger med hvert senere kald, uden at nogen tænker over det, så et origin, der navngiver en vært uden kryptering, afvises frem for at blive adlydt.

At overskrive origin for ét kald flytter aldrig det sted, klienten henter sin egen kode fra. Et flag pr. kald må ikke kunne udpege et installationsprogram.

Hvad klienten ikke vil sende

Der findes ikke et flag for et arbejdsområde, en konto, et filter eller en embedding-version, og en test fastslår, at ingen kan tilføjes. Nøglen opløses til det hele på serveren. At sende et af dem er præcis den måde, en klient ville læse andres hukommelser på.

To afgrænsningsflag findes, og de indsnævrer kun inden for det arbejdsområde, nøglen allerede er opløst til. Udelader du dem, spænder kaldet over alt, den nøgle i forvejen kan se; ingen af dem kan udvide noget.

--app-id · --project-id

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

Kommandoer

Referencekommandoen udskriver det hele i fuld længde — hvert flag, hver betingelse, hver svarform — genereret ud fra den samme specifikation, som argumentparseren bruger, så den kan ikke beskrive et flag, klienten ville afvise. Det er den side, du giver en model.

Kommandoer og hvad hver enkelt gør
Kommando	Hvad den gør
`add`	Indlæser beskeder til udtrækning. Asynkron; returnerer et task-id.
`search`	Rangerer hukommelser efter relevans for et spørgsmål i naturligt sprog.
`get`	Viser et subjekts hukommelser, filtreret og pagineret.
`edit`	Retter én hukommelse på stedet.
`delete`	Sletter hukommelser efter id, efter session eller efter alder.
`flush`	Kører en sessions ventende udtrækning nu.
`task · tasks`	Læser én baggrundsopgave, eller viser dem alle.
`init · doctor · logs · docs · update · version`	Lokale. De sender ingen API-kald, men to af dem rører stadig netværket.
`skill install\|status\|update`	Installerer, kontrollerer eller opdaterer den skill, en agent læser.

Der findes ingen kommando, der gemmer rå tekst uden udtrækning, og ingen, der henter et referat frem. At læse før en rettelse er en visning, fordi en rettelse kræver hukommelsens id og dens version.

Globale flag

De gælder for hver kommando.

Flag, som alle kommandoer accepterer
Flag	Hvad det gør
`--pretty`	Indrykker den JSON, der skrives til stdout.
`--verbose`	Skriver diagnostik om kaldet i logfilen.
`--origin <url>`	Overskriver API-origin for netop dette kald.
`--help, -h`	Udskriver hjælp til kommandoen og afslutter.
`--version, -v`	Udskriver versionen og afslutter.

Logs

En JSONL-fil, læsbar kun for ejeren, der registrerer hvert kalds metode, sti, status, varighed og request-id samt fejl. Den roterer ved 1 MB og beholder én generation.

pfmem logs

pfmem logs --lines 50

Legitimationsoplysninger maskeres på vej ind: feltnavne som authorization, api_key og token; enhver nøglestreng hvor som helst i en besked, en URL eller en indlejret værdi; og enhver bearer-header.

Citér request-id'et fra en fejl. Tjenesten registrerer det samme id, og det er dét, der gør et problem sporbart fra din terminal til vores logs.

Opdateringer

Ved opstart kontrollerer klienten udgivelsesfeedet, cachet i seks timer. Findes der en nyere version, spørger den kun, hvis både standard input og standard error er en terminal; ellers skriver den én linje til standard error og fortsætter. En harness blokeres aldrig, og en utilgængelig opdateringstjeneste får aldrig et hukommelseskald til at fejle.

pfmem update

pfmem update
pfmem update --check

En opdatering downloader, verificerer sha256 og udskifter bundtet atomisk. En kontrol rapporterer, hvad der er offentliggjort, og installerer intet.

Opdaterings- og skill-downloads kræver https, og installationsprogrammet fastholder protokollen på tværs af omdirigeringer. En checksum offentliggjort ved siden af et artefakt beviser kun, at bytes svarer til det, den samme server sendte; uden kryptering leverer en angriber på vejen begge dele, så det er transporten, der giver checksummen betydning. Et origin uden kryptering afvises, før der overhovedet sendes et kald.

Én miljøvariabel slår kontrollen helt fra.

environment

PFMEM_NO_UPDATE_CHECK=1

Skill'en

Klienten leveres med en skill: én fil, der lærer en agent, hvornår den skal bruge hukommelse, og hvordan den kaldes. Installér den, og din assistent holder op med at gætte sig til grænsefladen.

pfmem skill

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

Uden en angivet mappe vinder en projektkonfiguration fundet ved at gå opad fra den aktuelle mappe over konfigurationen på brugerniveau — at stå i et repository betyder dét repository. Findes ingen af delene, oplyser den begge steder, den kiggede, frem for at gætte en sti.