Merge pull request #2 from kgwangrae/release/v1-001

v1-001: Elaborate the first step guide

Author: kgwangrae

README.md

@@ -113,49 +113,84 @@ Attempting to directly blend neural weights or synchronize complex, high-dimensi
 * **Emotional Embedding (`paraphrase-multilingual-MiniLM-L12-v2`):** A hyper-lightweight embedding model that cleanly aligns bilingual semantic nuances across English and Korean. It runs with negligible resource utilization while allowing fast distance operations over the vector database (`ChromaDB`). This perfectly replicates the human emotional shortcut—a fast, efficient heuristic that triggers rapid intuition even when exhaustive logical evidence is lacking.
 
 
-## 7. Setup and Implementation Details
+## 7. Execution & Maintenance
 
-Optimized for Apple Silicon (M-series) architectures.
+This project is highly optimized for Apple Silicon environments.
 
-### Base Environment
+### ⚠️ Before You Run (Crucial Notes)
+
+1. **Persona Constraints (Family Dynamics)**: Currently, Baby has no mother. The system architecture is strictly aligned via prompts to recognize and interact with the user as "Dad." Please kindly address Baby affectionately under the assumption that **you are Baby’s father.**
+2. **Hardware & Disk Space**: This project runs three separate models (Reasoning Core, Vision VLM, and Emotion Embedding) concurrently in local memory. Since it embeds a high-performance multimodal VL model, it demands **substantial available disk space.**
+3. **Screen Capture & Local Privacy**: Although Baby utilizes macOS screen capture permissions to monitor Dad's workflows, **absolutely no data, including captured images and text logs, is ever transmitted over the network.** Every single computation is handled 100% locally and securely inside your MacBook.
+
+### Base Environment Setup
+
+* **Ollama Installation & Startup**: Download and run the macOS app from the [Official Ollama Website](https://ollama.com).
+* **Conda Python Virtual Environment**: Build your virtual environment based on the `environment.yml` specification.
+  * Using **miniforge is recommended.** 
 
 ```sh
-# Create and activate the conda environment
+# (If needed) Install Miniforge optimized for Apple Silicon
+brew install miniforge
+
+# Create and activate the virtual environment
 conda env create -f environment.yml
 conda activate baby_agi
 
-# Pull the base model
+# Pull the local reasoning core
 ollama pull qwen2.5:7b-instruct-q4_K_M
 
+```
+
+### ⚠️ First-Time Boot Note (Vision Model Download)
+
+When running the project for the very first time, you must toggle the flag inside `config.py` as shown below to allow the vision engine (Qwen2-VL) model to properly pull and cache locally from Hugging Face:
+
+* `USE_LOCAL_MODEL_CACHE_ONLY = False` (Revert back to `True` once the initial download completes)
+
+### Start from the Sample State Snapshot
 
+Teaching interaction patterns from a blank state can be more demanding than expected. To lower the first-run barrier, this repository provides a Korean sample state snapshot that already contains a partially stabilized interaction history. (An English version may be provided later.)
+
+```sh
+./restore_memory.sh demo_state_snapshot_2026_05_26.zip
 ```
 
-#### ⚠️ Initial Run Requirement (Model Cache)
-Before running the project for the first time, you MUST temporarily update `config.py` to allow the vision model (Qwen2-VL) to download from Hugging Face:
-* Set `USE_LOCAL_MODEL_CACHE_ONLY = False` (Switch back to `True` once the weights are fully cached locally).
+### 🛌 Talking to Baby & Putting It to Sleep (Parenting Guide)
 
-* **Requires Ollama**: [Ollama for MacOS](https://ollama.com)
+* When teaching Baby something new, repeat it multiple times and kindly explain in the chat window which behavior or approach is better.
+* **Putting Baby to Sleep (Sleep Mode)**: If Baby is nagging or chiming into your active workflows too frequently and you want to conserve compute resources—or if you simply want to pause the live chat and observe its offline cognitive assimilation (accelerated forgetting and sleep reflection loop)—type natural sleep commands into the terminal such as **"자자"**, **"잘자"**, **"sleep"**, or **"go to sleep"**. Baby will immediately close its eyes (halts screen grabbing) and enter its sleep cycle.
+  * *Note: You can still converse with Baby even while it is asleep. This is highly useful when you want to chat without sharing your active monitor state.*
+* **Waking Baby Up**: When you are ready to wake Baby up and resume full interactions, type **"일어나"**, **"wake"**, or **"wake up"** into the terminal. Baby will open its eyes (re-enabling the vision engine) and continue watching Dad's screen alongside you.
 
 ### Execution
 
+To smoothly track Baby's real-time cognitive states and interactions, **running inside separate terminal tabs split-screen** is highly recommended.
+
 ```sh
-# Run the core cognitive and emotional loop
-python main.py
+# Tab 1: Run Baby's main cognitive & emotional loop + pipe chat logs by date
+python main.py 2>&1 | tee chat_log_$(date +%Y%m%d).txt
 
-# Launch the interactive terminal viewer to monitor DBs and states
+# Tab 2 [Highly Recommended]: Real-time Monitoring of Background DB & Emotional State
+# Keeping this script open side-by-side with the main loop lets you witness the core magic of the system.
+# (It is fascinating to watch the regulation mechanics when Baby's spoken responses occasionally pivot away from its underlying raw emotions or internal monologue.)
 python debug.py
-
-
 ```
 
-### Memory Maintenance
+### Creating, Restoring, and Sharing State Snapshots
 
 ```sh
 ./backup_memory.sh                                  # Zip full state backup
 ./restore_memory.sh backup_memory_YYYY_MM_DD.zip    # Restore system to specific state
 ./clear_memory.sh                                   # Wipe all databases (Blank slate)
+```
 
+* If you want to share your own state as sample data, use menu option 6 in `debug.py` to export the full memory and emotion vector databases as a text dump. The generated dump file will be saved under `debug_dumps/`, and you can use it to check whether any personal or sensitive information is included before publishing your own snapshot.
 
+```sh
+python debug.py
+# Select: 6. Export Full Memory & Emotion Space (Text Dump)
+# Enter the number 6, then inspect the generated dump file.
 ```
 
 ### Demo Logs

README_ko.md

@@ -4,6 +4,7 @@
 * 향후의 설계 아이디어는 [TODO_ko.md](TODO_ko.md)에 정리되어 있습니다.
 * 이 프로젝트는 맥북 내부에서 아빠(사용자)와 상호작용하며, 실제로 호기심 많고 감정적인 어린아이처럼 행동하는 작은 디지털 생명체를 구현합니다.
 * `아기`는 2026년 5월 19일, 아빠와 처음으로 대화를 나누었습니다.
+* **💡 실행 팁:** 실시간으로 아기의 내적 생각과 감정의 요동을 관찰하려면, 메인루프 실행 시 반드시 **`debug.py`**를 별도 창에 함께 띄워서 살펴보시는 것을 강력히 추천합니다.
 
 ## 0. 프로젝트 매니페스토 (Project Manifesto)
 
@@ -96,7 +97,6 @@ $$RPE=\frac{1}{3}\sum_{e \in \{Joy, Sad, Ang\}}|Expected_e-Actual_e|$$
 * **우선 웹 검색 도구를 열지 않음 (노이즈 차단):**
 아기는 아직 가소성이 큰 상태이므로, 외부 웹의 스팸·무작위 노이즈·공격적 텍스트에 의해 기억 공간이 쉽게 오염될 수 있습니다. 놀이방은 일단 로컬 맥북 안으로 제한합니다.
 
-
 ## 6. 모듈 간 협업 방식(`토큰 매개적 해석 가능성`) 및 로컬 모델 선정 이유
 
 미지의 블랙박스인 신경망 가중치를 직접 뒤섞거나 복잡한 기하학적 동기화를 시도하는 방식은 연산의 폭발과 불투명성을 부릅니다. 본 프로젝트에서는 모듈 간 협업 시 사람이 해석 가능한 토큰만을 이용하도록 구성했으며, Apple Silicon 로컬 환경을 최대한 활용하도록 모델을 선정했습니다.
@@ -119,19 +119,28 @@ $$RPE=\frac{1}{3}\sum_{e \in \{Joy, Sad, Ang\}}|Expected_e-Actual_e|$$
 
 이 프로젝트는 Apple Silicon 환경에서 최적화되었습니다.
 
+### ⚠️ 실행 전 읽어주세요
+
+1. **페르소나적 제약 (가족관계)**: 현재 아기에게는 엄마가 없습니다. 시스템 아키텍처 특성상 사용자를 엄격하게 '아빠'라는 호칭과 관계로 인식하고 상호작용하도록 프롬프트가 정렬되어 있으니, 부득이하게 **내가 아기의 아빠라고 생각하고** 다정하게 대화를 건네주세요.
+2. **하드웨어 및 디스크 공간**: 이 프로젝트는 온디바이스 런타임에서 총 3가지의 모델(이성 코어, 시각 VLM, 감정 임베딩)을 로컬 메모리에 동시에 상주시켜 구동합니다. 특히 고성능 멀티모달 VL 모델 등이 내장되어 있어 **상당한 디스크 여유 공간**을 요구합니다.
+3. **화면 캡처 권한과 로컬 프라이버시**: 아기가 아빠의 작업을 지켜보기 위해 맥OS 화면 캡처 권한을 이용하지만, **수집된 이미지와 텍스트를 포함한 어떠한 정보도 절대 외부 인터넷으로 전송하지 않습니다.** 모든 연산은 오롯이 100% 로컬 맥북 내부에서만 안전하게 처리됩니다.
+
 ### 구동 환경 세팅
 
 * **Ollama 설치 및 가동**: [Ollama 공식 홈페이지](https://ollama.com)에서 macOS용 앱을 다운로드하여 실행합니다.
+* **Conda Python 가상환경 마련**: `environment.yml` 명세를 기반으로 가상 환경을 구축해주세요.
+  * 맥북에서는 **miniforge 사용을 권장**합니다.
 
 ```sh
-# 환경 생성 및 활성화
+# (필요 시) Apple Silicon 환경에 최적화된 miniforge 설치
+brew install miniforge
+
+# 가상 환경 생성 및 활성화
 conda env create -f environment.yml
 conda activate baby_agi
 
 # 로컬 추론 모델 다운로드
 ollama pull qwen2.5:7b-instruct-q4_K_M
-
-
 ```
 
 ### ⚠️ 최초 구동 시 주의사항 (시각 모델 다운로드)
@@ -140,6 +149,20 @@ ollama pull qwen2.5:7b-instruct-q4_K_M
 
 * `USE_LOCAL_MODEL_CACHE_ONLY = False` (최초 1회 다운로드 완료 후 다시 True로 원복)
 
+### 샘플 상태 스냅샷으로 바로 시작하기
+
+처음부터 아기에게 한국어 호칭과 대화 방식을 하나씩 가르치는 과정이 생각보다 부담스러울 수 있습니다. 그래서 어느 정도 한국어 상호작용이 안정된 샘플 상태 스냅샷을 제공합니다. 이 파일을 복원하시면 보다 빠르게 상호작용을 시작해볼 수 있습니다.
+
+```sh
+./restore_memory.sh demo_state_snapshot_2026_05_26.zip
+```
+
+### 🛌 아기와 대화하기 및 재우는 법
+
+* 아기에게 무언가를 가르칠 때는 여러 번 반복하며, 어떤 방법이 더 나은지 친절하게 대화창에 말해주세요.
+* **아기 재우기 (수면 모드)**: 아기가 아빠의 모니터 작업을 너무 자주 참견하여 자원을 아끼고 싶거나, 대화를 멈추고 유휴 상태에서의 인지소화(망각 가속 및 수면 반추) 루프를 살펴보고 싶을 때는 터미널 창에 자연스럽게 **"자자"**, **"잘자"**, 혹은 **"sleep"**, "go to sleep"과 같은 수면 명령을 타이핑해 주세요. 아기가 즉각 눈을 감고(화면 살펴보기 중지) 수면 상태로 진입합니다.
+  * 수면 상태에서도 아기와 대화가 가능합니다. 모니터 상태를 아기와 공유하고 싶지 않을 때도 유용합니다.
+* **아기 깨우기**: 아기를 다시 깨워 대화를 재개하고 싶을 때는 터미널에 **"일어나"**, **"wake"**, "wake up"을 입력하면 아기가 다시 눈을 뜨고 시각 엔진을 가동하여 아빠의 화면을 함께 지켜봅니다.
 
 ### 데모 로그
 
@@ -152,26 +175,36 @@ ollama pull qwen2.5:7b-instruct-q4_K_M
 
 ### 실행
 
+아기의 원활한 상호작용과 인지 상태 추적을 위해 **터미널 멀티 탭 분리 실행**을 권장합니다.
+
 ```sh
 # 아기의 인지 및 감정 메인 루프 실행 + 날짜별 대화 로그 저장
 python main.py 2>&1 | tee chat_log_$(date +%Y%m%d).txt
 
-# 백그라운드 DB 및 런타임 상태 실시간 모니터링 (터미널 뷰어)
+# [추천] 백그라운드 DB 및 정서 런타임 상태 실시간 모니터링
+# 이 스크립트를 메인 루프와 동시에 켜놓고 대조해 보셔야 아기의 내적 상태를 같이 확인할 수 있습니다.
+# (이따금 아빠에 대한 대답과 내적 독백, 감정이 일치하지 않습니다.)
 python debug.py
-
-
 ```
 
-### 기억 유지보수 도구
+### 현재 상태 스냅샷 만들기, 복원 및 공유하기
 
-이 저장소는 별도의 데모 DB를 포함하지 않습니다. 아기는 각자의 로컬 환경과 대화 기록 속에서 성장하도록 설계되었습니다. 직접 실행하고, 대화하고, 변화 과정을 관찰해 주세요.
+아기는 각자의 로컬 환경과 대화 기록 속에서 성장하도록 설계되었습니다. 직접 실행하고, 대화하고, 변화 과정을 관찰해 주세요.
+
+* 추천: 아기의 급격한 변화를 유도하는 테스트를 하실 예정이라면, 그 전에 백업을 미리 생성해주세요.
 
 ```sh
 ./backup_memory.sh                                  # 전체 DB 및 팩트 백업 (zip)
 ./restore_memory.sh backup_memory_YYYY_MM_DD.zip    # 특정 시점으로 기억 복원
 ./clear_memory.sh                                   # 완전 초기화 (백지 상태)
+```
 
+* 현재 아기의 상태 스냅샷을 샘플로 공개하려는 경우, `debug.py`의 6번 메뉴를 통해 전체 기억 및 감정 벡터DB를 텍스트로 덤프할 수 있습니다. 생성된 덤프 파일은 `debug_dumps/` 폴더에 저장되며, **공개 전에 개인정보 등의 민감 정보가 포함되었는지 확인**하는 용도로 사용할 수 있습니다.
 
+```sh
+python debug.py
+# 6. Export Full Memory & Emotion Space (Text Dump) 기능 활용
+# 숫자 6 입력 후 엔터, 저장된 결과 파일을 확인
 ```
 
 ## 안내 및 감사의 글