@prmichaelsen/remember-mcp 2.2.1 → 2.3.1

package/agent/tasks/task-35-create-space-memory-types-schema.md

@@ -0,0 +1,183 @@
+# Task 35: Create Space Memory Types and Schema
+
+**Milestone**: M10 - Shared Spaces & Confirmation Flow
+**Estimated Time**: 3 hours
+**Dependencies**: Task 34 (Token Service), M2 (Memory types)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create TypeScript types for space memories and Weaviate schema for shared space collections. Space memories are similar to personal memories but stored in shared collections with additional metadata for discovery and attribution.
+
+---
+
+## Steps
+
+### 1. Create SpaceMemory Type Definitions
+
+Create `src/types/space-memory.ts` with space-specific types.
+
+**Actions**:
+- Import base Memory type from `memory.ts`
+- Define SpaceMemory interface extending Memory
+- Add space-specific fields: `space_id`, `author_id`, `ghost_id`, `published_at`, `discovery_count`
+- Define SpaceSearchOptions and SpaceSearchResult types
+- Add JSDoc comments
+
+**Expected Outcome**: SpaceMemory types defined
+
+### 2. Create Space Schema File
+
+Create `src/weaviate/space-schema.ts` for space collection management.
+
+**Actions**:
+- Import Weaviate client utilities
+- Create `ensureSpaceCollection` function
+- Define space collection schema (similar to Memory schema)
+- Handle collection creation if doesn't exist
+- Export helper functions
+
+**Expected Outcome**: Space schema utilities created
+
+### 3. Implement ensureSpaceCollection Function
+
+Ensure a space collection exists, creating it if needed.
+
+**Actions**:
+- Accept space_id parameter (e.g., "the_void")
+- Generate collection name: `Memory_{space_id}`
+- Check if collection exists
+- If not, create with schema
+- Return collection reference
+- Handle errors gracefully
+
+**Expected Outcome**: Collections can be created on-demand
+
+### 4. Define Space Collection Schema
+
+Create Weaviate schema for space collections.
+
+**Actions**:
+- Use same properties as Memory collection
+- Add space-specific properties: `space_id`, `author_id`, `ghost_id`, `published_at`, `discovery_count`
+- Configure OpenAI vectorizer
+- Set vectorization properties
+- Add indexes for common queries
+
+**Expected Outcome**: Space collections have proper schema
+
+### 5. Create Collection Name Utilities
+
+Helper functions for space collection naming.
+
+**Actions**:
+- `getSpaceCollectionName(space_id)` - Returns `Memory_{space_id}`
+- `sanitizeSpaceId(display_name)` - Converts "The Void" → "the_void"
+- `getSpaceDisplayName(space_id)` - Maps IDs to display names
+- Add validation for space IDs
+
+**Expected Outcome**: Naming utilities available
+
+### 6. Add Space ID Constants
+
+Define supported space IDs as constants.
+
+**Actions**:
+- Create `SUPPORTED_SPACES` constant
+- Map space IDs to display names
+- Export for use in tools
+- Add type for space IDs
+
+**Expected Outcome**: Space IDs centralized
+
+### 7. Create Unit Tests
+
+Test space schema and utilities.
+
+**Actions**:
+- Create `tests/unit/space-schema.test.ts`
+- Test `ensureSpaceCollection` function
+- Test collection name generation
+- Test space ID sanitization
+- Test display name mapping
+- Mock Weaviate client
+
+**Expected Outcome**: All tests passing
+
+### 8. Update Type Exports
+
+Export new types from main types file.
+
+**Actions**:
+- Add exports to `src/types/memory.ts` or create index
+- Ensure SpaceMemory types are accessible
+- Update any type documentation
+
+**Expected Outcome**: Types properly exported
+
+---
+
+## Verification
+
+- [ ] `src/types/space-memory.ts` created with SpaceMemory interface
+- [ ] `src/weaviate/space-schema.ts` created
+- [ ] `ensureSpaceCollection` function implemented
+- [ ] Space collection schema defined
+- [ ] Collection naming utilities created
+- [ ] Space ID constants defined
+- [ ] Unit tests created and passing
+- [ ] TypeScript compiles without errors
+- [ ] Types properly exported
+
+---
+
+## Code Example
+
+```typescript
+// src/types/space-memory.ts
+export interface SpaceMemory extends Memory {
+  space_id: string;           // "the_void", "public_space"
+  author_id: string;          // Original user_id (for permissions)
+  ghost_id?: string;          // Optional ghost profile
+  published_at: string;       // ISO 8601 timestamp
+  discovery_count: number;    // How many times discovered
+  attribution: 'user' | 'ghost';
+}
+
+// src/weaviate/space-schema.ts
+export async function ensureSpaceCollection(
+  client: WeaviateClient,
+  spaceId: string
+): Promise<Collection> {
+  const collectionName = getSpaceCollectionName(spaceId);
+  
+  const exists = await client.collections.exists(collectionName);
+  if (!exists) {
+    await createSpaceCollection(client, spaceId);
+  }
+  
+  return client.collections.get(collectionName);
+}
+
+export function getSpaceCollectionName(spaceId: string): string {
+  return `Memory_${spaceId}`;
+}
+
+export function sanitizeSpaceId(displayName: string): string {
+  return displayName.toLowerCase().replace(/\s+/g, '_');
+}
+```
+
+---
+
+## Related Files
+
+- Design: [`agent/design/publish-tools-confirmation-flow.md`](../design/publish-tools-confirmation-flow.md)
+- Memory types: [`src/types/memory.ts`](../../src/types/memory.ts)
+- Memory schema: [`src/weaviate/schema.ts`](../../src/weaviate/schema.ts)
+
+---
+
+**Next Task**: Task 36 - Implement remember_publish Tool

package/agent/tasks/task-36-implement-remember-publish.md

@@ -0,0 +1,227 @@
+# Task 36: Implement remember_publish Tool
+
+**Milestone**: M10 - Shared Spaces & Confirmation Flow
+**Estimated Time**: 4 hours
+**Dependencies**: Task 34 (Token Service), Task 35 (Space Types)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement the `remember_publish` tool that generates a confirmation token for publishing a memory to a shared space. This is the first step in the two-phase publish workflow.
+
+---
+
+## Steps
+
+### 1. Create Tool File
+
+Create `src/tools/publish.ts` with tool definition and handler.
+
+**Actions**:
+- Import required dependencies (token service, Weaviate client, types)
+- Define tool schema with MCP Tool interface
+- Create handler function signature
+- Export both tool definition and handler
+
+**Expected Outcome**: Tool file structure created
+
+### 2. Define Tool Schema
+
+Create MCP tool definition for remember_publish.
+
+**Actions**:
+- Set tool name: `remember_publish`
+- Write clear description for LLM
+- Define input schema with properties:
+  - `memory_id` (required): ID of memory to publish
+  - `target` (required): Space ID (enum: ['the_void'])
+  - `additional_tags` (optional): Extra tags for discovery
+- Set default values
+- Add helpful descriptions
+
+**Expected Outcome**: Tool schema complete
+
+### 3. Implement Memory Validation
+
+Verify the memory exists and user owns it.
+
+**Actions**:
+- Get user's Weaviate collection
+- Fetch memory by ID
+- Check if memory exists
+- Verify `user_id` matches
+- Return detailed error if validation fails
+- Include context in error response
+
+**Expected Outcome**: Memory ownership verified
+
+### 4. Create Confirmation Payload
+
+Build the payload to store with the token.
+
+**Actions**:
+- Extract memory_id from args
+- Include additional_tags
+- Store only IDs (not full content)
+- Content will be fetched fresh during confirmation
+- Keep payload minimal
+
+**Expected Outcome**: Payload structure defined
+
+### 5. Generate Confirmation Token
+
+Use token service to create confirmation request.
+
+**Actions**:
+- Call `confirmationTokenService.createRequest()`
+- Pass userId, action='publish_memory', payload, target
+- Receive requestId and token
+- Handle any errors from token service
+
+**Expected Outcome**: Token generated successfully
+
+### 6. Format Success Response
+
+Return token and payload to agent.
+
+**Actions**:
+- Create response object with success flag
+- Include token
+- Include payload summary (action, memory_id, target, tags)
+- Format as JSON string
+- Use pretty printing for readability
+
+**Expected Outcome**: Clear response format
+
+### 7. Implement Error Handling
+
+Handle all error cases gracefully.
+
+**Actions**:
+- Memory not found error
+- Permission denied error
+- Token service errors
+- Weaviate connection errors
+- Use `handleToolError` utility
+- Include context in all errors
+
+**Expected Outcome**: Comprehensive error handling
+
+### 8. Add Tool to Server
+
+Register tool in both server files.
+
+**Actions**:
+- Import tool in `src/server.ts`
+- Add to tools list in ListToolsRequestSchema handler
+- Add to CallToolRequestSchema handler
+- Repeat for `src/server-factory.ts`
+- Test tool registration
+
+**Expected Outcome**: Tool available in MCP server
+
+### 9. Create Unit Tests
+
+Test the publish tool thoroughly.
+
+**Actions**:
+- Create `tests/unit/publish.test.ts`
+- Test successful token generation
+- Test memory not found error
+- Test permission denied error
+- Test invalid space ID
+- Mock Weaviate and token service
+- Verify response format
+
+**Expected Outcome**: All tests passing
+
+### 10. Update Tool Count
+
+Update documentation with new tool count.
+
+**Actions**:
+- Update README.md (13 tools now)
+- Update progress.yaml
+- Note in milestone documentation
+
+**Expected Outcome**: Documentation current
+
+---
+
+## Verification
+
+- [ ] `src/tools/publish.ts` created
+- [ ] Tool schema defined with correct parameters
+- [ ] Memory validation implemented
+- [ ] Token generation working
+- [ ] Success response formatted correctly
+- [ ] Error handling comprehensive
+- [ ] Tool registered in server.ts
+- [ ] Tool registered in server-factory.ts
+- [ ] Unit tests created and passing
+- [ ] TypeScript compiles without errors
+- [ ] Build successful
+
+---
+
+## Tool Schema
+
+```typescript
+export const publishTool = {
+  name: 'remember_publish',
+  description: 'Publish a memory to a shared space (like "The Void"). The memory will be COPIED (not moved) from your personal collection. Generates a confirmation token. Use remember_confirm to execute.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      memory_id: {
+        type: 'string',
+        description: 'ID of the memory from your personal collection to publish'
+      },
+      target: {
+        type: 'string',
+        description: 'Target space to publish to (snake_case ID)',
+        enum: ['the_void'],
+        default: 'the_void'
+      },
+      additional_tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Additional tags for discovery (merged with original tags)',
+        default: []
+      }
+    },
+    required: ['memory_id', 'target']
+  }
+};
+```
+
+---
+
+## Response Format
+
+```json
+{
+  "success": true,
+  "token": "550e8400-e29b-41d4-a716-446655440000",
+  "payload": {
+    "action": "publish_memory",
+    "memory_id": "uuid-original",
+    "target": "the_void",
+    "additional_tags": []
+  }
+}
+```
+
+---
+
+## Related Files
+
+- Design: [`agent/design/publish-tools-confirmation-flow.md`](../design/publish-tools-confirmation-flow.md)
+- Token Service: [`src/services/confirmation-token.service.ts`](../../src/services/confirmation-token.service.ts)
+- Space Types: [`src/types/space-memory.ts`](../../src/types/space-memory.ts)
+
+---
+
+**Next Task**: Task 37 - Implement remember_confirm Tool

package/agent/tasks/task-37-implement-remember-confirm.md

@@ -0,0 +1,225 @@
+# Task 37: Implement remember_confirm Tool
+
+**Milestone**: M10 - Shared Spaces & Confirmation Flow
+**Estimated Time**: 5 hours
+**Dependencies**: Task 34 (Token Service), Task 35 (Space Types), Task 36 (Publish Tool)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement the generic `remember_confirm` tool that executes any pending action using a confirmation token. This is the second phase of the confirmation workflow and is designed to be extensible to other confirmable actions.
+
+---
+
+## Steps
+
+### 1. Create Tool File
+
+Create `src/tools/confirm.ts` with generic confirmation logic.
+
+**Actions**:
+- Import required dependencies
+- Define tool schema
+- Create main handler function
+- Create action-specific executor functions
+- Export tool definition and handler
+
+**Expected Outcome**: Tool file structure created
+
+### 2. Define Tool Schema
+
+Create MCP tool definition for remember_confirm.
+
+**Actions**:
+- Set tool name: `remember_confirm`
+- Write clear description emphasizing generic nature
+- Define input schema with single parameter:
+  - `token` (required): Confirmation token from action tool
+- Add helpful description
+
+**Expected Outcome**: Tool schema complete
+
+### 3. Implement Token Validation
+
+Validate and confirm the token.
+
+**Actions**:
+- Call `confirmationTokenService.confirmRequest()`
+- Pass userId and token
+- Check if request is valid (not null)
+- Handle invalid/expired token error
+- Return detailed error with context
+
+**Expected Outcome**: Token validation working
+
+### 4. Create Action Dispatcher
+
+Route to appropriate executor based on action type.
+
+**Actions**:
+- Check `request.action` field
+- If 'publish_memory': call `executePublishMemory()`
+- If 'retract_memory': call `executeRetractMemory()` (future)
+- Add other action types as needed
+- Throw error for unknown action types
+- Make extensible for future actions
+
+**Expected Outcome**: Generic dispatch pattern established
+
+### 5. Implement executePublishMemory Function
+
+Execute the publish action.
+
+**Actions**:
+- Fetch original memory from user collection (fresh, not from payload)
+- Verify memory still exists
+- Verify user still owns it
+- Get target space collection via `ensureSpaceCollection()`
+- Create published memory object (copy with modifications)
+- Set space-specific fields: `space_id`, `author_id`, `published_at`, `discovery_count`
+- Merge additional_tags
+- Insert into space collection
+- Return space_memory_id
+
+**Expected Outcome**: Publish action executes successfully
+
+### 6. Format Success Response
+
+Return minimal success response.
+
+**Actions**:
+- Create response with success flag
+- Include payload with:
+  - action: 'publish_memory'
+  - space: target space ID
+  - space_memory_id: new ID in space collection
+- Keep response minimal (agent already knows original memory)
+- Format as JSON string
+
+**Expected Outcome**: Clear, minimal response
+
+### 7. Implement Error Handling
+
+Handle all error cases.
+
+**Actions**:
+- Invalid/expired token error
+- Memory no longer exists error
+- Permission denied error
+- Space collection creation error
+- Weaviate insertion error
+- Use `handleToolError` utility
+- Include detailed context
+
+**Expected Outcome**: Comprehensive error handling
+
+### 8. Add Tool to Server
+
+Register tool in both server files.
+
+**Actions**:
+- Import tool in `src/server.ts`
+- Add to tools list
+- Add to call handler
+- Repeat for `src/server-factory.ts`
+- Test tool registration
+
+**Expected Outcome**: Tool available in MCP server
+
+### 9. Create Unit Tests
+
+Test the confirm tool thoroughly.
+
+**Actions**:
+- Create `tests/unit/confirm.test.ts`
+- Test successful publish execution
+- Test invalid token error
+- Test memory no longer exists error
+- Test permission denied error
+- Test unknown action type error
+- Mock Weaviate, Firestore, token service
+- Verify response format
+
+**Expected Outcome**: All tests passing
+
+### 10. Test End-to-End Flow
+
+Test complete publish workflow.
+
+**Actions**:
+- Call remember_publish to get token
+- Call remember_confirm with token
+- Verify memory appears in space collection
+- Verify original memory unchanged
+- Test with actual Weaviate instance if available
+
+**Expected Outcome**: Full workflow verified
+
+---
+
+## Verification
+
+- [ ] `src/tools/confirm.ts` created
+- [ ] Tool schema defined
+- [ ] Token validation implemented
+- [ ] Action dispatcher created
+- [ ] executePublishMemory function working
+- [ ] Success response formatted correctly
+- [ ] Error handling comprehensive
+- [ ] Tool registered in server.ts
+- [ ] Tool registered in server-factory.ts
+- [ ] Unit tests created and passing
+- [ ] End-to-end flow tested
+- [ ] TypeScript compiles without errors
+- [ ] Build successful
+
+---
+
+## Tool Schema
+
+```typescript
+export const confirmTool = {
+  name: 'remember_confirm',
+  description: 'Confirm and execute a pending action using the token. Works for any action that requires confirmation (publish, delete, etc.).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      token: {
+        type: 'string',
+        description: 'The confirmation token from the action tool'
+      }
+    },
+    required: ['token']
+  }
+};
+```
+
+---
+
+## Response Format
+
+```json
+{
+  "success": true,
+  "payload": {
+    "action": "publish_memory",
+    "space": "the_void",
+    "space_memory_id": "uuid-new-in-space"
+  }
+}
+```
+
+---
+
+## Related Files
+
+- Design: [`agent/design/publish-tools-confirmation-flow.md`](../design/publish-tools-confirmation-flow.md)
+- Token Service: [`src/services/confirmation-token.service.ts`](../../src/services/confirmation-token.service.ts)
+- Space Schema: [`src/weaviate/space-schema.ts`](../../src/weaviate/space-schema.ts)
+- Publish Tool: [`src/tools/publish.ts`](../../src/tools/publish.ts)
+
+---
+
+**Next Task**: Task 38 - Implement remember_deny Tool