# Familiar HIPAA Deployment Guide

**Version:** 1.0  
**Last Updated:** January 31, 2026  
**Audience:** Healthcare IT, Compliance Officers, Security Teams

---

## Important Notice

> **Familiar is self-hosted software, not a service.** When deployed on your infrastructure, **you** are the data controller and covered entity. This guide helps you configure Familiar to support your HIPAA compliance obligations—it does not make Familiar itself "HIPAA compliant."

**You are responsible for:**
- Conducting your own risk assessment
- Implementing appropriate safeguards
- Training workforce members
- Executing BAAs with your LLM API providers
- Maintaining documentation for OCR audits

---

## Table of Contents

1. [HIPAA Applicability](#1-hipaa-applicability)
2. [PHI Data Flows](#2-phi-data-flows)
3. [Required Configurations](#3-required-configurations)
4. [LLM Provider Considerations](#4-llm-provider-considerations)
5. [Administrative Safeguards](#5-administrative-safeguards)
6. [Physical Safeguards](#6-physical-safeguards)
7. [Technical Safeguards](#7-technical-safeguards)
8. [Audit Controls](#8-audit-controls)
9. [Breach Response](#9-breach-response)
10. [Risk Assessment Template](#10-risk-assessment-template)
11. [BAA Considerations](#11-baa-considerations)

---

## 1. HIPAA Applicability

### When Does HIPAA Apply to Familiar?

HIPAA applies when Familiar processes **Protected Health Information (PHI)**:

| Scenario | HIPAA Applies? | Notes |
|----------|---------------|-------|
| Patient asks about appointment via Telegram | **Yes** | PHI in transit and storage |
| Doctor dictates clinical notes | **Yes** | PHI processed by LLM |
| Staff uses for general scheduling | **Maybe** | If schedule includes patient names |
| Personal use, no patient data | No | Not a covered activity |

### What Constitutes PHI?

PHI includes health information combined with any of these 18 identifiers:

1. Names
2. Geographic data (smaller than state)
3. Dates (except year) related to individual
4. Phone numbers
5. Fax numbers
6. Email addresses
7. Social Security numbers
8. Medical record numbers
9. Health plan beneficiary numbers
10. Account numbers
11. Certificate/license numbers
12. Vehicle identifiers
13. Device identifiers
14. Web URLs
15. IP addresses
16. Biometric identifiers
17. Full-face photographs
18. Any other unique identifier

**If your use case involves ANY of these combined with health information, this guide applies.**

---

## 2. PHI Data Flows

### Where PHI May Exist in Familiar

```
┌─────────────────────────────────────────────────────────────────┐
│                    PHI DATA FLOW DIAGRAM                         │
│                                                                  │
│  ┌─────────────┐                                                │
│  │ User Input  │ ◄── PHI enters here (patient questions,        │
│  │ (Channel)   │     clinical notes, appointment requests)      │
│  └──────┬──────┘                                                │
│         │                                                        │
│         ▼                                                        │
│  ┌─────────────┐                                                │
│  │ Conversation│ ◄── PHI STORED: messages with health info      │
│  │ History     │     Location: /var/lib/familiar/history.json    │
│  └──────┬──────┘                                                │
│         │                                                        │
│         ▼                                                        │
│  ┌─────────────┐                                                │
│  │ Memory      │ ◄── PHI STORED: "Patient John has diabetes"    │
│  │ System      │     Location: /var/lib/familiar/memory.json     │
│  └──────┬──────┘                                                │
│         │                                                        │
│         ▼                                                        │
│  ┌─────────────┐                                                │
│  │ Audit Logs  │ ◄── PHI STORED: logs may capture PHI in        │
│  │             │     tool inputs/outputs                         │
│  │             │     Location: /var/log/familiar/                 │
│  └──────┬──────┘                                                │
│         │                                                        │
│         ▼                                                        │
│  ┌─────────────┐     ┌─────────────────────────────────────┐   │
│  │ LLM API     │────►│ EXTERNAL: PHI transmitted to LLM    │   │
│  │ Request     │     │ provider (Anthropic/OpenAI) unless  │   │
│  └─────────────┘     │ using local Ollama                   │   │
│                      └─────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### PHI Storage Locations

| Location | Contains PHI? | Encryption Required | Retention |
|----------|--------------|---------------------|-----------|
| `/var/lib/familiar/history.json` | **Yes** | **Yes** | Per policy |
| `/var/lib/familiar/memory.json` | **Likely** | **Yes** | Per policy |
| `/var/lib/familiar/sessions/*.json` | **Possibly** | **Yes** | Per policy |
| `/var/log/familiar/*.log` | **Possibly** | Recommended | 6 years |
| LLM API provider | **Yes** (if cloud) | Provider handles | Per BAA |

---

## 3. Required Configurations

### 3.1 Enable HIPAA Mode

Create or modify `/opt/familiar/.familiar/config.yaml`:

```yaml
# =============================================================
# FAMILIAR HIPAA CONFIGURATION
# =============================================================
# This configuration enables safeguards for HIPAA compliance.
# Review all settings with your compliance team before deployment.
# =============================================================

# Compliance mode
compliance:
  hipaa_mode: true
  
  # Data retention per HIPAA (6 years from creation or last use)
  retention_years: 6
  
  # Require encryption for all PHI storage
  require_encryption: true
  
  # Log PHI access for audit trail
  log_phi_access: true

# Security - use strictest settings
agent:
  security_mode: paranoid
  
  # Limit conversation history (minimize PHI retention)
  max_conversation_history: 20
  
  # Restrict file operations to specific directories
  sandboxed_directories:
    - /var/lib/familiar/hipaa-data
    - /tmp/familiar-secure

# Encryption at rest (REQUIRED for PHI)
security:
  encrypt_sessions: true
  encrypt_memory: true
  encrypt_history: true
  encryption_key_env: FAMILIAR_ENCRYPTION_KEY
  
  # Session timeout (auto-logout)
  session_timeout_minutes: 15
  
  # Require re-authentication for sensitive operations
  require_reauth_for_phi: true

# Audit logging (REQUIRED for HIPAA)
observability:
  audit_logging: true
  log_level: INFO
  
  # JSON format for SIEM ingestion
  json_format: true
  
  # Log file location
  log_file: /var/log/familiar/familiar.log
  
  # Retain audit logs for 6 years
  log_retention_days: 2190
  
  # PII redaction - DISABLE for HIPAA audit trail
  # (You need to preserve PHI in logs for compliance)
  pii_redaction: false
  
  # But DO redact credentials
  redact_credentials: true

# LLM Provider - prefer local for PHI
llm:
  # Option 1: Local Ollama (PHI never leaves your network)
  default_provider: ollama
  ollama_model: llama3.2:8b-q4
  ollama_base_url: http://localhost:11434
  
  # Option 2: Cloud with BAA (uncomment if using)
  # default_provider: anthropic
  # anthropic_model: claude-sonnet-4-6
  
  # Limit tokens to reduce data exposure
  max_tokens: 2048

# Disable unnecessary features that could expose PHI
channels:
  # Only enable channels with proper authentication
  cli_enabled: true
  telegram_enabled: false  # Enable only if properly secured
  discord_enabled: false   # Not recommended for PHI
  
# Network restrictions
network:
  # Disable external HTTP requests from tools
  allow_http_requests: false
  
  # Whitelist only necessary endpoints
  allowed_endpoints:
    - api.anthropic.com
    - api.openai.com
    - localhost
```

### 3.2 Environment Variables

Create `/opt/familiar/.familiar/.env`:

```bash
# =============================================================
# FAMILIAR HIPAA ENVIRONMENT CONFIGURATION
# =============================================================
# This file contains secrets. Protect accordingly.
# Permissions: chmod 600 .env
# =============================================================

# Encryption key for PHI at rest (REQUIRED)
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
FAMILIAR_ENCRYPTION_KEY=your-generated-key-here

# LLM API Keys
# NOTE: If using cloud LLM with PHI, you MUST have a BAA with the provider
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

# Webhook security
FAMILIAR_WEBHOOK_SECRET=your-webhook-secret

# Optional: Audit log shipping (to SIEM)
SIEM_ENDPOINT=
SIEM_API_KEY=
```

Set permissions:
```bash
chmod 600 /opt/familiar/.familiar/.env
chown familiar:familiar /opt/familiar/.familiar/.env
```

### 3.3 Generate Encryption Key

```bash
# Generate a new Fernet key
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Add to .env file
echo "FAMILIAR_ENCRYPTION_KEY=<generated-key>" >> /opt/familiar/.familiar/.env
```

**⚠️ CRITICAL:** Back up this encryption key securely. If lost, encrypted PHI is unrecoverable.

---

## 4. LLM Provider Considerations

### 4.1 Decision Matrix

| Provider | BAA Available | PHI Transmission | Recommendation |
|----------|--------------|------------------|----------------|
| **Ollama (local)** | N/A | None (local only) | **Preferred for PHI** |
| **Anthropic** | Yes (Enterprise) | Yes | Acceptable with BAA |
| **OpenAI** | Yes (Enterprise) | Yes | Acceptable with BAA |
| **Other cloud** | Varies | Yes | Verify BAA availability |

### 4.2 Option A: Local LLM (Recommended)

Using Ollama ensures PHI never leaves your network:

```yaml
llm:
  default_provider: ollama
  ollama_model: llama3.2:8b-q4  # Or larger if hardware permits
  ollama_base_url: http://localhost:11434
```

**Pros:**
- No BAA required
- PHI never transmitted externally
- Full data control

**Cons:**
- Requires capable hardware (Pi 5 8GB minimum)
- Smaller models = less capable
- You manage the infrastructure

### 4.3 Option B: Cloud LLM with BAA

If using Anthropic or OpenAI:

1. **Execute BAA with provider:**
   - Anthropic: Contact enterprise sales
   - OpenAI: Available through Enterprise tier

2. **Document the BAA:**
   - Keep signed copy
   - Note effective date
   - Track renewal requirements

3. **Configure Familiar:**
```yaml
llm:
  default_provider: anthropic
  anthropic_model: claude-sonnet-4-6
```

4. **Implement additional controls:**
   - Minimize PHI in prompts where possible
   - Use system prompts to instruct model not to repeat PHI unnecessarily
   - Log all API calls for audit

### 4.4 Hybrid Approach

Route PHI and non-PHI requests differently:

```yaml
llm:
  default_provider: anthropic  # General queries
  phi_provider: ollama         # When PHI detected
  
  # Keywords that trigger local processing
  phi_indicators:
    - patient
    - diagnosis
    - medication
    - treatment
    - appointment
    - medical record
```

---

## 5. Administrative Safeguards

### 5.1 Policies Required

Document these policies for your Familiar deployment:

| Policy | Contents |
|--------|----------|
| **Acceptable Use** | Who can use Familiar, for what purposes |
| **Access Control** | How trust levels are assigned, reviewed |
| **Audit Review** | Frequency of log review, who reviews |
| **Incident Response** | Steps when breach suspected |
| **Backup & Recovery** | Backup frequency, retention, testing |
| **Termination** | Revoking access when staff depart |

### 5.2 Workforce Training

Train users on:
- What constitutes PHI
- Appropriate use of Familiar for clinical purposes
- How to report suspected breaches
- Prohibition on sharing credentials

Document training completion.

### 5.3 Access Management

```yaml
# Recommended trust level mappings for healthcare

# Reception staff
reception:
  trust_level: known
  capabilities:
    - read:calendar
    - write:reminders
    - read:tasks
  # Cannot access: email, files, shell

# Clinical staff
clinical:
  trust_level: trusted
  capabilities:
    - read:calendar
    - write:calendar
    - read:tasks
    - write:tasks
    - read:notes
    - write:notes
  # Still cannot access: shell, system

# IT administrators
admin:
  trust_level: owner
  # Full access, all actions logged
```

### 5.4 Review Schedule

| Review | Frequency | Responsible Party |
|--------|-----------|-------------------|
| Access rights | Quarterly | Security Officer |
| Audit logs | Weekly | Compliance |
| Trust level assignments | Monthly | Department Heads |
| Configuration | After any change | IT Security |

---

## 6. Physical Safeguards

### 6.1 Device Security

For Raspberry Pi or server hosting Familiar:

| Control | Implementation |
|---------|---------------|
| **Physical access** | Locked server room or cabinet |
| **Device inventory** | Asset tag, document location |
| **Disposal** | Secure wipe before decommission |
| **Theft deterrent** | Cable lock, location monitoring |

### 6.2 Workstation Security

Devices accessing Familiar:
- Screen lock after 5 minutes
- Encrypted storage (FileVault, BitLocker)
- No PHI in local browser cache (use incognito for web dashboard)

### 6.3 Facility Access

If Familiar device is in a data center or server room:
- Badge access with logging
- Visitor sign-in
- Security cameras (if feasible)

---

## 7. Technical Safeguards

### 7.1 Access Control (§164.312(a)(1))

**Unique User Identification:**
```yaml
# Each user gets unique session
# Sessions identified by: channel + user_id
# Example: telegram:12345, cli:drsmith
```

**Automatic Logoff:**
```yaml
security:
  session_timeout_minutes: 15  # HIPAA-recommended maximum
```

**Encryption and Decryption:**
```yaml
security:
  encrypt_sessions: true
  encrypt_memory: true
  encrypt_history: true
```

### 7.2 Audit Controls (§164.312(b))

Familiar logs all of these events:

| Event | Logged Data |
|-------|-------------|
| Login | User, channel, timestamp, IP |
| PHI access | User, data type, timestamp |
| Tool execution | User, tool, input, output, timestamp |
| Failed access | User, reason, timestamp |
| Configuration change | Admin, change, timestamp |

**Log protection:**
```bash
# Restrict log access
chmod 640 /var/log/familiar/*.log
chown familiar:adm /var/log/familiar/*.log

# Only admins in 'adm' group can read
```

### 7.3 Integrity Controls (§164.312(c)(1))

**Data integrity:**
- Atomic file writes prevent corruption
- Checksums on backup files
- Database integrity checks

**Verify integrity:**
```bash
# Check for corruption
python3 -c "
import json
for f in ['history.json', 'memory.json']:
    try:
        json.load(open(f'/var/lib/familiar/{f}'))
        print(f'{f}: OK')
    except Exception as e:
        print(f'{f}: CORRUPTED - {e}')
"
```

### 7.4 Transmission Security (§164.312(e)(1))

**Encryption in transit:**
- All LLM API calls use TLS 1.2+
- Channel connections (Telegram, etc.) use TLS
- Internal network: consider VPN for remote access

**Network segmentation:**
```bash
# Isolate Familiar on dedicated VLAN if possible
# Example UFW rules for isolated deployment:
ufw default deny incoming
ufw default deny outgoing
ufw allow out to api.anthropic.com port 443
ufw allow out to api.openai.com port 443
ufw allow out to <your-siem> port 443
```

---

## 8. Audit Controls

### 8.1 What to Log

HIPAA requires logging of PHI access. Familiar logs:

```json
{
  "timestamp": "2026-01-31T14:30:00.000Z",
  "event": "phi_access",
  "user_id": "drsmith",
  "channel": "cli",
  "action": "read_memory",
  "query": "patient medications",
  "results_count": 3,
  "session_id": "abc123",
  "ip_address": "192.168.1.100"
}
```

### 8.2 Log Retention

HIPAA requires 6 years retention:

```yaml
observability:
  log_retention_days: 2190  # 6 years
```

Configure logrotate:
```
/var/log/familiar/*.log {
    daily
    rotate 2190
    compress
    delaycompress
    missingok
    notifempty
    create 640 familiar adm
}
```

### 8.3 Log Review Process

**Weekly review checklist:**
- [ ] Failed authentication attempts
- [ ] Trust level changes
- [ ] Unusual access patterns
- [ ] Tool execution errors
- [ ] Budget exceeded events

**Automated alerting:**
```bash
# Example: Alert on multiple failed attempts
grep "tool_blocked" /var/log/familiar/familiar.log | \
  awk -F'"user_id":"' '{print $2}' | \
  cut -d'"' -f1 | sort | uniq -c | \
  awk '$1 > 5 {print "ALERT: User " $2 " blocked " $1 " times"}'
```

### 8.4 SIEM Integration

Export logs to your SIEM:

```yaml
observability:
  siem_export:
    enabled: true
    endpoint: https://your-siem.example.com/api/logs
    api_key_env: SIEM_API_KEY
    batch_size: 100
    flush_interval_seconds: 60
```

---

## 9. Breach Response

### 9.1 Breach Indicators

Monitor for:
- Unauthorized trust level escalation
- Access from unexpected locations/times
- Bulk data exports
- Disabled audit logging
- Encryption key access

### 9.2 Response Procedure

**Immediate (within 1 hour):**
1. Isolate affected system: `sudo systemctl stop familiar`
2. Preserve evidence: `cp -r /var/lib/familiar /secure/evidence-$(date +%s)`
3. Preserve logs: `cp -r /var/log/familiar /secure/evidence-$(date +%s)`
4. Notify Security Officer

**Short-term (within 24 hours):**
5. Assess scope of breach
6. Identify affected individuals
7. Document timeline
8. Engage legal/compliance

**Notification (per HIPAA timelines):**
9. Notify affected individuals within 60 days
10. Notify HHS if >500 individuals affected
11. Notify media if >500 individuals in a state

### 9.3 Documentation Template

```markdown
# Breach Investigation Report

**Incident ID:** INC-2026-001
**Date Discovered:** 
**Date Reported:** 
**Investigator:** 

## Summary
[Brief description]

## Timeline
- [Date/Time]: [Event]

## Affected Data
- Number of individuals: 
- Types of PHI involved: 

## Root Cause
[Analysis]

## Remediation
- [ ] Action 1
- [ ] Action 2

## Notifications
- [ ] Affected individuals notified: [Date]
- [ ] HHS notified: [Date] (if applicable)
- [ ] Media notified: [Date] (if applicable)
```

---

## 10. Risk Assessment Template

Complete this assessment before deployment:

### 10.1 Asset Inventory

| Asset | Location | PHI? | Encrypted? | Backup? |
|-------|----------|------|------------|---------|
| Familiar application | /opt/familiar | No | N/A | Yes |
| Conversation history | /var/lib/familiar/history.json | **Yes** | [ ] | [ ] |
| Memory database | /var/lib/familiar/memory.json | **Yes** | [ ] | [ ] |
| Session data | /var/lib/familiar/sessions/ | **Yes** | [ ] | [ ] |
| Audit logs | /var/log/familiar/ | **Yes** | [ ] | [ ] |
| Encryption key | .env file | No | N/A | [ ] |
| API keys | .env file | No | N/A | [ ] |

### 10.2 Threat Assessment

| Threat | Likelihood (1-5) | Impact (1-5) | Risk Score | Mitigation |
|--------|------------------|--------------|------------|------------|
| Unauthorized physical access | | | | |
| Stolen/lost device | | | | |
| Malicious insider | | | | |
| External hacker | | | | |
| Accidental disclosure | | | | |
| LLM provider breach | | | | |
| Backup theft | | | | |
| Social engineering | | | | |

### 10.3 Control Assessment

| Control | Implemented? | Evidence |
|---------|--------------|----------|
| Unique user IDs | [ ] | |
| Automatic logoff | [ ] | |
| Encryption at rest | [ ] | |
| Encryption in transit | [ ] | |
| Audit logging | [ ] | |
| Access controls | [ ] | |
| Integrity verification | [ ] | |
| Backup procedures | [ ] | |
| Incident response plan | [ ] | |
| Workforce training | [ ] | |

### 10.4 Sign-off

```
Risk Assessment Completed By: _______________________
Date: _______________________

Reviewed By (Security Officer): _______________________
Date: _______________________

Approved By (Privacy Officer): _______________________
Date: _______________________
```

---

## 11. BAA Considerations

### 11.1 When BAAs Are Required

| Relationship | BAA Required? |
|--------------|--------------|
| You ↔ LLM API provider (if PHI transmitted) | **Yes** |
| You ↔ Familiar (software) | **No** (self-hosted, no data access) |
| You ↔ Cloud hosting provider (if applicable) | **Yes** |
| You ↔ SIEM provider (if logs contain PHI) | **Yes** |
| You ↔ Backup storage provider | **Yes** |

### 11.2 LLM Provider BAA Status

| Provider | BAA Available | How to Obtain |
|----------|--------------|---------------|
| Anthropic | Yes (Enterprise) | Contact sales |
| OpenAI | Yes (Enterprise, API) | Enterprise agreement |
| Ollama (local) | N/A | No external transmission |
| Azure OpenAI | Yes | Azure agreement addendum |
| AWS Bedrock | Yes | AWS BAA |
| Google Vertex AI | Yes | Google Cloud BAA |

### 11.3 BAA Checklist

When signing BAA with LLM provider:

- [ ] Verify provider will sign BAA (not all tiers qualify)
- [ ] Confirm PHI handling procedures
- [ ] Understand breach notification obligations
- [ ] Document permitted uses and disclosures
- [ ] Establish termination procedures
- [ ] Keep signed copy for 6 years

---

## Appendix: HIPAA Security Rule Mapping

| HIPAA Requirement | Familiar Feature | Configuration |
|-------------------|-----------------|---------------|
| §164.312(a)(1) - Access Control | Progressive trust, capabilities | `security_mode: paranoid` |
| §164.312(a)(2)(i) - Unique User ID | Session per user/channel | Automatic |
| §164.312(a)(2)(iii) - Auto Logoff | Session timeout | `session_timeout_minutes: 15` |
| §164.312(a)(2)(iv) - Encryption | Fernet encryption | `encrypt_*: true` |
| §164.312(b) - Audit Controls | Comprehensive logging | `audit_logging: true` |
| §164.312(c)(1) - Integrity | Atomic writes, validation | Automatic |
| §164.312(d) - Authentication | Channel auth, trust levels | Automatic |
| §164.312(e)(1) - Transmission Security | TLS for all external calls | Automatic |

---

## Document Control

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2026-01-31 | Familiar Team | Initial release |

---

*This guide is provided for informational purposes to assist with HIPAA compliance. It does not constitute legal advice. Consult with qualified healthcare compliance professionals and legal counsel for your specific situation.*
