# Memento - Project Overview

## Project Summary

**Memento** is a Google Keep-inspired note-taking application with AI-powered features, semantic search, and MCP (Model Context Protocol) integration for workflow automation.

**Name:** Memento
**Version:** 0.2.0
**Type:** Multi-part Web Application + MCP Server
**Repository Type:** Monorepo/Multi-part
**License:** Open Source (to be published on GitHub)

---

## Quick Reference

| Aspect | Details |
|--------|---------|
| **Primary Language** | TypeScript (keep-notes), JavaScript (mcp-server) |
| **Architecture** | Full-stack JAMstack (Next.js) + Microservice API (Express) |
| **Database** | SQLite with Prisma ORM |
| **Authentication** | NextAuth.js v5 with email/password |
| **AI Integration** | Vercel AI SDK (OpenAI, Ollama) |
| **State Management** | React Context + Custom Hooks |
| **Testing** | Playwright (E2E) |
| **Deployment** | Docker (planned) |

---

## Tech Stack Summary

### keep-notes (Web Application)

**Frontend:**
- Next.js 16.1.1 (App Router)
- React 19.2.3
- TypeScript 5
- Tailwind CSS 4
- Radix UI (component library)
- Lucide React (icons)

**Backend (Integrated):**
- Next.js API Routes
- Prisma 5.22.0 (ORM)
- SQLite (better-sqlite3)

**Auth:**
- NextAuth.js 5.0.0-beta.30
- bcryptjs (password hashing)

**AI/LLM:**
- Vercel AI SDK 6.0.23
- OpenAI Provider
- Ollama Provider (local models)

**Features:**
- PWA (@ducanh2912/next-pwa)
- Markdown (react-markdown)
- Drag & Drop (@dnd-kit)
- Grid Layout (Muuri, react-grid-layout)
- Email (nodemailer)

### mcp-server (Backend API)

**Backend:**
- Express.js 4.22.1
- Node.js (ES modules)
- Prisma 5.22.0 (ORM)

**Protocol:**
- MCP SDK 1.0.4 (Model Context Protocol)
- Stdio transport
- Shared SQLite database

---

## Repository Structure

```
D:/dev_new_pc/Keep/
├── keep-notes/              # Next.js web application
│   ├── app/                 # Next.js App Router
│   │   ├── (auth)/         # Authentication routes
│   │   ├── (main)/         # Main application routes
│   │   ├── api/            # API endpoints
│   │   ├── actions/        # Server actions
│   │   ├── components/     # UI components
│   │   ├── context/        # React contexts
│   │   ├── hooks/          # Custom hooks
│   │   └── lib/            # Utilities
│   ├── components/         # Shared components
│   ├── prisma/             # Database schema & migrations
│   ├── tests/              # Playwright E2E tests
│   └── public/             # Static assets
│
├── mcp-server/             # MCP integration server
│   ├── index.js            # Main MCP server (stdio)
│   ├── index-sse.js        # SSE variant
│   └── prisma/             # Shared DB client
│
├── docs/                   # Generated documentation
├── _bmad/                  # BMAD framework artifacts
├── _bmad-output/           # BMAD workflow outputs
│   ├── planning-artifacts/  # PRD, epics, architecture
│   └── implementation-artifacts/  # Stories, sprint status
│
└── [Root files]
    ├── README.md
    ├── CHANGELOG.md
    ├── MCP-GUIDE.md
    └── Various technical docs
```

---

## Project Parts

### 1. keep-notes (Web App)
- **Path:** `D:/dev_new_pc/Keep/keep-notes`
- **Type:** Web Application (Next.js)
- **Purpose:** Main user interface for note-taking
- **Technology:** Next.js + React + TypeScript
- **Entry Point:** `app/layout.tsx`

### 2. mcp-server (Backend)
- **Path:** `D:/dev_new_pc/Keep/mcp-server`
- **Type:** Backend API (Express)
- **Purpose:** MCP protocol integration for N8N and AI assistants
- **Technology:** Express + MCP SDK + Prisma
- **Entry Point:** `index.js`

---

## Architecture Type

**Pattern:** Full-stack Monolith with Microservice Extension

**keep-notes:**
- JAMstack architecture with Next.js App Router
- Server-side rendering (SSR)
- API routes integrated
- Server Actions for mutations
- Client-side state with React Context

**mcp-server:**
- Separate microservice
- Protocol-based API (MCP)
- Shared database layer
- Standalone execution

---

## Integration Between Parts

**Database Sharing:**
- Both parts connect to the same SQLite database
- `keep-notes/prisma/dev.db` is the single source of truth
- MCP server reads/writes directly to this file

**Communication:**
- Web app uses REST/Next.js API routes
- MCP server exposes MCP protocol tools
- No direct HTTP calls between parts
- Communication is database-mediated

**Deployment:**
- Can be deployed together or separately
- Docker Compose can orchestrate both services
- Environment variables control configuration

---

## Key Features

### User Features
- ✅ Rich text notes with markdown support
- ✅ Checklist notes
- ✅ Color-coded notes
- ✅ Labeling/tagging system
- ✅ Pinning and archiving
- ✅ Image attachments
- ✅ Reminders with recurrence
- ✅ Drag-and-drop grid layout
- ✅ Semantic search (vector embeddings)
- ✅ AI-powered auto-tagging
- ✅ User authentication (email/password)
- ✅ User profile management
- ✅ Admin panel

### Technical Features
- ✅ PWA (Progressive Web App)
- ✅ Responsive design
- ✅ E2E testing (Playwright)
- ✅ MCP integration (N8N workflows)
- ✅ Multiple AI providers (OpenAI, Ollama)
- ✅ Email notifications
- ✅ Cron job support (reminders)

---

## Getting Started

### Prerequisites
- Node.js 20+
- npm or yarn
- SQLite3 (included via better-sqlite3)

### Installation (Current)
```bash
# Install dependencies
cd keep-notes
npm install

# Generate Prisma client
npm run db:generate

# Run development server
npm run dev

# Access app at http://localhost:3000
```

### MCP Server
```bash
cd mcp-server
npm install
npm start
```

---

## Development Workflow

**Current Status:**
- Active development on `bmad-features` branch
- Sprint status tracking implemented
- 6 stories completed
- PRD and Epics defined
- Implementation readiness reviewed

**Next Steps:**
1. Docker containerization
2. Complete documentation
3. Code review and cleanup
4. Monetization strategy
5. GitHub release preparation

---

## Documentation

**Generated Documentation:**
- [API Contracts - keep-notes](./api-contracts-keep-notes.md)
- [API Contracts - mcp-server](./api-contracts-mcp-server.md)
- [Data Models](./data-models.md)
- [Project Overview](./project-overview.md) (this file)

**Existing Documentation:**
- [README.md](../README.md) - Main project README
- [CHANGELOG.md](../CHANGELOG.md) - Version history
- [COMPLETED-FEATURES.md](../COMPLETED-FEATURES.md) - Feature list
- [MCP-GUIDE.md](../MCP-GUIDE.md) - MCP setup guide
- [MCP-SSE-ANALYSIS.md](../MCP-SSE-ANALYSIS.md) - SSE implementation notes
- [N8N-MCP-SETUP.md](../N8N-MCP-SETUP.md) - N8N integration guide

**Planning Artifacts:**
- `_bmad-output/planning-artifacts/prd.md` - Product Requirements Document
- `_bmad-output/planning-artifacts/epics.md` - Epic definitions
- `_bmad-output/implementation-artifacts/` - User stories and sprint tracking

---

## Testing

**E2E Tests:** Playwright
```bash
cd keep-notes
npm test          # Run all tests
npm run test:ui   # Run with UI
npm run test:headed  # Run in headed mode
```

**Test Results:** `keep-notes/test-results/`
**Playwright Report:** `keep-notes/playwright-report/`

---

## Configuration

**Environment Variables:** `.env` (root, keep-notes/, mcp-server/)

**Key Variables:**
- `DATABASE_URL` - SQLite database path
- `NEXTAUTH_SECRET` - Auth session secret
- `NEXTAUTH_URL` - Application URL
- Email configuration (SMTP)
- AI provider API keys (OpenAI, Ollama)

**See:** `.env.example` (if available) or ask for setup details

---

## Deployment

**Current:** Manual deployment
**Planned:** Docker Compose setup

**Target:** GitHub release with:
- Docker images for both services
- Docker Compose orchestration
- Environment configuration guide
- Deployment documentation

---

## Future Enhancements

**Requested Features:**
1. Complete Docker setup (docker-compose.yml)
2. Comprehensive installation documentation
3. Code review and test code cleanup
4. "Pay me a coffee" monitization
5. Business model analysis (open source monetization)
6. MCP feature restoration and enhancement

**Technical Debt:**
- Remove test/debug code before release
- Improve error handling
- Add comprehensive logging
- Implement rate limiting
- Add monitoring/observability

---

## License & Business Model

**License:** Open Source (to be determined - MIT/Apache/etc.)
**Monetization:** Under evaluation
**Status:** Preparing for GitHub public release

---

## Support

**Issues:** GitHub Issues (once published)
**Documentation:** See `/docs` folder
**Technical Guides:** Root-level markdown files