@unifiedmemory/cli 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,14 @@
 # UnifiedMemory CLI (`um`)
 
-One-command setup for AI code assistant integration with UnifiedMemory.
+[![npm version](https://badge.fury.io/js/@unifiedmemory%2Fcli.svg)](https://www.npmjs.com/package/@unifiedmemory/cli)
+[![License: PROPRIETARY](https://img.shields.io/badge/License-PROPRIETARY-red.svg)](./LICENSE)
+[![Node Version](https://img.shields.io/node/v/@unifiedmemory/cli)](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
 
@@ -8,52 +16,59 @@ One-command setup for AI code assistant integration with UnifiedMemory.
 # Install globally
 npm install -g @unifiedmemory/cli
 
-# Or run directly with npx
+# Or run directly with npx (no installation required)
 npx @unifiedmemory/cli init
 
 # In your project directory
+cd your-project
 um init
 ```
 
-## How It Works
+That's it! Your AI assistant can now access UnifiedMemory.
 
-UnifiedMemory uses a **local MCP (Model Context Protocol) server** approach:
+## What Does This Do?
 
-1. **One-time authentication**: `um login` stores your credentials locally in `~/.um/auth.json`
-2. **Project context**: `um init` creates `.um/config.json` in your project directory
-3. **Local MCP server**: AI assistants spawn `um mcp serve` which:
-   - Reads authentication from `~/.um/auth.json`
-   - Auto-detects project context from `.um/config.json` in current directory
-   - Forwards tool calls to UnifiedMemory API with proper authentication
-   - Handles token refresh automatically
+When you run `um init` in your project:
 
-This means:
-- ✅ No tokens stored in AI assistant configuration files
-- ✅ No re-authentication needed
-- ✅ Automatic project context detection based on directory
-- ✅ Works seamlessly across multiple projects
+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)
+```
 
-## What does `um init` do?
+**Note**: Authentication tokens are stored securely in `~/.um/auth.json` on your machine, never in your project directory.
 
-1. **Authenticates** you via OAuth (or uses saved session)
-2. **Prompts** for project selection (create new or link existing)
-3. **Creates** `.um/config.json` with org_id and project_id
-4. **Configures** all detected AI tools to use local MCP server
-5. **Ready to use** - just restart your AI assistant!
+## Supported AI Code Assistants
 
-## Features
+| 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` |
 
-- ✅ OAuth 2.0 authentication with automatic token refresh
-- ✅ Auto-detect and configure AI code assistants
-- ✅ Local MCP server with secure token storage
-- ✅ Multi-project support with automatic context switching
-- ✅ Automatic .gitignore updates
-- ✅ Supports Claude Code, Cursor, Cline, Codex CLI, and Gemini CLI
+The CLI automatically detects which tools you have installed and configures them for you.
 
 ## Commands
 
 ### `um init`
-Initialize UnifiedMemory in the current project (recommended).
+Set up UnifiedMemory in your current project (recommended).
 
 ```bash
 um init                    # Interactive setup
@@ -61,160 +76,220 @@ um init --skip-configure   # Skip AI tool configuration
 ```
 
 ### `um login`
-Authenticate with UnifiedMemory using OAuth. Opens browser for login.
+Sign in to UnifiedMemory. Opens your browser for authentication.
 
 ```bash
 um login
 ```
 
-### `um mcp serve`
-Start MCP server (used internally by AI assistants - you don't need to run this manually).
+### `um status`
+Check your authentication status and see which project is configured.
 
 ```bash
-um mcp serve
+um status
 ```
 
-### `um status`
-Show authentication status, current organization, and project configuration.
+**Example output:**
+```
+📋 UnifiedMemory Status
 
-```bash
-um 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)
 ```
 
 ### `um org switch`
-Switch between organizations or personal account.
+Switch between your organizations or personal account.
 
 ```bash
 um org switch
 ```
 
-### `um project`
-Manage project configuration (coming soon).
+### `um note create`
+Manually save a note to your vault (useful for capturing important context).
 
-### `um configure`
-Configure AI code assistants (coming soon).
+```bash
+um note create
+```
 
-## Configuration
+### `um mcp serve`
+Start the MCP server (used internally by AI assistants - you don't need to run this manually).
 
-### Environment Variables
+## How It Works
 
-Create a `.env` file in the CLI directory:
+UnifiedMemory uses the **Model Context Protocol (MCP)** to connect your AI assistant to your knowledge vault:
 
-```env
-CLERK_CLIENT_ID=your_clerk_client_id
-CLERK_DOMAIN=clear-caiman-45.clerk.accounts.dev
-API_ENDPOINT=https://api.unifiedmemory.ai
-```
+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
 
-### Project Configuration
+**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`
 
-After running `um init`, a `.um/config.json` file is created:
+## Multi-Project Support
 
-```json
-{
-  "version": "1.0",
-  "org_id": "org_xxx",
-  "project_id": "proj_xxx",
-  "project_name": "My Project",
-  "api_url": "https://api.unifiedmemory.ai",
-  "created_at": "2024-12-17T...",
-  "mcp_config": {
-    "inject_headers": true,
-    "auto_context": true
-  }
-}
-```
+Working on multiple projects? No problem!
 
-This file is automatically added to `.gitignore`.
+```bash
+cd project-1
+um init          # Links to "Project 1" in UnifiedMemory
 
-### AI Tool Configuration
+cd ../project-2
+um init          # Links to "Project 2" in UnifiedMemory
+```
 
-The CLI automatically detects and configures:
+The CLI automatically detects which project you're in and switches context. Your AI assistant will use the correct vault for each project.
 
-- **Claude Code**: `.mcp.json` (project-level)
-- **Cursor**: `~/.cursor/mcp.json`
-- **Cline**: `~/.cline/mcp.json`
-- **Codex CLI**: `~/.codex/config.toml` (TOML format)
-- **Gemini CLI**: `~/.gemini/settings.json`
+## Switching Organizations
 
-Example MCP configuration (JSON format):
+If you're part of multiple teams:
 
-```json
-{
-  "mcpServers": {
-    "vault": {
-      "command": "um",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
+```bash
+um org switch    # Choose between organizations
 ```
 
-Example MCP configuration (TOML format for Codex):
+All projects you create afterward will belong to the selected organization.
 
-```toml
-[mcp_servers.vault]
-command = "um"
-args = ["mcp", "serve"]
+## Installation Options
+
+**Option 1: Global Install (recommended)**
+```bash
+npm install -g @unifiedmemory/cli
+um --version
 ```
 
-**Note**: No tokens are stored in configuration files. The local MCP server reads authentication from `~/.um/auth.json` and project context from `.um/config.json` automatically.
+**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`.
 
-## Supported AI Tools
+## Requirements
 
-| Tool | MCP Config | Auto-Detect | Config Format |
-|------|-----------|-------------|---------------|
-| Claude Code | ✅ | ✅ | JSON (project-level) |
-| Cursor | ✅ | ✅ | JSON |
-| Cline | ✅ | ✅ | JSON |
-| Codex CLI | ✅ | ✅ | TOML |
-| Gemini CLI | ✅ | ✅ | JSON |
+- **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](https://unifiedmemory.ai)
 
-## Development
+## Troubleshooting
 
+### "Not logged in" error
 ```bash
-# Clone the repository
-git clone https://github.com/unifiedmemory/um-cli.git
-cd um-cli
+um login
+```
 
-# Install dependencies
-npm install
+### 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)
 
-# Run locally
-node index.js init
+### Wrong project/organization
+```bash
+um org switch              # Switch organization
+cd your-project && um init # Reconfigure project
+```
 
-# Build standalone binaries
-npm run build
+### Token expired
+Tokens automatically refresh. If you see auth errors:
+```bash
+um login
 ```
 
-## Architecture
+### Missing environment variables
+If you see "Missing required environment variables" error:
+1. Copy `.env.example` to `.env` in the CLI installation directory
+2. Fill in your Clerk and API credentials
+3. See Configuration section below for details
+
+## Configuration
+
+The CLI requires environment variables for Clerk OAuth and API access. These should never be hardcoded in your project.
 
+**Step 1: Create `.env` file**
+```bash
+# In the um-cli installation directory (find with: npm root -g)
+cp .env.example .env
 ```
-AI Tool (Claude/Cursor/Cline/Codex/Gemini)
-    ↓ stdio (JSON-RPC)
-um mcp serve (local MCP server)
-    ├─ Reads ~/.um/auth.json (authentication)
-    ├─ Reads .um/config.json (project context from cwd)
-    ├─ Validates/refreshes token if expired
-    ↓ HTTPS with auth headers
-Gateway: https://rose-asp-main-1c0b114.d2.zuplo.dev/mcp
-    ↓ Forwards with signed headers
-Backend: vault-product
+
+**Step 2: Add your credentials**
+```bash
+# Required: Clerk OAuth Configuration
+CLERK_CLIENT_ID=your_clerk_client_id_here
+CLERK_DOMAIN=your-app.clerk.accounts.dev
+
+# Required: API Configuration
+API_ENDPOINT=https://your-api-gateway.zuplo.dev
 ```
 
-**Key Components**:
-- **Authentication**: Clerk OAuth 2.0 with PKCE flow + automatic token refresh
-- **Session Storage**: `~/.um/auth.json` (tokens with refresh capability)
-- **Project Config**: `.um/config.json` (per-directory context)
-- **Provider Detection**: Auto-detect 5 AI tools
-- **MCP Server**: stdio transport proxying to HTTP gateway
-- **Context Auto-Detection**: Project-aware based on working directory
+Get these values from:
+- **Clerk credentials**: [Clerk Dashboard](https://dashboard.clerk.com)
+- **API endpoint**: Your UnifiedMemory deployment
 
-## License
+**Optional configuration**:
+```bash
+# Customize OAuth redirect (defaults shown)
+REDIRECT_URI=http://localhost:3333/callback
+PORT=3333
+```
+
+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
 
-MIT
+### 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 security@unifiedmemory.ai (do not use public issues).
+
+## Learn More
+
+- **Website**: [unifiedmemory.ai](https://unifiedmemory.ai)
+- **Documentation**: [docs.unifiedmemory.ai](https://docs.unifiedmemory.ai)
+- **Support**: [GitHub Issues](https://github.com/Episodic-Solutions/um-cli/issues)
+
+## License
 
-## Support
+PROPRIETARY - Copyright (c) 2024-2026 Episodic Solutions Limited. All rights reserved.
 
-- GitHub Issues: https://github.com/unifiedmemory/um-cli/issues
-- Documentation: https://docs.unifiedmemory.ai
+See [LICENSE](./LICENSE) for details.