🧠 Memos - Intelligent Chat History Management

A modern, AI-powered chat history storage and management system with semantic search capabilities. Store, organize, and intelligently retrieve conversational data across multiple sessions and users.

🚀 Project Overview

Memos is a full-stack application designed to revolutionize how we store and retrieve conversational data. By combining traditional keyword search with AI-powered semantic similarity, it provides an intelligent system for managing chat histories, conversations, and memory-based interactions.

✨ Key Features

🔍 Hybrid Search: Combines keyword matching (30%) with semantic similarity (70%) for intelligent retrieval
🤖 AI-Powered: Leverages Google Gemini AI for generating high-quality text embeddings
👥 Multi-User Support: Handle multiple users and conversation sessions
📊 Vector Database: Supabase PostgreSQL with pgvector for efficient semantic search
🔗 MCP Integration: Model Context Protocol server for AI tool integration
⚡ Real-time: Modern React frontend with real-time updates
🐳 Docker Ready: Full containerized development environment with hot reload
🔄 Hot Reload: All services support hot reload for rapid development

🛠️ Tech Stack

Backend

Runtime: Node.js 18+
Framework: Express.js with TypeScript
Database: Supabase PostgreSQL with pgvector extension
AI Service: Google Gemini AI (gemini-embedding-001)
Vector Dimensions: 1536-dimensional embeddings

Frontend

Framework: Next.js 15+ with React 19
UI Library: Radix UI + Tailwind CSS
State Management: Redux Toolkit
Styling: Tailwind CSS with custom animations
Icons: Lucide React + React Icons

MCP (Model Context Protocol)

SDK: @modelcontextprotocol/sdk
Runtime: TypeScript with tsx
Validation: Zod for schema validation

Development Tools

Package Manager: pnpm
Build Tool: TypeScript compiler
Development: Hot-reload with ts-node-dev
Containerization: Docker & Docker Compose

📦 Installation and Setup

Prerequisites

Node.js 18 or higher
pnpm (recommended) or npm
Docker and Docker Compose
Google Gemini AI API key

Quick Start

🐳 Docker Setup (Recommended)

Clone the repository
```
git clone <repository-url>
cd memos
```

Configure environment variables

# Create backend environment file
echo "GEMINI_API_KEY=your_gemini_api_key_here" > apps/backend/.env

Start all services with Docker

# Start all services (database, backend, frontend, MCP server)
./start-dev.sh

# Or manually
docker-compose up -d

Access the application
- Frontend: http://localhost:3000
- Backend API: http://localhost:3001
- MCP Server: http://localhost:3002
- Database: localhost:5432
Verify services are running
```
./verify-ports.sh
```

Stop services

./stop-dev.sh
# Or manually
docker-compose down

🔧 Manual Setup (Alternative)

Clone the repository
```
git clone <repository-url>
cd memos
```
Install dependencies
```
pnpm install
```

Set up the database

# Start PostgreSQL with pgvector
docker-compose up -d postgres

# Or use the setup script
./setup-db.sh

Configure environment variables

# Create backend environment file
cp apps/backend/.env.example apps/backend/.env

# Edit the file with your configuration
nano apps/backend/.env

Required environment variables:

PORT=3000
DB_HOST=localhost
DB_PORT=5432
DB_USER=memos_user
DB_PASSWORD=memos_password
DB_NAME=memos
GEMINI_API_KEY=your_gemini_api_key_here

Start the development servers

# Terminal 1: Start backend
cd apps/backend
pnpm dev

# Terminal 2: Start frontend
cd apps/frontend
pnpm dev

# Terminal 3: Start MCP server (optional)
cd apps/mcp
pnpm dev

Access the application
- Frontend: http://localhost:3000
- Backend API: http://localhost:3001/api
- Health Check: http://localhost:3001/health

📁 Folder Structure

memos/
├── apps/
│   ├── backend/                 # Node.js REST API
│   │   ├── src/
│   │   │   ├── controllers/     # Business logic
│   │   │   ├── routes/          # API endpoints
│   │   │   ├── services/        # External services (AI)
│   │   │   ├── config/          # Database & AI configuration
│   │   │   ├── types/           # TypeScript definitions
│   │   │   ├── utils/           # Utility functions
│   │   │   ├── app.ts           # Express app setup
│   │   │   └── server.ts        # Entry point
│   │   ├── database.sql         # Database schema
│   │   └── package.json
│   │
│   ├── frontend/                # Next.js React application
│   │   ├── app/                 # Next.js 15 app directory
│   │   │   ├── memories/        # Memory management pages
│   │   │   ├── settings/        # Settings page
│   │   │   └── layout.tsx       # Root layout
│   │   ├── components/          # Reusable UI components
│   │   │   ├── ui/              # Radix UI components
│   │   │   ├── shared/          # Shared components
│   │   │   └── dashboard/       # Dashboard components
│   │   ├── hooks/               # Custom React hooks
│   │   ├── store/               # Redux store
│   │   ├── lib/                 # Utility libraries
│   │   └── styles/              # Global styles
│   │
│   └── mcp/                     # Model Context Protocol server
│       ├── src/
│       │   └── index.ts         # MCP server entry point
│       └── package.json
│
├── packages/
│   └── shared/                  # Shared utilities & types
│
├── docker-compose.yml           # All services setup
├── setup-db.sh                 # Database setup script
├── start-dev.sh                # Start development environment
├── stop-dev.sh                 # Stop development environment
├── verify-ports.sh             # Port verification script
├── pnpm-workspace.yaml         # Workspace configuration
└── README.md                   # This file

🏃‍♂️ How to Run and Test

Development Mode

🐳 Docker Development (Recommended)

# Start all services with hot reload
./start-dev.sh

# View logs
docker-compose logs -f

# Stop services
./stop-dev.sh

# Rebuild specific service
docker-compose build backend
docker-compose up -d backend

🔧 Manual Development

# Start all services in development mode
pnpm dev

# Or start individual services
cd apps/backend && pnpm dev    # Backend on port 3000
cd apps/frontend && pnpm dev   # Frontend on port 3000
cd apps/mcp && pnpm dev        # MCP server

Production Build

# Build all applications
pnpm build

# Or build individual apps
cd apps/backend && pnpm build
cd apps/frontend && pnpm build
cd apps/mcp && pnpm build

Testing the API

# Health check
curl http://localhost:3001/health

# Create a new memo
curl -X POST http://localhost:3001/memo \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_123",
    "userId": "user_456",
    "content": "This is a test memo about machine learning",
    "authorRole": "user",
    "tags": ["test", "ml", "ai"]
  }'

# Search memos
curl -X POST http://localhost:3001/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning",
    "limit": 10,
    "sessionId": "session_123"
  }'

# Get all memos
curl http://localhost:3001/memos

# Get specific memo
curl http://localhost:3001/memo/1

Database Management

# Start database
docker-compose up -d postgres

# Stop database
docker-compose down

# View database logs
docker-compose logs -f postgres

# Access database directly
docker-compose exec postgres psql -U memos_user -d memos

📖 API Reference

Base URL

http://localhost:3001

Authentication

Currently, the API does not require authentication. This may change in future versions.

Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Create Memo

POST /memo

Request Body:

{
  "sessionId": "string",
  "userId": "string",
  "content": "string",
  "authorRole": "user" | "agent" | "system",
  "summary": "string (optional)",
  "importance": 1.0,
  "tags": ["string"]
}

Response:

{
  "id": 1,
  "sessionId": "session_123",
  "userId": "user_456",
  "content": "This is a test memo",
  "authorRole": "user",
  "importance": 1.0,
  "accessCount": 0,
  "tags": ["test"],
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Get Memos

GET /memos?sessionId=session_123&userId=user_456&limit=10&offset=0

Query Parameters:

sessionId (optional): Filter by session
userId (optional): Filter by user
limit (optional): Number of results (default: 50)
offset (optional): Pagination offset (default: 0)

Get Memo by ID

GET /memo/:id

Response: Same as Create Memo response

Update Memo

PATCH /memo/:id

Request Body: Same as Create Memo (all fields optional)

Delete Memo

DELETE /memo/:id

Response:

{
  "message": "Memo deleted successfully"
}

Search Memos

POST /search

Request Body:

{
  "query": "string",
  "limit": 10,
  "sessionId": "string (optional)",
  "userId": "string (optional)"
}

Response:

{
  "results": [
    {
      "id": 1,
      "content": "...",
      "similarity": 0.95,
      "relevanceScore": 0.87
    }
  ],
  "total": 1,
  "processingTime": "0.123s"
}

🤝 Contributing

We welcome contributions to the Memos project! Please follow these guidelines:

Development Guidelines

Code Style
- Use TypeScript with strict type checking
- Follow ESLint and Prettier configurations
- Write descriptive commit messages using conventional commits
- Maintain consistent code formatting
Before Contributing
- Check existing issues and pull requests
- Fork the repository and create a feature branch
- Ensure all tests pass and linting is clean
- Update documentation for any API changes
Pull Request Process
- Create descriptive pull request titles
- Include detailed description of changes
- Reference related issues
- Ensure CI/CD pipelines pass
- Request review from maintainers

Setting Up Development Environment

# Fork and clone the repository
git clone https://github.com/yourusername/memos.git
cd memos

# Install dependencies
pnpm install

# Create a new feature branch
git checkout -b feature/your-feature-name

# Make your changes and commit
git add .
git commit -m "feat: add new feature"

# Push to your fork
git push origin feature/your-feature-name

Code Quality Standards

Testing: Write unit tests for new features
Documentation: Update README and inline documentation
Error Handling: Implement proper error handling and logging
Performance: Consider performance implications of changes
Security: Follow security best practices

Reporting Issues

When reporting bugs or requesting features:

Check existing issues first
Use the appropriate issue template
Provide detailed reproduction steps
Include system information and logs
Tag issues appropriately

Architecture Decisions

Follow the established layered architecture
Keep components focused and single-purpose
Maintain clear separation between frontend and backend
Use TypeScript interfaces for data contracts
Follow REST API conventions

📄 License

This project is licensed under the ISC License. See the LICENSE file for details.

🌐 Service URLs

Frontend: http://localhost:3000
Backend API: http://localhost:3001
MCP Server: http://localhost:3002
Database: localhost:5432

🔍 Port Verification

Run the verification script to check all services:

./verify-ports.sh

🙏 Acknowledgments

Google Gemini AI for embedding generation
PostgreSQL and pgvector for vector database capabilities
The React and Next.js communities for excellent tooling
All contributors and maintainers

For more detailed information, see the PROJECT_OVERVIEW.md file.

Happy coding! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.cursor/rules		.cursor/rules
apps		apps
supabase		supabase
.gitignore		.gitignore
API_KEY_SYSTEM.md		API_KEY_SYSTEM.md
CLOUD_RUN_DEPLOYMENT.md		CLOUD_RUN_DEPLOYMENT.md
ENVIRONMENT_CONFIG.md		ENVIRONMENT_CONFIG.md
ENVIRONMENT_CONFIG_DETAILED.md		ENVIRONMENT_CONFIG_DETAILED.md
PORT_CONFIGURATION.md		PORT_CONFIGURATION.md
PROJECT_OVERVIEW.md		PROJECT_OVERVIEW.md
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
start-dev.sh		start-dev.sh
stop-dev.sh		stop-dev.sh

memosapp/memos

Folders and files

Latest commit

History

Repository files navigation

🧠 Memos - Intelligent Chat History Management

🚀 Project Overview

✨ Key Features

🛠️ Tech Stack

Backend

Frontend

MCP (Model Context Protocol)

Development Tools

📦 Installation and Setup

Prerequisites

Quick Start

🐳 Docker Setup (Recommended)

🔧 Manual Setup (Alternative)

📁 Folder Structure

🏃‍♂️ How to Run and Test

Development Mode

🐳 Docker Development (Recommended)

🔧 Manual Development

Production Build

Testing the API

Database Management

📖 API Reference

Base URL

Authentication

Endpoints

Health Check

Create Memo

Get Memos

Get Memo by ID

Update Memo

Delete Memo

Search Memos

🤝 Contributing

Development Guidelines

Setting Up Development Environment

Code Quality Standards

Reporting Issues

Architecture Decisions

📄 License

🌐 Service URLs

🔍 Port Verification

🙏 Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages