Metadata-Version: 2.5
Name: memorysync-cli
Version: 1.2.0
Summary: MemorySync from your terminal. Zero dependencies.
Project-URL: Documentation, https://docs.memorysync.io/cli
Project-URL: Homepage, https://memorysync.io/cli
Author: MemorySync
License: MIT
License-File: LICENSE
Keywords: agent-memory,ai-agents,cli,llm,long-term-memory,memory,memorysync,terminal
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

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

```bash
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](https://peps.python.org/pep-0668/)).

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:

```bash
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

```bash
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:

```bash
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.

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

## Exit codes

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

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Unclassified failure |
| 2 | Usage: unknown command, bad flag, bad value |
| 3 | Auth: missing, expired or revoked credentials |
| 4 | Quota: a plan limit is reached |
| 5 | Network: unreachable or timed out |
| 6 | Not found |
| 130 | Interrupted |

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.

| Platform | Storage |
|---|---|
| macOS | Keychain, via `security` |
| Linux | Keyring, via `secret-tool`, when libsecret is present |
| Windows | 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

| Variable | Purpose |
|---|---|
| `MEMORYSYNC_API_KEY` | Key, highest priority |
| `MEMORYSYNC_BASE_URL` | API base URL |
| `MEMORYSYNC_USER` | Default end user |
| `MEMORYSYNC_PROJECT` | Default project |
| `MEMORYSYNC_PROFILE` | Named profile |
| `MEMORYSYNC_OUTPUT` | Default output format |
| `MEMORYSYNC_CONFIG_DIR` | Where config and credentials live |
| `NO_COLOR` | Disable colour |

## Documentation

<https://docs.memorysync.io/cli>
