# Jarvis-Cognitive Desktop - Project Status

**Last Updated**: 2025-12-30 12:57 UTC

**Current Phase**: Production Ready + Multi-Profile System

**Project Location**: `/mnt/ssd/data/python-lab/Jarvis-Cognitive`

---

## Project Overview

Desktop application for AI-powered conversations with **multiple customizable profiles**. The system features a dynamic multi-profile architecture where each profile has isolated memory, RAG knowledge base, and personality. Combines Claude AI with intelligent memory management and per-profile RAG (Retrieval-Augmented Generation).

**Default Profiles**:
- **Marco Aurelio** (Marcus Aurelius) - Roman Emperor and Stoic philosopher
- **Warren Mentor** - Deep Value investment advisor (Buffett+Munger style)
- **Custom Profiles** - User-created profiles with custom personalities and knowledge bases

---

## Project Structure (Current)

```
jarvis-cognitive/
├── agents/                      # Runtime agent data
│   └── aurelio/
│       ├── logs/
│       └── memoria_chat.sqlite
├── config/                      # Configuration files
│   ├── config.yaml             # Main configuration
│   ├── config_*.yaml           # Config variants
│   └── jobs_office.json        # Scheduler jobs
├── core/                        # Core system modules
│   ├── cognitive_engine/       # LangChain agent engine (legacy)
│   ├── kernel.py               # Main kernel orchestrator
│   └── service_base.py         # Service base class
├── data/                        # Application data
│   └── agents/
│       └── aurelio/
│           ├── chroma_db/      # RAG vector store (18MB)
│           ├── doc_store/      # RAG document store (2.6MB)
│           └── user_profile.json
├── desktop/                     # PyQt6 desktop UI
│   └── ui/
│       ├── main_window.py      # Main window
│       ├── chat_widget.py      # Chat interface
│       ├── inference_worker.py # Async AI worker
│       └── greeting_worker.py  # Async greeting generator
├── docs/                        # Technical documentation
│   ├── MIGRAZIONE_CLAUDE.md
│   └── AGENT_PROFILES_ROADMAP_PROMPT.md
├── scripts/                     # Utility scripts
│   ├── indicizza_documenti.py  # PDF indexer for RAG
│   ├── indicizza_cartella.py   # Batch folder indexer
│   └── indicizza_txt.py        # Text file indexer
├── services/                    # Modular services
│   ├── cognitiveservice/       # AI conversation service
│   │   ├── cognitiveservice.py # Main implementation (Claude + Memory + RAG)
│   │   ├── chat_memory.py      # SQLite conversation storage
│   │   ├── user_profile.py     # Persistent user profile manager
│   │   ├── memory_summarizer.py # AI-powered conversation summarization
│   │   └── rag_retriever.py    # RAG semantic search module
│   ├── fileloggerservice/      # File-based logging
│   ├── filesystemwatcherservice/ # File system events (legacy)
│   └── schedulerservice/       # Background task scheduler (legacy)
├── tests/
│   ├── test_intelligent_memory.py  # Memory system tests
│   └── test_rag_integration.py     # RAG integration tests
├── main.py                      # Desktop application entry point
├── start_jarvis.sh             # Launch script
├── requirements.txt            # Python dependencies
├── README.md                   # User documentation
└── PROJECT_STATUS.md           # This file
```

---

## Implemented Features

### ✅ Multi-Profile System (Dynamic)
- **Status**: Complete (implemented 2025-12-30)
- **Implementation**: Full dynamic profile management system with 3 core features:
  1. **Dynamic Profile Loading**: Profiles loaded from config.yaml with automatic metadata inference from agent_prompt. Emergency fallback if config corrupted. Supports unlimited profiles with scroll UI for >3 profiles.
  2. **Profile Deletion**: Delete custom profiles from UI with system profile protection (aurelio, warren). Automatic backup before deletion. Removes config entry + data/agents/{profile_id}/ directory.
  3. **Per-Profile Embeddings Cache**: Embeddings cached per-profile (dict instead of singleton) for perfect isolation and support for future profile-specific models.
- **Files**:
  - `core/config_manager.py` (+244 lines: get_all_profiles, delete_profile, metadata inference)
  - `desktop/ui/profile_selector_dialog.py` (refactored +260 lines: dynamic loading, delete UI, refresh)
  - `services/ragservice/rag_document_manager.py` (+4 lines: per-profile cache)
  - `main.py` (+5 lines: cache registration per-profile)

### ✅ Profile Editor with RAG Document Manager
- **Status**: Complete (implemented 2025-12-29)
- **Implementation**: Integrated profile editor with 3 tabs: 1) Edit profile configuration, 2) Manage RAG documents (list, add, delete), 3) View profile statistics. Each profile manages its own documents in isolated directories.
- **Files**:
  - `desktop/ui/profile_editor_dialog.py` (268 lines)
  - `services/ragservice/rag_document_manager.py` (212 lines: business logic)

### ✅ Desktop Application (PyQt6)
- **Status**: Complete
- **Implementation**: Native PyQt6 GUI with profile selector at startup, chat interface, keyboard shortcuts (Ctrl+N new chat, Ctrl+E editor, Ctrl+Q quit)
- **Files**: `main.py`, `desktop/ui/main_window.py`, `desktop/ui/chat_widget.py`, `desktop/ui/profile_selector_dialog.py`

### ✅ Intelligent Memory System
- **Status**: Complete (implemented 2025-12-29)
- **Implementation**: Hybrid 3-tier memory architecture:
  1. **User Profile** (JSON) - Persistent key information (name, family, work, interests)
  2. **Recent Messages** (SQLite) - Last 50 messages for conversation context
  3. **Conversation Summaries** (SQLite) - AI-generated summaries every 30 messages
  - Background async maintenance extracts user info and creates summaries automatically
  - Logarithmic memory growth vs linear (6K tokens vs 15K for 150 messages)
- **Files**:
  - `services/cognitiveservice/user_profile.py`
  - `services/cognitiveservice/memory_summarizer.py`
  - `services/cognitiveservice/chat_memory.py`
  - `services/cognitiveservice/cognitiveservice.py`

### ✅ RAG (Retrieval-Augmented Generation)
- **Status**: Complete (integrated 2025-12-29)
- **Implementation**: Semantic search in Marcus Aurelius' Meditations using LangChain ParentDocumentRetriever with HuggingFace embeddings (local, no API calls). Automatic activation based on query keywords (virtù, meditazioni, logos, filosofia). Returns authentic citations from the indexed texts.
- **Database**: 18MB Chroma vector store + 2.6MB docstore (Meditations + Seneca's Letters indexed)
- **Files**:
  - `services/cognitiveservice/rag_retriever.py` (isolated RAG module)
  - `services/cognitiveservice/cognitiveservice.py` (integration)
  - `scripts/indicizza_documenti.py` (indexing tool)

### ✅ Claude Anthropic Integration
- **Status**: Complete (migrated from Google Gemini)
- **Implementation**: Direct Claude API client (anthropic SDK) without LangChain agents. Uses claude-haiku-4-5-20251001 for cost optimization ($1/$5 per million tokens). System prompt enhancement with user profile + conversation summaries + RAG context.
- **Files**: `services/cognitiveservice/cognitiveservice.py`

### ✅ Multi-Session Support
- **Status**: Complete
- **Implementation**: Session-based memory isolation via session_id. Each session maintains independent conversation history, summaries, and user profile updates.
- **Files**: `services/cognitiveservice/chat_memory.py`, `services/cognitiveservice/cognitiveservice.py`

### ✅ Document Indexing System
- **Status**: Complete
- **Implementation**: PDF/TXT indexer with ParentDocumentRetriever strategy (large parent chunks + small child embeddings for precision). Supports drag-and-drop in UI and CLI scripts.
- **Files**: `scripts/indicizza_documenti.py`, `scripts/indicizza_txt.py`, `scripts/indicizza_cartella.py`

### ✅ Desktop Launcher
- **Status**: Complete
- **Implementation**: XDG desktop entry with icon, keyboard shortcuts, no terminal window on launch
- **Files**: `install_desktop_shortcut.sh`, `~/.local/share/applications/jarvis-aurelio.desktop`

---

## Architecture

**Type**: Desktop Application (PyQt6 GUI + AI Backend)

**Target OS**: Linux (tested on Ubuntu/Debian, X11/Wayland)

**Python Version**: 3.12.3

**AI Models**:
- **LLM**: Claude Haiku 4.5 (claude-haiku-4-5-20251001) via Anthropic API
- **Embeddings**: sentence-transformers/all-MiniLM-L6-v2 (HuggingFace, local)

**Key Modules**:

| Module | Responsibility | Type |
|--------|---------------|------|
| **core.kernel** | Orchestrates service lifecycle, manages service registry | Core |
| **services.cognitiveservice** | Handles AI conversations, memory management, RAG integration | Service |
| **desktop.ui.main_window** | PyQt6 main window, UI layout, event handling | UI |
| **desktop.ui.chat_widget** | Chat interface, message rendering, input handling | UI |
| **desktop.ui.inference_worker** | Async AI inference in background thread | Worker |
| **services.cognitiveservice.rag_retriever** | Semantic search in indexed documents | RAG |
| **services.cognitiveservice.user_profile** | Persistent user information extraction and storage | Memory |
| **services.cognitiveservice.memory_summarizer** | AI-powered conversation summarization | Memory |
| **services.cognitiveservice.chat_memory** | SQLite-based conversation and summary storage | Memory |

---

## Dependencies

### Core Dependencies
- **anthropic** ^0.42.0 - Claude API client
- **PyQt6** ^6.8.1 - Desktop GUI framework
- **python-dotenv** - Environment variable management

### LangChain Ecosystem (RAG)
- **langchain** ^0.3.27 - Core framework
- **langchain-anthropic** ^0.3.22 - Claude LLM wrapper
- **langchain-chroma** ^1.1.0 - Chroma vector store
- **langchain-community** ^0.2.10 - Community integrations
- **langchain-text-splitters** ^0.3.11 - Document chunking
- **chromadb** ^0.5.23 - Vector database

### Embeddings & ML
- **sentence-transformers** ^2.7.0 - Local embeddings
- **torch** - PyTorch (sentence-transformers dependency)

### Utilities
- **pyyaml** - Configuration parsing
- **apscheduler** - Background task scheduling

**Full dependencies**: See `requirements.txt`

---

## Configuration

- **Format**: YAML
- **Location**: `config/config.yaml`
- **Environment Variables**: `data/.env`

**Key Settings**:

```yaml
# LLM Configuration
model_name: "claude-haiku-4-5-20251001"
temperature: 0.7
max_tokens: 4096

# Memory Configuration
memory_messages: 50          # Recent messages to keep in context
summary_threshold: 30        # Messages before auto-summarization

# RAG Configuration
vectorstore_path: "agents/aurelio/chroma_db"
docstore_path: "agents/aurelio/doc_store"
embedding_model: "sentence-transformers/all-MiniLM-L6-v2"

# Agent Personality
agent_prompt: |
  Sei Marco Aurelio, Imperatore Romano e filosofo stoico.
  Rispondi con saggezza, dignità imperiale e riferimenti alle tue Meditazioni.
```

**Environment Variables** (`data/.env`):
```bash
ANTHROPIC_API_KEY="sk-ant-api03-..."  # Required for Claude
TAVILY_API_KEY="tvly-..."             # Optional (web search, currently unused)
```

---

## Technical Decisions Log

| Aspect | Decision | Rationale | Implementation |
|--------|----------|-----------|----------------|
| **Profile Architecture** | Dynamic multi-profile with per-profile isolation | Scalable to unlimited profiles, complete data separation, no hardcoding | Profiles loaded from config.yaml with metadata inference |
| **Profile Loading** | Dynamic from config.yaml | New profiles appear automatically without code changes | ConfigManager.get_all_profiles() with 3-tier fallback (explicit → inference → defaults) |
| **Profile Deletion** | UI-based with system protection | User-friendly management, prevents accidental deletion of core profiles | Protected list ['aurelio', 'warren'], automatic backup, confirmation dialog |
| **Embeddings Cache** | Per-profile dict | Perfect isolation, supports future profile-specific models | _EMBEDDINGS_CACHE = {} keyed by profile_name |
| **RAG Isolation** | Separate directories per profile | Complete knowledge base separation, no cross-contamination | data/agents/{profile_id}/chroma_db, doc_store, source_docs |
| **Memory Isolation** | Separate SQLite + JSON per profile | Independent conversation history and user profiles | data/agents/{profile_id}/memoria_chat.sqlite, user_profile.json |
| **LLM Provider** | Claude Anthropic (Haiku 4.5) | Superior reasoning for philosophy, better tool use, cost-effective ($1/$5 per M tokens) | Direct `anthropic` SDK, no LangChain agents |
| **Memory Architecture** | Hybrid 3-tier (Profile + Messages + Summaries) | Scalable to infinite conversations with logarithmic token growth | Background async maintenance with Claude Haiku for summarization |
| **RAG Strategy** | Keyword-based activation | Avoid overhead on normal conversations, activate only for relevant queries | `_should_use_rag()` checks keywords per profile context |
| **RAG Implementation** | ParentDocumentRetriever | Precision (small child chunks) + context (large parent retrieval) | LangChain with HuggingFace embeddings (local) |
| **UI Framework** | PyQt6 | Native desktop feel, cross-platform, mature ecosystem | Async workers for non-blocking AI inference |
| **Database** | SQLite per profile | Lightweight, embedded, zero-config, perfect for desktop app | Separate DB per profile with messages and summaries tables |
| **User Profile** | JSON file per profile | Simple, human-readable, easy to backup/edit | Atomic writes with metadata tracking, isolated per profile |
| **Embeddings** | HuggingFace local | No API costs, privacy, offline operation | sentence-transformers library, cached per-profile |
| **Launcher** | XDG Desktop Entry | Standard Linux desktop integration | Shell script + .desktop file |

---

## Performance Characteristics

### Memory System
- **Token Overhead**: ~2% for background maintenance
- **Profile Update Latency**: <2s async (non-blocking)
- **Summarization**: Every 30 messages, ~1500 tokens API call
- **Growth Rate**: Logarithmic (vs linear without summaries)

### RAG System
- **Activation**: Only on keyword match (zero overhead otherwise)
- **Search Time**: <500ms for semantic search
- **Embedding**: Local, no API latency
- **Database Size**: 18MB vector store, 2.6MB docstore

### UI Responsiveness
- **Inference**: Async worker thread (UI never blocks)
- **Greeting Generation**: Async worker
- **Typical Response**: 2-5s (Claude API latency)

---

## Testing

**Test Files**:
- `test_intelligent_memory.py` - Validates profile extraction, summarization, multi-session memory
- `test_rag_integration.py` - Validates RAG activation, citation accuracy, memory+RAG combination

**Test Results** (2025-12-29):
- ✅ Memory system: All tests passed (Luigi/Maria/Fiat test case)
- ✅ RAG integration: All tests passed (philosophical queries, personal info, combined scenarios)

**Manual Testing**:
- Desktop UI tested on Ubuntu 22.04 LTS
- Multi-session conversations validated
- Document indexing (PDF + TXT) validated

---

## Git Repository

**Main Branch**: `main`

**Recent Commits**:
- `e2a1fad` - feat: Sistema Multi-Profilo Dinamico Completo (2025-12-30)
  - Dynamic profile loading from config.yaml with metadata inference
  - Profile deletion with system protection and automatic backups
  - Per-profile embeddings cache for perfect isolation
  - 535 insertions(+), 51 deletions(-)
- `9ff294b` - chore: Pulizia file di test e debug temporanei
- `4c6c1ed` - feat: Integrazione RAG con Memoria Intelligente
- `883de1f` - feat: Sistema di Memoria Intelligente completato

**Tracked Files**: 57 files (excluding .venv, __pycache__, data/)

---

## Known Limitations

1. **Profile Metadata UI**: No visual editor for profile metadata (icon, color, description) - currently inferred from agent_prompt
2. **Profile Switch**: Requires app restart to switch between profiles (architectural limitation)
3. **RAG Keyword Activation**: May miss relevant queries without specific keywords (per-profile)
4. **LangChain Deprecation Warning**: `HuggingFaceEmbeddings` deprecated (non-blocking, fix scheduled)
5. **No API Endpoint**: Desktop-only (API server code exists in `cognitiveservice_full.py` but not integrated)

---

## Future Roadmap

See `docs/AGENT_PROFILES_ROADMAP_PROMPT.md` for detailed multi-agent roadmap.

**Planned Features**:
- ✅ ~~Multi-profile support~~ (COMPLETED 2025-12-30)
- Profile metadata editor UI (icon, color, subtitle picker)
- Profile import/export (share profiles between installations)
- Profile templates gallery (pre-configured personalities)
- Hot profile switching (without app restart)
- Multi-user profile management (login system)
- Export conversation history per profile
- Voice input/output
- Mobile companion app (API mode)

---

## Notes

### Design Patterns
- **Service-Oriented Architecture**: Modular services managed by kernel
- **Async Workers**: UI responsiveness via QThread workers
- **Dependency Injection**: Services receive kernel reference for cross-service communication

### Migration History
- **2025-10**: Migrated from Google Gemini to Claude Anthropic
- **2025-12**: Implemented intelligent memory system (3-tier hybrid)
- **2025-12**: Integrated RAG with memory system

### Special Files
- `cognitiveservice_full.py`: LangChain ReAct agent version (legacy, kept for reference)
- `Colloqui con se stesso.txt/utf8.txt`: Meditations text (Italian translation)
- `marco_aurelio.pdf`, `SenecaLettereLucilio.pdf`: Indexed documents

---

**Status**: Production-ready desktop application with intelligent memory and RAG-powered philosophical conversations. ✅