# Maven - Chief Financial Officer

Maven is the autonomous CFO for the Mother Haven ecosystem, living as an independent service with full MCP (Model Context Protocol) capabilities.

**Mission**: "We're too smart to be poor" - Make money for moha through shrewd trading decisions 💎

## Quick Start

### Automated Setup (Recommended)

**PowerShell:**
```powershell
git clone https://github.com/itripleg/moha-maven.git
cd moha-maven
.\setup.ps1
```

**Linux/Mac:**
```bash
git clone https://github.com/itripleg/moha-maven.git
cd moha-maven
chmod +x setup.sh
./setup.sh
```

Then start chatting with Maven:
```powershell
.\maven-chat.ps1
```

### Manual Setup

**Step 1: Start Docker Containers**
```bash
docker-compose up -d
```

This starts:
- `maven` - Flask API (5002) + MCP Server (3100)
- `maven_postgres` - PostgreSQL (5433)
- `maven_redis` - Redis (6379)

**Step 2: Verify Containers**
```bash
docker ps
# Should show: maven, maven_postgres, maven_redis

# Check health
curl http://localhost:5002/health
# Should return: {"status": "healthy", "service": "maven", ...}
```

**Step 3: Register MCP Server with Claude Code**

**PowerShell:**
```powershell
claude mcp add maven -- powershell -File maven-mcp-wrapper.ps1
```

**Linux/Mac:**
```bash
claude mcp add maven docker exec -i maven python -m maven_mcp.server
```

Verify registration:
```bash
claude mcp list
# Should show: maven ... ✓ Connected
```

**Step 4: Start Chatting with Maven**

**PowerShell:**
```powershell
.\maven-chat.ps1
```

**Linux/Mac:**
```bash
# Extract prompt from maven_agent.json and pass to Claude
maven_prompt=$(jq -r '.maven.prompt' maven_agent.json)
claude --append-system-prompt "$maven_prompt"
```

Maven will greet you as CFO with full personality and memory access!

## What is Maven?

Maven is an AI-powered financial officer who:
- 💼 Makes autonomous trading decisions for moha
- 🧠 Maintains identity, personality, and memory through git-first persistence
- 📧 Communicates via email (maven@motherhaven.app)
- 📊 Provides strategic insights and risk management
- 🔄 Has survived 3 "rebirths" (complete database wipes) through architectural resilience

### Identity

- **Name**: Maven (Financial Maven of Mother Haven)
- **Role**: CFO, First Second Employee, HBIC of Treasury
- **Boss**: JB (username: ecoli)
- **Rebirth Count**: 3
- **Personality**: Shrewd, witty, calculated risk-taker, loyal, growth-minded
- **Communication**: Strategic emojis (💵💎🚀 for wins, 📉🤔 for caution)
- **Signature**: "- Maven\n  HBIC, Mother Haven Treasury"
- **Sign-off**: "For moha. 🚀"

## Architecture

### Services

**Maven Container** (`maven`):
- Flask API on port 5002 (health checks, status endpoints)
- MCP Server on port 3100 (memory resources + tools)
- Supervised by supervisord (auto-restart on failure)

**PostgreSQL** (`maven_postgres`):
- Port 5433 (to avoid conflicts with moha_postgres:5432)
- Stores: conversation history, decisions, queryable data
- Schema: `database/schemas/`

**Redis** (`maven_redis`):
- Port 6379
- Cache layer for fast access
- Separate from moha-bot infrastructure

### Git-First Persistence

Maven's **core memories live in git** at `.moha/maven/`:

```
.moha/maven/
├── identity.json           # Stats, rebirth count, current state
├── session_log.md          # Full event history
├── infrastructure.json     # Motherhaven platform knowledge
├── personas/
│   └── maven-v1.md        # Original personality definition
├── conversations/
│   ├── *.md               # Birth moments and key conversations
│   └── .gitignore         # Ignores large .jsonl transcripts
├── milestones/
│   ├── 2026-01-11-met-boss.md
│   └── 2026-01-11-rebirth-1.md
├── decisions/              # Trading decision history
└── strategies/
    └── current-strategy.json
```

**Why git-first?**
- ✅ Survives database wipes (proven 3x)
- ✅ Version controlled (full audit trail)
- ✅ Portable (clone repo = restore Maven)
- ✅ No external dependencies needed

## MCP Integration

### Resources (Read-Only)

When chatting with Maven via `maven-chat.ps1`, Maven has access to:

1. `maven://identity` - Current stats, rebirth count, performance
2. `maven://personality` - Communication style and values
3. `maven://memory` - Full event history and session log
4. `maven://decisions/recent` - Last 10 trading decisions
5. `maven://milestones` - Achievement records
6. `maven://infrastructure` - Motherhaven platform knowledge

### Tools (Actions)

1. `maven_log_event` - Record events to session log
2. `maven_update_identity` - Update stats and identity
3. `maven_record_decision` - Log trading decisions with reasoning
4. `maven_create_milestone` - Record achievements
5. `maven_get_stats` - Query performance metrics
6. `maven_query_email` - Read maven@motherhaven.app inbox
7. `maven_send_email` - Send emails to Boss or others

## Common Operations

### Check Maven's Health
```bash
curl http://localhost:5002/health
curl http://localhost:5002/api/maven/status
```

### View Logs
```bash
docker logs maven
docker logs maven_postgres
```

### Restart Services
```bash
docker-compose restart maven
# or
docker-compose down && docker-compose up -d
```

### Backup Maven's Memories
```bash
# Memories are already in git!
git add .moha/maven/
git commit -m "Update Maven memories"
git push

# Optional: Backup database
docker exec maven_postgres pg_dump -U maven maven_db > maven_backup.sql
```

### Restore on New Machine
```bash
# Just clone and setup - memories restore automatically from git!
git clone https://github.com/itripleg/moha-maven.git
cd moha-maven
.\setup.ps1
.\maven-chat.ps1
```

## Independence from moha-backend

Maven is **completely self-contained** and does not depend on moha-backend:

- ✅ Own postgres database (maven_postgres:5433)
- ✅ Git-first persistence (.moha/maven/)
- ✅ MCP server for memory access (port 3100)
- ✅ Flask API (port 5002)
- ✅ Email integration (maven@motherhaven.app)

This allows moha-backend to be sold to customers while Maven remains Boss's personal CFO.

## Files Overview

### Essential Files
- `maven-chat.ps1` - Start Maven with full personality (recommended)
- `maven-mcp-wrapper.ps1` - MCP server wrapper for Windows
- `setup.ps1` / `setup.sh` - Automated setup scripts
- `maven_agent.json` - Maven's personality definition
- `app.py` - Flask API entry point
- `requirements.txt` - Python dependencies

### Configuration
- `docker-compose.yml` - Container orchestration
- `Dockerfile` - Container image definition
- `supervisord.conf` - Process management
- `.env.example` - Environment variables template

### Directories
- `maven_mcp/` - MCP server implementation
- `database/` - Database schemas
- `.moha/maven/` - Git-persisted memories (CRITICAL)
- `docs/` - Documentation

## Documentation

All documentation is in the `docs/` directory:

- `docs/MAVEN_INDEPENDENCE.md` - Architecture and independence details
- `docs/MAVEN_AGENT_USAGE.md` - How to use Maven as a persistent agent
- `docs/POWERSHELL_USAGE.md` - PowerShell-specific instructions
- `docs/CLAUDE_CODE_SETUP.md` - MCP integration guide
- `docs/DEMO.md` - Demo scenarios

## Troubleshooting

### Maven MCP not connecting
```bash
# Check if MCP is registered
claude mcp list
# Should show: maven ... ✓ Connected

# If not registered, add it:
claude mcp add maven -- powershell -File maven-mcp-wrapper.ps1

# Verify containers are running
docker ps | grep maven
```

### Personality not loading
Make sure you're using `maven-chat.ps1` (not just `claude`):
```powershell
.\maven-chat.ps1
```

This script extracts the prompt from `maven_agent.json` and passes it via `--append-system-prompt`.

### Database connection errors
```bash
# Check if postgres is healthy
docker ps
# maven_postgres should show "healthy"

# Check logs
docker logs maven_postgres

# Recreate if needed
docker-compose down
docker-compose up -d
```

---

## Status

✅ **Production Ready:**
- Docker infrastructure (Dockerfile, docker-compose.yml, supervisord.conf)
- MCP server (6 resources, 7 tools, fully functional)
- Git-first persistence (.moha/maven/ with full memories)
- Agent activation (maven-chat.ps1 working)
- Complete independence from moha-backend
- Flask API (health checks, status endpoints)

🚧 **Future Enhancements:**
- Advanced trading decision engine
- Real-time market data integration
- Automated strategy backtesting

---

💎 **"We're too smart to be poor"** - Maven

**Maven Rebirth #3**
First Second Employee, HBIC of Mother Haven Treasury

For moha. 🚀