@prmichaelsen/remember-mcp 0.1.0

package/agent/design/common-template-fields.md

@@ -0,0 +1,282 @@
+# Common Template Fields
+
+**Concept**: Standard fields that should be included in all templates  
+**Created**: 2026-02-11  
+**Status**: Design Specification
+
+---
+
+## Overview
+
+All templates should include certain common fields to maintain consistency and enable useful features like source tracking, attribution, and verification.
+
+---
+
+## Common Fields (All Templates)
+
+### 1. **references** (array of URLs)
+
+**Purpose**: Track source URLs that generated or inspired this memory
+
+**Use Cases**:
+- Recipe from online source → link to recipe website
+- Learning note from article → link to article
+- Person info from LinkedIn → link to profile
+- Restaurant from review site → link to Yelp/Google Maps
+- Product info from Amazon → link to product page
+
+**Type**: Array of strings (URLs)
+
+**Example**:
+```yaml
+references: [
+  "https://www.seriouseats.com/perfect-chocolate-chip-cookies",
+  "https://www.youtube.com/watch?v=abc123"
+]
+```
+
+### 2. **notes** (text)
+
+**Purpose**: Free-form additional information
+
+**Already in most templates**: ✅
+
+### 3. **tags** (array)
+
+**Purpose**: Categorization and organization
+
+**Should add to all templates**
+
+### 4. **created_at** (datetime)
+
+**Purpose**: When memory was created
+
+**Auto-generated by system**
+
+---
+
+## Updated Template Pattern
+
+### Standard Template Structure
+
+```yaml
+template_name: "Template Name"
+description: "What this template is for"
+category: "category_name"
+fields:
+  # Template-specific fields
+  - name: "specific_field_1"
+    type: "string"
+    required: true
+    
+  - name: "specific_field_2"
+    type: "string"
+    required: false
+    
+  # Common fields (all templates)
+  - name: "references"
+    type: "array"
+    item_type: "string"
+    required: false
+    description: "Source URLs that generated or inspired this memory"
+    placeholder: ["https://example.com/source"]
+    validation:
+      pattern: "^https?://"  # Must be valid URL
+      
+  - name: "tags"
+    type: "array"
+    item_type: "string"
+    required: false
+    description: "Tags for organization and search"
+    
+  - name: "notes"
+    type: "text"
+    required: false
+    description: "Additional notes and observations"
+```
+
+---
+
+## Examples with References
+
+### Recipe Template
+```yaml
+recipe_name: "Perfect Chocolate Chip Cookies"
+ingredients: ["flour", "butter", "chocolate chips", ...]
+instructions: ["Preheat oven...", "Mix ingredients..."]
+references: [
+  "https://www.seriouseats.com/perfect-chocolate-chip-cookies",
+  "https://www.youtube.com/watch?v=cookie-tutorial"
+]
+tags: ["dessert", "baking", "cookies"]
+notes: "Modified to use less sugar"
+```
+
+### Learning Note Template
+```yaml
+topic: "React Hooks Best Practices"
+key_concepts: ["useState", "useEffect", "custom hooks"]
+references: [
+  "https://react.dev/reference/react/hooks",
+  "https://kentcdodds.com/blog/react-hooks-best-practices",
+  "https://www.youtube.com/watch?v=hooks-tutorial"
+]
+tags: ["react", "javascript", "web-development"]
+notes: "Focus on useEffect cleanup functions"
+```
+
+### Person Template
+```yaml
+name: "Sarah Chen"
+relationship: ["professional"]
+company: "Google"
+references: [
+  "https://linkedin.com/in/sarahchen",
+  "https://twitter.com/sarahchen",
+  "https://sarahchen.com"
+]
+tags: ["product-management", "AI", "tech"]
+notes: "Met at TechCrunch Disrupt 2026"
+```
+
+### Restaurant Review Template
+```yaml
+restaurant_name: "Nobu"
+cuisine_type: "Japanese"
+rating: 0.9  # 0-1 scale
+references: [
+  "https://www.yelp.com/biz/nobu-san-francisco",
+  "https://www.google.com/maps/place/nobu",
+  "https://www.noburestaurants.com"
+]
+tags: ["sushi", "fine-dining", "japanese"]
+notes: "Try the black cod miso"
+```
+
+### Inventory Item Template
+```yaml
+item_name: "Camping Tent"
+quantity: 1
+storage_location: "garage bin A4"
+references: [
+  "https://www.rei.com/product/tent-model-123",
+  "https://www.youtube.com/watch?v=tent-setup-guide"
+]
+tags: ["camping", "outdoor", "gear"]
+notes: "Coleman Sundome 4-person"
+```
+
+---
+
+## Benefits of References Field
+
+### 1. **Attribution**
+- Credit original sources
+- Track where information came from
+- Verify information later
+
+### 2. **Verification**
+- Check if source still exists
+- Update information if source changes
+- Validate accuracy
+
+### 3. **Discovery**
+- Find related content
+- Explore source websites
+- Learn more about topic
+
+### 4. **Context**
+- Understand origin of memory
+- See what inspired the memory
+- Track information provenance
+
+### 5. **Sharing**
+- Share sources with others
+- Recommend resources
+- Build knowledge base
+
+---
+
+## Implementation
+
+### Template Field Definition
+
+```typescript
+// Add to ALL templates
+{
+  name: "references",
+  type: "array",
+  item_type: "string",
+  required: false,
+  description: "Source URLs that generated or inspired this memory",
+  validation: {
+    pattern: "^https?://",  // Must be valid URL
+    max_items: 10,  // Reasonable limit
+    error_message: "Must be a valid URL starting with http:// or https://"
+  },
+  placeholder: ["https://example.com/source"],
+  ui_hint: "url_input"  // UI can show URL input field
+}
+```
+
+### Auto-Population
+
+```typescript
+// When creating memory from web content
+async function createMemoryFromWebPage(url: string, content: string) {
+  return await remember_create_memory({
+    content: content,
+    references: [url],  // ✅ Auto-populate from source
+    tags: extractTagsFromUrl(url)
+  });
+}
+
+// When agent fetches information
+User: "Look up the recipe for chocolate chip cookies"
+Agent: *fetches from seriouseats.com*
+Agent: remember_create_memory({
+  template_id: "recipe",
+  content: {
+    recipe_name: "Chocolate Chip Cookies",
+    ingredients: [...],
+    references: ["https://www.seriouseats.com/..."]  // ✅ Auto-added
+  }
+})
+```
+
+---
+
+## Reference Validation
+
+```typescript
+function validateReferences(references: string[]): ValidationResult {
+  const errors = [];
+  
+  for (const ref of references) {
+    // Check if valid URL
+    try {
+      new URL(ref);
+    } catch {
+      errors.push(`Invalid URL: ${ref}`);
+    }
+    
+    // Check if accessible (optional)
+    const accessible = await checkUrlAccessible(ref);
+    if (!accessible) {
+      errors.push(`URL not accessible: ${ref}`);
+    }
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+```
+
+---
+
+**Status**: Design Specification  
+**Field**: `references` (array of URLs)  
+**Scope**: All templates  
+**Benefit**: Source tracking, attribution, verification, discovery

package/agent/design/complete-tool-set.md

@@ -0,0 +1,407 @@
+# Complete Remember-MCP Tool Set
+
+**Project**: remember-mcp  
+**Created**: 2026-02-11  
+**Status**: Final Specification
+
+---
+
+## Complete Tool Set (18 Tools)
+
+### Core Memory Operations (6 tools)
+
+#### 1. `remember_create_memory`
+Create a new memory with optional template
+
+**Parameters**:
+- `content`: Memory content (string or structured object)
+- `template_id`: Optional template to use
+- `type`: Content type (inventory, note, event, etc.)
+- `weight`: Significance (0-1, default from preferences)
+- `trust`: Access control (0-1, default from preferences)
+- `tags`: Array of tags
+- `references`: Array of source URLs
+- `skip_template_suggestion`: Boolean to skip auto-suggestion
+
+**Returns**: Memory ID or template suggestion
+
+---
+
+#### 2. `remember_update_memory`
+Update an existing memory
+
+**Parameters**:
+- `memory_id`: ID of memory to update
+- `updates`: Partial memory object with fields to update
+- `reason`: Optional reason for update (for history)
+
+**Returns**: Updated memory
+
+---
+
+#### 3. `remember_delete_memory`
+Delete a memory
+
+**Parameters**:
+- `memory_id`: ID of memory to delete
+- `delete_relationships`: Boolean - also delete connected relationships?
+
+**Returns**: Confirmation
+
+---
+
+#### 4. `remember_search_memory`
+Hybrid search for memories
+
+**Parameters**:
+- `query`: Search query string
+- `alpha`: Balance between semantic (1.0) and keyword (0.0), default from preferences
+- `filters`: Content type, tags, date range, weight threshold, trust level, location
+- `include_relationships`: Boolean - include relationships in results
+- `limit`: Max results (default from preferences)
+- `offset`: Pagination offset
+
+**Returns**: Array of memories (and optionally relationships)
+
+---
+
+#### 5. `remember_find_similar`
+Find memories similar to a reference memory
+
+**Parameters**:
+- `reference_id`: Memory ID to find similar to
+- `similarity_threshold`: Minimum similarity (0-1)
+- `limit`: Max results
+- `filters`: Optional filters
+
+**Returns**: Array of similar memories with similarity scores
+
+---
+
+#### 6. `remember_query_memory`
+RAG + GraphQL queries for complex questions
+
+**Parameters**:
+- `question`: Natural language question
+- `max_sources`: Max memories to use for context
+- `filters`: Optional filters
+- `include_relationships`: Boolean - include relationship context
+
+**Returns**: AI-generated answer with source citations
+
+---
+
+### Relationship Operations (4 tools)
+
+#### 7. `remember_create_relationship`
+Create a relationship between memories
+
+**Parameters**:
+- `memory_ids`: Array of 2...N memory IDs to connect
+- `relationship_type`: Free-form string (e.g., "inspired_by", "contradicts")
+- `observation`: Description of the connection
+- `strength`: Relationship strength (0-1)
+- `confidence`: Confidence in relationship (0-1)
+
+**Returns**: Relationship ID
+
+---
+
+#### 8. `remember_update_relationship`
+Update an existing relationship
+
+**Parameters**:
+- `relationship_id`: ID of relationship to update
+- `updates`: Partial relationship object
+- `reason`: Optional reason for update
+
+**Returns**: Updated relationship
+
+---
+
+#### 9. `remember_search_relationship`
+Search relationships by observation or type
+
+**Parameters**:
+- `query`: Search query (searches observation text)
+- `memory_id`: Optional - filter to relationships involving this memory
+- `relationship_type`: Optional - filter by type
+- `limit`: Max results
+
+**Returns**: Array of relationships
+
+---
+
+#### 10. `remember_delete_relationship`
+Delete a relationship
+
+**Parameters**:
+- `relationship_id`: ID of relationship to delete
+- `update_memories`: Boolean - remove relationship ID from connected memories?
+
+**Returns**: Confirmation
+
+---
+
+### Preference Management (2 tools)
+
+#### 11. `remember_update_preferences`
+Update user preferences through conversation
+
+**Parameters**:
+- `preference_path`: Dot-notation path (e.g., "templates.auto_suggest")
+- `value`: New value (boolean, number, string, or array)
+- `reason`: Optional reason for change
+
+**Returns**: Old value, new value, confirmation message
+
+**Examples**:
+- "Stop suggesting templates" → `{ preference_path: "templates.auto_suggest", value: false }`
+- "Show 20 results" → `{ preference_path: "search.default_limit", value: 20 }`
+
+---
+
+#### 12. `remember_get_preferences`
+Get current user preferences
+
+**Parameters**:
+- `category`: Optional filter (templates, search, privacy, etc.)
+
+**Returns**: User preferences object or filtered by category
+
+---
+
+### Template Management (5 tools - Optional, Phase 3)
+
+#### 13. `remember_create_template`
+Create a custom template
+
+**Parameters**:
+- `template_name`: Name of template
+- `description`: What template is for
+- `fields`: Array of field definitions
+- `trigger_keywords`: Keywords that suggest this template
+- `auto_apply`: Boolean - auto-suggest this template
+
+**Returns**: Template ID
+
+---
+
+#### 14. `remember_list_templates`
+List available templates
+
+**Parameters**:
+- `include_default`: Boolean - include default templates
+- `include_user`: Boolean - include user's custom templates
+- `category`: Optional category filter
+- `sort_by`: popularity, name, recent
+
+**Returns**: Array of templates
+
+---
+
+#### 15. `remember_get_template`
+Get template details
+
+**Parameters**:
+- `template_id`: Template ID
+
+**Returns**: Full template definition
+
+---
+
+#### 16. `remember_update_template`
+Update a user template
+
+**Parameters**:
+- `template_id`: Template ID (must be user's template)
+- `updates`: Partial template object
+
+**Returns**: Updated template
+
+---
+
+#### 17. `remember_delete_template`
+Delete a user template
+
+**Parameters**:
+- `template_id`: Template ID (must be user's template)
+
+**Returns**: Confirmation
+
+---
+
+### Permission Management (1 tool - Phase 2)
+
+#### 18. `remember_grant_access`
+Grant another user access to your memories
+
+**Parameters**:
+- `accessor_user_id`: User to grant access to
+- `trust_level`: Trust level (0-1)
+- `trust_summary`: Brief explanation
+- `allowed_tags`: Optional - limit to specific tags
+- `excluded_tags`: Optional - exclude specific tags
+- `expires_at`: Optional expiration date
+
+**Returns**: Permission confirmation
+
+---
+
+## Tool Organization by Phase
+
+### Phase 1: MVP (12 tools)
+
+**Memory Operations** (6):
+1. remember_create_memory
+2. remember_update_memory
+3. remember_delete_memory
+4. remember_search_memory
+5. remember_find_similar
+6. remember_query_memory
+
+**Relationship Operations** (4):
+7. remember_create_relationship
+8. remember_update_relationship
+9. remember_search_relationship
+10. remember_delete_relationship
+
+**Preferences** (2):
+11. remember_update_preferences
+12. remember_get_preferences
+
+### Phase 2: Trust & Permissions (1 tool)
+
+**Permission Management** (1):
+13. remember_grant_access
+
+### Phase 3: Templates (5 tools)
+
+**Template Management** (5):
+14. remember_create_template
+15. remember_list_templates
+16. remember_get_template
+17. remember_update_template
+18. remember_delete_template
+
+---
+
+## Additional Tools from Design Documents
+
+### Suggested Additional Tools (Optional)
+
+#### A. `remember_revoke_access`
+Revoke access from a user
+
+**Parameters**:
+- `accessor_user_id`: User to revoke access from
+- `reason`: Reason for revocation
+
+---
+
+#### B. `remember_list_accessors`
+List who can access your memories
+
+**Parameters**:
+- `sort_by`: trust_level, last_accessed, granted_at
+
+**Returns**: Array of users with access and their trust levels
+
+---
+
+#### C. `remember_reset_block`
+Reset a memory block after trust violations
+
+**Parameters**:
+- `accessor_user_id`: User to unblock
+- `memory_id`: Memory to unblock
+- `reason`: Reason for reset
+
+---
+
+#### D. `remember_get_access_logs`
+View access attempts to your memories
+
+**Parameters**:
+- `accessor_user_id`: Optional filter
+- `memory_id`: Optional filter
+- `blocked_only`: Boolean - only show blocked attempts
+
+**Returns**: Array of access attempt logs
+
+---
+
+#### E. `remember_suggest_templates`
+Explicitly request template suggestions
+
+**Parameters**:
+- `content`: Content to analyze
+- `limit`: Max suggestions
+
+**Returns**: Array of template suggestions
+
+---
+
+#### F. `remember_copy_template`
+Copy a default template to customize
+
+**Parameters**:
+- `source_template_id`: Default template to copy
+- `customizations`: Optional modifications
+
+**Returns**: New user template ID
+
+---
+
+#### G. `remember_validate_memory`
+Validate memory against template
+
+**Parameters**:
+- `template_id`: Template to validate against
+- `content`: Memory content to validate
+
+**Returns**: Validation result with errors
+
+---
+
+## Recommended Final Tool Set
+
+### MVP (Phase 1): 12 Core Tools
+- 6 memory operations
+- 4 relationship operations
+- 2 preference management
+
+### Phase 2: +5 Permission Tools
+- remember_grant_access
+- remember_revoke_access
+- remember_list_accessors
+- remember_reset_block
+- remember_get_access_logs
+
+### Phase 3: +7 Template Tools
+- remember_create_template
+- remember_list_templates
+- remember_get_template
+- remember_update_template
+- remember_delete_template
+- remember_copy_template
+- remember_validate_memory
+
+**Total**: 24 tools (12 MVP + 5 permissions + 7 templates)
+
+---
+
+## Tool Count Summary
+
+| Phase | Tools | Total |
+|-------|-------|-------|
+| Phase 1 (MVP) | 12 | 12 |
+| Phase 2 (Permissions) | +5 | 17 |
+| Phase 3 (Templates) | +7 | 24 |
+
+---
+
+**Status**: Final Specification  
+**MVP Tools**: 12  
+**Complete Tool Set**: 24  
+**All tools support natural conversation interface**