MemoryRouter / Documentation
CLI
Install the MemoryRouter CLI, upload reviewed files, and verify that a connected AI can recall them in a fresh session.
The standalone @memoryrouter/cli package uploads selected documents and code to a MemoryRouter vault, checks vault status, and provides a separate approval-based ChatGPT archive importer. It does not require OpenClaw, LangChain, or a running AI model.
CLI overview | All integrations | Create an account
Prerequisites
- Node.js 20.16 or later within Node 20, or Node.js 22.3 or later. Node 21 is not in the package's supported engine range.
- npm and network access to
https://api.memoryrouter.ai. - A MemoryRouter account and a writable Memory Key for the intended vault.
- A reviewed local file or dedicated upload directory. Upload only material you have permission to store.
- For the recall proof, an AI client already connected to that same vault through MCP or a supported integration.
Install
npm install --global @memoryrouter/cli
memoryrouter --version
memoryrouter --helpThe npm package is scoped; the installed executable is memoryrouter. Without a global installation, use:
npx @memoryrouter/cli --helpAuthenticate
Get the Memory Key from your dashboard. Supply it through your local secret-management workflow, then run:
memoryrouter auth "$MEMORYROUTER_KEY"
memoryrouter whoami
memoryrouter statusMEMORYROUTER_KEY in this example is a shell variable that you populate locally. The CLI does not automatically read this environment variable as authentication. The auth command saves the supplied key to ~/.memoryrouter/config.json.
Keep that file out of source control and shared backups. On a POSIX system you can restrict local access after authentication:
chmod 700 ~/.memoryrouter
chmod 600 ~/.memoryrouter/config.jsonwhoami displays the configured endpoint and a masked key; it does not prove the server accepted the key. auth also saves the key if its validation request cannot complete, so check status and the subsequent upload result before calling setup successful. Never include an unmasked key or the configuration file in a support message.
Custom endpoint
Configure an explicitly trusted endpoint during authentication, not during upload:
memoryrouter auth "$MEMORYROUTER_KEY" --endpoint https://your-trusted-api.example
memoryrouter upload ./reviewed-docs/The CLI removes a trailing /v1 before constructing API paths. There is no upload --endpoint option. Custom endpoint support is not a claim that a self-hosted MemoryRouter distribution is available.
Upload reviewed files
memoryrouter upload ./reviewed-docs/README.md
memoryrouter upload ./reviewed-docs/Directory upload is recursive. The CLI does not honor .gitignore or automatically exclude .git, node_modules, hidden directories, credentials, or private source. Prepare a clean directory containing only approved files. Do not point it at your home directory or a whole repository without reviewing the contents.
File handling
| Input | Behavior |
|---|---|
| Documents | Directory discovery includes .md, .mdx, .txt, .rst, .pdf, and .docx. PDF and DOCX are converted to text. |
| Source and configuration | Includes common formats such as .ts, .js, .py, .go, .rs, .java, .json, .yaml, .yml, .toml, and shell scripts. |
| Data and markup | Includes .csv, .tsv, .sql, .html, and .xml. CSS is not in directory discovery's supported extension list. |
| Session JSONL | Parses records with type: "message", a nested message.role of user or assistant, and text content. This is not a generic JSONL import parser. |
| Small or large files | Ordinary files with fewer than 50 trimmed characters are skipped. Directory discovery includes only nonempty files smaller than 10,000,000 bytes. |
Ordinary files are stored as user-role text with the filename included and the file modification time as their timestamp. Large text is split near line boundaries with an approximately 8,000-character target. Very long individual lines can exceed that target; do not assume the split is a hard maximum.
Batches target 100 items or approximately two million serialized characters. The CLI makes up to five attempts for retryable network errors, HTTP 429, or server errors. Read the stored and failed counts: a finished command is not proof that every item was accepted.
Session-scoped upload
memoryrouter upload ./reviewed-project/ --session demo-projectThis sends X-Session-ID: demo-project with the upload. Session scoping is not a separate account or an access-control boundary. Your retrieval client must use the corresponding session scope where required. See core concepts for vault and session behavior.
Synthetic cross-session proof
This procedure demonstrates persistence beyond the upload process. It is a recipe, not a claim that a test has run in your account.
- Use a dedicated test vault and connect an MCP-capable client to that same vault.
- In terminal session A, create and upload a harmless note:
mkdir -p ./mr-cli-demo
printf '%s\n' 'For the synthetic harbor demo, the review day is Thursday and the approved project label is copper-lantern-42.' > ./mr-cli-demo/proof.txt
memoryrouter upload ./mr-cli-demo/proof.txt
memoryrouter status- Confirm the upload reports a stored memory and no failed items. Close terminal session A.
- Open a new AI conversation using the same test vault. Ask:
Search MemoryRouter for the synthetic harbor demo. What are its review day and approved project label?- Do not paste the note or the expected answer into the new conversation. Check the returned memory content for
Thursdayandcopper-lantern-42. - If recall is empty, verify the vault selection, inspect the actual tool result, and retry after the upload is available. A plausible model answer without a memory result is not sufficient evidence.
The CLI has no recall or search subcommand. Retrieval happens through the connected client or the memory API, not through the upload command.
ChatGPT archive import
For an official ChatGPT data export, use the dedicated ChatGPT import guide. The CLI has separate chatgpt-import inspect, prepare, approve, run, resume, status, cancel, and receipt commands.
Do not substitute generic upload for that workflow. The archive importer provides preview-bound approval and resumable import receipts. Generic file upload does not provide the same approval manifest or exactly-once import contract. For Claude Code, Codex, and OpenClaw history, use agent history import.
Limitations
- Uploading documents does not install automatic conversational capture into your AI client.
- The CLI stores a key in a local JSON file, not an OS credential vault. Treat it as a secret.
- Directory discovery is not a privacy filter. It can include sensitive supported files inside nested directories.
- PDF text extraction is not OCR for scanned pages. Verify the extracted result before relying on it.
- Generic upload does not promise automatic synchronization or removal when source files change.
- A generic upload retry does not carry the dedicated importer receipt and idempotency contract. Review failures before repeating a large upload.
- Vault status is a diagnostic, not proof of exact recall or of every uploaded file's contents.
Troubleshooting
| Symptom | Check |
|---|---|
memoryrouter: command not found | Confirm installation of @memoryrouter/cli and npm's global executable directory on PATH, or use npx @memoryrouter/cli. |
unknown option '--endpoint' on upload | Set the endpoint with memoryrouter auth ... --endpoint ...; upload has only the session option. |
Not authenticated | Run auth for the current OS user and confirm the config file is readable. A different user or container has a different home directory. |
| Authentication appears saved but requests fail | auth can save after failed validation. Check the key, account access, endpoint, and network using status. |
No supported files found | Check the directory's extensions and size limits. Explicit file input and directory discovery do not use identical filtering. |
No content to upload | Check minimum text length and the special JSONL transcript shape. For arbitrary memory records use the documented API instead. |
| Some items failed | Read batch results and server errors. Resolve authentication, quota, or content issues before retrying. Never infer complete success from the final success icon alone. |
| New AI session cannot recall the note | Verify the same Memory Key or OAuth-selected vault, tool availability, and session scope. Ask for an explicit memory search. |
Upgrade, remove, and delete
Upgrade the executable with npm install --global @memoryrouter/cli. Remove it with npm uninstall --global @memoryrouter/cli. Uninstalling the package does not remove stored memories or the local config file.
memoryrouter delete clears the selected vault after an interactive confirmation. memoryrouter delete --session demo-project targets that session. These are destructive operations, not routine troubleshooting. Use only a disposable test vault for cleanup of the proof above, and verify the selected key first. Avoid --yes unless you intentionally want to bypass the confirmation.
To remove local access, remove ~/.memoryrouter/config.json through your normal file-management process and rotate or revoke the key in the dashboard if needed. Deleting the config file alone does not revoke the key.