UnifiedMemory CLI (um)

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

# 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

um init

Set up UnifiedMemory in your current project (recommended).

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

um login

Sign in to UnifiedMemory. Opens your browser for authentication.

um login

um status

Check your authentication status and see which project is configured.

um status

Example output:

📋 UnifiedMemory Status

Authentication:
  Status: Active
  Email: [email protected]
  Expires: 1/7/2026

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

Project Configuration:
  ✓ Configured: My Project (proj_xxx)

um usage

Check your current usage and quota allowances.

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)

um org switch

Switch between your organizations or personal account.

um org switch

um org fix

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

um org fix

This command diagnoses and repairs tokens that are missing organization claims. Use it when:

• MCP server returns 401 MISMATCH errors
• um status shows an org selected but API calls fail
• After switching organizations if token update failed

um note create

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

um note create

um mcp serve

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 serve in the background
2. The local MCP server reads your authentication from ~/.um/auth.json
3. It detects which project you're in by looking for .um/config.json
4. 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!

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:

um org switch    # Choose between organizations

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

Installation Options

Option 1: Global Install (recommended)

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)

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

"Not logged in" error

um login

AI assistant not seeing UnifiedMemory tools

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)

Wrong project/organization

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

Token expired

Tokens automatically refresh. If you see auth errors:

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)

# In the um-cli installation directory (find with: npm root -g)
cp .env.example .env

Step 2: Override the values you need (optional)

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

Secure Token Storage

• 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

Authentication Security

• 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

Project Security

• 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

What We Don't Collect

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

Security Updates

Security issues are taken seriously. To report a vulnerability, please email [email protected] (do not use public issues).

Learn More

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

License

PROPRIETARY - Copyright (c) 2024-2026 Episodic Solutions Limited. All rights reserved.

See LICENSE for details.