웹 페이지, 비디오 스크립트, 또는 긴 형식의 기사와 같이 다양한 소스로부터 정보를 수집하고 유지해야 하는 시스템을 구축하고 있다면, 절대 경로 (absolute paths)와 취약한 설정 (fragile configurations)을 다루는 과정에서 발생하는 마찰을 잘 알고 있을 것입니다. Knowledge-and-Memory-Management의 v0.0.2 릴리스는 이러한 문제를 해결합니다. 이번 버전은 모든 하드코딩된 개인 경로를 $AGENT_HOME으로 대체하여 배포의 휴대성 (portability)을 진정으로 확보하였으며, 지식 수집 파이프라인 (knowledge collection pipeline)을 강화했습니다. 에이전트 (agents)를 위한 신뢰할 수 있는 메모리 계층 (memory layer)이 필요한 개발자들에게 무엇이 바뀌었으며 이것이 왜 중요한지 살펴보겠습니다.

v0.0.2에서 수정된 사항 (및 변경 사항)

주요한 파괴적 변경 사항 (breaking change)은 /Users/you/projects/knowledge 또는 /home/user/data와 같이 절대 경로를 참조하는 이전의 모든 설정이 로드되지 않는다는 점입니다. 대신, 반드시 $AGENT_HOME 환경 변수 (environment variable)를 정의해야 합니다. 수집된 지식, 인덱스 (indexes), 메타데이터 (metadata)를 포함한 모든 내부 저장소는 이제 $AGENT_HOME/data 아래에 위치합니다. 이러한 작은 변화는 팀 간에 설정을 공유하거나 컨테이너 (containers)에 배포할 때 발생하는 "내 컴퓨터에서는 작동하는데" 문제를 제거합니다.

마이그레이션 (Migration)은 간단합니다: AGENT_HOME을 쓰기 가능한 디렉토리로 내보내고(export), 기존의 지식 컬렉션 (knowledge collections)이 해당 디렉토리를 가리키도록 설정하면 됩니다. 이번 릴리스에는 이전 설정을 스캔하고 경로를 변수로 다시 작성하는 마이그레이션 스크립트(scripts/migrate_paths.py)가 포함되어 있습니다.

v0.0.2의 지식 수집 (Knowledge Collection)

핵심 수집 엔진은 이제 웹 (web), 비디오 (video), 기사 (articles)라는 세 가지 명시적인 도메인 (domains)을 지원합니다. 각 도메인은 저장하기 전에 콘텐츠를 공통 메모리 형식 (common memory format)으로 정규화 (normalises)하는 전용 추출기 (extractor)를 가지고 있습니다.

• Web: 헤드리스 브라우저 (headless browser)를 사용하여 전체 페이지 콘텐츠를 가져오며, 내비게이션, 광고 및 페이월 (paywalls)을 제거합니다. 의미론적 구조 (semantic structure, 제목, 목록, 코드 블록)를 보존하며 깨끗한 Markdown 표현을 생성합니다.
• Video: 자동 음성 인식 (automatic speech recognition) 통합을 통해 YouTube, Vimeo 또는 로컬 미디어 파일에서 트랜스크립트 (transcripts)를 가져옵니다. 각 세그먼트에 타임스탬프를 찍고 가능한 경우 핵심 프레임 (key frames)을 추출합니다. 출력물은 재생 시간 및 화자 라벨과 같은 메타데이터 (metadata)가 포함된 검색 가능한 텍스트 트랜스크립트입니다.
• Articles: 긴 형식의 텍스트 (블로그 포스트, PDF, 연구 논문)에 최적화되어 있습니다. 구조화된 메타데이터 (제목, 저자, 발행일)를 추출하고, 임베딩 (embedding) 또는 요약 (summarisation)과 같은 후속 처리를 위해 구성 가능한 토큰 제한 (token limit)에 따라 콘텐츠를 청크 (chunks) 단위로 나눕니다.

모든 수집기 (collectors)는 공통 인터페이스인 KnowledgeSource(name, uri, domain, options)를 공유합니다. 이를 통해 별도의 커스텀 글루 코드 (glue code) 없이도 다양한 소스를 혼합하는 파이프라인 (pipeline)을 구축할 수 있습니다.

휴대 가능한 경로 컨벤션 (The Portable Path Convention)

$AGENT_HOME이 설정을 어떻게 단순화하는지 살펴보겠습니다. 다음은 YAML에서 지식 수집을 정의하는 예시입니다:

knowledge_sources:
  - name: tech_reference
    domain: web
...

이 파일이 로드되면 모든 ${AGENT_HOME} 참조는 환경 변수 (environment variable)로 확장됩니다. 더 이상 홈 디렉토리를 하드코딩할 필요가 없습니다. AGENT_HOME이 일관되게 설정되어 있다면 동일한 설정이 노트북, CI 러너 (CI runner), 또는 베어메탈 서버 (bare-metal server)에서 모두 작동합니다.

내부 메모리 관리 메커니즘 (Memory Management Under the Hood)

v0.0.2는 약하게 스키마가 강제되는 (weakly schema-forced) 메모리 모델을 도입합니다. 수집된 각 항목 (페이지, 트랜스크립트, 기사)은 다음과 같은 메모리 단위 (memory unit)가 됩니다:

• id (콘텐츠 + 소스의 해시 값)
• source (원본 URI)
• domain (web|video|article)
• content (정규화된 텍스트)
• metadata (JSON 블롭 (blob))
• created_at 및 updated_at 타임스탬프

중복 제거 (Deduplication)는 URI가 아닌 콘텐츠 해시 (content hash)를 사용합니다. 즉, 동일한 기사가 두 페이지에 나타나더라도 한 번만 저장됩니다. 만료 정책 (Expiration policies)은 $AGENT_HOME 디스크 사용량이 임계값(설정 가능, 기본값 85%)을 초과할 때 오래된 메모리를 순환(rotate)시킵니다.

새로운 CLI 명령인 agent-memory collect는 증분 스윕 (incremental sweep)을 실행합니다. 이 명령은 웹 소스에 대해 Etag 및 last-modified 헤더를 준수하며, 변경되지 않은 전사 데이터 (transcripts)는 건너뛰고, 소스 파일이 변경될 때만 기사를 다시 청킹 (re-chunk)합니다.

실무 고려 사항

• 기본값 없음: AGENT_HOME이 설정되지 않은 경우, 시스템은 명확한 에러 메시지와 함께 종료됩니다. 이는 명시적인 설정을 강제하여 임의의 디렉토리에 데이터가 실수로 기록되는 것을 방지합니다.
• 로깅 (Logging): 모든 수집 이벤트는 ${AGENT_HOME}/logs/collection.log에 구조화된 JSON Lines 형식으로 기록되어, 사용자의 모니터링 시스템에 쉽게 통합할 수 있습니다.
• 테스트: 이번 릴리스에는 모든 collect 명령에 --dry-run 플래그가 포함되어 있습니다. 이를 사용하여 데이터를 실제로 쓰지 않고 무엇이 수집될지 확인할 수 있습니다.

한 가지 더: 변경 로그(Changelog)의 "S"

주제 설명 끝에 붙은 "S"는 새로운 기능인 **요약 (Summaries)**을 암시합니다. v0.0.2에는 수집 후 실행되는 가볍고 설정 가능한 요약 단계가 내장되어 있습니다. 각 메모리 단위의 콘텐츠가 500 토큰 (tokens)을 초과하는 경우, 선택적으로 로컬 LLM 또는 API 호출을 통해 세 문장으로 된 요약을 생성합니다. 이 요약은 전체 콘텐츠와 함께 저장되며 더 빠른 검색 쿼리 (retrieval queries)를 위해 사용됩니다. 소스별로 options: { summarize: false }를 통해 이 기능을 비활성화할 수 있습니다.

운영 환경(production)에서 이는 평균 검색 지연 시간 (retrieval latency)을 절반으로 줄여주는데, 요약 벡터 (summary vector)가 전체 콘텐츠 벡터보다 작기 때문입니다. 물론, 수집 시점에 연산 시간 (compute time)을 비용으로 지불해야 합니다. 도메인별로 토큰 임계값을 조정하십시오.

시작하기

마이그레이션 스크립트를 실행하여 기존 v0.0.1 설치 버전을 업데이트한 다음, AGENT_HOME을 설정하십시오. 새로 시작하는 경우 다음과 같이 진행합니다:

export AGENT_HOME=/path/to/agent
pip install knowledge-memory==0.0.2
agent-memory init
...

init 명령은 디렉토리 구조와 기본 설정 (config) 템플릿을 생성합니다. 그 후, 데이터 수집 (ingestion) 대상에 맞춰 knowledge_sources.yaml 파일을 편집하십시오.

v0.0.2는 기능이 과하게 포함된 (feature-bloated) 릴리스가 아닙니다. 이는 지식 관리 (knowledge management)를 재현 가능하고 유지보수 가능하게 만들기 위한 의도적인 엔지니어링 결정들의 집합입니다. 경로 수정 (path fix) 하나만으로도 업그레이드할 가치가 충분합니다. 이를 새로운 구조화된 수집기 (structured collectors) 및 선택적 요약 (optional summaries) 기능과 결합하면, 기억이 필요한 모든 에이전트 (agent)를 위한 견고한 기반을 갖추게 됩니다.