sepehr/Keep
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Keep/docs/project-overview.md
sepehr 640fcb26f7 fix: improve note interactions and markdown LaTeX support 
## Bug Fixes

### Note Card Actions
- Fix broken size change functionality (missing state declaration)
- Implement React 19 useOptimistic for instant UI feedback
- Add startTransition for non-blocking updates
- Ensure smooth animations without page refresh
- All note actions now work: pin, archive, color, size, checklist

### Markdown LaTeX Rendering
- Add remark-math and rehype-katex plugins
- Support inline equations with dollar sign syntax
- Support block equations with double dollar sign syntax
- Import KaTeX CSS for proper styling
- Equations now render correctly instead of showing raw LaTeX

## Technical Details

- Replace undefined currentNote references with optimistic state
- Add optimistic updates before server actions for instant feedback
- Use router.refresh() in transitions for smart cache invalidation
- Install remark-math, rehype-katex, and katex packages

## Testing

- Build passes successfully with no TypeScript errors
- Dev server hot-reloads changes correctly
2026-01-09 22:13:49 +01:00

8.6 KiB
Raw Permalink Blame History

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)

# 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

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:

Existing Documentation:

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

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