@joseairosa/recall 1.2.1 → 1.3.0

package/.claude/settings.local.json

@@ -11,7 +11,13 @@
       "Bash(npm whoami:*)",
       "Bash(curl:*)",
       "Bash(npm run build:*)",
-      "Bash(npm publish:*)"
+      "Bash(npm publish:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh repo edit:*)",
+      "Bash(cat:*)",
+      "Bash(git checkout:*)",
+      "Bash(git pull:*)",
+      "Bash(node:*)"
     ],
     "deny": [],
     "ask": []

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.3.0] - 2025-10-03
+
+### Added
+- **Global Memories** - Cross-workspace memory sharing
+  - `is_global` field on memories - Mark memories as accessible across all workspaces
+  - `workspace_id` field - Track workspace origin for each memory
+  - Three workspace modes via `WORKSPACE_MODE` environment variable:
+    - `isolated` (default) - Workspace-only, no cross-workspace access
+    - `global` - All memories shared globally, no workspace isolation
+    - `hybrid` - Both workspace AND global memories with smart weighting
+  - Hybrid search weighting: workspace memories 1.0x, global memories 0.9x (prefer local context)
+- **Global Memory Tools** (2 new tools)
+  - `convert_to_global` - Convert workspace-specific memory to global
+  - `convert_to_workspace` - Convert global memory to workspace-specific
+- **Global Memory Resources** (5 new resources)
+  - `memory://global/recent?limit=50` - Recent global memories
+  - `memory://global/by-type/{type}?limit=50` - Global memories by context type
+  - `memory://global/by-tag/{tag}?limit=50` - Global memories by tag
+  - `memory://global/important?min=8&limit=50` - Important global memories
+  - `memory://global/search?q=query&limit=10` - Search global memories
+  - All global resources throw helpful errors in `isolated` mode
+
+### Changed
+- Enhanced `CreateMemory` schema with optional `is_global` field (defaults to `false`)
+- Updated `MemoryEntry` schema with `is_global` and `workspace_id` fields
+- Updated `searchMemories()` to support three workspace modes with weighted results
+- Enhanced `getMemory()` to check both workspace and global storage
+- All retrieval methods respect workspace mode configuration
+
+### Technical
+- Added `WorkspaceMode` enum and `getWorkspaceMode()` helper
+- Added global Redis key helpers: `globalMemory()`, `globalMemories()`, `globalByType()`, etc.
+- Added `ConvertToGlobalSchema` and `ConvertToWorkspaceSchema` validation
+- Updated `MemoryStore` with `convertToGlobal()` and `convertToWorkspace()` methods
+- All global resources validate workspace mode and provide clear error messages
+- Backward compatible: defaults to `isolated` mode, no breaking changes
+
+### Use Cases
+- Personal preferences across all projects (coding standards, communication style)
+- Team conventions and organizational knowledge
+- Cross-project patterns and solutions
+- Shared tools and commands
+
+**Tools:** 15 total (6 core + 3 smart context + 4 advanced + 2 global)
+**Resources:** 14 total (9 workspace + 5 global)
+**Prompts:** 1 (`workspace_context`)
+
+See [WORKSPACE_MODES.md](WORKSPACE_MODES.md) for detailed documentation.
+
+---
+
 ## [1.2.1] - 2025-10-02
 
 ### Added
@@ -141,6 +192,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Migration Guides
 
+### Migrating from v1.2.1 to v1.3.0
+
+**No breaking changes.** All existing functionality works identically.
+
+**Defaults:**
+- Workspace mode: `isolated` (same as v1.2.1)
+- All memories: `is_global: false` (workspace-only)
+- No configuration changes required
+
+**New features available:**
+1. **Enable global memories** - Set `WORKSPACE_MODE=hybrid` in config
+2. **Convert existing memories** - Use `convert_to_global` tool
+3. **Browse global memories** - Use `memory://global/*` resources
+
+**Configuration example:**
+```json
+{
+  "env": {
+    "WORKSPACE_MODE": "hybrid",  // Enable both workspace + global
+    "REDIS_URL": "redis://localhost:6379",
+    "ANTHROPIC_API_KEY": "sk-ant-..."
+  }
+}
+```
+
+**Use cases:**
+- Keep mode as `isolated` for project-only memories (default behavior)
+- Use `hybrid` for personal preferences + project memories
+- Use `global` for team-wide shared knowledge across all projects
+
+See [WORKSPACE_MODES.md](WORKSPACE_MODES.md) for detailed guide.
+
 ### Migrating from v1.1.0 to v1.2.0
 
 **No breaking changes.** All existing functionality works identically.

package/README.md

@@ -191,6 +191,61 @@ Then in a new conversation:
 
 ---
 
+## Upgrading
+
+### Automatic Updates (Recommended)
+
+If you use **`npx -y @joseairosa/recall`** in your config, you **automatically get the latest version** on every Claude restart. No action needed! 🎉
+
+```json
+{
+  "mcpServers": {
+    "recall": {
+      "command": "npx",
+      "args": ["-y", "@joseairosa/recall"]  // ← Always fetches latest
+    }
+  }
+}
+```
+
+### Manual Updates
+
+**If using global installation:**
+
+```bash
+# Update to latest version
+npm update -g @joseairosa/recall
+
+# Or install specific version
+npm install -g @joseairosa/recall@1.3.0
+
+# Check installed version
+npm list -g @joseairosa/recall
+```
+
+**If using from source:**
+
+```bash
+cd recall
+git pull origin main
+npm install
+npm run build
+```
+
+**After updating:**
+1. Restart Claude Code or Claude Desktop
+2. Verify new version: Ask Claude "What Recall version are you using?"
+3. Check CHANGELOG.md for new features and breaking changes
+
+### Version-Specific Upgrades
+
+**Upgrading to v1.3.0:**
+- No breaking changes, fully backward compatible
+- To use global memories: Add `WORKSPACE_MODE=hybrid` to your config
+- See [Migration Guide](#migrating-from-v121-to-v130) below
+
+---
+
 ## How to Use
 
 ### Store Important Information
@@ -208,6 +263,17 @@ Claude can automatically extract and store memories, or you can be explicit:
 
 **What Claude does:** Uses the `store_memory` tool to save this information with appropriate context type and importance.
 
+**Store globally (v1.3+):**
+```
+"Remember globally: I prefer TypeScript strict mode for all projects"
+```
+
+```
+"Store this as a global preference: Always use ULIDs for database IDs"
+```
+
+**What Claude does:** Uses `store_memory` with `is_global: true` to make it accessible across all workspaces (requires `WORKSPACE_MODE=hybrid` or `global`).
+
 ### Recall Context
 
 Claude automatically retrieves relevant memories, but you can also ask:
@@ -242,6 +308,22 @@ Group related work:
 
 **What Claude does:** Uses `summarize_session` to create a session snapshot with all relevant memories.
 
+### Convert Memories (v1.3+)
+
+**Promote workspace memory to global:**
+```
+"Convert this memory to global: mem_abc123"
+```
+
+**What Claude does:** Uses `convert_to_global` to move the memory from workspace-specific to globally accessible.
+
+**Convert back to workspace:**
+```
+"Convert this global memory to workspace-specific: mem_xyz789"
+```
+
+**What Claude does:** Uses `convert_to_workspace` to move the memory from global to current workspace.
+
 ---
 
 ## Memory Types
@@ -263,7 +345,7 @@ Memories are categorized for better organization:
 
 ---
 
-## Available Tools (13)
+## Available Tools (15)
 
 Claude has access to these memory tools:
 
@@ -286,12 +368,17 @@ Claude has access to these memory tools:
 - **`find_duplicates`** - Detect similar memories
 - **`consolidate_memories`** - Merge multiple memories
 
+### Global Memories (v1.3+)
+- **`convert_to_global`** - Convert workspace memory to global
+- **`convert_to_workspace`** - Convert global memory to workspace-specific
+
 ---
 
-## Available Resources (9)
+## Available Resources (14)
 
 Browse memories directly using MCP resources:
 
+### Workspace Resources
 - **`memory://recent`** - Recent memories (default 50)
 - **`memory://by-type/{type}`** - Filter by context type
 - **`memory://by-tag/{tag}`** - Filter by tag
@@ -302,6 +389,13 @@ Browse memories directly using MCP resources:
 - **`memory://search?q=query`** - Semantic search
 - **`memory://analytics`** - Usage analytics dashboard (v1.2+)
 
+### Global Resources (v1.3+)
+- **`memory://global/recent`** - Recent global memories (cross-workspace)
+- **`memory://global/by-type/{type}`** - Global memories by context type
+- **`memory://global/by-tag/{tag}`** - Global memories by tag
+- **`memory://global/important`** - Important global memories
+- **`memory://global/search?q=query`** - Search global memories
+
 ---
 
 ## Workspace Isolation
@@ -383,9 +477,44 @@ Developer B: "What's our API rate limit?"
 
 See [WORKSPACE_MODES.md](WORKSPACE_MODES.md) for future plans on enhanced organizational memory features.
 
-### Future: Global Memories
+### Global Memories (v1.3+)
+
+**Cross-workspace memory sharing** enables memories that work across all workspaces. Perfect for:
+- Personal preferences and coding standards
+- Team conventions and organizational knowledge
+- Shared patterns and solutions
+
+**Workspace Modes:**
+- **`isolated`** (default) - Workspace-only memories, no cross-workspace access
+- **`global`** - All memories shared globally, no workspace isolation
+- **`hybrid`** - Both workspace-specific AND global memories (best of both worlds)
+
+**Configure workspace mode:**
+```json
+{
+  "env": {
+    "WORKSPACE_MODE": "hybrid"
+  }
+}
+```
+
+**Create global memories:**
+```
+"Remember globally: I prefer TypeScript strict mode for all projects"
+```
+Claude stores with `is_global: true`, accessible across all workspaces.
+
+**Convert existing memories:**
+```
+"Convert this memory to global: [memory_id]"
+```
 
-Coming in v1.3.0: Support for **global memories** that work across all workspaces (e.g., personal preferences, team conventions). See [WORKSPACE_MODES.md](WORKSPACE_MODES.md) for details.
+**Browse global memories:**
+- Use `memory://global/recent` resource
+- Use `memory://global/search?q=query` for semantic search
+- Global resources only work in `global` or `hybrid` modes
+
+See [WORKSPACE_MODES.md](WORKSPACE_MODES.md) for detailed documentation.
 
 ---
 
@@ -510,6 +639,34 @@ Claude: [Retrieves session memories]
          - Updated middleware for new auth flow"
 ```
 
+### Example 4: Global Memories (v1.3+)
+```
+# In project A (with WORKSPACE_MODE=hybrid)
+You: "Remember globally: I prefer async/await over .then() in all projects"
+
+Claude: [Stores with is_global: true]
+        ✓ Stored globally: async/await preference (importance: 9)
+
+# Switch to project B
+You: "What are my coding preferences?"
+
+Claude: [Retrieves global memories]
+        "Your global coding preferences include:
+         - Prefer async/await over .then() in all projects"
+
+# Project-specific memory
+You: "Remember for this project only: Use MongoDB with Mongoose"
+
+Claude: [Stores with is_global: false]
+        ✓ Stored: MongoDB with Mongoose (workspace-only, importance: 8)
+
+# Back in project A
+You: "What database are we using?"
+
+Claude: [Only sees project A memories, not project B's MongoDB]
+        "I don't see any database information stored for this workspace."
+```
+
 ---
 
 ## Configuration
@@ -518,6 +675,10 @@ Claude: [Retrieves session memories]
 
 - **`REDIS_URL`** - Redis connection (default: `redis://localhost:6379`)
 - **`ANTHROPIC_API_KEY`** - Claude API key for analysis and embeddings
+- **`WORKSPACE_MODE`** (v1.3+) - Workspace memory mode (default: `isolated`)
+  - `isolated` - Workspace-only memories, no cross-workspace access
+  - `global` - All memories shared globally across workspaces
+  - `hybrid` - Both workspace-specific AND global memories
 
 ### Redis Setup Options
 
@@ -801,7 +962,8 @@ Typical performance characteristics:
 
 ## Version History
 
-- **v1.2.0** (Current) - TTL support, Export/Import, Consolidation, Analytics
+- **v1.3.0** (Current) - Global memories, cross-workspace sharing, workspace modes
+- **v1.2.0** - TTL support, Export/Import, Consolidation, Analytics
 - **v1.1.0** - Smart context management (recall, analyze, summarize)
 - **v1.0.0** - Initial release with core memory operations
 

package/WORKSPACE_MODES.md

@@ -1,8 +1,8 @@
 # Workspace Modes & Global Memories
 
-## Current Behavior (v1.2.0)
+## Current Behavior (v1.3.0)
 
-**Workspace Isolation:** All memories are automatically isolated by directory.
+**Workspace Isolation (default):** All memories are automatically isolated by directory.
 
 ```
 /Users/you/project-a/  → Workspace A memories (isolated)
@@ -11,9 +11,14 @@
 
 This prevents memory pollution between projects.
 
+**Global Memories (v1.3.0):** Cross-workspace memory sharing with three modes:
+- **`isolated`** (default) - Workspace-only, no cross-workspace access
+- **`global`** - All memories shared globally, no workspace isolation
+- **`hybrid`** - Both workspace AND global memories
+
 ---
 
-## Future Enhancement: Hybrid Mode (v1.3.0)
+## Global Memories (v1.3.0)
 
 ### Use Cases for Global Memories
 
@@ -31,30 +36,36 @@ This prevents memory pollution between projects.
 
 ---
 
-## Proposed Implementation
+## Implementation (v1.3.0)
 
-### Option 1: Global Flag on Memories
+### Schema Changes
 
-Add `is_global` field to memory schema:
+Added `is_global` field to memory schema:
 
 ```typescript
-{
-  content: "I prefer TypeScript strict mode in all projects",
-  context_type: "preference",
-  importance: 9,
-  is_global: true  // ← New field
-}
+// New field in MemoryEntry
+is_global: boolean  // If true, memory is accessible across all workspaces
+workspace_id: string  // Workspace identifier (empty for global memories)
+
+// New field in CreateMemory
+is_global?: boolean  // Optional, defaults to false
 ```
 
-**Storage:**
+### Storage Architecture
+
+**Redis Key Structure:**
 - Global memories: `global:memory:{id}`
 - Workspace memories: `ws:{workspace_id}:memory:{id}`
 
-**Search behavior:**
-- Always searches workspace + global memories
-- Global memories have slightly lower weight (0.9x) to prefer local context
+**Indexes:**
+- Global timeline: `global:memories:timeline`
+- Global by type: `global:memories:type:{type}`
+- Global by tag: `global:memories:tag:{tag}`
+- Global important: `global:memories:important`
+
+### Workspace Modes
 
-### Option 2: Environment Variable Configuration
+Configure via `WORKSPACE_MODE` environment variable:
 
 ```json
 {
@@ -69,51 +80,56 @@ Add `is_global` field to memory schema:
 }
 ```
 
-**Modes:**
-- `isolated` (default): Current behavior
-- `global`: All memories shared across workspaces
-- `hybrid`: Support both global and workspace memories
+**Mode Behaviors:**
 
-### Option 3: Separate MCP Instances
+| Mode | Workspace Memories | Global Memories | Search Behavior |
+|------|-------------------|-----------------|-----------------|
+| **`isolated`** (default) | ✅ Stored & retrieved | ❌ Not accessible | Workspace only |
+| **`global`** | ❌ All stored as global | ✅ All memories global | Global only |
+| **`hybrid`** | ✅ Stored & retrieved | ✅ Stored & retrieved | Both, weighted |
 
-Run two instances:
+**Hybrid Mode Search Weighting:**
+- Workspace memories: 1.0x similarity score (preferred)
+- Global memories: 0.9x similarity score (slightly lower priority)
+- This ensures local context is preferred over global knowledge
 
-```json
+### New Tools (v1.3.0)
+
+**`convert_to_global`** - Convert workspace memory to global:
+```typescript
 {
-  "mcpServers": {
-    "recall-workspace": {
-      "command": "npx",
-      "args": ["-y", "@joseairosa/recall"],
-      "env": {
-        "WORKSPACE_MODE": "isolated"
-      }
-    },
-    "recall-global": {
-      "command": "npx",
-      "args": ["-y", "@joseairosa/recall"],
-      "env": {
-        "WORKSPACE_MODE": "global"
-      }
-    }
+  tool: "convert_to_global",
+  arguments: {
+    memory_id: "mem_abc123"
   }
 }
 ```
 
-**Pros:** Simple, explicit control
-**Cons:** Two processes, more configuration
-
----
+**`convert_to_workspace`** - Convert global memory to workspace:
+```typescript
+{
+  tool: "convert_to_workspace",
+  arguments: {
+    memory_id: "mem_abc123",
+    workspace_id: "/Users/you/project-a"  // Optional, defaults to current
+  }
+}
+```
 
-## Recommended Approach: Hybrid Mode (Option 1 + 2)
+### New Resources (v1.3.0)
 
-### Implementation Plan
+Global memory resources (only work in `global` or `hybrid` modes):
+- `memory://global/recent?limit=50` - Recent global memories
+- `memory://global/by-type/{type}?limit=50` - Global memories by context type
+- `memory://global/by-tag/{tag}?limit=50` - Global memories by tag
+- `memory://global/important?min=8&limit=50` - Important global memories
+- `memory://global/search?q=query&limit=10` - Search global memories
 
-1. **Add `is_global` field** to `CreateMemorySchema`
-2. **Add `WORKSPACE_MODE` environment variable**
-3. **Update search logic** to include global memories
-4. **Add tools:**
-   - `convert_to_global` - Promote workspace memory to global
-   - `convert_to_workspace` - Demote global memory to workspace
+**Error in isolated mode:**
+```
+McpError: Global memories are not available in isolated mode.
+Set WORKSPACE_MODE=hybrid or global to access global memories.
+```
 
 ### User Experience
 
@@ -153,49 +169,118 @@ Run two instances:
 ### Migration Path
 
 For existing users (v1.2.0 → v1.3.0):
-- All existing memories remain workspace-isolated
-- No breaking changes
-- `is_global` defaults to `false`
-- Users opt-in to global memories
+- ✅ **No breaking changes** - defaults to `isolated` mode
+- ✅ All existing memories remain workspace-isolated
+- ✅ `is_global` defaults to `false` for all new memories
+- ✅ Users opt-in to global memories by setting `WORKSPACE_MODE`
+
+**Backward compatibility:**
+```typescript
+// v1.2.0 memories (no is_global field)
+{
+  id: "mem_123",
+  content: "...",
+  // is_global: undefined → treated as false
+}
+
+// v1.3.0+ automatically adds fields
+{
+  id: "mem_123",
+  content: "...",
+  is_global: false,  // Added with default value
+  workspace_id: "/Users/you/project-a"
+}
+```
+
+### Implementation Details
+
+**CreateMemory behavior by mode:**
+
+| Mode | `is_global` param | Storage Location | Indexes |
+|------|------------------|------------------|---------|
+| `isolated` | Ignored | Workspace | Workspace only |
+| `global` | Forced to `true` | Global | Global only |
+| `hybrid` | Respected | Based on flag | Both as appropriate |
+
+**Search behavior:**
+
+```typescript
+// Isolated mode
+searchMemories("query", 10)
+// → Searches: workspace memories only
+
+// Global mode
+searchMemories("query", 10)
+// → Searches: global memories only
+
+// Hybrid mode
+searchMemories("query", 10)
+// → Searches: workspace (1.0x) + global (0.9x)
+// → Merges results, sorts by weighted similarity
+```
+
+**Conversion logic:**
+
+```typescript
+// Convert to global
+// 1. Fetch memory from workspace
+// 2. Delete from workspace indexes (memory, timeline, by-type, by-tag, important)
+// 3. Store in global indexes with is_global=true
+// 4. Update workspace_id to empty string
+
+// Convert to workspace
+// 1. Fetch memory from global
+// 2. Delete from global indexes
+// 3. Store in workspace indexes with is_global=false
+// 4. Update workspace_id to target workspace
+```
 
 ---
 
 ## Alternative: Remote Redis with Shared Workspace
 
-Instead of global memories, users can:
+Instead of using global memories feature, users can share memories by:
 
 1. **Use remote Redis** (Upstash, Redis Cloud)
 2. **Share Redis URL** across team
-3. **Use same workspace path** for shared memories
+3. **Use same workspace path** for project memories
 
 ```json
 {
   "env": {
     "REDIS_URL": "rediss://team-redis.upstash.io:6379",
-    "WORKSPACE_PATH": "/team/project-x"  // Override detection
+    "WORKSPACE_MODE": "isolated"  // Traditional workspace isolation
   }
 }
 ```
 
 This enables:
-- Team-shared memories for a project
+- Team-shared memories for specific projects
 - Consistent memories across machines
-- Backup and sync automatically
+- Automatic backup and sync
+- Simpler than global memories for single-project teams
 
 ---
 
 ## Summary
 
-**Current (v1.2.0):** ✅ Workspace isolation works perfectly
-
-**Near-term solution:**
-- Document cloud Redis options (Upstash, Redis Cloud)
-- No local install required
-- Remote server fully supported
-
-**Future enhancement (v1.3.0):**
-- Add `is_global` flag for hybrid mode
-- Implement `WORKSPACE_MODE` environment variable
-- Add conversion tools
-
-**Recommendation:** Ship v1.2.0 now with cloud Redis docs, plan v1.3.0 for hybrid mode based on user feedback.
+**v1.3.0 Implementation:** ✅ Complete
+
+**Features shipped:**
+- ✅ Global memories with `is_global` flag
+- ✅ Three workspace modes: `isolated`, `global`, `hybrid`
+- ✅ Hybrid search with 0.9x global weighting
+- ✅ Conversion tools (`convert_to_global`, `convert_to_workspace`)
+- ✅ Global resources (`memory://global/*`)
+- ✅ No breaking changes, fully backward compatible
+
+**Use Cases:**
+- Personal preferences across all projects → Global memories
+- Team conventions and patterns → Global memories
+- Project-specific architecture → Workspace memories
+- Local debugging notes → Workspace memories
+
+**Next Steps (Future Versions):**
+- v1.4.0: Memory relationships (links between memories)
+- v1.5.0: Memory versioning (track changes over time)
+- v1.6.0: Smart suggestions (AI-powered memory recommendations)