matrix-ai-agent/CLAUDE.md

Matrix AI Agent

Matrix bot with memory, voice, RAG, and Confluence collaboration.

Deployment

• VM: matrix.agiliton.internal
• Path: /opt/matrix-ai-agent/
• Deploy: agiliton-deploy matrix-ai-agent
• Jira project: MAT

Architecture

• bot.py — Main Matrix bot (131KB, E2EE, memory-aware)
• voice.py — LiveKit voice integration
• agent.py — Pipecat voice agent
• memory-service/ — FastAPI service for encrypted memory storage (pgvector)
• confluence-collab/ — Confluence collaboration MCP server
• article_summary/ — Article summarization + TTS

Docker Services

• bot — Main bot process
• agent — Voice agent (host networking)
• memory-service — Memory API (port 8090, connects as memory_app with RLS)
• memory-db — pgvector/pg17 with SSL + Row-Level Security

Memory Encryption (MAT-107)

• Per-user Fernet encryption: HMAC-SHA256(master_key, user_id) key derivation
• Encrypted fields: fact, chunk_text, summary
• Embeddings unencrypted (required for vector search)
• RLS policies enforce user isolation at DB level
• memory_app role for queries, memory owner for DDL/health
• SSL between memory-service and memory-db

Secrets

All in .env (gitignored). Key vars:

• MEMORY_ENCRYPTION_KEY — Master key for memory encryption
• MEMORY_APP_PASSWORD — Restricted DB role password
• MATRIX_BOT_PASSWORD, LITELLM_API_KEY, ELEVENLABS_API_KEY, etc.