@unifiedmemory/cli 1.0.0

package/.env.example

@@ -0,0 +1,9 @@
+# Optional: Override Clerk OAuth Configuration
+# By default, the CLI uses the production UnifiedMemory Clerk application
+# Only set these if you're developing/testing with a different Clerk app
+
+# CLERK_CLIENT_ID=your_test_clerk_client_id
+# CLERK_DOMAIN=your-test-app.clerk.accounts.dev
+# API_ENDPOINT=http://localhost:8000
+# REDIRECT_URI=http://localhost:3333/callback
+# PORT=3333

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-06
+
+### Added
+- Initial release of UnifiedMemory CLI
+- OAuth 2.0 authentication with automatic token refresh
+- `um init` command for one-step project setup
+- `um login` command for manual authentication
+- `um status` command to show auth and project status
+- `um org switch` command to switch between organizations
+- `um mcp serve` command for local MCP server
+- `um note create` command for direct note creation
+- Auto-detection and configuration for 5 AI tools:
+  - Claude Code (project-level .mcp.json)
+  - Cursor (~/.cursor/mcp.json)
+  - Cline (~/.cline/mcp.json)
+  - Codex CLI (~/.codex/config.toml)
+  - Gemini CLI (~/.gemini/settings.json)
+- Local MCP server with automatic project context detection
+- Secure token storage in ~/.um/auth.json
+- Per-project configuration in .um/config.json
+- Automatic .gitignore updates to exclude .um/ directory
+
+### Fixed
+- Token refresh not persisting refresh_token during login
+- Status command not detecting project configuration files
+- Improved error messages for token refresh failures
+- Centralized token validation helper prevents duplicate code

package/HOOK_SETUP.md

@@ -0,0 +1,338 @@
+# UnifiedMemory CLI Hook Integration
+
+## Overview
+
+This document explains how to set up automatic vault recording using Claude Code hooks with the `um note create` CLI command.
+
+## Background
+
+Claude Code's "prompt" type hooks are not supported outside REPL mode. To work around this limitation, we've implemented a command-style hook that calls the `um note create` CLI command directly.
+
+## Components
+
+### 1. CLI Command: `um note create`
+
+A new CLI command that creates notes in the vault:
+
+```bash
+um note create "<summary text>" [options]
+```
+
+**Options**:
+- `--topic <topic>` - Topic for the note (default: "general")
+- `--source <source>` - Source identifier (default: "um-cli")
+- `--confidence <confidence>` - Confidence score 0-1 (default: "0.7")
+- `--tags <tags>` - Comma-separated tags
+- `--metadata <json>` - Additional metadata as JSON string
+
+**Example**:
+```bash
+um note create "Completed implementation of user authentication" \
+  --topic "development" \
+  --source "manual" \
+  --confidence "0.9" \
+  --tags "auth,feature,completed"
+```
+
+### 2. Hook Script: `.claude/hooks/post-exit-plan-mode.sh`
+
+A shell script that automatically calls `um note create` after exiting plan mode:
+
+**Location**: `<project>/.claude/hooks/post-exit-plan-mode.sh`
+
+**Requirements**:
+- Must be executable (`chmod +x`)
+- Update the `UM_CLI` path to point to your um-cli installation
+
+### 3. Hook Configuration: `.claude/settings.json`
+
+Configure Claude Code to run the hook:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./.claude/hooks/post-exit-plan-mode.sh 'Plan summary: Completed plan mode session'",
+            "statusMessage": "Recording plan to vault..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Setup Instructions
+
+### Step 1: Install um-cli
+
+The `um` CLI should be installed and configured:
+
+```bash
+# Authenticate
+um login
+
+# Initialize project
+cd <your-project>
+um init
+```
+
+This creates:
+- `~/.um/auth.json` - User authentication
+- `.um/config.json` - Project configuration (org_id, project_id)
+
+### Step 2: Create Hook Script
+
+Create `.claude/hooks/post-exit-plan-mode.sh` in your project:
+
+```bash
+mkdir -p .claude/hooks
+cat > .claude/hooks/post-exit-plan-mode.sh << 'EOF'
+#!/usr/bin/env bash
+set -e
+
+SUMMARY="$@"
+if [ -z "$SUMMARY" ]; then
+  SUMMARY=$(cat)
+fi
+if [ -z "$SUMMARY" ]; then
+  SUMMARY="Plan completed and exited plan mode"
+fi
+
+# Update this path to your um-cli installation
+UM_CLI="/path/to/vault/um-cli/index.js"
+
+if [ ! -f "$UM_CLI" ]; then
+  echo "Error: um CLI not found at $UM_CLI" >&2
+  exit 1
+fi
+
+node "$UM_CLI" note create "$SUMMARY" \
+  --topic "plans" \
+  --source "claude-code-hook" \
+  --confidence "0.8" \
+  --tags "plan,automated" \
+  2>&1
+
+exit 0
+EOF
+
+chmod +x .claude/hooks/post-exit-plan-mode.sh
+```
+
+### Step 3: Configure Hook in Settings
+
+Update `.claude/settings.json` (or `.claude/settings.local.json`):
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./.claude/hooks/post-exit-plan-mode.sh 'Plan summary: Completed plan mode session'",
+            "statusMessage": "Recording plan to vault..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Step 4: Test the Setup
+
+Test the CLI command manually:
+
+```bash
+cd <your-project>
+um note create "Test note from CLI" --topic "testing"
+```
+
+Test the hook script:
+
+```bash
+./.claude/hooks/post-exit-plan-mode.sh "Test note from hook"
+```
+
+## How It Works
+
+### Authentication Flow
+
+1. **User Context**: Loaded from `~/.um/auth.json` (created by `um login`)
+   - User ID from JWT `decoded.sub`
+   - Organization ID from `selectedOrg.id` or fallback to user ID
+
+2. **Project Context**: Loaded from `.um/config.json` (created by `um init`)
+   - Organization ID
+   - Project ID
+   - Project name
+
+3. **API Call**: The `um note create` command:
+   - Builds authentication headers (Authorization, X-Org-Id, X-User-Id)
+   - Injects org/proj/user into tool arguments
+   - Calls the MCP gateway's `create_note` tool
+   - Returns success/failure status
+
+### Hook Execution
+
+When you exit plan mode in Claude Code:
+
+1. Claude Code detects `ExitPlanMode` tool usage
+2. Matches the `PostToolUse` hook with `matcher: "ExitPlanMode"`
+3. Executes the command hook: `.claude/hooks/post-exit-plan-mode.sh`
+4. Hook script calls: `node um-cli/index.js note create "..."`
+5. CLI command creates the note in vault
+6. Success/failure status shown in Claude Code
+
+## Troubleshooting
+
+### Error: "Not authenticated"
+
+```bash
+# Re-authenticate
+um login
+```
+
+### Error: "No project configuration found"
+
+```bash
+# Re-initialize project
+cd <your-project>
+um init
+```
+
+### Error: "um CLI not found"
+
+Update the `UM_CLI` path in the hook script to point to your installation:
+
+```bash
+UM_CLI="/absolute/path/to/vault/um-cli/index.js"
+```
+
+### Error: Hook not executing
+
+1. Ensure the hook script is executable:
+   ```bash
+   chmod +x .claude/hooks/post-exit-plan-mode.sh
+   ```
+
+2. Test the hook manually:
+   ```bash
+   ./.claude/hooks/post-exit-plan-mode.sh "Test message"
+   ```
+
+3. Check Claude Code settings are valid JSON
+
+### Error: "Tool execution failed"
+
+Check authentication headers are being set correctly:
+
+```bash
+# Check auth file exists
+cat ~/.um/auth.json | jq .
+
+# Check project config exists
+cat .um/config.json | jq .
+```
+
+## Customization
+
+### Change Hook Trigger
+
+Instead of `PostToolUse:ExitPlanMode`, you can trigger on other events:
+
+```json
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./.claude/hooks/record-session.sh 'Session summary'",
+            "statusMessage": "Recording session to vault..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Available hook types:
+- `PreToolUse` - Before any tool execution
+- `PostToolUse` - After any tool execution
+- `PostToolUseFailure` - After tool execution fails
+- `SessionStart` - When session starts
+- `SessionEnd` - When session ends
+- `PreCompact` - Before context summarization
+
+### Customize Note Properties
+
+Edit the hook script to change topic, source, confidence, or tags:
+
+```bash
+node "$UM_CLI" note create "$SUMMARY" \
+  --topic "my-custom-topic" \
+  --source "my-source" \
+  --confidence "0.9" \
+  --tags "custom,tags,here" \
+  2>&1
+```
+
+### Add Metadata
+
+Pass JSON metadata:
+
+```bash
+node "$UM_CLI" note create "$SUMMARY" \
+  --metadata '{"branch":"main","commit":"abc123"}' \
+  2>&1
+```
+
+## Security Notes
+
+- Authentication tokens are stored in `~/.um/auth.json` (user-only permissions)
+- Project config in `.um/config.json` contains no secrets (only IDs)
+- The CLI command inherits user's authentication automatically
+- Hook scripts run with the same permissions as Claude Code
+
+## Alternatives to Hooks
+
+If you don't want automatic recording, you can manually call the CLI:
+
+```bash
+# After exiting plan mode
+um note create "Completed feature X implementation" \
+  --topic "development" \
+  --confidence "0.9"
+```
+
+Or ask Claude Code to record notes explicitly:
+
+```
+User: Record this plan to the vault
+Claude: [Uses mcp__vault__create_note tool directly]
+```
+
+## Files Modified
+
+This implementation required the following changes:
+
+1. **New file**: `um-cli/commands/record.js` - CLI command implementation
+2. **Modified**: `um-cli/index.js` - Added `note create` command registration
+3. **New file**: `.claude/hooks/post-exit-plan-mode.sh` - Hook script (per-project)
+4. **Modified**: `.claude/settings.json` - Hook configuration (per-project)
+
+## Summary
+
+This solution bypasses the "prompt hooks not supported outside REPL" limitation by using command-style hooks to call the `um note create` CLI command directly. All authentication infrastructure (schema transformation, parameter injection, headers) works perfectly - the only issue was with Claude Code's hook mechanism, which we've now resolved.

package/LICENSE

@@ -0,0 +1,51 @@
+PROPRIETARY LICENSE
+
+Copyright (c) 2024-2026 Episodic Solutions Limited. All rights reserved.
+
+This software and associated documentation files (the "Software") are the proprietary
+property of Episodic Solutions Limited and are protected by copyright law and
+international treaties.
+
+NOTICE TO USER: Carefully read the following legal agreement. By downloading, installing,
+copying, or otherwise using the Software, you are agreeing to be bound by the terms of
+this Agreement. If you do not agree to the terms of this Agreement, do not install or
+use the Software.
+
+1. LICENSE GRANT
+   Subject to the terms of this Agreement, Episodic Solutions Limited grants you a
+   non-exclusive, non-transferable, revocable license to use the Software solely for
+   your internal business purposes.
+
+2. RESTRICTIONS
+   You may not:
+   - Modify, adapt, translate, reverse engineer, decompile, disassemble, or create
+     derivative works based on the Software
+   - Remove any proprietary notices, labels, or marks from the Software
+   - Rent, lease, loan, sublicense, distribute, or otherwise transfer the Software to
+     any third party
+   - Use the Software for any purpose other than as expressly permitted herein
+
+3. OWNERSHIP
+   The Software is licensed, not sold. Episodic Solutions Limited retains all right,
+   title, and interest in and to the Software, including all intellectual property rights.
+
+4. TERMINATION
+   This license is effective until terminated. Your rights under this license will
+   terminate automatically without notice if you fail to comply with any term of this
+   Agreement.
+
+5. DISCLAIMER OF WARRANTIES
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL EPISODIC SOLUTIONS LIMITED BE LIABLE FOR ANY DIRECT, INDIRECT,
+   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+   INABILITY TO USE THE SOFTWARE.
+
+7. GOVERNING LAW
+   This Agreement shall be governed by and construed in accordance with the laws of
+   England and Wales, without regard to its conflict of law provisions.
+
+For licensing inquiries, please contact: support@unifiedmemory.ai

package/README.md

@@ -0,0 +1,220 @@
+# UnifiedMemory CLI (`um`)
+
+One-command setup for AI code assistant integration with UnifiedMemory.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @unifiedmemory/cli
+
+# Or run directly with npx
+npx @unifiedmemory/cli init
+
+# In your project directory
+um init
+```
+
+## How It Works
+
+UnifiedMemory uses a **local MCP (Model Context Protocol) server** approach:
+
+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
+
+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
+
+## What does `um init` do?
+
+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!
+
+## Features
+
+- ✅ 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
+
+## Commands
+
+### `um init`
+Initialize UnifiedMemory in the current project (recommended).
+
+```bash
+um init                    # Interactive setup
+um init --skip-configure   # Skip AI tool configuration
+```
+
+### `um login`
+Authenticate with UnifiedMemory using OAuth. Opens browser for login.
+
+```bash
+um login
+```
+
+### `um mcp serve`
+Start MCP server (used internally by AI assistants - you don't need to run this manually).
+
+```bash
+um mcp serve
+```
+
+### `um status`
+Show authentication status, current organization, and project configuration.
+
+```bash
+um status
+```
+
+### `um org switch`
+Switch between organizations or personal account.
+
+```bash
+um org switch
+```
+
+### `um project`
+Manage project configuration (coming soon).
+
+### `um configure`
+Configure AI code assistants (coming soon).
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the CLI directory:
+
+```env
+CLERK_CLIENT_ID=your_clerk_client_id
+CLERK_DOMAIN=clear-caiman-45.clerk.accounts.dev
+API_ENDPOINT=https://api.unifiedmemory.ai
+```
+
+### Project Configuration
+
+After running `um init`, a `.um/config.json` file is created:
+
+```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
+  }
+}
+```
+
+This file is automatically added to `.gitignore`.
+
+### AI Tool Configuration
+
+The CLI automatically detects and configures:
+
+- **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`
+
+Example MCP configuration (JSON format):
+
+```json
+{
+  "mcpServers": {
+    "vault": {
+      "command": "um",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+Example MCP configuration (TOML format for Codex):
+
+```toml
+[mcp_servers.vault]
+command = "um"
+args = ["mcp", "serve"]
+```
+
+**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.
+
+## Supported AI Tools
+
+| Tool | MCP Config | Auto-Detect | Config Format |
+|------|-----------|-------------|---------------|
+| Claude Code | ✅ | ✅ | JSON (project-level) |
+| Cursor | ✅ | ✅ | JSON |
+| Cline | ✅ | ✅ | JSON |
+| Codex CLI | ✅ | ✅ | TOML |
+| Gemini CLI | ✅ | ✅ | JSON |
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/unifiedmemory/um-cli.git
+cd um-cli
+
+# Install dependencies
+npm install
+
+# Run locally
+node index.js init
+
+# Build standalone binaries
+npm run build
+```
+
+## Architecture
+
+```
+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
+```
+
+**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
+
+## License
+
+MIT
+
+## Support
+
+- GitHub Issues: https://github.com/unifiedmemory/um-cli/issues
+- Documentation: https://docs.unifiedmemory.ai