UnifiedMemory CLI - AI code assistant integration
npm install @unifiedmemory/clium)


Connect your AI code assistant to UnifiedMemory's knowledge vault with one command.
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.
``bashInstall globally
npm install -g @unifiedmemory/cli
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 StatusAuthentication:
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 & QuotaAccount:
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 status shows 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 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 contextSecurity:
- 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 .gitignoreMulti-Project Support
Working on multiple projects? No problem!
`bash
cd project-1
um init # Links to "Project 1" in UnifiedMemorycd ../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.devOptional: 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`- Website: unifiedmemory.ai
- Documentation: docs.unifiedmemory.ai
- Support: GitHub Issues
PROPRIETARY - Copyright (c) 2024-2026 Episodic Solutions Limited. All rights reserved.
See LICENSE for details.