Support Agent - Agentic AI Memory System

A comprehensive exploration and implementation of agentic AI memory components, featuring dual-memory architecture with short-term and long-term memory systems.

🧠 Architecture Overview

This project implements a dual-memory architecture inspired by cognitive science principles:

• Short-Term Memory (STM): Redis-backed conversation context with configurable TTL
• Long-Term Memory (LTM): PostgreSQL-backed persistent facts with confidence scoring
• Episodic Memory: Session tracking and comprehensive event logging
• Semantic Memory: Vector-based knowledge retrieval using embeddings
• Procedural Memory: YAML-based workflow definitions with memory integration

🏗️ System Components

Memory Systems

• STM Store (memory/stm_redis.py): Manages conversation context with automatic cleanup
• LTM Store (memory/ltm_store.py): Persistent fact storage with upsert operations
• LTM Extractor (ltm/extractor.py): Rule-based information extraction from user input

Knowledge Management

• RAG System (rag/): Vector-based retrieval using sentence transformers
• Embeddings (rag/embeddings.py): Text vectorization with configurable models

Workflow Engine

• Procedure Engine (procedures/engine.py): YAML-based workflow execution
• Flow Runner (procedures/runner.py): Flow matching and execution
• Tool Registry: Extensible tool system for external integrations

API Layer

• FastAPI Server (api/main.py): RESTful endpoints for chat and memory operations
• Session Management: Database session handling with dependency injection

🚀 Features

• Intelligent Information Extraction: Automatic detection of names, emails, preferences
• Confidence Scoring: Fact reliability assessment with source tracking
• Memory Consolidation: Seamless integration between STM and LTM
• Procedural Memory: Declarative workflow definitions with memory persistence
• Comprehensive Logging: Full audit trail of agent decisions and tool usage
• Vector Search: Semantic retrieval of relevant knowledge chunks

📋 Prerequisites

• Python 3.13+
• PostgreSQL with pgvector extension
• Redis server
• LM Studio or compatible LLM server

🛠️ Installation

1. Clone the repository

   git clone <your-repo-url>
   cd support-agent

2. Install dependencies

   uv sync

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your actual configuration

4. Initialize database

   python -m src.support_agent.db.init_schema

5. Start the application

   uvicorn src.support_agent.api.main:app --reload

⚙️ Configuration

Environment Variables

Variable	Description	Default
POSTGRES_HOST	PostgreSQL host	localhost
POSTGRES_PORT	PostgreSQL port	5432
POSTGRES_USER	Database username	agent
POSTGRES_PASSWORD	Database password	agentpw
POSTGRES_DB	Database name	agent_store
REDIS_URL	Redis connection URL	redis://localhost:6379
LLM_BASE_URL	LLM server URL	http://localhost:1234/v1
LLM_MODEL	LLM model name	Required
STM_MAX_TURNS	Max STM turns	12
STM_TTL_SECONDS	STM TTL in seconds	86400

Database Schema

The system creates several tables:

• long_term_facts: User facts with confidence scoring
• episodes: Conversation session tracking
• episode_events: Detailed event logging
• kb_chunks: Knowledge base with vector embeddings

📖 Usage Examples

Chat API

curl -X POST "http://localhost:8000/api/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "session_id": "session456",
    "message": "My name is John and I prefer email notifications"
  }'

Memory Confirmation

curl -X POST "http://localhost:8000/api/v1/ltm/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "key": "preference",
    "value": "email"
  }'

Workflow Flows

The system includes example workflows:

• Password Reset (flows/password_reset.yaml): Email-based password recovery
• Refund Processing (flows/refund_flow.yaml): Order verification and ticket creation

🔧 Development

Project Structure

support-agent/
├── src/support_agent/
│   ├── api/           # FastAPI endpoints
│   ├── db/            # Database models and session management
│   ├── llm/           # Language model integration
│   ├── ltm/           # Long-term memory extraction
│   ├── memory/        # Memory stores (STM/LTM)
│   ├── procedures/    # Workflow engine and flows
│   ├── rag/           # Retrieval-augmented generation
│   └── tools/         # External service integrations
├── docs/              # Documentation
├── scripts/           # Utility scripts
└── flows/             # Workflow definitions

Adding New Tools

1. Create tool function in tools/ directory
2. Register in procedures/runner.py
3. Use in YAML flow definitions

Adding New Memory Patterns

1. Add regex patterns to ltm/extractor.py
2. Update confidence scores and auto-save rules
3. Test with sample inputs

🧪 Testing

# Run tests (when implemented)
pytest

# Check code quality
ruff check .
black --check .

📚 API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🙏 Research Foundation

This project explores concepts from cognitive science memory models, agentic AI architectures, and retrieval-augmented generation systems.

---

Note: This is a research/exploration project. For production use, implement proper security measures, error handling, and monitoring.