@prmichaelsen/remember-mcp 2.0.0 → 2.0.2

package/agent/design/requirements.template.md

@@ -0,0 +1,387 @@
+# Project Requirements
+
+**Project Name**: [Your Project Name]
+**Created**: YYYY-MM-DD
+**Status**: Draft | Active | Implemented
+
+---
+
+## Overview
+
+[Provide a high-level description of what this project is and what it aims to accomplish. This should be a clear, concise summary that anyone can understand.]
+
+**Example**: "A multi-tenant memory system that enables AI agents to store, retrieve, and manage contextual information across sessions with vector search capabilities and relationship tracking."
+
+---
+
+## Problem Statement
+
+[Describe the problem this project solves. What pain points or needs does it address?]
+
+**Example**: "AI agents currently have no persistent memory between sessions, leading to loss of context and requiring users to repeatedly provide the same information."
+
+---
+
+## Goals and Objectives
+
+[List the primary goals this project aims to achieve. Be specific and measurable where possible.]
+
+### Primary Goals
+1. Goal 1: [Description]
+2. Goal 2: [Description]
+3. Goal 3: [Description]
+
+### Secondary Goals
+1. Goal 1: [Description]
+2. Goal 2: [Description]
+
+**Example**:
+
+### Primary Goals
+1. Enable persistent memory storage across agent sessions
+2. Provide fast vector-based semantic search
+3. Support multi-tenant isolation for data security
+
+### Secondary Goals
+1. Implement relationship tracking between memories
+2. Add trust-based access control
+3. Support template-based memory creation
+
+---
+
+## Functional Requirements
+
+[List what the system must do. These are the features and capabilities.]
+
+### Core Features
+1. **Feature 1**: [Description of what it does]
+2. **Feature 2**: [Description of what it does]
+3. **Feature 3**: [Description of what it does]
+
+### Additional Features
+1. **Feature 1**: [Description]
+2. **Feature 2**: [Description]
+
+**Example**:
+
+### Core Features
+1. **Memory Storage**: Store structured memories with metadata (title, content, tags, timestamps)
+2. **Vector Search**: Find semantically similar memories using vector embeddings
+3. **Multi-Tenancy**: Isolate user data with per-user access control
+
+### Additional Features
+1. **Relationship Graph**: Track connections between related memories
+2. **Template System**: Pre-defined memory structures for common use cases
+3. **Trust Levels**: Control memory visibility based on trust scores
+
+---
+
+## Non-Functional Requirements
+
+[Describe quality attributes and constraints.]
+
+### Performance
+- Requirement 1: [Specific metric]
+- Requirement 2: [Specific metric]
+
+### Security
+- Requirement 1: [Security requirement]
+- Requirement 2: [Security requirement]
+
+### Scalability
+- Requirement 1: [Scalability requirement]
+- Requirement 2: [Scalability requirement]
+
+### Reliability
+- Requirement 1: [Reliability requirement]
+- Requirement 2: [Reliability requirement]
+
+**Example**:
+
+### Performance
+- Search queries return results in < 200ms for 95th percentile
+- Support 1000+ concurrent users
+
+### Security
+- Complete data isolation between tenants
+- All API endpoints require authentication
+- Sensitive data encrypted at rest
+
+### Scalability
+- Horizontal scaling for increased load
+- Support millions of memories per tenant
+
+### Reliability
+- 99.9% uptime SLA
+- Automatic backups every 24 hours
+- Graceful degradation under load
+
+---
+
+## Technical Requirements
+
+[Specify technical constraints and requirements.]
+
+### Technology Stack
+- **Language**: [Programming language and version]
+- **Framework**: [Framework and version]
+- **Database**: [Database technology]
+- **Infrastructure**: [Hosting/deployment platform]
+
+### Dependencies
+- Dependency 1: [Purpose]
+- Dependency 2: [Purpose]
+- Dependency 3: [Purpose]
+
+### Integrations
+- Integration 1: [What it integrates with and why]
+- Integration 2: [What it integrates with and why]
+
+**Example**:
+
+### Technology Stack
+- **Language**: TypeScript 5.x
+- **Runtime**: Node.js 20+
+- **Protocol**: Model Context Protocol (MCP)
+- **Vector DB**: Weaviate
+- **Document DB**: Firestore
+- **Authentication**: Firebase Auth
+
+### Dependencies
+- @modelcontextprotocol/sdk: MCP protocol implementation
+- weaviate-client: Vector database client
+- firebase-admin: Firestore and auth
+
+### Integrations
+- OpenAI API: Generate vector embeddings
+- Firebase Auth: User authentication and authorization
+
+---
+
+## User Stories
+
+[Describe functionality from the user's perspective.]
+
+### As a [User Type]
+1. I want to [action] so that [benefit]
+2. I want to [action] so that [benefit]
+3. I want to [action] so that [benefit]
+
+**Example**:
+
+### As an AI Agent
+1. I want to store memories about user preferences so that I can personalize responses
+2. I want to search for relevant memories so that I can provide contextual answers
+3. I want to create relationships between memories so that I can understand connections
+
+### As a User
+1. I want my data isolated from other users so that my privacy is protected
+2. I want to control which memories are shared so that I maintain control over my data
+3. I want to export my memories so that I can back them up
+
+---
+
+## Constraints
+
+[List any limitations or constraints on the project.]
+
+### Technical Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+### Business Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+### Resource Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+**Example**:
+
+### Technical Constraints
+- Must use existing Firebase infrastructure
+- Vector embeddings limited to OpenAI models
+- MCP protocol requires stdio or SSE transport
+
+### Business Constraints
+- Must launch MVP within 3 months
+- Free tier must support 1000 memories per user
+- Must comply with GDPR and data privacy regulations
+
+### Resource Constraints
+- Single developer for initial implementation
+- Limited budget for cloud infrastructure
+- No dedicated QA team
+
+---
+
+## Success Criteria
+
+[Define what success looks like. How will you know the project is complete and successful?]
+
+### MVP Success Criteria
+- [ ] Criterion 1: [Measurable condition]
+- [ ] Criterion 2: [Measurable condition]
+- [ ] Criterion 3: [Measurable condition]
+
+### Full Release Success Criteria
+- [ ] Criterion 1: [Measurable condition]
+- [ ] Criterion 2: [Measurable condition]
+- [ ] Criterion 3: [Measurable condition]
+
+**Example**:
+
+### MVP Success Criteria
+- [ ] Users can create, read, update, and delete memories
+- [ ] Vector search returns relevant results
+- [ ] Multi-tenant isolation verified through security testing
+- [ ] Basic documentation complete
+
+### Full Release Success Criteria
+- [ ] All core and additional features implemented
+- [ ] Performance meets specified metrics
+- [ ] Security audit passed
+- [ ] 100 active users with positive feedback
+- [ ] Comprehensive documentation and examples
+
+---
+
+## Out of Scope
+
+[Explicitly list what is NOT included in this project to manage expectations.]
+
+1. Feature/capability 1: [Why it's out of scope]
+2. Feature/capability 2: [Why it's out of scope]
+3. Feature/capability 3: [Why it's out of scope]
+
+**Example**:
+
+1. **Mobile app**: Focus is on MCP server, not end-user applications
+2. **Real-time collaboration**: Single-user focus for MVP
+3. **Advanced analytics**: Basic usage stats only, no complex analytics
+4. **Custom embedding models**: OpenAI only for MVP
+5. **On-premise deployment**: Cloud-only for initial release
+
+---
+
+## Assumptions
+
+[List assumptions being made about the project.]
+
+1. Assumption 1: [Description]
+2. Assumption 2: [Description]
+3. Assumption 3: [Description]
+
+**Example**:
+
+1. Users have stable internet connectivity
+2. OpenAI API will remain available and affordable
+3. Firebase infrastructure will scale to meet demand
+4. MCP protocol will remain stable (no breaking changes)
+5. Users understand basic AI agent concepts
+
+---
+
+## Risks
+
+[Identify potential risks and mitigation strategies.]
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+| [Risk 2] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+| [Risk 3] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+
+**Example**:
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| OpenAI API cost escalation | High | Medium | Implement caching, batch processing, consider alternative providers |
+| Security vulnerability | High | Low | Regular security audits, follow best practices, bug bounty program |
+| Performance degradation at scale | Medium | Medium | Load testing, performance monitoring, optimization plan |
+| MCP protocol changes | Medium | Low | Stay updated with MCP community, version pinning |
+
+---
+
+## Timeline
+
+[Provide a high-level timeline for the project.]
+
+### Phase 1: [Phase Name] (Duration)
+- Milestone 1
+- Milestone 2
+
+### Phase 2: [Phase Name] (Duration)
+- Milestone 3
+- Milestone 4
+
+### Phase 3: [Phase Name] (Duration)
+- Milestone 5
+- Milestone 6
+
+**Example**:
+
+### Phase 1: Foundation (Weeks 1-2)
+- Project setup and infrastructure
+- Basic MCP server implementation
+- Database connections
+
+### Phase 2: Core Features (Weeks 3-6)
+- Memory CRUD operations
+- Vector search implementation
+- Multi-tenant isolation
+
+### Phase 3: Advanced Features (Weeks 7-10)
+- Relationship tracking
+- Template system
+- Trust-based access control
+
+### Phase 4: Polish & Launch (Weeks 11-12)
+- Testing and bug fixes
+- Documentation
+- Deployment and monitoring
+
+---
+
+## Stakeholders
+
+[Identify who is involved in or affected by this project.]
+
+| Role | Name/Team | Responsibilities |
+|------|-----------|------------------|
+| [Role 1] | [Name] | [What they do] |
+| [Role 2] | [Name] | [What they do] |
+| [Role 3] | [Name] | [What they do] |
+
+**Example**:
+
+| Role | Name/Team | Responsibilities |
+|------|-----------|------------------|
+| Product Owner | [Name] | Define requirements, prioritize features |
+| Lead Developer | [Name] | Architecture, implementation, code review |
+| DevOps | [Name] | Infrastructure, deployment, monitoring |
+| Users | AI Agent Developers | Provide feedback, report issues |
+
+---
+
+## References
+
+[Link to related documents, research, or resources.]
+
+- [Document/Resource 1](URL): Description
+- [Document/Resource 2](URL): Description
+- [Document/Resource 3](URL): Description
+
+**Example**:
+
+- [Model Context Protocol Specification](https://modelcontextprotocol.io): MCP protocol documentation
+- [Weaviate Documentation](https://weaviate.io/developers/weaviate): Vector database docs
+- [Firebase Documentation](https://firebase.google.com/docs): Firebase platform docs
+- [Similar Project Analysis](URL): Research on existing solutions
+
+---
+
+**Status**: [Current status of requirements]
+**Last Updated**: [YYYY-MM-DD]
+**Next Review**: [YYYY-MM-DD]

package/agent/milestones/milestone-1-{title}.template.md

@@ -0,0 +1,206 @@
+# Milestone {N}: {Descriptive Name}
+
+**Goal**: [One-line objective that clearly states what this milestone achieves]
+**Duration**: [Estimated time: e.g., "1-2 weeks", "3-5 days"]
+**Dependencies**: [List prerequisite milestones or external dependencies, or "None"]
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Overview
+
+[Provide a comprehensive description of what this milestone accomplishes and why it's important to the project. Explain how it fits into the overall project roadmap.]
+
+**Example**: "This milestone establishes the foundational infrastructure for the project, including build system, database connections, and basic server setup. It creates the scaffolding that all future features will build upon."
+
+---
+
+## Deliverables
+
+[List concrete, measurable outputs this milestone will produce. Be specific about what will exist when this milestone is complete.]
+
+### 1. [Deliverable Category 1]
+- Specific item 1
+- Specific item 2
+- Specific item 3
+
+### 2. [Deliverable Category 2]
+- Specific item 1
+- Specific item 2
+
+### 3. [Deliverable Category 3]
+- Specific item 1
+- Specific item 2
+
+**Example**:
+
+### 1. Project Structure
+- New `project-name/` directory with organized subdirectories
+- package.json with all metadata and scripts
+- TypeScript configuration (tsconfig.json)
+- Build system using esbuild
+- Directory structure: src/, tests/, agent/
+
+### 2. Core Dependencies
+- @modelcontextprotocol/sdk installed and configured
+- Database client libraries installed
+- Development tools (TypeScript, testing framework)
+
+---
+
+## Success Criteria
+
+[Define objective, verifiable criteria that indicate this milestone is complete. Each criterion should be testable.]
+
+- [ ] Criterion 1: [Specific, measurable condition]
+- [ ] Criterion 2: [Specific, measurable condition]
+- [ ] Criterion 3: [Specific, measurable condition]
+- [ ] Criterion 4: [Specific, measurable condition]
+- [ ] Criterion 5: [Specific, measurable condition]
+
+**Example**:
+- [ ] Project builds successfully (`npm run build` completes without errors)
+- [ ] TypeScript compiles without errors (`npm run typecheck` passes)
+- [ ] All dependencies install correctly (`npm install` succeeds)
+- [ ] Basic server starts and responds to health check
+- [ ] All tests pass (`npm test` succeeds)
+
+---
+
+## Key Files to Create
+
+[List the specific files and directories that will be created during this milestone. Use a tree structure for clarity.]
+
+```
+project-root/
+├── file1.ext
+├── file2.ext
+├── directory1/
+│   ├── file3.ext
+│   └── file4.ext
+└── directory2/
+    ├── subdirectory/
+    │   └── file5.ext
+    └── file6.ext
+```
+
+**Example**:
+```
+my-project/
+├── package.json
+├── tsconfig.json
+├── esbuild.build.js
+├── .gitignore
+├── .env.example
+├── README.md
+├── src/
+│   ├── index.ts
+│   ├── server.ts
+│   ├── types/
+│   │   └── index.ts
+│   └── utils/
+│       └── logger.ts
+└── tests/
+    └── setup.test.ts
+```
+
+---
+
+## Tasks
+
+[List the tasks that comprise this milestone. Reference task documents if they exist.]
+
+1. [Task 1: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+2. [Task 2: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+3. [Task 3: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+4. [Task 4: task-N-{name}.md](../tasks/task-N-{name}.md) - [Brief description]
+
+**Example**:
+1. [Task 1: Initialize Project Structure](../tasks/task-1-initialize-project-structure.md) - Set up directories and config files
+2. [Task 2: Install Dependencies](../tasks/task-2-install-dependencies.md) - Install and configure npm packages
+3. [Task 3: Create Basic Server](../tasks/task-3-create-basic-server.md) - Implement minimal MCP server
+
+---
+
+## Environment Variables
+
+[If this milestone requires environment configuration, document it here:]
+
+```env
+# Category 1
+VAR_NAME_1=example_value
+VAR_NAME_2=example_value
+
+# Category 2
+VAR_NAME_3=example_value
+VAR_NAME_4=example_value
+```
+
+**Example**:
+```env
+# Database Configuration
+DATABASE_URL=postgresql://localhost:5432/mydb
+DATABASE_POOL_SIZE=10
+
+# API Configuration
+API_KEY=your_api_key_here
+API_URL=https://api.example.com
+
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+```
+
+---
+
+## Testing Requirements
+
+[Describe what testing should be in place by the end of this milestone:]
+
+- [ ] Test category 1: [Description]
+- [ ] Test category 2: [Description]
+- [ ] Test category 3: [Description]
+
+**Example**:
+- [ ] Unit tests for core utilities
+- [ ] Integration test for database connection
+- [ ] Server initialization test
+- [ ] Environment variable loading test
+
+---
+
+## Documentation Requirements
+
+[List documentation that should be created or updated:]
+
+- [ ] Document 1: [Description]
+- [ ] Document 2: [Description]
+- [ ] Document 3: [Description]
+
+**Example**:
+- [ ] README.md with project overview and quick start
+- [ ] API documentation for core interfaces
+- [ ] Development setup guide
+
+---
+
+## Risks and Mitigation
+
+[Identify potential risks and how to address them:]
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+| [Risk 2] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+
+**Example**:
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| Database connection issues | High | Medium | Provide clear error messages and connection testing utilities |
+| Dependency conflicts | Medium | Low | Pin dependency versions and test thoroughly |
+
+---
+
+**Next Milestone**: [Link to next milestone: milestone-{N+1}-{name}.md]
+**Blockers**: [List any current blockers, or "None"]
+**Notes**: [Any additional context or considerations]