대화 기록기에서 컨텍스트 엔진으로: AI 개발을 위한 로컬 우선(Local-First) 메모리 구축

ContextVault 1.3이 백엔드, 추적, 또는 숨겨진 AI 호출 없이 브라우저 대화, 터미널 세션, 코딩 에이전트(coding-agent)의 결정을 하나의 검색 가능한 로컬 컨텍스트 엔진(context engine)으로 통합하는 방법.

당신은 코딩 에이전트와 함께 Redis 연결 버그를 해결하기 위해 45분을 보냅니다. 함께 근본 원인을 찾고, 수정 사항을 테스트하며, 어디에도 문서화되지 않은 설정 세부 사항을 발견합니다. 그러다 컨텍스트 윈도우(context window)가 가득 찹니다. 2주 후, 동일한 버그가 스테이징(staging) 환경에서 나타납니다. 원래의 세션은 사라졌고, 브라우저 대화는 묻혀버렸으며, 다음 에이전트는 당신이 이미 발견한 것에 대해 아무것도 모릅니다. 당신은 다시 시작합니다. 이것이 바로 컨텍스트 파편화(context fragmentation)입니다. 프로젝트 지식이 ChatGPT 대화, 코딩 에이전트 세션, 터미널, 계정, 모델, 그리고 제한된 컨텍스트 윈도우에 흩어져 있는 상태를 말합니다. 이는 모든 AI 보조 워크플로우(AI-assisted workflow)에 조용한 세금을 부과합니다.

대화를 내보내는(Exporting) 것이 도움이 되긴 하지만, 부분적일 뿐입니다. Markdown 내보내기 파일로 가득 찬 디렉토리는 여전히 서로 연결되지 않은 파일들로 가득 찬 디렉토리일 뿐입니다. 정보는 보존되지만, 프로젝트 메모리(project memory)로서 조직화되지는 않습니다. 그 차이가 ContextVault의 방향을 바꾸었습니다. 브라우저 대화 기록기로 시작된 것은 더 넓은 아이디어를 중심으로 설계된 로컬 우선(local-first) 컨텍스트 엔진으로 진화했습니다:

Git이 코드를 추적한다면, ContextVault는 컨텍스트를 추적한다.

대화 내보내기만으로는 충분하지 않은 이유

저는 원래 여러 LLM 플랫폼에 걸친 대화를 캡처하기 위한 Chrome 확장 프로그램으로 ContextVault를 구축했습니다. 이 확장 프로그램은 즉각적인 문제, 즉 완전한 대화를 로컬에 보존하고 휴대 가능한 형식으로 내보내는 문제를 해결했습니다.

하지만 브라우저 대화를 캡처하는 것은 단 하나의 표면만을 다루는 것이었습니다.

프로젝트를 형성한 결정들은 Codex 세션, Claude Code 조사, Cursor 워크플로우, 터미널 디버깅(terminal debugging), 인간의 노트, 실패한 실험, 그리고 작업 논의 과정에서도 일어나고 있었습니다. 이러한 세션들은 터미널이 닫히거나 에이전트(agent)가 컨텍스트 제한(context limit)에 도달하면 종종 사라져 버렸습니다.

저에게 필요한 것은 또 다른 내보내기(export) 폴더가 아니었습니다. 일어난 일을 보존하고, 분류하고, 검색하며, 다음 에이전트를 위해 준비할 수 있는 방법이 필요했습니다.

그 결과 세 가지 연결된 계층(layer)이 도출되었습니다:

• 브라우저 캡처 (Browser Capture)
• 볼트 터미널 (Vault Terminal)
• 통합 컨텍스트 엔진 (The Unified Context Engine)
  
  Context Fragmentation

계층 1: 브라우저 캡처 구축하기

브라우저 캡처(Browser Capture)는 ContextVault의 최초 인터페이스입니다. 이는 ChatGPT, Claude, Gemini, Perplexity, Poe, DeepSeek, 그리고 Copilot의 대화를 캡처하는 Chrome Manifest V3 확장 프로그램입니다.

이 확장 프로그램은 하이브리드 DOM 및 네트워크 캡처 전략을 사용합니다. 제공업체의 DOM 변이(mutation)를 감시하고, 지원되는 네트워크 응답을 관찰하며, 콘텐츠 캡처 계층에서 스트리밍되는 메시지를 조립한 뒤, 최종 확정된 메시지를 로컬 저장을 위해 백그라운드 서비스 워커(background service worker)로 전송합니다.

이러한 하이브리드 접근 방식이 중요한 이유는 LLM 인터페이스가 동적이기 때문입니다. 어시스턴트(Assistant)의 응답은 점진적으로 도착하고, 스트리밍 중에 DOM 요소가 변경되며, 제공업체마다 구현 방식이 다릅니다.

캡처된 대화는 기본적으로 IndexedDB에 유지됩니다. 사용자는 이를 개별 마크다운(Markdown) 파일이나 대량의 ZIP 아카이브로 내보낼 수 있습니다. 내보내진 각 대화에는 플랫폼, 모델, 날짜, 대화 ID, 태그와 같은 메타데이터를 포함하는 YAML 프론트매터(frontmatter)가 포함됩니다.

데이터 흐름은 의도적으로 제한되어 있습니다:

제공업체 페이지 (Provider page)
    ↓
DOM 및 지원되는 네트워크 캡처
...

이 확장 프로그램은 캡처된 대화를 ContextVault 서버로 전송하지 않는데, 이는 ContextVault 서버가 존재하지 않기 때문입니다. 계정을 요구하지 않으며, 텔레메트리(telemetry)를 수집하거나 외부 AI API를 호출하지도 않습니다.

브라우저 캡처는 첫 번째 문제인 '대화 보존'을 해결했습니다. 하지만 아직 '프로젝트 메모리' 문제를 해결하지는 못했습니다.

계층 2: 볼트 터미널 구축하기

브라우저 대화는 AI 개발 워크플로우의 일부일 뿐입니다. 코딩 에이전트(coding agents) 및 터미널(terminals)과 작업하는 동안에도 중요한 컨텍스트(context)가 발생합니다. 예를 들어, 실패한 인증 수정 사항, 미들웨어(middleware) 경계에 대한 결정, 해결되지 않은 프로덕션 문제, 디버깅 중에 발견된 작업, 또는 특정 접근 방식을 거부한 이유를 설명하는 메모리 등이 이에 해당합니다.

Vault Terminal은 이러한 순간들을 기록할 수 있는 명시적인 방법을 제공합니다. 이는 npm에 @aliabdm/contextvault로 게시된 Node.js CLI (Command Line Interface)입니다.

전역(globally)으로 아무것도 설치하지 않고 직접 실행하려면:

npx @aliabdm/contextvault init

또는 전역으로 설치하려면:

npm install -g @aliabdm/contextvault
contextvault init

기록을 시작하려면:

contextvault record

기록기(recorder) 내부에서는 타이핑된 명령어를 사용하여 컨텍스트를 입력합니다:

/source codex
/title Fix auth middleware

...

이러한 명령어들은 구조화된 컨텍스트 이벤트(context events)가 됩니다. 각 세션은 .contextvault/sessions/ 디렉토리 아래에 로컬 마크다운 (Markdown) 파일로 저장됩니다. 이 파일들은 사람이 읽을 수 있고, 검사 가능하며, 표준 도구로 검색할 수 있고, 아카이브하기 쉬우며, 기본적으로 Git에서 무시(ignored)됩니다.

자동 요약, 재작성 또는 외부 모델 호출은 수행되지 않습니다. Vault Terminal은 사용자가 명시적으로 제공하는 것만을 기록합니다. 모든 터미널 프로세스를 가로채거나 Codex, Claude Code 또는 Cursor 세션 전체를 자동으로 캡처하지 않습니다. 이러한 제한 사항은 의도적이며 명확하게 공개되어 있습니다.

또한 CLI는 다음을 지원합니다:

contextvault list
contextvault search "Redis"
contextvault export

Vault Terminal은 두 번째 문제인 브라우저 외부에서의 에이전트 작업, 결정, 작업, 문제 및 메모리 보존 문제를 해결했습니다.

다음 과제는 두 가지 캡처 인터페이스를 연결하는 것이었습니다.

계층 3: 통합 컨텍스트 엔진 구축하기

통합 컨텍스트 엔진(Unified Context Engine)은 분리된 캡처 데이터들을 검색 가능한 프로젝트 컨텍스트로 변환합니다. 이 엔진은 브라우저 캡처(Browser Capture) 내보내기 파일을 가져오고, Vault Terminal 세션을 읽으며, 두 소스를 공유 모델로 정규화(normalize)하여 로컬 인덱스(local index)를 구축합니다.

브라우저 내보내기(Browser exports)는 Markdown 파일, ZIP 아카이브 또는 디렉토리에서 가져오기(import)할 수 있습니다:

contextvault import ./chatgpt-export.md
contextvault import ./contextvault-export.zip
contextvault import ./browser-exports/

임포터(Importer)는 메모리 내에서 Markdown 항목을 읽고, ContextVault 프론트매터(frontmatter)를 검증하며, 파일 이름을 정제(sanitize)하고, 안전하지 않은 아카이브 추출을 방지하며, 결정론적 중복 탐지(deterministic duplicate detection)를 적용하고, 안전 제한(safety limits)을 강제합니다.

현재 제한 사항:

• 아카이브당 100 MB
• Markdown 파일당 10 MB
• 임포트당 1,000개 파일

ZIP 항목은 임의의 디스크 경로로 추출되는 대신 메모리 내에서 처리됩니다. 동일한 내보내기 파일이 두 번 임포트되면 중복 항목은 건너뜁니다. 업데이트된 내보내기 파일이 동일한 conversation_id를 공유하는 경우, 기존 소스는 중복 생성되는 대신 업데이트됩니다.

서로 다른 컨텍스트 소스의 정규화 (Normalizing Different Context Sources)

브라우저 채팅과 터미널 세션은 동일한 구조로 시작하지 않습니다. 정규화 계층(normalization layer)은 두 소스 모두를 ContextSession 및 ContextEvent라는 두 가지 공유 모델로 매핑합니다.

브라우저 메시지는 플랫폼 및 역할(role) 메타데이터를 보존하면서 사용자(user) 및 에이전트(agent) 이벤트로 매핑됩니다. 터미널 이벤트는 user, agent, decision, task, problem, note와 같은 명시적 유형을 유지합니다.

또한 정규화 도구는 현재의 camelCase 필드와 함께 기존의 snake_case 메타데이터 필드인 started_at, ended_at, git_branch를 지원합니다. 이를 통해 파괴적인 마이그레이션(destructive migration) 없이도 기존 Markdown 세션을 읽을 수 있는 상태로 유지할 수 있습니다.

로컬 인덱스 구축 (Building the Local Index)

컨텍스트를 임포트하거나 기록한 후, 다음 명령어로 인덱스를 다시 구축합니다:

contextvault index

엔진은 터미널 세션과 임포트된 브라우저 대화를 읽고, 이를 정규화하여 .contextvault/index/context-index.json에 로컬 JSON 인덱스를 작성합니다.

Markdown이 신뢰할 수 있는 단일 원천 (Source of Truth)으로 유지됩니다. JSON 인덱스는 파생된 데이터입니다. 만약 인덱스가 손상되거나 오래된 상태가 되면, 이를 삭제하고 원본 Markdown 파일로부터 다시 구축하십시오:

Local Markdown
    ↓
Normalize
...

독점적인 데이터베이스 형식이 없으며 호스팅된 서비스에 대한 의존성도 없습니다. 사용자는 ContextVault 없이도 자신의 컨텍스트를 검사, 편집, 아카이브 또는 처리할 수 있습니다.

캡처 표면 전반에 걸친 증거 검색 (Retrieving Evidence Across Capture Surfaces)

인덱싱이 완료되면, 두 표면 모두에서 컨텍스트를 쿼리할 수 있습니다:

contextvault history --since 2w
contextvault decisions auth --source codex
contextvault problems redis --since 30d
...

지원되는 필터: --type, --source, --since, --limit.

검색은 로컬에서 결정론적 (Deterministic)으로 이루어집니다. 랭킹 (Ranking)은 구절 일치 (Phrase matches), 토큰 일치 (Token matches), 이벤트 유형 부스트 (Event-type boosts), 그리고 최신성 (Recency)을 고려합니다. 임베딩 (Embeddings), 벡터 데이터베이스 (Vector databases), 시맨틱 검색 (Semantic search), 외부 모델 (External models) 또는 숨겨진 AI 호출을 사용하지 않습니다.

이 엔진은 다음 질문에 답합니다: "이 주제에 대해 내가 무엇을 캡처했는가?"

다음 질문에 답한다고 주장하지는 않습니다: "내 프로젝트 데이터 전체가 무엇을 의미하는가?"

첫 번째 질문은 근거가 있고 테스트 가능합니다. 두 번째 질문은 ContextVault가 현재 포함하고 있지 않은 시맨틱 검색 레이어 (Semantic retrieval layer)를 필요로 합니다.

다음 에이전트를 위한 컨텍스트 준비 (Preparing Context for the Next Agent)

prepare 명령은 집중된 컨텍스트 패키지를 생성합니다:

contextvault prepare "auth middleware"

생성된 파일은 .contextvault/exports/prepared-context.md에 기록됩니다. 여기에는 프로젝트 메모리, 관련 세션, 결정 사항, 작업, 문제 및 소스 메타데이터가 포함될 수 있으며, Codex, Claude Code, Cursor 또는 다른 AI 도구에 직접 전달할 수 있는 휴대 가능한 Markdown 형식입니다.

ContextVault는 해당 도구들을 호출하지 않습니다. 사용자가 명시적으로 이동할 수 있도록 근거가 있는 컨텍스트를 준비할 뿐입니다.

아키텍처 개요 (Architecture Overview)

아키텍처는 네 가지 책임을 분리합니다:

• **Capture (캡처)**는 브라우저 또는 터미널 컨텍스트 (context)를 보존합니다.
• **Normalization (정규화)**는 소스들을 공유된 레코드 (records)로 변환합니다.
• **Indexing and retrieval (인덱싱 및 검색)**은 해당 레코드들을 검색 가능하게 만듭니다.
• **Preparation (준비)**는 다른 에이전트 (agent)를 위한 휴대 가능한 컨텍스트 (context)를 생성합니다. 이러한 분리는 핵심 저장 모델 (storage model)을 변경하지 않고도 향후 어댑터 (adapters)를 위한 경계를 생성합니다.

통합 (Integrations)은 어댑터 (adapters)입니다. 엔진 (engine)이 곧 제품 (product)입니다.

Markdown이 진실의 원천 (Source of Truth)으로 남는 이유

프로젝트 컨텍스트 (context)는 그것을 생성한 애플리케이션 없이도 사용 가능한 상태로 유지되어야 합니다. 독점적인 데이터베이스 (proprietary database)는 빠를 수 있지만, 의존성을 생성하고 원시 자료 (raw material)를 불투명하게 만듭니다.

Markdown은 다음과 같은 차별화된 보장을 제공합니다: 어떤 에디터 (editor)에서도 열 수 있고, 표준 검색 도구 (search tools)와 함께 작동하며, 직접 아카이브 (archive)할 수 있고, ContextVault가 사라지더라도 읽을 수 있는 상태로 유지되며, 스크립트 (scripts)를 통해 변환하거나 도구 간에 이동할 수 있습니다.

JSON 인덱스 (index)는 검색 성능 (retrieval performance)을 위해 존재합니다. 이는 폐기 가능합니다. 하지만 Markdown은 그렇지 않습니다.

Git은 코드 이력 (code history)을 추적합니다. ContextVault는 그 코드를 둘러싼 토론, 실패한 시도, 결정, 그리고 발견들을 보존합니다.

설계에 의한 프라이버시 (Privacy by Design)

ContextVault는 로컬 퍼스트 (local-first) 모델을 따릅니다. 캡처된 데이터는 ContextVault 백엔드 (backend)로 전송되지 않는데, 왜냐하면 백엔드 (backend) 자체가 존재하지 않기 때문입니다.