Persistent-Memory-Academic-Advisor

🎓 Persistent-Memory AI Academic Advisor

---

🌐 Live Demo & Deployment

Deploy this project with 1 click to get a free, permanent HTTPS live link:

1. Click the Deploy to Render button above (or create a Web Service on Render.com and select your GitHub repository Persistent-Memory-Academic-Advisor).
2. Render automatically detects render.yaml and builds the Docker container.
3. Once deployed, your live URL will be active with:
   • Interactive Web Playground: https://<your-service-name>.onrender.com/
   • Swagger API Documentation: https://<your-service-name>.onrender.com/docs
   • Live Health Probe: https://<your-service-name>.onrender.com/health

---

📌 Executive Overview

The Persistent-Memory AI Academic Advisor provides an intelligent, dual-tier memory engine built to bridge long-term student state across advising sessions. Conventional conversational AI systems suffer from stateless amnesia across context windows; this system guarantees persistent, cross-session continuity through:

1. Deterministic Structured Memory: Relational tracking of sequential conversations, customizable student preference models, and academic milestone progressions stored with strict relational integrity via SQLAlchemy 2.x and SQLite.
2. Contextual Semantic Memory: Sub-second approximate nearest neighbor (ANN) vector retrieval powered by ChromaDB and Hugging Face's sentence-transformers (all-MiniLM-L6-v2) embeddings.
3. Dual Protocol Interoperability: Exposes unified memory capabilities across standard FastAPI REST endpoints and an official Model Context Protocol (MCP) server for seamless native integration into LLM agents (Claude Desktop, Cursor, LangChain, etc.).

---

🏛️ System Architecture

                            ┌────────────────────────┐
                            │     Student Client     │
                            └───────────┬────────────┘
                                        │
                                        ▼
                            ┌────────────────────────┐
                            │ Academic Advisor Agent │
                            └───────────┬────────────┘
                                        │
                    ┌───────────────────┴───────────────────┐
                    │                                       │
                    ▼                                       ▼
         ┌─────────────────────┐                 ┌─────────────────────┐
         │  FastAPI REST API   │                 │   Stdio MCP Server  │
         │  (/invoke/*, /tools)│                 │   (JSON-RPC 2.0)    │
         └──────────┬──────────┘                 └──────────┬──────────┘
                    │                                       │
                    └───────────────────┬───────────────────┘
                                        ▼
                            ┌────────────────────────┐
                            │     MemoryService      │
                            │ (Business Logic Layer) │
                            └───────────┬────────────┘
                                        │
                    ┌───────────────────┴───────────────────┐
                    │                                       │
                    ▼                                       ▼
         ┌─────────────────────┐                 ┌─────────────────────┐
         │  Memory Repository  │                 │  Embedding Service  │
         │  (SQLAlchemy 2.x)   │                 │ (all-MiniLM-L6-v2)  │
         └──────────┬──────────┘                 └──────────┬──────────┘
                    │                                       │
                    ▼                                       ▼
         ┌─────────────────────┐                 ┌─────────────────────┐
         │    SQLite Store     │                 │      ChromaDB       │
         │ (Relational Tables) │                 │ (Vector Collection) │
         └─────────────────────┘                 └─────────────────────┘

Flow Breakdown

• Write Path: Incoming memory payloads are validated via Pydantic v2 schemas, persisted into the relational store (SQLite), transformed into high-dimensional dense vector embeddings, and indexed into the ChromaDB vector collection.
• Read Path (Structured): Direct relational queries filtered by user_id retrieve historical turns (chronological order), key-value student preferences, and milestone tracking.
• Retrieve Path (Semantic): User-isolated similarity queries against ChromaDB match queries to past academic disclosures, returning content, distance scores, and rich metadata.

---

✨ Key Features

• 🧠 Dual-Tier Persistence: Synchronous relational storage paired with an indexed vector space for exact records and fuzzy semantic lookups.
• 🔌 Model Context Protocol (MCP) Compliant: Genuine MCP standard tools exposed for direct consumption by modern AI harnesses and agents.
• 🛡️ Strict User Isolation: Multi-tenant memory boundaries guarantee student data cannot leak across semantic or relational queries.
• ⚡ High-Throughput REST API: Fully typed FastAPI interface with automatic OpenAPI/Swagger documentation (/docs).
• 📦 Container-First Architecture: One-command Docker Compose deployment mounting persistent storage volumes (/app/data).
• ✅ Comprehensive Quality Suite: Unit, integration, and contract tests with strict linting via Ruff.

---

📁 Repository Structure

.
├── app/
│   ├── api/                    # FastAPI route controllers
│   │   ├── health.py           # Health check endpoint (/health)
│   │   ├── memory.py           # Memory write, read, and retrieve routes
│   │   └── tools.py            # Tool discovery endpoint (/tools)
│   ├── db/                     # Database engine & ORM models
│   │   ├── database.py         # SQLAlchemy engine & session factory
│   │   └── models.py           # SQLite tables (conversations, preferences, milestones)
│   ├── mcp/                    # Model Context Protocol implementation
│   │   └── server.py           # MCP server exposing stdio tools
│   ├── repositories/           # Data access layer
│   │   └── memory_repository.py# Relational CRUD operations
│   ├── schemas/                # Pydantic v2 data validation schemas
│   │   └── memory_schemas.py   # Request/response and domain contracts
│   ├── services/               # Core business services
│   │   ├── embedding_service.py# SentenceTransformers embedding generation
│   │   ├── memory_service.py   # Unified memory orchestrator
│   │   ├── retrieval_service.py# ChromaDB ANN query runner
│   │   └── vector_store.py     # Persistent ChromaDB client manager
│   ├── config.py               # Environment configuration via Pydantic Settings
│   └── main.py                 # FastAPI application root
├── docs/                       # Architectural specs & design diagrams
│   ├── architecture.md         # Detailed architectural documentation
│   ├── evaluation_report.md    # Requirement verification matrix
│   ├── memory_architecture.mmd # Mermaid diagram source
│   └── memory_architecture.png # Rendered architecture diagram
├── tests/                      # Automated test suite
│   ├── conftest.py             # Pytest fixtures and test environments
│   ├── contract/               # Schema and API contract validation
│   ├── integration/            # Multi-component workflow tests
│   └── unit/                   # Isolated unit tests
├── docker-compose.yml          # Container orchestration with volume mounts
├── Dockerfile                  # Multi-stage production container build
├── pyproject.toml              # Build configurations & package dependencies
├── submission.json             # Evaluation payload benchmark
└── .env.example                # Template environment variables

---

🚀 Quick Start Guide

Option 1: One-Command Docker Setup (Recommended)

Ensure Docker and Docker Compose are installed on your machine:

# Clone the repository
git clone https://github.com/Manirider/Persistent-Memory-Academic-Advisor.git
cd Persistent-Memory-Academic-Advisor

# Build and start container
docker compose up --build

Verify service readiness:

curl http://localhost:8000/health
# Output: {"status":"ok"}

Access interactive Swagger documentation at http://localhost:8000/docs.

---

Option 2: Local Python Development

1. Prerequisites

• Python 3.11+
• Git

2. Environment Setup

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Linux/macOS:
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

3. Configuration

Copy the configuration template:

cp .env.example .env

Default parameters in .env:

DB_PATH=./data/advisor_memory.db
CHROMA_DB_PATH=./data/chroma_db
EMBEDDING_MODEL_NAME=all-MiniLM-L6-v2
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

4. Run the API Server

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

---

📡 API Reference & Contracts

1. Health Probe

• Endpoint: GET /health
• Response: 200 OK

{
  "status": "ok"
}

---

2. Tool Discovery

• Endpoint: GET /tools
• Response: 200 OK

{
  "tools": [
    {"name": "memory_write", "description": "Write a memory of type conversation, preference, or milestone"},
    {"name": "memory_read", "description": "Read memories for a user with query type and params"},
    {"name": "memory_retrieve_by_context", "description": "Retrieve semantically relevant memories by context query"}
  ]
}

---

3. Write Memory

• Endpoint: POST /invoke/memory_write
• Response: 201 Created

Writing a Conversation Turn:

curl -X POST http://localhost:8000/invoke/memory_write \
  -H "Content-Type: application/json" \
  -d '{
    "memory_type": "conversation",
    "data": {
      "user_id": "student_402",
      "turn_id": 1,
      "role": "user",
      "content": "I am interested in taking advanced bioinformatics and data structures next semester."
    }
  }'

{
  "status": "success",
  "memory_id": "conv:student_402:1"
}

Writing Preferences or Milestones:

// Preferences Payload
{
  "memory_type": "preference",
  "data": {
    "user_id": "student_402",
    "preferences": { "max_credits": 16, "preferred_time": "morning", "target_major": "Bioinformatics" }
  }
}

// Milestone Payload
{
  "memory_type": "milestone",
  "data": {
    "user_id": "student_402",
    "milestone_id": "CS101_REQ",
    "description": "Completed Introduction to Programming",
    "status": "completed"
  }
}

---

4. Read Structured Memories

• Endpoint: POST /invoke/memory_read
• Response: 200 OK

curl -X POST http://localhost:8000/invoke/memory_read \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "student_402",
    "query_type": "last_n_turns",
    "params": {"n": 5}
  }'

{
  "results": [
    {
      "user_id": "student_402",
      "turn_id": 1,
      "role": "user",
      "content": "I am interested in taking advanced bioinformatics and data structures next semester.",
      "timestamp": "2026-10-11T08:15:30.000000Z"
    }
  ]
}

Supported query_type options: last_n_turns, preferences, milestones.

---

5. Semantic Context Retrieval

• Endpoint: POST /invoke/memory_retrieve_by_context
• Response: 200 OK

curl -X POST http://localhost:8000/invoke/memory_retrieve_by_context \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "student_402",
    "query_text": "What computational fields did the student want to explore?",
    "top_k": 3
  }'

{
  "results": [
    {
      "id": "conv:student_402:1",
      "content": "user: I am interested in taking advanced bioinformatics and data structures next semester.",
      "score": 0.312,
      "metadata": {
        "user_id": "student_402",
        "memory_type": "conversation",
        "role": "user",
        "turn_id": 1,
        "timestamp": "2026-10-11T08:15:30.000000Z"
      }
    }
  ]
}

---

🤖 Model Context Protocol (MCP) Integration

The server provides a standard stdio JSON-RPC transport interface compliant with Anthropic's Model Context Protocol.

Running Standalone MCP Server

python -m app.mcp.server

Client Integration (e.g., Claude Desktop / Cursor)

Add the server entry to your MCP configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "academic-advisor-memory": {
      "command": "python",
      "args": ["-m", "app.mcp.server"],
      "env": {
        "DB_PATH": "/path/to/data/advisor_memory.db",
        "CHROMA_DB_PATH": "/path/to/data/chroma_db",
        "EMBEDDING_MODEL_NAME": "all-MiniLM-L6-v2"
      }
    }
  }
}

---

🧪 Testing & Code Quality

Running the Test Suite

Execute tests with pytest:

pytest tests/ -v

Linting and Formatting

Check code style and enforce formatting rules:

# Check code style with Ruff
ruff check .

# Automatically apply format fixes
ruff format .

---

🔒 Security & Production Roadmap

• Relational Isolation: User ID scoping on all SQL queries preventing horizontal privilege escalation.
• Metadata-Filtering in Vector Space: Hard constraints on vector queries (where={"user_id": user_id}).
• Authentication & Authorization: Integrate OAuth2 / JWT bearer tokens for role-based academic advisor sessions.
• Distributed Vector Scalability: Seamless plug-in replacement for Qdrant or Milvus for horizontal clustering.
• PostgreSQL + pgvector Integration: Support for single-engine multi-model relational + vector storage.

---

📄 License

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

---