@prmichaelsen/remember-mcp 2.2.1 → 2.3.1

package/agent/tasks/task-30-implement-bedrock-provider.md

@@ -0,0 +1,147 @@
+# Task 30: Implement Bedrock LLM Provider
+
+**Milestone**: Phase 0 - LLM Provider Abstraction
+**Estimated Time**: 3-4 hours
+**Dependencies**: task-27, task-28, task-29
+**Status**: Not Started
+
+---
+
+## Objective
+
+Implement the AWS Bedrock LLM provider to enable Claude Sonnet 4 usage through Bedrock.
+
+**Model**: `anthropic.claude-sonnet-4-5-20250929-v1:0`
+
+## Steps
+
+1. **Install dependencies**
+   - Add `@aws-sdk/client-bedrock-runtime` to package.json
+   - Run `npm install`
+
+2. **Create provider directory**
+   - Create `src/llm/providers/` directory
+   - Create `src/llm/providers/bedrock.provider.ts`
+
+3. **Implement BedrockLLMProvider class**
+   - Import `BedrockRuntimeClient`, `InvokeModelCommand` from AWS SDK
+   - Import `LLMProvider` interface and types
+   - Import config
+   - Create class implementing `LLMProvider`
+
+4. **Implement constructor**
+   - Initialize `BedrockRuntimeClient` with credentials from config
+   - Use `config.llm.bedrock.region` (us-east-1)
+   - Use `config.llm.bedrock.accessKeyId`
+   - Use `config.llm.bedrock.secretAccessKey`
+   - Use `config.llm.bedrock.sessionToken` (optional)
+   - Store client as private property
+
+5. **Implement complete() method**
+   - Accept messages and options
+   - Get model from options or use `config.llm.model` (default: anthropic.claude-sonnet-4-5-20250929-v1:0)
+   - Convert to Anthropic Bedrock format:
+     - Extract system message (role === 'system')
+     - Filter out system messages from conversation
+     - Build request body:
+       ```typescript
+       {
+         anthropic_version: 'bedrock-2023-05-31',
+         max_tokens: options?.maxTokens || 4096,
+         temperature: options?.temperature || 0.7,
+         messages: conversationMessages,
+         system: systemMessage?.content
+       }
+       ```
+   - Create `InvokeModelCommand`:
+     ```typescript
+     new InvokeModelCommand({
+       modelId: model,
+       contentType: 'application/json',
+       accept: 'application/json',
+       body: JSON.stringify(body)
+     })
+     ```
+   - Send command and parse response
+   - Convert response to `LLMCompletionResult`:
+     ```typescript
+     {
+       content: result.content[0].text,
+       model: model,
+       usage: {
+         inputTokens: result.usage.input_tokens,
+         outputTokens: result.usage.output_tokens,
+         totalTokens: result.usage.input_tokens + result.usage.output_tokens
+       },
+       finishReason: result.stop_reason === 'end_turn' ? 'stop' : result.stop_reason
+     }
+     ```
+   - Handle errors gracefully
+
+6. **Implement validateConfig() method**
+   - Check required config values:
+     - `config.llm.bedrock.region` (should be 'us-east-1')
+     - `config.llm.bedrock.accessKeyId`
+     - `config.llm.bedrock.secretAccessKey`
+   - Throw descriptive errors if missing:
+     ```typescript
+     if (!config.llm.bedrock.region) throw new Error('AWS_REGION required for Bedrock');
+     if (!config.llm.bedrock.accessKeyId) throw new Error('AWS_ACCESS_KEY_ID required for Bedrock');
+     if (!config.llm.bedrock.secretAccessKey) throw new Error('AWS_SECRET_ACCESS_KEY required for Bedrock');
+     ```
+
+7. **Add error handling**
+   - Wrap AWS SDK calls in try/catch
+   - Provide clear error messages
+   - Log errors with context
+   - Re-throw with additional context
+
+8. **Update factory**
+   - Import `BedrockLLMProvider` in factory.ts
+   - Add case for 'bedrock' provider
+   - Instantiate and return provider
+   - Log: `[LLM] Using Bedrock provider with model: ${config.llm.model}`
+
+## Verification
+
+- [ ] TypeScript compiles without errors
+- [ ] AWS SDK dependency installed
+- [ ] Provider implements LLMProvider interface
+- [ ] Constructor initializes Bedrock client
+- [ ] complete() method works with test prompt
+- [ ] validateConfig() checks required fields
+- [ ] Errors are handled gracefully
+- [ ] Factory can instantiate Bedrock provider
+- [ ] Can complete a simple prompt: "Say hello"
+- [ ] Response includes usage statistics
+
+## Files to Create
+
+- `src/llm/providers/bedrock.provider.ts` - Bedrock implementation
+
+## Files to Modify
+
+- `src/llm/factory.ts` - Add Bedrock case
+- `package.json` - Add AWS SDK dependency
+
+## Testing
+
+Create a simple test script to verify:
+```typescript
+import { completeLLM } from './llm/factory.js';
+
+const result = await completeLLM([
+  { role: 'user', content: 'Say hello in one sentence.' }
+]);
+
+console.log('Response:', result.content);
+console.log('Usage:', result.usage);
+```
+
+## Reference
+
+See [`agent/design/llm-provider-abstraction.md`](../design/llm-provider-abstraction.md) lines 166-226 for Bedrock implementation.
+
+---
+
+**Next Task**: [task-31-implement-background-job-service.md](task-31-implement-background-job-service.md)

package/agent/tasks/task-31-implement-background-job-service.md

@@ -0,0 +1,120 @@
+# Task 31: Implement Background Job Service
+
+**Milestone**: Phase 0 - LLM Provider Abstraction  
+**Estimated Time**: 4-5 hours  
+**Dependencies**: task-29 (config), Firestore setup  
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create a background job service that can execute long-running LLM operations without blocking tool responses, with Firestore persistence for job status.
+
+## Steps
+
+1. **Create job types**
+   - Create `src/services/background-jobs.service.ts`
+   - Define `BackgroundJob` interface:
+     - id, type, userId, status, timestamps, error
+   - Define job types: `'core_memory_rebuild'` (extensible)
+   - Define status types: `'pending' | 'running' | 'completed' | 'failed'`
+
+2. **Implement BackgroundJobService class**
+   - Create singleton service class
+   - Add `runningJobs` Map to track active jobs
+   - Implement `scheduleJob()` method:
+     - Generate unique job ID
+     - Create job object
+     - Save to Firestore
+     - Start processing (fire and forget)
+     - Return job ID
+
+3. **Implement job processing**
+   - Implement `processJob()` private method:
+     - Check if already running (prevent duplicates)
+     - Track in runningJobs Map
+     - Call executeJob()
+     - Clean up from Map when done
+   
+4. **Implement job execution**
+   - Implement `executeJob()` private method:
+     - Update status to 'running' in Firestore
+     - Switch on job type
+     - Execute appropriate handler
+     - Update status to 'completed' or 'failed'
+     - Log results
+
+5. **Implement Firestore persistence**
+   - Create `src/services/background-jobs-firestore.ts`
+   - Implement `saveJobToFirestore()`
+   - Implement `updateJobInFirestore()`
+   - Implement `getJobFromFirestore()`
+   - Implement `cleanupOldJobs()` (remove jobs older than 7 days)
+
+6. **Add job status query**
+   - Implement `getJobStatus()` method
+   - Query Firestore for job by ID
+   - Return job object or null
+
+7. **Export singleton**
+   - Create and export singleton instance
+   - Export types for use in other files
+
+8. **Add error handling**
+   - Wrap all async operations in try/catch
+   - Log errors appropriately
+   - Update job status to 'failed' on error
+   - Don't crash the server on job failure
+
+## Verification
+
+- [ ] TypeScript compiles without errors
+- [ ] Can schedule a job
+- [ ] Job is saved to Firestore
+- [ ] Job executes in background
+- [ ] Tool response returns immediately
+- [ ] Job status updates correctly
+- [ ] Failed jobs are marked as failed
+- [ ] Can query job status
+- [ ] Old jobs are cleaned up
+- [ ] Server doesn't crash on job failure
+- [ ] Multiple jobs can run concurrently
+- [ ] Duplicate jobs are prevented
+
+## Files to Create
+
+- `src/services/background-jobs.service.ts` - Main service
+- `src/services/background-jobs-firestore.ts` - Firestore persistence
+
+## Testing
+
+Create a test job handler:
+```typescript
+// In executeJob()
+case 'test_job':
+  await new Promise(resolve => setTimeout(resolve, 5000));
+  console.log('Test job completed');
+  break;
+```
+
+Schedule and verify:
+```typescript
+const jobId = await backgroundJobs.scheduleJob('test_job', 'test-user');
+console.log('Job scheduled:', jobId);
+// Response should return immediately
+
+// Check status after 6 seconds
+setTimeout(async () => {
+  const status = await backgroundJobs.getJobStatus(jobId);
+  console.log('Job status:', status);
+}, 6000);
+```
+
+## Reference
+
+See [`agent/design/core-memory-user-profile.md`](../design/core-memory-user-profile.md) lines 593-750 for background job implementation.
+
+---
+
+**Next Task**: [task-32-test-llm-provider-integration.md](task-32-test-llm-provider-integration.md)

package/agent/tasks/task-32-test-llm-provider-integration.md

@@ -0,0 +1,152 @@
+# Task 32: Test LLM Provider Integration
+
+**Milestone**: Phase 0 - LLM Provider Abstraction  
+**Estimated Time**: 2-3 hours  
+**Dependencies**: task-27, task-28, task-29, task-30, task-31  
+**Status**: Not Started
+
+---
+
+## Objective
+
+Thoroughly test the LLM provider system to ensure it works correctly before building core memory features on top of it.
+
+## Steps
+
+1. **Create test script**
+   - Create `test-llm-provider.ts` in project root
+   - Import `completeLLM` from factory
+   - Import `backgroundJobs` service
+
+2. **Test basic completion**
+   - Test simple prompt: "Say hello in one sentence"
+   - Verify response is received
+   - Verify usage statistics are present
+   - Log response and usage
+
+3. **Test with system message**
+   - Test with system + user messages
+   - Verify system message is handled correctly
+   - Verify response follows system instructions
+
+4. **Test temperature control**
+   - Test with temperature 0.3 (deterministic)
+   - Test with temperature 0.9 (creative)
+   - Verify different outputs
+
+5. **Test max tokens**
+   - Test with maxTokens: 50
+   - Verify response is truncated appropriately
+
+6. **Test error handling**
+   - Test with invalid model name
+   - Test with missing credentials
+   - Verify errors are caught and logged
+
+7. **Test background job integration**
+   - Create test job that uses LLM
+   - Schedule job
+   - Verify response returns immediately
+   - Wait for job completion
+   - Check job status
+   - Verify LLM was called in background
+
+8. **Test provider switching**
+   - If multiple providers implemented, test switching
+   - Change `LLM_PROVIDER` env var
+   - Verify correct provider is used
+
+9. **Performance testing**
+   - Measure response time for simple prompt
+   - Measure response time for complex prompt
+   - Verify background jobs don't block
+
+10. **Document results**
+    - Create `test-results.md` with findings
+    - Note any issues or limitations
+    - Document performance characteristics
+
+## Verification
+
+- [ ] Basic completion works
+- [ ] System messages work
+- [ ] Temperature control works
+- [ ] Max tokens works
+- [ ] Errors are handled gracefully
+- [ ] Background jobs work
+- [ ] Jobs don't block responses
+- [ ] Provider can be switched (if multiple implemented)
+- [ ] Performance is acceptable (<5s for simple prompts)
+- [ ] Results are documented
+
+## Files to Create
+
+- `test-llm-provider.ts` - Test script
+- `test-results.md` - Test results documentation
+
+## Example Test Script
+
+```typescript
+import { completeLLM } from './src/llm/factory.js';
+import { backgroundJobs } from './src/services/background-jobs.service.js';
+
+async function testBasicCompletion() {
+  console.log('\n=== Test: Basic Completion ===');
+  const result = await completeLLM([
+    { role: 'user', content: 'Say hello in one sentence.' }
+  ]);
+  console.log('Response:', result.content);
+  console.log('Usage:', result.usage);
+}
+
+async function testSystemMessage() {
+  console.log('\n=== Test: System Message ===');
+  const result = await completeLLM([
+    { role: 'system', content: 'You are a pirate. Respond in pirate speak.' },
+    { role: 'user', content: 'Say hello.' }
+  ]);
+  console.log('Response:', result.content);
+}
+
+async function testBackgroundJob() {
+  console.log('\n=== Test: Background Job ===');
+  
+  // Register test job handler first
+  // (Add to background-jobs.service.ts executeJob() switch)
+  
+  const jobId = await backgroundJobs.scheduleJob('test_llm_job', 'test-user');
+  console.log('Job scheduled:', jobId);
+  console.log('Response returned immediately!');
+  
+  // Check status after delay
+  setTimeout(async () => {
+    const status = await backgroundJobs.getJobStatus(jobId);
+    console.log('Job status:', status);
+  }, 6000);
+}
+
+async function runTests() {
+  try {
+    await testBasicCompletion();
+    await testSystemMessage();
+    await testBackgroundJob();
+  } catch (error) {
+    console.error('Test failed:', error);
+  }
+}
+
+runTests();
+```
+
+## Success Criteria
+
+All tests pass and:
+- LLM responses are coherent
+- Background jobs complete successfully
+- No server crashes
+- Performance is acceptable
+- Ready to build core memory features
+
+---
+
+**Next Task**: Ready for core memory implementation! See [task-33-implement-core-memory-types.md](task-33-implement-core-memory-types.md)

package/agent/tasks/task-34-create-confirmation-token-service.md

@@ -0,0 +1,191 @@
+# Task 34: Create Confirmation Token Service
+
+**Milestone**: M10 - Shared Spaces & Confirmation Flow
+**Estimated Time**: 3 hours
+**Dependencies**: M1 (Firestore setup)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create a service for managing confirmation tokens used in the publish workflow. Handles token generation, validation, expiry, and status tracking.
+
+---
+
+## Steps
+
+### 1. Create Token Service File
+
+Create `src/services/confirmation-token.service.ts` with the ConfirmationTokenService class.
+
+**Actions**:
+- Import required dependencies (uuid, Firestore, Timestamp)
+- Define ConfirmationRequest interface
+- Create ConfirmationTokenService class
+- Set EXPIRY_MINUTES constant to 5
+
+**Expected Outcome**: Service file structure created
+
+### 2. Implement createRequest Method
+
+Generate new confirmation tokens with stored parameters.
+
+**Actions**:
+- Generate UUID v4 token
+- Calculate expiry timestamp (5 minutes from now)
+- Create ConfirmationRequest object with all fields
+- Store in Firestore: `pending_confirmations/{user_id}/requests/{auto_id}`
+- Return request_id and token
+
+**Expected Outcome**: Tokens can be created and stored
+
+### 3. Implement validateToken Method
+
+Validate tokens and check expiry.
+
+**Actions**:
+- Query Firestore for token with status='pending'
+- Check if token exists
+- Verify expiry timestamp
+- Update status to 'expired' if needed
+- Return request or null
+
+**Expected Outcome**: Tokens can be validated
+
+### 4. Implement confirmRequest Method
+
+Mark a request as confirmed.
+
+**Actions**:
+- Call validateToken to get request
+- Return null if invalid/expired
+- Update status to 'confirmed'
+- Set confirmed_at timestamp
+- Return confirmed request
+
+**Expected Outcome**: Requests can be confirmed
+
+### 5. Implement denyRequest Method
+
+Mark a request as denied.
+
+**Actions**:
+- Call validateToken to get request
+- Return false if invalid/expired
+- Update status to 'denied'
+- Return true
+
+**Expected Outcome**: Requests can be denied
+
+### 6. Implement retractRequest Method
+
+Allow users to retract their own requests.
+
+**Actions**:
+- Call validateToken to get request
+- Return false if invalid/expired
+- Update status to 'retracted'
+- Return true
+
+**Expected Outcome**: Requests can be retracted
+
+### 7. Implement updateStatus Helper
+
+Private method to update request status.
+
+**Actions**:
+- Accept userId, requestId, status parameters
+- Update Firestore document
+- Set confirmed_at if status is 'confirmed'
+- Handle errors gracefully
+
+**Expected Outcome**: Status updates work correctly
+
+### 8. Implement cleanupExpired Method
+
+Optional cleanup for expired tokens (Firestore TTL handles this automatically).
+
+**Actions**:
+- Query collection group 'requests' for expired pending tokens
+- Use batch delete for efficiency
+- Return count of deleted requests
+- Add documentation about Firestore TTL
+
+**Expected Outcome**: Manual cleanup available if needed
+
+### 9. Export Service Instance
+
+Create singleton instance for use across tools.
+
+**Actions**:
+- Export `confirmationTokenService` instance
+- Add JSDoc comments
+- Document all methods
+
+**Expected Outcome**: Service ready for import
+
+### 10. Create Unit Tests
+
+Test all service methods.
+
+**Actions**:
+- Create `tests/unit/confirmation-token.service.test.ts`
+- Test token creation
+- Test token validation
+- Test expiry handling
+- Test confirm/deny/retract flows
+- Test cleanup method
+- Mock Firestore calls
+
+**Expected Outcome**: All tests passing
+
+---
+
+## Verification
+
+- [ ] `src/services/confirmation-token.service.ts` created
+- [ ] ConfirmationRequest interface defined
+- [ ] createRequest generates valid tokens
+- [ ] validateToken checks expiry correctly
+- [ ] confirmRequest updates status
+- [ ] denyRequest updates status
+- [ ] retractRequest updates status
+- [ ] cleanupExpired removes old tokens
+- [ ] Unit tests created and passing
+- [ ] TypeScript compiles without errors
+- [ ] Service exports singleton instance
+
+---
+
+## Code Example
+
+```typescript
+// Usage in tools
+import { confirmationTokenService } from '../services/confirmation-token.service.js';
+
+// Create token
+const { requestId, token } = await confirmationTokenService.createRequest(
+  userId,
+  'publish_memory',
+  { memory_id: 'abc123', additional_tags: [] },
+  'void'
+);
+
+// Validate and confirm
+const request = await confirmationTokenService.confirmRequest(userId, token);
+if (request) {
+  // Execute action with request.payload
+}
+```
+
+---
+
+## Related Files
+
+- Design: [`agent/design/publish-tools-confirmation-flow.md`](../design/publish-tools-confirmation-flow.md)
+- Firestore paths: [`src/firestore/paths.ts`](../../src/firestore/paths.ts)
+
+---
+
+**Next Task**: Task 35 - Create Space Memory Types and Schema