emma-hermes/docs/profile-isolation/README.md

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. issue-body-templates.md — GitHub issue body templates for this workstream
5. 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.