memorysync-cli (Python)

MemorySync from your terminal. Zero dependencies.

The same CLI as the npm package memorysync-cli, implemented in Python. Same 21 commands, same flags, same output formats, same exit codes. The two are interchangeable, so you only need one.

pipx install memorysync-cli

pipx is recommended because this is an application rather than a library. pip install works too, but outside a virtual environment it fails on externally-managed Pythons — Homebrew and most Linux distributions — with externally-managed-environment (PEP 668).

Requires Python 3.9 or newer.

memorysync: command not found after installing

The install worked; your shell cannot see the directory pipx puts binaries in. Run pipx ensurepath, then reopen the terminal. Or invoke it by full path — pipx list prints the location.

To skip PATH entirely:

pipx run --spec memorysync-cli memorysync <command>

--spec is needed because pipx run memorysync-cli looks for a console script named after the package, and this package's scripts are memorysync and msync.

Both CLIs installed? Only one memorysync can win

The npm package installs the same two command names, so whichever directory comes first on PATH answers. To run this one specifically, use the full path from pipx list, or pipx run --spec as above.

python -m memorysync_cli works only when the package is installed into that interpreter with pip install. After a pipx install it will report No module named memorysync_cli, because pipx deliberately isolates the package in its own virtualenv.

Getting started

memorysync init                       # store a key, pick a default user
memorysync add "Prefers pnpm" --user alice
memorysync search "package manager" --user alice
memorysync quota                      # how much of the plan is left

Both memorysync and msync are installed; msync is just shorter.

Parity is enforced, not promised

Both CLIs read one generated command tree, so help --json is byte-identical between them. The test suite runs both and compares stdout for every offline command, including all four completion scripts, and compares exit codes for each failure mode. A command added to one and not the other fails the build.

That matters because the alternative does not hold. Mem0 ships a Node and a Python CLI and documents them as identical; their Python CLI answers help --json with twelve commands while their Node CLI answers with a name, a version and a description and no commands at all, and the two sit on different versions.

Zero dependencies

argparse, urllib.request and json cover everything. Mem0's Python CLI depends on httpx, rich and typer.

Every dependency is code on a customer's machine that they cannot audit on our behalf, which matters more for a closed-source tool because nobody else is reading our lockfile. A table and eight colours do not justify it.

Agent mode

Pass --json (or --agent) before the command for one JSON envelope, no colour, no spinners, errors as JSON with a non-zero exit:

memorysync --json search "preferences" --user alice

data is always a list, for every command. An agent parses one shape rather than remembering which commands return an object.

memorysync help --json     # the whole command tree, for self-discovery

Exit codes

A script can branch on the cause rather than parsing prose.

Code 4 earns its place. Over a plan limit the API returns success with an empty result rather than an error, deliberately, so an assistant never narrates billing state to an end user. From a terminal that silence is unhelpful, so the CLI reads usage and turns it into a distinct code — otherwise an exhausted plan is indistinguishable from an empty database.

Where your key is stored

Never in the config file. In order: MEMORYSYNC_API_KEY, then the OS keychain, then an owner-only encrypted file.

Windows has no scriptable Credential Manager path that avoids a dependency, so it uses the file tier. That is the same on the Node CLI. The file is 0600 and its contents are tied to the machine and user, which stops a casual cat or a backup scraper; anyone who can already run code as you can read it. The keychain is better, which is why it is tried first.

Deleting

delete is two-step by default: without --yes it previews and changes nothing.

delete --all clears that one end user's memories and nothing else. No form of any command can delete an account, a project or an API key.

To clear every memory for an end user through the API directly, use a wide filter on DELETE /memory/forget, for example {"before": "<now>"}. Not /memory/user/purge: despite its path it is not end-user scoped and erases the account behind the credential.

Environment variables

Documentation

https://docs.memorysync.io/cli