@prmichaelsen/remember-mcp 2.0.0 → 2.0.4

package/AGENT.md

@@ -1,7 +1,7 @@
 # Agent Context Protocol (ACP)
 
 **Also Known As**: The Agent Directory Pattern  
-**Version**: 1.0.2
+**Version**: 1.0.3
 **Created**: 2026-02-11  
 **Status**: Production Pattern  
 
@@ -555,10 +555,14 @@ The Agent Pattern represents a **paradigm shift** in how we approach AI-assisted
 
 ### Initialize Prompt
 
+**Trigger**: `AGENT.md: Initialize`
+
 Use this prompt when starting work on an ACP-structured project:
 
 ```markdown
-Read ALL files in @agent. We are going to understand this project then work on a generic task.
+First, check for ACP updates by running ./agent/scripts/check-for-updates.sh (if it exists). If updates are available, report what changed and ask if I want to update.
+
+Then read ALL files in @agent. We are going to understand this project then work on a generic task.
 
 Then read KEY src files per your understanding.
 
@@ -566,6 +570,7 @@ Then read @agent again, update stale @agent/tasks, stale documentation, and upda
 ```
 
 **Purpose**:
+- Checks for updates to ACP methodology and documentation
 - Loads complete project context from agent directory
 - Reviews source code to understand current implementation
 - Updates documentation to reflect current state
@@ -573,6 +578,8 @@ Then read @agent again, update stale @agent/tasks, stale documentation, and upda
 
 ### Proceed Prompt
 
+**Trigger**: `AGENT.md: Proceed`
+
 Use this prompt to continue with the next task:
 
 ```markdown
@@ -584,6 +591,57 @@ Let's proceed with implementing the current or next task. Remember to update @ag
 - Reminds agent to maintain progress tracking
 - Keeps workflow focused and documented
 
+### Update Prompt
+
+**Trigger**: `AGENT.md: Update`
+
+Updates all ACP files to the latest version:
+
+```markdown
+Run ./agent/scripts/update.sh to update all ACP files (AGENT.md, templates, and scripts) to the latest version.
+```
+
+**Purpose**:
+- Updates AGENT.md methodology
+- Updates all template files
+- Updates utility scripts
+- Keeps ACP current with latest improvements
+
+### Check for Updates Prompt
+
+**Trigger**: `AGENT.md: Check for updates`
+
+Checks if updates are available without applying them:
+
+```markdown
+Run ./agent/scripts/check-for-updates.sh to see if ACP updates are available.
+```
+
+**Purpose**:
+- Non-destructive check for updates
+- Shows what changed via CHANGELOG
+- Informs user of available improvements
+
+### Uninstall Prompt
+
+**Trigger**: `AGENT.md: Uninstall`
+
+Removes all ACP files from the project:
+
+```markdown
+Run ./agent/scripts/uninstall.sh to remove all ACP files (agent/ directory and AGENT.md) from this project.
+```
+
+**Note**: This script requires user confirmation. If the user confirms they want to uninstall, run:
+```bash
+./agent/scripts/uninstall.sh -y
+```
+
+**Purpose**:
+- Complete removal of ACP
+- Clean project state
+- Reversible via git
+
 ---
 
 ## Instructions for Future Agents
@@ -724,6 +782,17 @@ Let's proceed with implementing the current or next task. Remember to update @ag
    - Update percentages
    - Add recent work notes
 
+7. **NEVER handle secrets or sensitive data**
+   - ❌ **DO NOT** read `.env` files, `.env.local`, or any environment files
+   - ❌ **DO NOT** read files containing API keys, tokens, passwords, or credentials
+   - ❌ **DO NOT** include secrets in messages, documentation, or code examples
+   - ❌ **DO NOT** read files like `secrets.yaml`, `credentials.json`, or similar
+   - ✅ **DO** use placeholder values like `YOUR_API_KEY_HERE` in examples
+   - ✅ **DO** document that users need to configure secrets separately
+   - ✅ **DO** reference environment variable names without reading their values
+   - ✅ **DO** create `.env.example` files with placeholder values only
+   - **Rationale**: Secrets must never be exposed in chat logs, documentation, or version control. Agents should treat all credential files as off-limits to prevent accidental exposure.
+
 ---
 
 ## Best Practices
@@ -804,6 +873,28 @@ Let's proceed with implementing the current or next task. Remember to update @ag
 
 ---
 
+## Keeping ACP Updated
+
+This repository is actively maintained with improvements to the ACP methodology and documentation. To keep your project's AGENT.md current:
+
+```bash
+# Run from your project root (if you have the update script installed)
+./agent/scripts/update.sh
+
+# Or download and run directly
+curl -fsSL https://raw.githubusercontent.com/prmichaelsen/agent-context-protocol/mainlin./agent/scripts/update.sh | bash
+```
+
+The update script will:
+1. Create a backup of your current AGENT.md
+2. Download the latest version
+3. Show you the changes
+4. Ask for confirmation before applying
+
+See [CHANGELOG.md](https://github.com/prmichaelsen/agent-context-protocol/blob/main/CHANGELOG.md) for version history and changes.
+
+---
+
 ## Conclusion
 
 The Agent Directory Pattern transforms software development from an implicit, memory-dependent process into an explicit, documented system that enables AI agents to work effectively on complex projects.
@@ -833,6 +924,129 @@ The Agent Directory Pattern transforms software development from an implicit, me
 
 ---
 
+## What NOT to Do
+
+### ❌ CRITICAL: Don't Create Summary Documents
+
+**NEVER create these files under ANY circumstances:**
+- `TASK_SUMMARY.md`
+- `PROJECT_SUMMARY.md`
+- `MILESTONE_SUMMARY.md`
+- `PROGRESS_SUMMARY.md`
+- Any file with `SUMMARY` in the name
+
+**Why**: All summary information belongs in [`progress.yaml`](agent/progress.yaml). Creating separate summary documents:
+- Duplicates information
+- Creates inconsistency
+- Requires maintaining multiple files
+- Defeats the purpose of structured progress tracking
+
+**Instead**: Update [`progress.yaml`](agent/progress.yaml):
+```yaml
+recent_work:
+  - date: 2026-02-13
+    description: Summary of work completed
+    items:
+      - ✅ Completed task 1
+      - ✅ Completed task 2
+```
+
+### ❌ CRITICAL: Don't Create Variant Task Documents
+
+**NEVER create these files under ANY circumstances:**
+- `task-1-simplified.md`
+- `task-1-revised.md`
+- `task-1-v2.md`
+- `task-1-updated.md`
+- `task-1-alternative.md`
+
+**Why**: Task documents are living documents that should be updated in place. Creating variants:
+- Creates confusion about which is current
+- Scatters information across multiple files
+- Makes progress tracking impossible
+- Violates single source of truth principle
+
+**Instead**: Modify the existing task document directly:
+```markdown
+# Task 1: Setup Project
+
+**Status**: In Progress (Updated 2026-02-13)
+
+## Steps
+1. Create directory ✅ (Completed)
+2. Install dependencies ✅ (Completed)
+3. Configure build (Updated: Changed from webpack to esbuild)
+
+## Notes
+- Originally planned to use webpack
+- Switched to esbuild for better performance
+- Updated configuration accordingly
+```
+
+### ✅ Correct Approach
+
+1. **For summaries**: Update [`progress.yaml`](agent/progress.yaml)
+2. **For task changes**: Modify existing task documents in place
+3. **For major changes**: Update the task and note the changes in [`progress.yaml`](agent/progress.yaml)
+4. **For new work**: Create new task documents with new numbers
+
+---
+
+## IMPORTANT: CHANGELOG.md Guidelines
+
+### ❌ CRITICAL: Keep CHANGELOG.md Pure
+
+**CHANGELOG.md must ONLY contain:**
+- Version numbers and dates
+- Added features
+- Changed functionality
+- Removed features
+- Fixed bugs
+
+**NEVER include in CHANGELOG.md:**
+- ❌ Future enhancements or roadmap
+- ❌ How-to instructions or usage guides
+- ❌ Installation instructions
+- ❌ Configuration examples
+- ❌ Detailed documentation
+
+**Why**: CHANGELOG.md is a historical record of what changed, not a documentation file. Mixing concerns makes it harder to:
+- Understand version history
+- Track actual changes
+- Maintain the changelog
+- Find relevant information
+
+**Correct CHANGELOG.md format:**
+```markdown
+## [1.0.4] - 2026-02-13
+
+### Added
+- New feature X
+- New feature Y
+
+### Changed
+- Modified behavior of Z
+
+### Removed
+- Deprecated feature A
+```
+
+**Wrong CHANGELOG.md format:**
+```markdown
+## [1.0.4] - 2026-02-13
+
+### Added
+- New feature X
+
+### How to Use Feature X
+[Installation instructions...]  # ❌ WRONG - belongs in README
+
+### Future Enhancements
+- Plan to add Y  # ❌ WRONG - belongs in design docs or issues
+```
+
+---
+
 **The Agent Pattern is not just documentation—it's a development methodology that makes complex software projects tractable for AI agents.**
 
 ---

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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).
 
+## [2.0.2] - 2026-02-14
+
+### ✨ Added
+
+- **Comprehensive Error Handling**: Applied centralized error handler to all 12 MCP tools
+  - All tools now use `handleToolError()` from `src/utils/error-handler.ts`
+  - Consistent error logging with full context across all operations
+  - Stack traces included in all error messages
+  - Tool-specific context (userId, IDs, operation details) in every error
+
+### 🔧 Improved
+
+- **Error Diagnostics**: Production debugging significantly enhanced
+  - Memory tools: create, update, delete, search, find-similar, query
+  - Relationship tools: create, update, delete, search
+  - Preference tools: set, get
+  - All errors now include operation context and user information
+
+---
+
+## [2.0.1] - 2026-02-14
+
+### 🐛 Fixed
+
+- **Error Reporting**: Improved error logging in `remember_update_memory` for better debugging
+  - Added detailed error context including userId, memoryId, and provided fields
+  - Added stack traces to error messages for easier troubleshooting
+  - Added specific error handling for fetch and update operations
+  - Errors now include collection name and operation details
+  - Helps diagnose production issues in Cloud Run logs
+
+### 📝 Changes
+
+- Error messages now include full context for debugging
+- Separate try-catch blocks for fetch and update operations
+- Better structured logging with error details
+
+---
+
+## [2.0.0] - 2026-02-12
+
+### 🚨 BREAKING CHANGES
+
+- **`createServer` is now async**: The factory function now returns `Promise<Server>` instead of `Server`
+- Same breaking change as v1.0.0, but bumped to v2.0.0 for clarity
+
+---
+
 ## [1.0.2] - 2026-02-12
 
 ### 🐛 Fixed

package/README.md

@@ -2,15 +2,76 @@
 
 Multi-tenant memory system MCP server with vector search, relationships, and trust-based access control.
 
+## Value Proposition
+
+**remember-mcp** gives AI assistants a persistent, searchable memory system that enables them to:
+
+- **Remember Everything**: Store and recall information across conversations
+- **Find Connections**: Discover relationships between memories using semantic search
+- **Learn Over Time**: Build a knowledge graph that grows with each interaction
+- **Personalize Responses**: Access user preferences and context for tailored interactions
+- **Search Intelligently**: Use hybrid semantic + keyword search to find relevant memories
+- **Organize Knowledge**: Categorize memories with 45+ content types (people, events, recipes, notes, etc.)
+
+### Why Use remember-mcp?
+
+**For AI Assistants**:
+- Persistent memory across sessions (no more forgetting previous conversations)
+- Semantic search finds relevant context even with different wording
+- Relationship tracking reveals connections between memories
+- RAG-optimized queries for natural language understanding
+- Trust-based access control for privacy-sensitive information
+
+**For Developers**:
+- Multi-tenant architecture with per-user isolation
+- Production-ready with comprehensive error handling
+- Compatible with Claude Desktop, mcp-auth, and custom integrations
+- Vector embeddings via OpenAI for semantic understanding
+- Firestore for metadata and preferences
+
+**For Users**:
+- Their AI assistant remembers important information
+- Discovers connections between different topics
+- Provides personalized responses based on preferences
+- Respects privacy with trust-based access control
+
+## Use Cases
+
+### Personal Assistant
+- "Remember that Sarah's birthday is June 15th"
+- "What did I learn about React hooks last week?"
+- "Find all my camping trip memories"
+- "What recipes have I saved that use chicken?"
+
+### Knowledge Management
+- Store research notes with semantic search
+- Track relationships between concepts
+- Build a personal knowledge graph
+- Query with natural language
+
+### Project Tracking
+- Remember project decisions and context
+- Link related tasks and ideas
+- Search across all project memories
+- Track what inspired each decision
+
+### Relationship Management
+- Remember details about people you meet
+- Track connections between contacts
+- Recall conversation context
+- Find related interactions
+
 ## Features
 
-- 10 MCP tools for memory and relationship management
-- Multi-tenant with per-user isolation
-- Vector search with Weaviate (semantic + keyword hybrid search)
-- Knowledge graph with relationship tracking
-- RAG queries with natural language
-- 45 content types (notes, events, people, recipes, etc.)
-- Trust-based access control (planned for M7)
+- **12 MCP Tools**: Complete CRUD for memories, relationships, and preferences
+- **Multi-Tenant**: Per-user isolation with secure data boundaries
+- **Vector Search**: Semantic + keyword hybrid search with Weaviate
+- **Knowledge Graph**: N-way relationships with bidirectional tracking
+- **RAG Queries**: Natural language queries with context-aware responses
+- **45 Content Types**: Notes, events, people, recipes, goals, tasks, and more
+- **User Preferences**: Customizable search, location, privacy, and display settings
+- **Trust-Based Access**: Fine-grained access control (0-1 trust levels)
+- **Production-Ready**: Comprehensive error handling and logging
 
 ## Quick Start
 

package/agent/design/design.template.md

@@ -0,0 +1,136 @@
+# {Feature/Pattern Name}
+
+**Concept**: [One-line description of what this design addresses]
+**Created**: YYYY-MM-DD
+**Status**: Proposal | Design Specification | Implemented
+
+---
+
+## Overview
+
+[High-level description of what this design document covers and why it exists. Provide context about the problem space and the importance of this design decision.]
+
+**Example**: "This document describes the authentication flow for multi-tenant access, enabling secure per-user data isolation across the system."
+
+---
+
+## Problem Statement
+
+[Clearly articulate the problem this design solves. Include:]
+- What challenge or limitation exists?
+- Why is this a problem worth solving?
+- What are the consequences of not solving it?
+
+**Example**: "Without proper multi-tenant isolation, users could potentially access each other's data, creating security vulnerabilities and privacy concerns."
+
+---
+
+## Solution
+
+[Describe the proposed solution at a conceptual level. Include:]
+- High-level approach
+- Key components involved
+- How the solution addresses the problem
+- Alternative approaches considered (and why they were rejected)
+
+**Example**: "Implement row-level security using user_id as a tenant identifier, enforced at both the database and application layers."
+
+---
+
+## Implementation
+
+[Provide technical details needed to implement this design. Include:]
+- Architecture diagrams (as ASCII art or references)
+- Data structures and schemas
+- API interfaces
+- Code examples (use placeholder names)
+- Configuration requirements
+- Dependencies
+
+**Example**:
+```typescript
+interface TenantContext {
+  userId: string;
+  permissions: string[];
+}
+
+class DataService {
+  constructor(private context: TenantContext) {}
+  
+  async getData(id: string): Promise<Data> {
+    // Implementation with tenant filtering
+  }
+}
+```
+
+---
+
+## Benefits
+
+[List the advantages of this approach:]
+- Benefit 1: [Description]
+- Benefit 2: [Description]
+- Benefit 3: [Description]
+
+**Example**:
+- **Security**: Complete data isolation between tenants
+- **Scalability**: Horizontal scaling without data mixing concerns
+- **Compliance**: Meets data privacy regulations (GDPR, etc.)
+
+---
+
+## Trade-offs
+
+[Honestly assess the downsides and limitations:]
+- Trade-off 1: [Description and mitigation strategy]
+- Trade-off 2: [Description and mitigation strategy]
+- Trade-off 3: [Description and mitigation strategy]
+
+**Example**:
+- **Performance**: Additional filtering adds query overhead (mitigated by proper indexing)
+- **Complexity**: More complex queries and testing requirements
+- **Migration**: Existing data requires backfill with tenant identifiers
+
+---
+
+## Dependencies
+
+[List any dependencies this design has:]
+- External services or APIs
+- Other design documents
+- Infrastructure requirements
+- Third-party libraries
+
+---
+
+## Testing Strategy
+
+[Describe how to verify this design works correctly:]
+- Unit test requirements
+- Integration test scenarios
+- Security test cases
+- Performance benchmarks
+
+---
+
+## Migration Path
+
+[If this changes existing functionality, describe the migration strategy:]
+1. Step 1: [Description]
+2. Step 2: [Description]
+3. Step 3: [Description]
+
+---
+
+## Future Considerations
+
+[Note any future enhancements or related work:]
+- Future enhancement 1
+- Future enhancement 2
+- Related design documents to create
+
+---
+
+**Status**: [Current implementation status]
+**Recommendation**: [What should be done next - implement, review, revise, etc.]
+**Related Documents**: [Links to related design docs, milestones, or tasks]