pfmem

curl -fsSL https://pfmem-api.packagefactory.dk/install.sh | sh
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.

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

{"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.

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.

Opsætningen spørger serveren først. En nøgle, der er udstedt til ét subjekt, bærer det allerede, og det svar gemmes uden at spørge, for en skrivning som en anden afvises alligevel. Ellers spørger den dig og foreslår en adresse, den finder i din git-opsætning, dernæst dit kontonavn på maskinen.

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]

Et id skal blot være stabilt og staves ens, uanset hvor du kalder fra. En e-mailadresse er et fint valg og er som regel den, der foreslås.

Uden en terminal spørges der om intet, for et spørgsmål, ingen er der til at besvare, venter for evigt. Angiv i stedet tilstand og id som flag; med ingen af delene gemmer opsætningen stadig nøglen, registrerer intet subjekt og siger det, og hvert kald navngiver så sit eget.

Derefter udfyldes både arten og subjektet for dig, når du udelader dem. Det, du selv angiver, vinder over det gemte, og ved en læsning findes et flag, der udvider igen til alle de subjekter, nøglen må se. Diagnosekommandoen viser, hvad der blev gemt.

# 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"

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.

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
  }
}

Markeringen på ikke-godkendt indhold

[unverified]

Indhold, som ingen har godkendt, kommer tilbage med dette præfiks foran sin tekst. Præfikset lægges på svaret og gemmes aldrig, så den samme erindring, læst af et indlogget menneske, bærer intet præfiks.

Det tilbageholdte, som et antal

withheld_count

Når en søgning eller en liste udelader noget, fordi det er tilbageholdt for denne nøgle, står antallet i JSON'en, og pfmem skriver det også til stderr i menneskelig tilstand. Et resultat, der lydløst blev mindre, er en model, der læser en mindre sandhed, end der findes, og antallet er den eneste advarsel.

En fremgangsmåde udleverer den version, et menneske har godkendt, når der er en

pending_version

En nøgle får den nyeste version, et menneske har godkendt. Har en nøgle skrevet en nyere version, som ingen har godkendt endnu, svarer opslaget med den godkendte version og nævner den ventende i dette felt, så agenten følger en fremgangsmåde, nogen stod inde for. Er der aldrig godkendt nogen version, udleveres den nyeste med markøren i stedet: en fremgangsmåde, som kun en nøgle har skrevet, kan stadig bruges, og intet tilbageholdes, før der er en godkendt version at falde bagud for.

Hvor en godkendelse sker

Godkendelsen sker i dashboardet på siden under Gennemgang — Markeret til gennemgang. Intet, en nøgle sender, kan gøre en post betroet, og det er det, der holder "et menneske har godkendt dette" som et faktum.

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.

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.

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.

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"

Søg, når du ved, at der nok findes en procedure, men ikke hvad den hed; list, når du vil se alt, denne nøgle kan nå. Begge svarer med sammendrag; kun søgningen tilføjer det afsnit, der matchede, med de matchende ord markeret, og selve teksten kommer fra læsningen.

En opdatering tilføjer en ny version og retter aldrig på stedet, så en gammel vejledning går aldrig tabt under en ny. Angiv den version, du læste, og en ændring, en anden nåede først, fejler tydeligt i stedet for at blive begravet. At tage en ud af brug fjerner den fra oversigt og søgning, mens dens tekst og alle versioner forbliver læsbare for enhver, der har id'et. Intet her sletter, og intet fortryder en udtagning: en procedure, der er taget ud af brug, får ingen flere versioner, så en afløser er en ny procedure.

En procedure er privat som udgangspunkt — dens ejende agent og enhver nøgle, der læser hele arbejdsområdet. At dele den med alle i arbejdsområdet er en beslutning, ikke en standard, og en opdatering kan flytte den begge veje. En nøgle uden en agent har ingen at holde en procedure privat for og må derfor dele dem, den skriver.

Kun det subjekt, der ejer en procedure, eller en nøgle uden noget subjekt overhovedet, kan tilføje til den eller tage den ud af brug. For alle andre svarer den som en, der ikke findes — så et afslag på en procedure, du kan se i oversigten, betyder, at den ikke er din at ændre, ikke at id'et er forkert. En master-nøgle er ikke sådan en nøgle her: den svarer for en konto og ikke for ét arbejdsområde, og denne klient sender aldrig et arbejdsområdes navn, så ethvert procedure-kald med den bliver afvist. Udsted en arbejdsområdenøgle, og giv klienten den.

De har intet med skill-kommandoerne nedenfor at gøre. En skill er én offentliggjort fil, der lærer din assistent at bruge denne klient; en procedure er indhold, dit arbejdsområde ejer og versionerer. At installere en skill gemmer ingen hukommelse, og at skrive en procedure installerer ingenting.

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.