CLI

Install

npm install -g memorysync-cli

Or run it without installing, which is the easier path inside a container or a one-off script:

npx memorysync-cli help

Needs Node 18 or newer. The package has no dependencies, so there is no transitive tree to audit and nothing is compiled at install time.

Authenticate

init asks for a key, verifies it against the API before saving anything, and records a default user and project.

memorysync init

For CI or any non-interactive shell, pass the values instead. Without a terminal there is no prompt, and the command fails with the flag to add rather than hanging on stdin.

memorysync init --api-key ms_live_xxx --user alice --force

Or skip stored credentials entirely and set MEMORYSYNC_API_KEY, which takes precedence over anything on disk.

Quick start

# Store a fact
memorysync add "I prefer TypeScript over JavaScript" --user alice

# Search it back
memorysync search "language preference" --user alice

# Recent memories, as a table
memorysync list --user alice -o table

# Pipe something in
echo "Ships on Fridays" | memorysync add --user alice

Commands

Every command accepts every output format, and memorysync help <command> prints its flags and examples.

Use it inside an agent

Put --json (or --agent) before the command name. Every command then answers with one envelope on stdout, whether it succeeded or failed, with no colour and no spinners.

memorysync --json search "preferences" --user alice | jq '.data[].text'

{
  "status": "success",
  "command": "search",
  "duration_ms": 134,
  "scope": { "user": "alice", "profile": "default" },
  "count": 2,
  "data": [
    { "id": "m_60632", "text": "Prefers TypeScript", "score": 0.97 }
  ],
  "quota": {
    "metric": "retrieval_requests",
    "used": 12,
    "limit": 1000,
    "exhausted": false
  }
}

Results are always an array under data, for every command, so .data[] works everywhere. Failures use the same envelope with status: "error" and a non-zero exit, so one code path handles both outcomes.

memorysync help --json returns the entire command tree, so an agent can discover the surface for itself rather than being told about it in a prompt.

Exit codes

Distinct per cause, so a script can branch without parsing stderr.

memorysync add "$FACT" --user "$USER_ID"
case $? in
  0) echo "stored" ;;
  3) echo "credential problem"; exit 1 ;;
  4) echo "out of quota - nothing was stored"; exit 1 ;;
  5) echo "network problem, retrying"; sleep 5 ;;
esac

Output formats

Set with -o. Every command accepts all five, so a script never has to remember which command refuses which format.

text

Human-readable, with colour when the terminal supports it. The default.

table

Aligned columns, with long values truncated to keep rows on one line.

json

The raw structured result, for piping to jq.

yaml

The same data, easier to read at a glance for nested objects.

quiet

Nothing on stdout. Use the exit code.

Profiles

For more than one environment or account, without juggling exported variables in separate shells.

memorysync init --profile staging --api-key ms_live_xxx --user alice
memorysync config profiles
memorysync config use-profile staging
memorysync --profile production status

Precedence, highest first: explicit flags, environment variables, the profile, then defaults. Environment beats the profile deliberately, so a CI image cannot be steered by a config file that happens to be baked into it.

Deleting

delete previews by default and changes nothing until you pass --yes. The preview is the server's own dry run, so what it lists is exactly what a confirmed run removes.

memorysync delete m_60632 --user alice          # previews, deletes nothing
memorysync delete m_60632 --user alice --yes    # performs it
memorysync delete --all --user alice            # previews the whole scope

Connected sources

Inspect and drive the connectors feeding memory — GitHub, Slack, Notion, Google Drive, OneDrive, Granola, Amazon S3 and crawled sites — without opening the dashboard.

memorysync source list
memorysync source status github
memorysync source sync github
memorysync source pause slack

Connecting a new source needs a browser round trip for OAuth, so that stays in the dashboard. A CLI that half-connected a source would be worse than one that does not try.

Shell completion

# bash
memorysync completion bash > /etc/bash_completion.d/memorysync

# zsh
memorysync completion zsh > "${fpath[1]}/_memorysync"

# fish
memorysync completion fish > ~/.config/fish/completions/memorysync.fish

# PowerShell — add to your profile
memorysync completion powershell | Out-String | Invoke-Expression

Start a new shell afterwards for it to take effect.

When something is wrong

Start with doctor. It checks the credential and where it is stored, file permissions, DNS, API reachability, quota headroom, the project binding and your Node version, then prints what to fix. It exits 0 even when checks fail, because diagnosing is what it was asked to do.

memorysync doctor

Environment variables

Where to go next

MemorySync MCP

Give an assistant the same memory through the Model Context Protocol, instead of shelling out.

SDKs

Call the API from your own code, in Python or TypeScript.

API reference

Every endpoint the CLI wraps, with request and response shapes.