# Profile Isolation & Memory Layering

This folder is the readable map for the **system profile / principal profile / session context** split.

Read order:
1. `technical-design.md` — architecture and precedence rules
2. `checklist.md` — implementation and acceptance checklist
3. `implementation-status.md` — what has already landed in code and what still needs review
4. `restart-recovery-runbook.md` — safe gateway/api_server/OpenWebUI restart and recovery workflow
5. `closing-notes.md` — merge/rollout summary for the latest hardening batch
6. `issue-body-templates.md` — GitHub issue body templates for this workstream
7. `README.md` — quick file map and why these files exist

## What belongs where

- **System profile**
  - Global rules shared by every user
  - Admin-only edits from the local machine
  - Examples: product policy, security rules, output style, platform-wide behavior

- **Principal profile**
  - One profile per canonical principal
  - Bound to the verified email / platform identities for that person
  - Examples: personal name preference, delivery preference, verified email, local habits

- **Session context**
  - Temporary turn-by-turn facts for the current conversation
  - Must not be written back as permanent profile state unless it is a durable preference

## Code paths to inspect when changing this flow

- `agent/prompt_builder.py`
  - prompt assembly order
  - memory injection boundaries
  - identity-only prompt blocks

- `agent/shared_knowledge.py`
  - global reusable knowledge layer
  - content sanitization for shared FAQ-style notes

- `gateway/principal_profiles.py`
  - principal-id to profile-path mapping
  - creation / resolution of per-principal profile directories

- `hermes_cli/subcommands/memory.py`
  - built-in memory reset commands
  - what is and is not affected by memory provider commands

## Practical rule

If a fact answers "is this about everyone, or just this person?" then:
- everyone -> system profile / shared knowledge
- just this person -> principal profile
- just this turn -> session context

If you cannot tell, fail closed and keep it out of the permanent layer.