clinical-memory

Governed long-term memory for clinical AI agents — a FastAPI service on top of mem0 that gives agents durable, patient-scoped recall with PHI redaction, strict tenant isolation, and an audit trail on every read and write.

RAG answers a question from documents. Agents also need to remember — what a clinician already told them, a patient's stated preferences, decisions made in a prior session. Dropping raw notes into a shared memory store is a compliance incident waiting to happen. clinical-memory wraps mem0's memory layer with the governance a clinical setting requires: every memory is scoped to a patient, scrubbed of PHI before storage, and access-logged for audit.

Built on mem0ai/mem0 (Apache-2.0). mem0 is the memory engine; this repo is the governed clinical service around it — scoping, redaction, audit, and an agent tool. Runs fully offline out of the box with a local backend, so you can try it without any API keys.

Architecture

flowchart LR
  A[Agent / clinician] -->|add memory| B[PHI redaction gate]
  B --> C[Patient-scoped write]
  C --> D[(Memory store<br/>mem0 · pgvector)]
  A -->|search| E[Scoped retrieval]
  E --> D
  E --> F[Ranked memories<br/>+ citations]
  G[Audit log<br/>actor · action · patient · ts] -.-> B & C & E

Loading

What it adds over raw mem0

• Patient scoping — every memory is namespaced to a patient_id; a search can never return another patient's data. Cross-tenant isolation is enforced in the service, not left to the caller.
• PHI redaction — names, emails, phone numbers, MRNs, dates of birth and Medicare-style numbers are scrubbed before anything is persisted. Defence in depth even for "already de-identified" input.
• Audit trail — actor, action, patient, and timestamp for every add/search/delete, the 21 CFR 11 pattern.
• Agent tool — a ready-to-drop remember / recall tool for CrewAI or LangGraph agents.

Quickstart

Prerequisites: Python 3.11+. Runs offline with the local backend — no API key needed. For the real mem0 backend, set MEM0_ENABLED=1 and an LLM key (see .env.example).

git clone https://github.com/skalaliya/clinical-memory && cd clinical-memory
pip install -e ".[dev]"           # or: uv sync

uvicorn clinical_memory.api:app --reload      # http://localhost:8000/docs

Add and recall a memory:

curl -X POST localhost:8000/memories -H "Content-Type: application/json" -d '{
  "patient_id": "P-001",
  "actor": "dr.smith",
  "text": "Patient John Doe (DOB 1980-04-12) prefers morning appointments and is allergic to penicillin."
}'
# stored text is redacted: "[NAME] (DOB [DATE]) prefers morning appointments and is allergic to penicillin."

curl "localhost:8000/memories/search?patient_id=P-001&query=penicillin%20allergy&actor=dr.smith"
# returns the penicillin-allergy memory — scoped to P-001 only

Agent tool

from clinical_memory.agent_tool import make_memory_tools

remember, recall = make_memory_tools(patient_id="P-001", actor="care-agent")
remember("Patient wants results by SMS, not email.")
recall("how does the patient want to be contacted?")

Stack

Python 3.12 · FastAPI · mem0 (optional real backend) · pgvector · Pydantic · pytest · ruff · Docker · GitHub Actions

Design notes

• Governed wrapper, not a fork — mem0 does the hard memory work; this repo is the thin, auditable clinical layer around it. That separation is the point.
• Local-first — a deterministic in-process backend makes the service runnable and testable with no external services or keys; flip MEM0_ENABLED=1 for the real thing.
• Redact before persist — PHI never reaches the store, so the vector index and any downstream copy are already clean.

Roadmap

• Neo4j graph backend for relationship memory (conditions ↔ medications)
• Configurable retention windows + right-to-be-forgotten purge
• Presidio-based PHI detection to complement the regex gate
• Streamlit memory inspector

License

MIT