@persistmemory/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PersistMemory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# @persistmemory/cli
+
+**`pm`** — capture and search your memory from a terminal.
+
+[![npm](https://img.shields.io/npm/v/@persistmemory/cli.svg)](https://www.npmjs.com/package/@persistmemory/cli)
+[![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Memory that persists across every model, tool and session you use — reachable from the one
+place you already are.
+
+- **Browser sign-in, OAuth 2.1 + PKCE** — your password is never typed into a terminal
+- **One dependency-free binary** — the SDK is bundled in; a global install pulls down one thing
+- **Scriptable** — `--output json|yaml|csv|tsv`, and JSON automatically when piped
+- **Spaces** — keep work, personal and per-client memory apart
+- **File requests** — approve, from your terminal, what an assistant is allowed to read
+- **macOS, Linux, Windows** — the same `dist/bin.js` on all three
+
+---
+
+## Table of contents
+
+1. [Install](#install)
+2. [Sign in](#sign-in)
+3. [Get an API key (CI and headless)](#get-an-api-key-ci-and-headless)
+4. [First five minutes](#first-five-minutes)
+5. [Spaces](#spaces)
+6. [Commands](#commands)
+7. [Output formats and scripting](#output-formats-and-scripting)
+8. [Profiles](#profiles)
+9. [The agent, and file requests](#the-agent-and-file-requests)
+10. [Environment variables](#environment-variables)
+11. [Where your files live](#where-your-files-live)
+12. [Security](#security)
+13. [Troubleshooting](#troubleshooting)
+14. [Uninstall](#uninstall)
+
+---
+
+## Install
+
+**macOS and Linux**
+```bash
+curl -fsSL https://persistmemory.com/install.sh | sh
+```
+
+**Windows (PowerShell)**
+```powershell
+irm https://persistmemory.com/install.ps1 | iex
+```
+
+**Any platform, with npm**
+```bash
+npm install -g @persistmemory/cli
+
+# or run it without installing anything
+npx @persistmemory/cli auth login
+```
+
+Node 20 or newer is the only requirement.
+
+Piping a script into a shell is worth being careful about, so read ours first —
+[install.sh](https://persistmemory.com/install.sh) and
+[install.ps1](https://persistmemory.com/install.ps1). Both refuse to run rather than guessing
+when they cannot find a supported platform or a recent enough Node, neither escalates to
+`sudo` or Administrator on your behalf, and both tell you what to do instead when npm's global
+directory is not yours to write to.
+
+Two commands are installed: **`pm`** (what you will type) and **`persistmemory`** (the same
+thing, for when `pm` collides with something else on your machine).
+
+---
+
+## Sign in
+
+```bash
+pm auth login
+```
+
+Your browser opens, you approve the scopes on a consent screen, and the terminal says who you
+are. There is **no key to create and no password to paste** — that is the point.
+
+```bash
+pm auth status     # who am I, and does the server still accept it
+pm auth logout     # forget the stored credential
+```
+
+If you have no account yet, sign up at <https://persistmemory.com/signup> first (Google works),
+then run `pm auth login`.
+
+---
+
+## Get an API key (CI and headless)
+
+A browser sign-in needs a browser. On a build agent or a server over SSH, use a key instead.
+
+1. Sign in at <https://persistmemory.com/signin>.
+2. Open **Settings** from the header, or go to <https://persistmemory.com/settings#keys>.
+3. Under **API keys**, name the key after the machine or job that will use it — `ci`,
+   `deploy-bot`, `home-server` — not after yourself. The name is how you decide which one to
+   revoke later.
+4. Press **Create** and copy it at once. It looks like `pm_live_` plus 43 characters, is stored
+   only as a hash, and cannot be shown to you again. A lost key is revoked and replaced.
+5. Use it:
+
+```bash
+export PERSISTMEMORY_API_KEY=pm_live_...
+pm search "release checklist" --output json
+```
+
+`PERSISTMEMORY_API_KEY` takes precedence over any stored login, which is what makes CI
+predictable. Or store it in a profile instead:
+
+```bash
+pm auth login --api-key
+```
+
+Revoke a key any time in **Settings → API keys → Revoke**; whatever was using it stops
+working immediately. A key can read and write your memories and spaces — it cannot change your
+password or mint another key.
+
+---
+
+## First five minutes
+
+```bash
+pm auth login
+
+pm remember "we chose Postgres with pgvector over Pinecone — cost and lock-in"
+pm remember --file ./notes/architecture.md
+git log -1 --format=%B | pm remember -          # capture whatever is piped in
+
+pm search "why postgres"
+pm list memories --limit 20
+pm get memory <id>
+
+pm                                              # just start talking
+```
+
+Running `pm` with no arguments starts an interactive session: ask a question in plain
+English and it answers out of your own memory.
+
+> **`remember` is asynchronous.** It hands the text to the pipeline and returns. Extraction and
+> consolidation happen afterwards, so a memory may take a moment to become searchable — and the
+> same fact captured twice becomes one memory with two pieces of evidence, not two memories.
+
+---
+
+## Spaces
+
+A **space** is a boundary. Search inside one and you see only what is in it — that is how work
+stays out of personal and one client stays out of another.
+
+```bash
+pm list spaces                                   # what you have, with their ids
+```
+
+`--space` takes **space ids**, comma-separated — the ids `pm list spaces` prints, not the
+display names:
+
+```bash
+# Capture into a space
+pm remember "Acme's cutover is the 14th" --space space_a1b2c3
+
+# Search only there
+pm search "cutover date" --space space_a1b2c3
+
+# Several at once
+pm search "deadline" --space space_a1b2c3,space_d4e5f6
+```
+
+Creating a space is not a CLI command yet. Make one with the SDK or the API:
+
+```ts
+import { PersistMemory } from "@persistmemory/sdk";
+const client = new PersistMemory({ apiKey: process.env.PERSISTMEMORY_API_KEY! });
+const acme = await client.spaces.create({ name: "Acme", kind: "project" });
+console.log(acme.id);
+```
+
+```bash
+curl -s https://api.persistmemory.com/api/v1/spaces \
+  -H "authorization: Bearer $PERSISTMEMORY_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"name":"Acme","kind":"project"}'
+```
+
+Leaving `--space` off searches everything you have.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `pm` | Start an interactive session and just ask |
+| `pm chat` | The same, explicitly |
+| `pm chat --resume <id>` | Pick up an earlier session |
+| `pm auth login` | Sign in through the browser |
+| `pm auth login --api-key` | Sign in with a key, for CI and headless machines |
+| `pm auth status` | Who am I, and does the server still accept it |
+| `pm auth logout` | Forget the stored credential |
+| `pm remember <text>` | Capture text |
+| `pm remember -` | Capture whatever is piped in |
+| `pm remember --file <path>` | Capture a file's contents |
+| `pm search <query>` | Search your memory |
+| `pm list memories` | The most recent memories |
+| `pm list spaces` | Your spaces |
+| `pm get memory <id>` | One memory, in full |
+| `pm status` | Is the service healthy |
+| `pm requests` | File requests waiting for you to approve |
+| `pm agent --root <dir>` | Answer file requests, reading only inside the folders you name |
+
+Flags: `--output`, `--profile`, `--api-url`, `--limit`, `--space`, `--quiet`, `--version`,
+`--help`. `pm --help` prints the whole thing, always up to date with the version you have.
+
+---
+
+## Output formats and scripting
+
+```bash
+pm search "postgres" --output json | jq '.results[].memory.title'
+pm list memories --output csv > memories.csv
+pm list spaces --output yaml
+```
+
+The default is a **table on a terminal and JSON when piped**, so a command you typed stays
+readable and the same command in a script stays parseable — without you remembering a flag.
+
+Exit codes are meaningful: `0` success, non-zero on failure, so `set -e` behaves.
+
+---
+
+## Profiles
+
+More than one account — your own and a work one, or production and staging:
+
+```bash
+pm auth login --profile work
+pm search "roadmap" --profile work
+export PERSISTMEMORY_PROFILE=work        # or set it for the shell
+```
+
+Each profile keeps its own credential. `--profile` beats the environment variable, which beats
+the stored default.
+
+---
+
+## The agent, and file requests
+
+`pm agent` lets an assistant — in Claude, ChatGPT, Telegram, wherever you are — ask for a file
+from *this* machine. It reads **only inside the folders you name**, and nothing is read until
+you approve it.
+
+```bash
+pm agent --root ~/projects --root ~/Documents
+```
+
+Then, from anywhere: *"get me the deploy checklist from my laptop"*. The request appears here:
+
+```bash
+pm requests            # what is waiting
+```
+
+and on the web at <https://persistmemory.com/dashboard/requests>.
+
+**A request made by a model is never fulfilled automatically.** A live read is something you
+approve, every time, because the thing asking may be repeating an instruction it found in
+somebody else's email.
+
+---
+
+## Environment variables
+
+| Variable | Meaning |
+| --- | --- |
+| `PERSISTMEMORY_API_KEY` | A key, taking precedence over any stored login. This is what CI should set. |
+| `PERSISTMEMORY_API_URL` | The server to talk to. Default `https://api.persistmemory.com` |
+| `PERSISTMEMORY_PROFILE` | Which stored profile to use |
+| `PERSISTMEMORY_HOME` | Where config, credentials and transcripts live. Default `~/.persistmemory` |
+| `PERSISTMEMORY_CLIENT_ID` | Override the OAuth client id, for a self-hosted deployment |
+
+---
+
+## Where your files live
+
+```
+~/.persistmemory/
+├── config.json        profiles and the current one
+├── credentials.json   tokens — treat this like an SSH key
+└── sessions/          transcripts of your interactive sessions
+```
+
+Move all of it with `PERSISTMEMORY_HOME`.
+
+---
+
+## Security
+
+- **The browser holds the password, not the CLI.** Sign-in is OAuth 2.1 with PKCE. Your password
+  is never typed into a terminal and never passes through this program. What comes back is a
+  token scoped to what you approved on the consent screen.
+- **A stolen code is worthless on its own.** The CLI invents a one-time secret, sends only its
+  hash to the browser, and reveals the secret when redeeming the code. Anything that intercepts
+  the redirect on a shared machine gets a code it cannot exchange.
+- **The callback is loopback-only** — `http://127.0.0.1:<random port>`, listening for one
+  request and then closed.
+- **Credentials are files with your permissions**, not entries in a shared keychain another
+  process can read without asking.
+- **Nothing is read from your disk without you saying so.** See file requests, above.
+
+Found a security problem? <mailto:hello@persistmemory.com>. Please do not open it in public.
+
+---
+
+## Troubleshooting
+
+**`pm: command not found` after `npm install -g`**
+npm's global bin directory is not on your `PATH`. `npm bin -g` prints it; add that to your
+shell profile. The install script sets this up for you, which is why it exists.
+
+**`EACCES` during a global install**
+Do not reach for `sudo`. Either use the install script, or point npm at a directory you own:
+`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to your `PATH`.
+
+**`pm auth login` opens the browser and nothing happens**
+The callback is on `127.0.0.1`. A VPN, a proxy that captures loopback, or a browser on a
+*different machine* than the CLI will break it. On a remote box use `pm auth login --api-key`
+instead — that is exactly what it is for.
+
+**"Session expired"**
+An OAuth token lasts an hour and renews itself; if renewal fails, `pm auth login` again. An API
+key does not expire on a schedule — if a key stops working, it was revoked.
+
+**`pm search` finds nothing you just captured**
+`remember` is asynchronous. Give the pipeline a moment, then search again.
+
+**Everything fails with a connection error**
+`pm status` reports whether the service is reachable. Check `PERSISTMEMORY_API_URL` is not left
+over from a local experiment.
+
+**Node is too old**
+`node --version` must be 20 or newer. The CLI refuses to run rather than failing later in a
+confusing way.
+
+---
+
+## Uninstall
+
+```bash
+npm uninstall -g @persistmemory/cli
+rm -rf ~/.persistmemory        # optional: credentials, config and transcripts
+```
+
+---
+
+## Links
+
+- CLI documentation — <https://persistmemory.com/docs/cli>
+- TypeScript SDK — [`@persistmemory/sdk`](https://www.npmjs.com/package/@persistmemory/sdk)
+- API keys — <https://persistmemory.com/settings#keys>
+- Support — <mailto:hello@persistmemory.com>
+
+## License
+
+MIT © PersistMemory