🧠 MemoryAgent

An AI assistant that truly remembers you — powered by Qwen and a 3-layer persistent memory system.

---

🎯 What is MemoryAgent?

MemoryAgent is a conversational AI assistant that remembers users across sessions. Unlike standard chatbots that reset after every conversation, MemoryAgent builds a persistent memory profile for each user — getting smarter, more personalized, and more efficient with every interaction.

The result: After 5 sessions, the agent responds with zero questions asked. It already knows you.

---

🧠 3-Layer Memory Architecture

Layer	Description	Storage
📖 Episodic	Raw message/response history	episodes table
🔍 Semantic	Extracted behavioral patterns with confidence scores	semantic_patterns table
⚙️ Procedural	Active behavioral adaptations	procedural_adaptations table

Memory Decay

Patterns lose 10% confidence per day without reinforcement. Below 20%, they are automatically deleted — keeping only what matters.

---

✨ Key Features

• 💬 Persistent chat interface with session management
• 🧠 Thinking Animation — visualizes the 3 memory layers activating in real time
• 📊 Memory Dashboard — full visibility into what the agent has learned
• 🔍 Confidence Rings — SVG animations showing pattern reliability
• 📉 Decay Visualizer — shows how memories fade over time
• ⚡ Comparison Mode — Session 1 vs Session 5 side by side
• 🏷️ Memory Tags — every response shows which memories were used

---

🛠️ Tech Stack

Frontend

• Next.js 14 (App Router)
• TypeScript
• TailwindCSS
• Shadcn/ui
• Zustand (state management)
• ReactMarkdown + remark-gfm

Backend

• Node.js + Express
• TypeScript
• Qwen API (qwen-plus model via Dashscope)
• Supabase (PostgreSQL + pgvector)
• tsx (development server)
• Docker (deployment)

---

📁 Project Structure

Memory-Agents/
├── backend/                    # Express API server
│   ├── src/
│   │   ├── ai/                 # Qwen client + prompts
│   │   │   ├── qwen.client.ts
│   │   │   └── prompts/
│   │   │       ├── chat.prompt.ts
│   │   │       └── extraction.prompt.ts
│   │   ├── api/
│   │   │   ├── routes/
│   │   │   │   ├── chat.routes.ts
│   │   │   │   └── memory.routes.ts
│   │   │   ├── middlewares/
│   │   │   │   ├── error.middleware.ts
│   │   │   │   └── validation.middleware.ts
│   │   │   └── mocks/
│   │   │       └── mock.routes.ts
│   │   ├── db/
│   │   │   ├── client.ts
│   │   │   ├── migrations/
│   │   │   │   └── 001_initial.sql
│   │   │   └── repositories/
│   │   │       ├── episodes.repository.ts
│   │   │       ├── patterns.repository.ts
│   │   │       └── adaptations.repository.ts
│   │   ├── memory/
│   │   │   ├── episodic/
│   │   │   │   └── episodic.service.ts
│   │   │   ├── semantic/
│   │   │   │   └── semantic.service.ts
│   │   │   ├── procedural/
│   │   │   │   └── procedural.service.ts
│   │   │   └── decay/
│   │   │       └── decay.service.ts
│   │   ├── jobs/
│   │   │   └── decay.job.ts
│   │   └── index.ts
│   ├── Dockerfile
│   ├── .env.example
│   └── package.json
│
└── frontend/                   # Next.js 14 App
    └── src/
        ├── app/
        │   ├── page.tsx            # Chat interface
        │   ├── dashboard/
        │   │   └── page.tsx        # Memory Dashboard
        │   ├── layout.tsx
        │   ├── globals.css
        │   └── api/
        │       ├── chat/
        │       │   └── route.ts
        │       └── memory/
        │           ├── episodes/[userId]/route.ts
        │           ├── patterns/[userId]/route.ts
        │           └── adaptations/[userId]/route.ts
        ├── store/
        │   └── chatStore.ts        # Zustand store
        └── lib/
            ├── api.ts
            └── types.ts

---

🚀 Getting Started

Prerequisites

• Node.js v20+
• npm v9+
• A Supabase account
• A Qwen API key (Dashscope)

1. Clone the repository

git clone https://github.com/<your-username>/memory-agent.git
cd memory-agent

2. Set up the database

Go to your Supabase project → SQL Editor and run:

CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA extensions;

CREATE TABLE IF NOT EXISTS episodes (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT NOT NULL,
  session_id TEXT NOT NULL,
  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  message TEXT NOT NULL,
  response TEXT NOT NULL,
  metadata JSONB NOT NULL DEFAULT '{}'
);

CREATE TABLE IF NOT EXISTS semantic_patterns (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT NOT NULL,
  pattern_name TEXT NOT NULL,
  pattern_value TEXT NOT NULL,
  confidence FLOAT NOT NULL DEFAULT 1.0,
  activation_count INTEGER NOT NULL DEFAULT 1,
  last_updated TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  embedding extensions.vector(1536),
  UNIQUE(user_id, pattern_name)
);

CREATE TABLE IF NOT EXISTS procedural_adaptations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT NOT NULL,
  behavior_rule TEXT NOT NULL,
  rule_value TEXT NOT NULL,
  activation_count INTEGER NOT NULL DEFAULT 0,
  is_active BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE(user_id, behavior_rule)
);

ALTER TABLE episodes ENABLE ROW LEVEL SECURITY;
ALTER TABLE semantic_patterns ENABLE ROW LEVEL SECURITY;
ALTER TABLE procedural_adaptations ENABLE ROW LEVEL SECURITY;

3. Configure the backend

cd backend
cp .env.example .env

Edit .env:

QWEN_API_KEY=your_qwen_api_key
QWEN_API_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-plus
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_service_role_key
PORT=3001
NODE_ENV=development

4. Run the backend

cd backend
npm install
npm run dev

The backend will start on http://localhost:3001

5. Configure the frontend

cd frontend

Create .env.local:

NEXT_PUBLIC_API_URL=http://localhost:3001

6. Run the frontend

npm install --legacy-peer-deps
npm run dev

Open http://localhost:3000

---

🐳 Docker Deployment

cd backend
docker build -t memory-agent-backend .
docker run -p 3001:3001 --env-file .env memory-agent-backend

---

☁️ Cloud Deployment

Backend → Alibaba Cloud ECS

# On your ECS instance (Ubuntu 22.04)
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
npm install -g pm2

git clone https://github.com/<your-username>/memory-agent.git
cd memory-agent/backend
cp .env.example .env
# Fill in your credentials
npm install
npm run build
pm2 start dist/index.js --name "memory-agent"
pm2 save

Frontend → Vercel

cd frontend
npm install -g vercel
vercel deploy

Set environment variable in Vercel dashboard:

NEXT_PUBLIC_API_URL=http://<your-ecs-ip>:3001

---

📡 API Reference

POST /api/chat

Send a message to the agent.

Request:

{
  "user_id": "user-001",
  "message": "How should I manage my finances?",
  "session_id": "optional-session-id"
}

Response:

{
  "user_id": "user-001",
  "session_id": "uuid",
  "response": "Based on what I know about you..."
}

GET /api/memory/episodes/:userId

Returns all episodic memory for a user.

GET /api/memory/patterns/:userId

Returns semantic patterns with confidence scores.

GET /api/memory/adaptations/:userId

Returns active procedural adaptations.

---

🏆 Built for

Qwen Hackathon 2026 — Track 1: MemoryAgent

Build a memory-augmented AI agent using Qwen models.

---

👥 Team

Role	Responsibility
M1 — Backend	Memory engine, Qwen integration, database, API
M2 — Frontend	Chat interface, Memory Dashboard, demo video

---

📄 License

MIT License — see LICENSE file.