UnifiedMemory CLI (`um`)

![npm version](https://www.npmjs.com/package/@unifiedmemory/cli)
![License: PROPRIETARY](./LICENSE)
![Node Version](https://nodejs.org)

Connect your AI code assistant to UnifiedMemory's knowledge vault with one command.

What is UnifiedMemory?

UnifiedMemory is an AI-powered knowledge management system that lets your code assistant remember context across all your projects. The um CLI connects your local AI tools (Claude Code, Cursor, Cline, etc.) to your UnifiedMemory vault so they can access and store project knowledge automatically.

Quick Start

``bash

`Install globally`


npm install -g @unifiedmemory/cli
Or run directly with npx (no installation required)

npx @unifiedmemory/cli init
In your project directory

cd your-project
um init


That's it! Your AI assistant can now access UnifiedMemory.
What Does This Do?

When you run um init in your project:

1. Authenticates you - Opens your browser to sign in with UnifiedMemory (one-time) 2. Links your project - Choose an existing project or create a new one in your vault 3. Configures AI tools - Automatically detects and configures Claude Code, Cursor, Cline, Codex CLI, or Gemini CLI 4. Creates local config - Adds a.um/ folder to your project (auto-added to .gitignore)

After setup, your AI assistant will automatically: - ✅ Store important code context in your UnifiedMemory vault - ✅ Retrieve relevant knowledge when working on similar problems - ✅ Remember decisions and patterns across sessions - ✅ Switch context automatically when you change projects

`What Gets Created in Your Project?`

`your-project/ ├── .um/ │ └── config.json # Project configuration (auto-ignored by git) ├── .gitignore # Updated to exclude .um/ └── .mcp.json # MCP server config (Claude Code only)`

Note: Authentication tokens are stored securely in ~/.um/auth.json on your machine, never in your project directory.

`Supported AI Code Assistants`

| Tool | Status | Configuration | |------|--------|--------------| | Claude Code | ✅ Fully Supported | Project-level.mcp.json| | Cursor | ✅ Fully Supported | Global~/.cursor/mcp.json| | Cline | ✅ Fully Supported | Global~/.cline/mcp.json| | Codex CLI | ✅ Fully Supported | Global~/.codex/config.toml| | Gemini CLI | ✅ Fully Supported | Global~/.gemini/settings.json |

The CLI automatically detects which tools you have installed and configures them for you.

`Commands`

`$3`


Set up UnifiedMemory in your current project (recommended).

`bash um init # Interactive setup um init --skip-configure # Skip AI tool configuration`

`$3`


Sign in to UnifiedMemory. Opens your browser for authentication.

`bash um login`

`$3`


Check your authentication status and see which project is configured.

`bash um status`

Example output:`📋 UnifiedMemory Status

Authentication: Status: Active Email: you@example.com Expires: 1/7/2026

Organization Context: My Organization (my-org) Role: admin

Project Configuration: ✓ Configured: My Project (proj_xxx)`

`$3`


Check your current usage and quota allowances.

`bash um usage`

Example output:`📊 Usage & Quota

Account: Organization: My Team

Monthly Queries: 450 / 1,000 (45.0%) [█████████░░░░░░░░░░░] Remaining: 550 queries Resets: 2/1/2026`

Context-aware: Shows personal or organization quota based on current context (um org switch).

Color indicators: - 🟢 Green: <70% usage - 🟡 Yellow: 70-89% usage - 🔴 Red: ≥90% usage (with upgrade prompt)

`$3`


Switch between your organizations or personal account.

`bash um org switch`

`$3`


Fix organization token if API calls fail with org mismatch errors.

`bash um org fix`

This command diagnoses and repairs tokens that are missing organization claims. Use it when: - MCP server returns 401 MISMATCH errors -um statusshows an org selected but API calls fail - After switching organizations if token update failed

`$3`


Manually save a note to your vault (useful for capturing important context).

`bash um note create`

`$3`


Start the MCP server (used internally by AI assistants - you don't need to run this manually).
How It Works
UnifiedMemory uses the Model Context Protocol (MCP) to connect your AI assistant to your knowledge vault:

1. Your AI assistant calls um mcp servein the background 2. The local MCP server reads your authentication from~/.um/auth.json3. It detects which project you're in by looking for.um/config.json4. Tool requests from your AI flow through the server to UnifiedMemory's API 5. Knowledge is stored and retrieved automatically based on context

Security: - Authentication tokens are stored locally in your home directory, never in project files - Tokens automatically refresh when they expire - Each project directory has its own configuration - The.um/ folder is automatically added to .gitignore

`Multi-Project Support`

Working on multiple projects? No problem!

`bash cd project-1 um init # Links to "Project 1" in UnifiedMemory

cd ../project-2 um init # Links to "Project 2" in UnifiedMemory`

The CLI automatically detects which project you're in and switches context. Your AI assistant will use the correct vault for each project.

`Switching Organizations`

If you're part of multiple teams:

`bash um org switch # Choose between organizations`

All projects you create afterward will belong to the selected organization.

`Installation Options`

Option 1: Global Install (recommended)`bash npm install -g @unifiedmemory/cli um --version`

No configuration required! The CLI includes production defaults and works immediately after installation.

Option 2: Use with npx (no installation)`bash npx @unifiedmemory/cli init npx @unifiedmemory/cli status`

Option 3: Use with MCP directly

Your AI assistant will call the MCP server automatically after running um init.

`Requirements`

- Node.js: Version 18.0.0 or higher - npm: Latest version recommended - AI Code Assistant: One of Claude Code, Cursor, Cline, Codex CLI, or Gemini CLI - UnifiedMemory Account: Sign up at unifiedmemory.ai

`Troubleshooting`

`$3`

bash
um login


$3

1. Check status:

um status


2. Verify project is configured
3. Restart your AI assistant
4. Check the MCP configuration was created (

.mcp.json

 or tool-specific config)
$3

bash
um org switch              # Switch organization
cd your-project && um init # Reconfigure project


$3

Tokens automatically refresh. If you see auth errors:

bash
um login


Advanced Configuration (Optional)
For most users, no configuration is needed! The CLI includes production defaults and works out of the box.

For development, testing, or custom deployments, you can override defaults by creating a .env file:

Step 1: Create .env file(optional)`bash

`In the um-cli installation directory (find with: npm root -g)`


cp .env.example .env

Step 2: Override the values you need (optional)`bash

`Optional: Override production defaults`


CLERK_CLIENT_ID=custom_clerk_client_id
CLERK_DOMAIN=custom-app.clerk.accounts.dev
API_ENDPOINT=https://custom-api-gateway.zuplo.dev
Optional: Customize OAuth redirect (defaults to localhost:3333)

REDIRECT_URI=http://localhost:3333/callback
PORT=3333


When you might need this:
- 🔧 Development: Testing with a local API backend
- 🧪 Testing: Using a staging or test Clerk instance
- 🏢 Custom Deployment: Running your own UnifiedMemory instance

See .env.example for the complete template with documentation.

`Privacy & Security`

UnifiedMemory CLI follows security best practices to protect your credentials and data:

`$3`


- File permissions: Tokens stored in

~/.um/auth.json with 0600

 permissions (owner read/write only)
- Directory permissions:

~/.um/ directory has 0700

 permissions (owner access only)
- No plaintext exposure: Tokens are never logged to console or stored in project files
- Auto-refresh: Tokens refresh automatically before expiring
$3

- PKCE flow: Uses OAuth 2.0 PKCE for secure authentication without client secrets
- CSRF protection: Cryptographically secure random state parameters
- Local-first: All authentication happens on your machine, never shared with third parties
$3

- No git commits:

.um/ directory automatically added to .gitignore`
- Project isolation: Each project has its own configuration and vault
- Environment-based config: No hardcoded credentials in source code
- Minimal permissions: CLI only requests access it needs

$3

- ❌ No tokens in analytics
- ❌ No credentials in error reports
- ❌ No project code sent to our servers
- ✅ Only encrypted knowledge stored in your vault

$3

Security issues are taken seriously. To report a vulnerability, please email security@unifiedmemory.ai (do not use public issues).

Learn More

- Website: unifiedmemory.ai
- Documentation: docs.unifiedmemory.ai
- Support: GitHub Issues

License

See LICENSE for details.

UnifiedMemory CLI (`um`)

![npm version](https://www.npmjs.com/package/@unifiedmemory/cli)
![License: PROPRIETARY](./LICENSE)
![Node Version](https://nodejs.org)

Connect your AI code assistant to UnifiedMemory's knowledge vault with one command.

What is UnifiedMemory?

Quick Start

``bash

`Install globally`


npm install -g @unifiedmemory/cli
Or run directly with npx (no installation required)

npx @unifiedmemory/cli init
In your project directory

cd your-project
um init


That's it! Your AI assistant can now access UnifiedMemory.
What Does This Do?

When you run um init in your project:

`What Gets Created in Your Project?`

Note: Authentication tokens are stored securely in ~/.um/auth.json on your machine, never in your project directory.

`Supported AI Code Assistants`

The CLI automatically detects which tools you have installed and configures them for you.

`Commands`

`$3`


Set up UnifiedMemory in your current project (recommended).

`bash um init # Interactive setup um init --skip-configure # Skip AI tool configuration`

`$3`


Sign in to UnifiedMemory. Opens your browser for authentication.

`bash um login`

`$3`


Check your authentication status and see which project is configured.

`bash um status`

Example output:`📋 UnifiedMemory Status

Authentication: Status: Active Email: you@example.com Expires: 1/7/2026

Organization Context: My Organization (my-org) Role: admin

Project Configuration: ✓ Configured: My Project (proj_xxx)`

`$3`


Check your current usage and quota allowances.

`bash um usage`

Example output:`📊 Usage & Quota

Account: Organization: My Team

Monthly Queries: 450 / 1,000 (45.0%) [█████████░░░░░░░░░░░] Remaining: 550 queries Resets: 2/1/2026`

Context-aware: Shows personal or organization quota based on current context (um org switch).

Color indicators: - 🟢 Green: <70% usage - 🟡 Yellow: 70-89% usage - 🔴 Red: ≥90% usage (with upgrade prompt)

`$3`


Switch between your organizations or personal account.

`bash um org switch`

`$3`


Fix organization token if API calls fail with org mismatch errors.

`bash um org fix`

`$3`


Manually save a note to your vault (useful for capturing important context).

`bash um note create`

`$3`


Start the MCP server (used internally by AI assistants - you don't need to run this manually).
How It Works
UnifiedMemory uses the Model Context Protocol (MCP) to connect your AI assistant to your knowledge vault:

`Multi-Project Support`

Working on multiple projects? No problem!

`bash cd project-1 um init # Links to "Project 1" in UnifiedMemory

cd ../project-2 um init # Links to "Project 2" in UnifiedMemory`

The CLI automatically detects which project you're in and switches context. Your AI assistant will use the correct vault for each project.

`Switching Organizations`

If you're part of multiple teams:

`bash um org switch # Choose between organizations`

All projects you create afterward will belong to the selected organization.

`Installation Options`

Option 1: Global Install (recommended)`bash npm install -g @unifiedmemory/cli um --version`

No configuration required! The CLI includes production defaults and works immediately after installation.

Option 2: Use with npx (no installation)`bash npx @unifiedmemory/cli init npx @unifiedmemory/cli status`

Option 3: Use with MCP directly

Your AI assistant will call the MCP server automatically after running um init.

`Requirements`

`Troubleshooting`

`$3`

bash
um login


$3

1. Check status:

um status


2. Verify project is configured
3. Restart your AI assistant
4. Check the MCP configuration was created (

.mcp.json

 or tool-specific config)
$3

bash
um org switch              # Switch organization
cd your-project && um init # Reconfigure project


$3

Tokens automatically refresh. If you see auth errors:

bash
um login


Advanced Configuration (Optional)
For most users, no configuration is needed! The CLI includes production defaults and works out of the box.

For development, testing, or custom deployments, you can override defaults by creating a .env file:

Step 1: Create .env file(optional)`bash

`In the um-cli installation directory (find with: npm root -g)`


cp .env.example .env

Step 2: Override the values you need (optional)`bash

`Optional: Override production defaults`


CLERK_CLIENT_ID=custom_clerk_client_id
CLERK_DOMAIN=custom-app.clerk.accounts.dev
API_ENDPOINT=https://custom-api-gateway.zuplo.dev
Optional: Customize OAuth redirect (defaults to localhost:3333)

REDIRECT_URI=http://localhost:3333/callback
PORT=3333


When you might need this:
- 🔧 Development: Testing with a local API backend
- 🧪 Testing: Using a staging or test Clerk instance
- 🏢 Custom Deployment: Running your own UnifiedMemory instance

See .env.example for the complete template with documentation.

`Privacy & Security`

UnifiedMemory CLI follows security best practices to protect your credentials and data:

`$3`


- File permissions: Tokens stored in

~/.um/auth.json with 0600

 permissions (owner read/write only)
- Directory permissions:

~/.um/ directory has 0700

 permissions (owner access only)
- No plaintext exposure: Tokens are never logged to console or stored in project files
- Auto-refresh: Tokens refresh automatically before expiring
$3

- PKCE flow: Uses OAuth 2.0 PKCE for secure authentication without client secrets
- CSRF protection: Cryptographically secure random state parameters
- Local-first: All authentication happens on your machine, never shared with third parties
$3

- No git commits:

$3

- ❌ No tokens in analytics
- ❌ No credentials in error reports
- ❌ No project code sent to our servers
- ✅ Only encrypted knowledge stored in your vault

$3

Security issues are taken seriously. To report a vulnerability, please email security@unifiedmemory.ai (do not use public issues).

Learn More

- Website: unifiedmemory.ai
- Documentation: docs.unifiedmemory.ai
- Support: GitHub Issues

License

See LICENSE for details.

@unifiedmemory/cli

UnifiedMemory CLI (um)

What is UnifiedMemory?

Quick Start

Install globally

Or run directly with npx (no installation required)

In your project directory

What Does This Do?

What Gets Created in Your Project?

Supported AI Code Assistants

Commands

$3

$3

$3

$3

$3

$3

$3

$3

How It Works

Multi-Project Support

Switching Organizations

Installation Options

Requirements

Troubleshooting

$3

$3

$3

$3

Advanced Configuration (Optional)

In the um-cli installation directory (find with: npm root -g)

Optional: Override production defaults

Optional: Customize OAuth redirect (defaults to localhost:3333)

Privacy & Security

$3

$3

$3

$3

$3

Learn More

License

@unifiedmemory/cli

UnifiedMemory CLI (um)

What is UnifiedMemory?

Quick Start

Install globally

Or run directly with npx (no installation required)

In your project directory

What Does This Do?

What Gets Created in Your Project?

Supported AI Code Assistants

Commands

$3

$3

$3

$3

$3

$3

$3

$3

How It Works

Multi-Project Support

Switching Organizations

Installation Options

Requirements

Troubleshooting

$3

$3

$3

$3

Advanced Configuration (Optional)

In the um-cli installation directory (find with: npm root -g)

Optional: Override production defaults

Optional: Customize OAuth redirect (defaults to localhost:3333)

Privacy & Security

$3

$3

$3

$3

$3

UnifiedMemory CLI (`um`)

`Install globally`

`What Gets Created in Your Project?`

`Supported AI Code Assistants`

`Commands`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Multi-Project Support`

`Switching Organizations`

`Installation Options`

`Requirements`

`Troubleshooting`

`$3`

`In the um-cli installation directory (find with: npm root -g)`

`Optional: Override production defaults`

`Privacy & Security`

`$3`

UnifiedMemory CLI (`um`)

`Install globally`

`What Gets Created in Your Project?`

`Supported AI Code Assistants`

`Commands`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Multi-Project Support`

`Switching Organizations`

`Installation Options`

`Requirements`

`Troubleshooting`

`$3`

`In the um-cli installation directory (find with: npm root -g)`

`Optional: Override production defaults`

`Privacy & Security`

`$3`