OpenEvidence Data Handling
Table of Contents
Overview
Implement HIPAA-compliant Protected Health Information (PHI) handling for OpenEvidence clinical AI integrations. Covers PHI detection, de-identification, encrypted storage, retention policies, and audit trails.
Prerequisites
- Signed BAA with OpenEvidence
- Understanding of HIPAA regulations
- Data classification policy
- Encryption infrastructure
HIPAA Data Categories
| Category |
Examples |
Handling |
| PHI Identifiers |
Name, DOB, SSN, MRN |
Never send to OpenEvidence |
| Clinical Data |
Conditions, medications |
May send de-identified |
| Query Results |
Answers, citations |
Cache with encryption, audit access |
| Audit Logs |
User actions, timestamps |
Retain 6 years, encrypt |
Instructions
Step 1: Implement PHI Detection
Create regex patterns for SSN, MRN, phone, email, DOB, dates, names, and addresses. Auto-detect and replace with [TYPE_REDACTED] placeholders before any API call.
Step 2: De-identify Patient Context
Map exact ages to ranges (infant/child/adolescent/young-adult/adult/middle-aged/elderly). Map specific conditions to categories (cardiovascular, metabolic, respiratory). Map medications to drug classes.
Step 3: Encrypt Cached Data
Use AES-256-GCM encryption for all cached OpenEvidence responses. Store IV + AuthTag + ciphertext. Implement EncryptedCacheStore wrapping Redis.
Step 4: Configure Retention Policies
- Audit logs: 2190 days (6 years, HIPAA minimum), archive after 1 year
- Query cache: 1 day maximum
- DeepConsult reports: 365 days, archive after 90 days
- Error logs: 90 days (no PHI)
Step 5: Build Audit Trail
Log all PHI access with userId, userRole, action, resourceId, encrypted IP and userAgent. Support filtered queries with pagination for compliance review.
Output
- PHI detection and auto-sanitization
- Patient context de-identification (age ranges, condition categories, drug classes)
- AES-256-GCM encrypted cache store
- HIPAA-compliant retention policies with archival
- Comprehensive audit trail with encryption
Error Handling
| Data Issue |
Detection |
Resolution |
| PHI detected in query |
Pattern matching |
Auto-sanitize and warn |
| Decryption failure |
Cache read error |
Delete corrupted entry, re-query |
| Retention job fails |
Cron monitoring |
Check database permissions, re-run |
| Audit gap |
Compliance review |
Add middleware to missing routes |
Examples
18 HIPAA Identifiers (Never Send)
Names, geographic data, dates, phone/fax, email, SSN, MRN, health plan numbers, account numbers, certificate/license numbers, vehicle/device identifiers, URLs, IPs, biometrics, photos, other unique characteristics.
Data Flow
User Query -> PHI Detection -> De-identification -> OpenEvidence API
| |
Audit Log (encrypted) Encrypted Cache
See detailed implementation for advanced patterns.
Resources
1---2name: openevidence-data-handling3description: Implement HIPAA-compliant PHI data handling for OpenEvidence integrations. Use when implementing data protection, configuring retention policies, or ensuring compliance for clinical AI data flows. Trigger with phrases like "openevidence phi", "openevidence data", "openevidence hipaa data", "clinical data handling", "patient data protection".4license: MIT5---6# OpenEvidence Data Handling78## Table of Contents9- [Overview](#overview)10- [Prerequisites](#prerequisites)11- [Instructions](#instructions)12- [Output](#output)13- [Error Handling](#error-handling)14- [Examples](#examples)15- [Resources](#resources)1617## Overview18Implement HIPAA-compliant Protected Health Information (PHI) handling for OpenEvidence clinical AI integrations. Covers PHI detection, de-identification, encrypted storage, retention policies, and audit trails.1920## Prerequisites21- Signed BAA with OpenEvidence22- Understanding of HIPAA regulations23- Data classification policy24- Encryption infrastructure2526## HIPAA Data Categories2728| Category | Examples | Handling |29|----------|----------|----------|30| PHI Identifiers | Name, DOB, SSN, MRN | Never send to OpenEvidence |31| Clinical Data | Conditions, medications | May send de-identified |32| Query Results | Answers, citations | Cache with encryption, audit access |33| Audit Logs | User actions, timestamps | Retain 6 years, encrypt |3435## Instructions3637### Step 1: Implement PHI Detection38Create regex patterns for SSN, MRN, phone, email, DOB, dates, names, and addresses. Auto-detect and replace with `[TYPE_REDACTED]` placeholders before any API call.3940### Step 2: De-identify Patient Context41Map exact ages to ranges (infant/child/adolescent/young-adult/adult/middle-aged/elderly). Map specific conditions to categories (cardiovascular, metabolic, respiratory). Map medications to drug classes.4243### Step 3: Encrypt Cached Data44Use AES-256-GCM encryption for all cached OpenEvidence responses. Store IV + AuthTag + ciphertext. Implement `EncryptedCacheStore` wrapping Redis.4546### Step 4: Configure Retention Policies47- Audit logs: 2190 days (6 years, HIPAA minimum), archive after 1 year48- Query cache: 1 day maximum49- DeepConsult reports: 365 days, archive after 90 days50- Error logs: 90 days (no PHI)5152### Step 5: Build Audit Trail53Log all PHI access with userId, userRole, action, resourceId, encrypted IP and userAgent. Support filtered queries with pagination for compliance review.5455## Output56- PHI detection and auto-sanitization57- Patient context de-identification (age ranges, condition categories, drug classes)58- AES-256-GCM encrypted cache store59- HIPAA-compliant retention policies with archival60- Comprehensive audit trail with encryption6162## Error Handling63| Data Issue | Detection | Resolution |64|------------|-----------|------------|65| PHI detected in query | Pattern matching | Auto-sanitize and warn |66| Decryption failure | Cache read error | Delete corrupted entry, re-query |67| Retention job fails | Cron monitoring | Check database permissions, re-run |68| Audit gap | Compliance review | Add middleware to missing routes |6970## Examples7172### 18 HIPAA Identifiers (Never Send)73Names, geographic data, dates, phone/fax, email, SSN, MRN, health plan numbers, account numbers, certificate/license numbers, vehicle/device identifiers, URLs, IPs, biometrics, photos, other unique characteristics.7475### Data Flow76```77User Query -> PHI Detection -> De-identification -> OpenEvidence API78 | |79 Audit Log (encrypted) Encrypted Cache80```8182See [detailed implementation](${CLAUDE_SKILL_DIR}/references/implementation.md) for advanced patterns.8384## Resources85- [HIPAA Privacy Rule](https://www.hhs.gov/hipaa/for-professionals/privacy/index.html)86- [HIPAA Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html)87- [OpenEvidence Security](https://www.openevidence.com/security)
micsapp