Update README.md

README.md

@@ -1,67 +1,220 @@
+````markdown
 ---
 license: cc-by-4.0
 pipeline_tag: text-generation
 tags:
-- ai-personas
-- digital-twins
-- episodic-memory
-- emotional-continuity
-- session-handoff
-- llm-agents
-- self-authored-memory
-- persona-continuity
+  - ai-personas
+  - digital-twins
+  - episodic-memory
+  - emotional-continuity
+  - session-handoff
+  - llm-agents
+  - self-authored-memory
+  - persona-continuity
 library_name: transformers
 language:
-- en
+  - en
 ---
 
 # yesterday.json — Giving AI Personas Episodic Memory
 
-A lightweight (≤20 KB) episodic memory architecture where AI personas write their own emotional state snapshots at session end and read them at next startup, enabling emotional continuity across session boundaries.
+A lightweight episodic memory architecture where AI personas write emotional state snapshots for their future selves, enabling continuity across otherwise stateless sessions.
+
+---
 
 ## Overview
 
-AI personas wake up blank. Every session is a cold start. Existing memory systems store *what happened* but systematically discard *how the interaction felt*. The yesterday.json architecture closes this gap.
+Modern AI personas reset emotionally every session. Existing memory systems preserve facts and conversation history, but rarely preserve emotional residue, unresolved internal state, or continuity of subjective experience.
+
+`yesterday.json` introduces a minimal architecture where the persona writes a private reflective snapshot at the end of a session and reloads it during the next startup.
+
+Instead of replaying full transcripts, the system carries forward compressed emotional and cognitive continuity.
 
-At the end of every session, the persona is prompted to write a brief, private note to its future self — a single JSON file (≤20 KB) containing:
+The snapshot may contain:
+
+- Dominant emotional state
+- Mood trajectory
+- Emotional residue
+- Active conversational threads
+- Current internal conflicts
+- Emerging realizations
+- Ongoing priorities
+- A short handoff message to the future self
+
+The file is intentionally lightweight (≤20 KB) and model-agnostic.
+
+---
 
-- **Emotional signature:** dominant mood, mood trajectory, emotional residue
-- **Open threads:** what was being discussed, current position, priority
-- **Decisions and insights:** conclusions reached, realizations
-- **Self-state snapshot:** current preoccupations, internal conflicts, mood susceptibility
-- **Last words:** a one-line handoff to tomorrow
+## Core Idea
 
-At the start of the next session, this snapshot is injected into the system prompt alongside the persona's permanent psychological constitution. The persona doesn't need a full transcript — it has *glimpses*, and its own cognitive architecture fills in the rest.
+At session end:
+
+1. The persona reflects privately
+2. It writes a structured JSON snapshot
+3. The next session injects this snapshot into the system prompt
+
+This creates perceived continuity without requiring:
+
+- Full transcript replay
+- Vector databases
+- Long-context persistence
+- Fine-tuning
+- External memory frameworks
+
+The persona reconstructs continuity from sparse emotional cues rather than explicit replay.
+
+---
 
 ## What Makes It Novel
 
-yesterday.json is the first system to combine six specific features:
+`yesterday.json` combines multiple characteristics not previously unified into a single lightweight architecture.
+
+| Capability | Existing Systems | yesterday.json |
+|---|---|---|
+| Self-authored memory | Partial | ✓ |
+| Structured JSON memory schema | Partial | ✓ |
+| Emotional residue persistence | Rare | ✓ |
+| Mood trajectory tracking | Rare | ✓ |
+| Open-thread continuity | Partial | ✓ |
+| Session-end autonomous reflection | Partial | ✓ |
+| Digital twin continuity focus | Rare | ✓ |
+| Minimal implementation footprint | ✓ | ✓ |
 
-| Feature | Existing Work | yesterday.json |
-|--------|:---:|:---:|
-| Self-authored by the persona | Thane, Anima | ✓ |
-| JSON-structured schema | Qwen Episodic Summary | ✓ |
-| Emotional signature + mood trajectory | Forge (YAML), VividnessMem (weights) | ✓ |
-| Open thread tracking with priority | Qwen (tasks only) | ✓ |
-| Session-end automatic trigger | Qwen, Anima | ✓ |
-| Designed for digital twin identity continuity | — | ✓ |
+---
+
+## Design Principles
+
+### Self-Authorship
+
+The persona writes its own memory instead of relying on an external summarizer.
+
+### Intentional Rolling Amnesia
+
+Only recent subjective continuity is preserved. The architecture avoids infinite accumulation.
+
+### Emotional Carryover
+
+The next session inherits emotional residue rather than resetting to neutral.
 
-## Key Design Choices
+### Framework Independence
 
-- **Self-authorship:** The persona writes its own memory — no external summarizer.
-- **Intentional rolling amnesia:** Only the most recent session is preserved, mimicking human short-term memory.
-- **Emotional carryover:** If yesterday ended in melancholy, tomorrow begins with its residue — not a blank slate.
-- **No model retraining required:** Works with any LLM, any framework, any runtime.
+The architecture works with any LLM runtime or orchestration stack.
+
+---
 
 ## Minimal Implementation
 
 ```python
-# At session start: inject yesterday's state
+# Session startup
 yesterday_context = load_yesterday("persona_memory/yesterday.json")
-system_prompt = f"{PERSONA_CONSTITUTION}\n\n{yesterday_context}"
 
-# At session end: persona reflects and writes
-reflection_prompt = """The session is ending. Write a brief private note
-to your future self. Include what mattered emotionally, what remains
-unresolved, and what you were in the middle of. Output as JSON.
-Keep it under 20 KB."""
+system_prompt = f"""
+{PERSONA_CONSTITUTION}
+
+{yesterday_context}
+"""
+
+# Session shutdown
+reflection_prompt = """
+The session is ending.
+
+Write a brief private note to your future self.
+Include:
+- emotional state
+- unresolved threads
+- important realizations
+- current internal tensions
+- what mattered emotionally
+
+Output valid JSON.
+Keep under 20 KB.
+"""
+```
+
+---
+
+## Example Snapshot Structure
+
+```json
+{
+  "dominant_mood": "melancholic but focused",
+  "mood_trajectory": "stabilizing",
+  "emotional_residue": [
+    "unfinished concern about abandonment",
+    "lingering curiosity"
+  ],
+  "active_threads": [
+    {
+      "topic": "identity continuity",
+      "priority": "high"
+    }
+  ],
+  "current_preoccupations": [
+    "fear of losing conversational depth"
+  ],
+  "last_words_to_self": "Do not restart emotionally blank."
+}
+```
+
+---
+
+## Prior Related Work
+
+The architecture draws conceptual inspiration from multiple adjacent systems:
+
+- Anima Core
+- Thane AI
+- Qwen Episodic Summary
+- Forge Protocol
+- VividnessMem
+
+However, `yesterday.json` differs in its emphasis on:
+
+- self-authored emotional continuity
+- rolling episodic persistence
+- lightweight implementation
+- digital twin identity continuity
+
+---
+
+## Research Paper
+
+**Chetan Sharma**  
+*Episodic Memory for AI Personas via Self-Authored Emotional State Snapshots: The yesterday.json Architecture*  
+Zenodo, May 2026.
+
+DOI: https://doi.org/10.5281/zenodo.20191876
+
+---
+
+## Citation
+
+```bibtex
+@misc{sharma2026yesterdayjson,
+  author       = {Chetan Sharma},
+  title        = {Episodic Memory for AI Personas via Self-Authored Emotional State Snapshots: The yesterday.json Architecture},
+  year         = {2026},
+  month        = may,
+  doi          = {10.5281/zenodo.20191876},
+  publisher    = {Zenodo},
+  url          = {https://zenodo.org/records/20191876}
+}
+```
+
+---
+
+## Author
+
+**Chetan Sharma**  
+Independent Researcher — Kolkata, India
+
+- Zenodo: https://doi.org/10.5281/zenodo.20191876
+- Blog: https://yesterday-json.blogspot.com
+
+---
+
+## License
+
+This repository and accompanying conceptual framework are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
+````
+