v0.0.2는 클린 릴리스 (clean release)입니다. 이 프로젝트를 추적해 오셨다면, 가장 눈에 띄는 변화는 간단하면서도 시급했던 것입니다. 모든 하드코딩된 개인 경로 (hardcoded personal path)가 제거되었으며, 휴대 가능한 $AGENT_HOME 기본 디렉토리 (base directory)로 대체되었습니다. 더 이상 설정 파일에 /home/someone/...과 같은 정보가 유출되지 않으며, 저장 인덱스 (storage indexes)에 절대 경로 (absolute paths)가 박혀 있는 일도 없습니다. 환경 변수 (environment variable) 하나만 설정하면 전체 지식 저장소 (knowledge store)를 깔끔하게 이동할 수 있습니다.

이번 릴리스는 두 가지 요소의 상호작용에 관한 것입니다: 외부 소스로부터 지식을 수집하는 것과, 그 결과로 생성된 메모리 (memory)를 유용하게 유지되도록 관리하는 것입니다. 실제로 무엇이 바뀌었는지 살펴보겠습니다.

$AGENT_HOME 경로 전환

이전 버전에는 좋지 않은 습관이 있었습니다. 수집 메타데이터 (collection metadata)와 메모리 저장소 (memory store)에 절대 경로 (absolute paths)를 포함시킨 것이었습니다. 이로 인해 백업, 컨테이너 이동, 그리고 다중 기기 동기화 (multi-machine sync)가 매우 번거로웠습니다. v0.0.2는 이 모든 것을 단일화된, 해결된 기본 디렉토리 (resolved base directory)로 대체합니다.

이 도구는 시작 시 $AGENT_HOME을 읽습니다. 설정되어 있지 않으면 기본 위치로 대체되지만, 실제 배포를 위한 권장 사항은 명시적입니다:

export AGENT_HOME=/opt/agent-data
mkdir -p "$AGENT_HOME"/{collections,memory,index}

이후의 모든 쓰기 작업 — 가공되지 않은 수집 콘텐츠 (raw collected content), 추출된 전사 데이터 (extracted transcripts), 정규화된 기사 텍스트 (normalized article text), 그리고 메모리 인덱스 (memory index) — 는 모두 $AGENT_HOME 아래로 들어갑니다. 이제 인덱스 내부의 상대 경로 (relative paths)가 표준이 됩니다. 변수 하나를 변경하고 재인덱싱 (re-index) 단계를 다시 실행함으로써 전체 저장소를 이동할 수 있습니다. 이것이 바로

• 웹 페이지 (Web pages): 페처 (fetcher)가 원본 HTML을 가져와서 불필요한 요소 (boilerplate)를 제거하고, 정규화된 (normalized) 기사 또는 페이지 콘텐츠를 저장합니다. URL, 가져온 시간, 제목, 사이트와 같은 메타데이터 (Metadata)도 함께 캡처됩니다. 여기서 핵심적인 개선 사항은 저장된 기록이 자기 완결적 (self-contained)이라는 점입니다. 즉, 기본적인 검색을 위해 원본 URL에 실시간으로 의존할 필요가 없습니다.
• 비디오 (Video): 비디오 수집 (ingestion)은 전사 데이터 (transcript)를 기반으로 합니다. 도구가 전사 데이터 또는 자막 트랙을 가져와 이를 기본 콘텐츠로 저장하며, 비디오 URL과 재생 시간을 메타데이터로 저장합니다. 이를 통해 메모리 저장소의 텍스트 검색 가능성을 유지하며, 미디어 캐싱 (media caching)을 명시적으로 활성화하지 않는 한 대용량 바이너리 파일을 저장하는 것을 방지합니다. 개발자를 위한 팁: 비디오 입력을 "바이트 (bytes)가 아닌 전사 데이터를 가져오는 것"으로 생각하세요.
• 기사 (Articles): 기사 수집 (ingestion)은 구조화된 콘텐츠를 처리하며, 일반적으로 RSS/Atom 피드 또는 직접적인 기사 URL로부터 가져옵니다. 파서 (parser)는 본문, 저자, 발행일 및 첨부된 모든 태그를 추출합니다. 기사는 명확한 콘텐츠 경계가 있을 것으로 기대되기 때문에 일반적인 웹 페처 (web fetcher)보다 더 엄격하게 작동합니다.

수집된 각 항목은 고유한 ID를 부여받으며 $AGENT_HOME/collections/<source-type>/에 기록됩니다. 원본 페치 (raw fetch) 데이터는 정규화된 콘텐츠와 분리되어 보관되므로, 원본을 잃지 않고도 재처리하거나 디버깅할 수 있습니다.

메모리 관리 (Memory Management): 수집 이후에 일어나는 일

관리 없는 수집은 그저 파일 더미에 불과합니다. 메모리 계층 (memory layer)은 이것을 단순한 폴더가 아닌 지식 '저장소 (store)'로 만드는 역할을 합니다.

v0.0.2에서 메모리 관리는 다음을 포함합니다:

• 콘텐츠 해시를 통한 중복 제거 (Deduplication by content hash): 새로운 항목이 수집될 때, 도구는 정규화된 텍스트의 해시 (hash)를 계산합니다. 만약 메모리 인덱스 (memory index)에 동일한 해시가 이미 존재한다면, 새 항목은 중복으로 표시되며 설정 (config)에 따라 병합되거나 건너뛰어집니다. 이를 통해 동일한 기사나 비디오 스크립트 (transcript)가 중복되어 쌓이는 것을 방지합니다.
• 제목 및 엔티티 정규화 (Title and entity normalization): 제목에서 불필요한 접미사("- YouTube", "| Site Name" 등)를 제거합니다. 엔티티 (entity) 언급은 휴리스틱 (heuristically) 방식으로 추출되어 태그 (tag)로 저장되므로, 이후 검색 (retrieval) 시 단순한 문자열 일치가 아닌 개념 (concept) 단위로 매칭할 수 있습니다.
• 단일 추가 전용 메모리 인덱스 (A single append-only memory index): 모든 수집 이벤트는 $AGENT_HOME/memory/index에 레코드를 추가합니다. 이 파일은 줄바꿈으로 구분된 JSON (newline-delimited JSON) 파일이며, 한 줄에 하나의 레코드가 기록됩니다. 이것은 데이터베이스 (database)가 아니라 로그 (log)입니다. tail 명령어로 확인하거나, 표준 Unix 도구로 처리하거나, 자체 검색 엔진 (search engine)에 로드할 수 있습니다. 추가 전용 (append-only) 방식을 유지함으로써 백업을 매우 쉽게 만들고, 라이브 서버 프로세스 (live server process)의 복잡성을 피할 수 있습니다.
• 망각 및 가지치기 작업 (Forget and prune operations): 메모리 관리 (memory management)는 단순히 추가하는 것만을 의미하지 않습니다. 이번 릴리스 (release)는 ID를 통한 항목 삭제와, 누락된 파일에 대한 참조를 제거하기 위한 인덱스 가지치기 (pruning) 기능을 지원합니다. 이것은 자연스러운 망각 (decay)이나 자동화된 망각이 아니라 명시적인 유지보수 (explicit maintenance)이며, 수집된 데이터가 오래되었을 때 제어권을 제공합니다.

설계 철학은 메모리 인덱스 (memory index)가 항상 수집 폴더 (collection folders)로부터 재현 가능해야 한다는 것입니다. 만약 인덱스를 삭제하더라도, $AGENT_HOME/collections/를 스캔하고 모든 항목의 해시를 다시 계산함으로써 인덱스를 재구축할 수 있습니다. 인덱스는 편의를 위한 도구일 뿐, 진실의 원천 (source of truth)이 아닙니다.

v0.0.2가 수행하지 않는 작업

기대치를 정확하게 유지하십시오. 이번 릴리스에는 시맨틱 임베딩 (semantic embeddings)이나 벡터 검색 (vector search)이 포함되어 있지 않습니다. 이는 향후 마일스톤 (milestone)입니다. 또한 웹을 자율적으로 크롤링 (crawl)하지 않습니다. 수집은 명시적인 입력에 의해 트리거되는 풀 기반 (pull-based) 방식입니다. 비디오 수집 (ingestion)은 오디오 전사 (audio transcription)가 아닌 스크립트 (transcript)와 자막 (subtitle)을 통해 작동합니다. 이러한 기능이 필요하다면, 아직 구현되지 않았습니다.

마이그레이션 및 테스트 (Migration and Testing)

v0.0.1에서 업그레이드하는 경우, 설정 파일(config files)을 수정해야 할 수도 있습니다. 이전의 경로 패턴(path patterns)은 자동으로 마이그레이션되지 않습니다. 권장되는 이동 방법은 $AGENT_HOME을 설정하고, 주요 URL에 대해 수집(collection)을 다시 실행하는 것이며, 절대 경로를 포함한 이전 인덱스 레코드(index records)는 해결되지 않을 수 있음을 인지하는 것입니다. 데이터 자체는 일반 텍스트(plain text)와 JSON 형식이므로 읽을 수 있지만, 인덱스 항목(index entries)은 설계상 오래된 상태(stale)로 남게 됩니다.

먼저 임시 $AGENT_HOME으로 실행하여 단일 웹 페이지와 단일 비디오 스크립트(video transcript)를 수집한 다음, 저장된 파일들을 점검해 보십시오. 경로가 올바르게 보이고 인덱스 레코드가 $AGENT_HOME 상대 경로를 참조하고 있다면 문제없습니다.

v0.0.2는 기초 릴리스(foundation release)입니다. 이 버전은 휴대 가능한 저장소(portable storage), 깔끔한 수집(clean collection), 유지 관리 가능한 메모리 로그(maintainable memory log)와 같은 기반 작업(plumbing)을 올바르게 수행합니다. 이는 그 위에서 무언가를 구축하기에 충분한 토대가 됩니다.