Implementation Guide | Healthcare

    Redacting PHI at LlamaIndex Ingestion Before Documents Are Embedded

    Run PHI redaction as an enforced transformation after documents are loaded and before they are chunked, enriched with metadata, embedded or written to any store. Embeddings, node text and metadata are derived from the source, so PHI that reaches them is hard to inspect or purge. Treat detector errors and low-confidence matches as fail-closed events, and record redaction actions as evidence without storing the raw PHI.

    Where redaction belongs: load, parse, redact, chunk, embed, store

    1. 1

      Readers

      Raw text, file names, paths and source fields enter here. Treat reader metadata as untrusted until scrubbed.

    2. 2

      Redaction transformation

      Detect, apply masking, tokenization or removal, and rewrite or drop metadata keys. Run it before any other transformation.

    3. 3

      Node parsers

      Chunking copies document metadata onto every node. Parsing redacted documents keeps that copy clean.

    4. 4

      Metadata extractors

      Generated summaries and questions are new derived text. Run them only on redacted nodes.

    5. 5

      Embedding model

      Embed only redacted node text, and exclude metadata keys that are not needed from the embedded content.

    6. 6

      Docstore, vector store, cache

      Write only post-redaction nodes. Confirm that caches are keyed on redacted content.

    Why embeddings and metadata inherit the PHI problem

    Clinical notes, claims, intake forms and scanned records contain PHI in free text, in structured fields and in file-level details such as names and paths. A LlamaIndex pipeline copies that content into several artifacts: node text, node metadata, docstore entries, vector store records and any ingestion cache. An embedding is computed from the text it represents, so if the text contained PHI when it was embedded, the vector is derived from PHI. It cannot be read like a record, which makes it difficult to inspect, scope or purge.

    The HIPAA Security Rule sets national standards for electronic PHI that a covered entity or business associate creates, receives, uses or maintains. Whether a given derived artifact falls within that scope is a question for your privacy and legal teams. The engineering position is simpler: every artifact that never held PHI is one fewer place to defend, delete from and explain. That is the reason to redact upstream of retention rather than clean up afterward.

    Choosing detection and a treatment: masking, tokenization or removal

    Detection usually combines rule-based patterns for structured identifiers such as phone numbers, record numbers and dates, with NER models or recognizer frameworks for names and other free-text entities. Rules are predictable but miss context. Statistical models handle context better but are probabilistic and tuned on text that may not resemble your notes. Scanned records add OCR noise, so redact the OCR output and handle the source image separately. Start from the HIPAA identifier categories, then add your own local ones.

    HHS de-identification guidance notes that esoteric notation, such as acronyms known to few employees, and incomplete descriptions can cause unnecessary redaction or missed redaction. It also says documenting which features or values pertain to identifiers makes the work more efficient and effective. Build that inventory of fields, values and local abbreviations before configuring any detector.

    The treatment is a risk decision. NIST describes redaction as removal-based suppression, notes that it alone is generally insufficient for formal privacy guarantees, and warns that selective redaction can reduce accuracy and introduce bias. It lists setting a re-identification risk threshold as a first step. Record that threshold, then choose the treatment against it.

    • Masking: Replace a value with a category label such as [NAME]. Simple and irreversible, and it preserves sentence structure for retrieval.
    • Removal: Delete the span. Lowest residual risk, but it can break context and degrade retrieval quality.
    • Tokenization: Replace a value with a stable token. It allows linking across chunks, but the token map becomes a sensitive store and the tokens can themselves link records. Use it only with a documented re-identification need.

    Failure handling: fail closed and keep the evidence

    Decide in advance what happens when redaction cannot complete. If the detector errors, times out or cannot parse a file, the document should not continue down the pipeline. Quarantine it with a reason code and a document identifier, and raise it for review. Never fall through to embedding with the original text.

    Low-confidence matches need a threshold. Below it, the safer default is to redact. A human review queue for borderline cases is one option: an HHS document redaction tool recommends redactions and applies them only after authorized users review and finalize them. That is a document workflow rather than a high-volume ingestion pattern, so reserve review for the cases that justify it.

    Verification belongs in the process too. Measure recall on labeled samples of your own notes, claims and OCR output, and track it per identifier category. Rerun the same tests whenever detectors or rules change. When policy changes, plan to re-ingest affected documents and purge the nodes and vectors that the earlier policy produced, which is only practical if each node carries the policy version that produced it.

    What evidence an auditor would expect to see

    The HIPAA Security Rule's technical safeguards include audit controls at 164.312(b). In practice, this means you should be able to show that redaction ran, which rules ran, and what happened to every document, including the ones that failed. Verify the exact wording of the provision with your compliance team.

    For each document, record the document identifier, timestamp, detector and policy version, counts of redactions by identifier category, and the outcome: processed, quarantined or blocked. Add the coverage test results and the dates they were run.

    Be deliberate about the logs themselves. An HHS example separates internal compliance logs that may capture exact redacted text, retained for 18 months in that system, from forwarded logs that are action-based and exclude it. Copying that split avoids rebuilding the PHI problem inside your audit trail. Set retention to your own policy. A proposed update to the Security Rule, which as of November 2026 is not final, would require periodic documented review of compensating controls. Whether or not it is adopted, reviewing the redaction design on a schedule is sound practice.

    Where runtime policy enforcement complements pipeline code

    A redaction transformation protects one pipeline. Other paths still carry PHI: users who paste text into prompts, tools that return records, and agents that call services. Pipeline code is also easy to bypass by adding a second ingestion job that skips the step.

    Trussed enforces policy in the execution path, where it can allow, redact or block individual interactions and tool calls, and it generates audit-ready evidence from that enforcement, mapped to HIPAA among other frameworks. Enforcement happens at runtime, not through review after the fact. It runs in production with healthcare and pharma organizations, and it can be self-managed in the customer cloud with configurable retention and data residency. It complements the ingestion step described here and does not replace it.

    Ingestion sequence with redaction enforced before embedding

    Load

    Readers return raw documents and file-level metadata.

    Redact

    Detect identifiers, apply the chosen treatment, scrub metadata.

    Chunk

    Node parsers split already-redacted text.

    Embed and store

    Only redacted nodes reach the embedding model, docstore and vector store.

    Put redaction in the execution path

    Talk through where PHI enters your RAG pipelines and how enforced redaction and audit-ready evidence fit your design.

    Talk to an Expert
    Next step

    How does your AI governance program compare?

    See where your program has gaps in less than 2 minutes.