Context Atlas

Context Atlas는 소프트웨어 프로젝트를 위한 로컬 우선(local-first), 증거 기반(evidence-backed) 메모리 계층입니다. Git 히스토리, 저장소 구조, 매니페스트, 프로젝트 문서, 인간이 검토한 설명을 다음과 같은 형태로 변환합니다:

• 신규 사용자에게 친숙한 프로젝트 개요;

• 탐색 가능한 컴포넌트 및 의존성 맵;

• 프로젝트가 어떻게 변경되었는지에 대한 연대기적 기록;

• 컴포넌트와 결정에 대한 증거 연결 설명; 그리고

• 코딩 에이전트가 변경을 수행하기 전에 읽을 수 있는 경계가 있는 컨텍스트 팩;

• 인간의 동의를 받아 명시적으로 선택된 문서 및 대화 요약; 그리고

• 신뢰할 수 있는 호스트를 위한 버전 관리된 확장 및 공급자-이그레스(provider-egress) 안전 계약.

이 저장소는 실험적인 0.1.0 알파 릴리스 후보의 소스를 포함합니다: Node.js CLI, 로컬 웹 대시보드, TypeScript 라이브러리, stdio MCP 서버, Codex 플러그인 번들. 아래 설명된 생성된 플러그인 런타임, 로컬 동작 게이트, 최신 로컬 패키지 후보, 그리고 깨끗한 설치 패키지 스모크(smoke)는 현재 작업 트리에서 검증되었습니다. 호스팅된 워크플로우와 GitHub 릴리스는 검증되지 않았습니다; 0.1.0은 아직 게시되지 않았으며, 더 넓은 프로덕션 계획은 docs/에 명시적으로 추적되고 있습니다.

존재 이유

긴 코딩 세션은 맥락을 잃기 쉽습니다. 채팅 히스토리는 압축되고, 에이전트는 변경되며, 문서화되지 않은 결정은 사라지고, 생성된 요약은 조용히 낡거나 잘못될 수 있습니다. Context Atlas는 관찰된 사실, 문서화된 주장, 추론, 제안, 인간이 승인한 설명 사이의 엄격한 경계를 유지하면서, 단일 채팅 외부에 지속적인 고수준 맵을 유지합니다.

flowchart LR
  A["Git history"] --> I["Evidence-first ingestion"]
  B["Repository structure"] --> I
  C["README, ADRs, manifests"] --> I
  I --> D["Local SQLite knowledge graph"]
  I --> L["Hash-chained audit ledger"]
  D --> O["Overview and orientation"]
  D --> M["Mind map and timeline"]
  D --> P["Task-bounded context pack"]
  O --> H["Developer"]
  M --> H
  P --> X["Coding agent through MCP"]
  R["Human review"] --> D

Related MCP server: CodeIntel MCP Server

빠른 시작

요구 사항: Git 및 Node.js 24 이상.

git clone https://github.com/moelomda/context-atlas.git
cd context-atlas
npm.cmd ci
npm.cmd run build
node dist/cli.js init C:\path\to\your\git-repository --name "My Project"
node dist/cli.js serve --repo C:\path\to\your\git-repository

http://127.0.0.1:4242를 엽니다. 서버는 의도적으로 인증되지 않은 비-루프백 호스트를 거부합니다.

첫 번째 핸드오프를 위해 다음 순서를 사용하십시오:

node dist/cli.js overview --repo C:\path\to\repo
node dist/cli.js health --repo C:\path\to\repo
node dist/cli.js timeline --repo C:\path\to\repo
node dist/cli.js pack "add subscription retry handling" --json --repo C:\path\to\repo
node dist/cli.js proposals pending --repo C:\path\to\repo

생성된 내러티브 제안은 자동으로 진실로 받아들여지지 않습니다. 증거를 검토한 다음 특정 제안을 명시적으로 승인하거나 거부하십시오:

node dist/cli.js approve <proposal-id> --actor human:alice --note "Reviewed against ADR-0001 and current code" --repo C:\path\to\repo
node dist/cli.js reject <proposal-id> --actor human:alice --note "Superseded by the current architecture" --repo C:\path\to\repo

루프백 대시보드는 또한 증거 준비 상태, 충돌 그룹화, 검토 기록, 명시적 승인/거부 확인을 갖춘 인간 제안 검토 작업 공간을 제공합니다. 브라우저 변형은 정확한 동일 출처 요청과 인메모리 세션 토큰을 요구합니다; 이는 에이전트 기능이 아닙니다.

대시보드의 소스 추가 워크플로우 또는 CLI를 통해 외부 텍스트/Markdown 문서 하나 또는 대화 요약 하나를 추가할 수 있습니다. 미리보기는 읽기 전용이며 정확한 바이트, 출처, 목적, 권한, 민감도, 귀속된 인간 행위자를 바인딩합니다. 적용은 신선한 계획과 리터럴 IMPORT를 요구합니다; 민감한 가져오기는 본문을 생략하면서 메타데이터와 출처를 유지합니다. 가져온 자료는 신뢰할 수 없는 증거로 남아 있으며 자동으로 주장을 승인하거나 개요를 다시 쓰지 않습니다.

$plan = node dist/cli.js source-import-preview C:\path\to\notes.md --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo | ConvertFrom-Json
node dist/cli.js source-import C:\path\to\notes.md --plan $plan.planId --confirm IMPORT --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo

의미 있는 커밋 후에 sync를 실행하십시오. 건강 보고서는 저장소가 마지막으로 인덱싱된 커밋을 넘어 이동했을 때 명확하게 경고합니다.

새 저장소는 8,000-토큰 컨텍스트 팩 예산으로 시작합니다. 기존 저장소는 운영자가 변경할 때까지 .context-atlas/config.json에 이미 저장된 값(레거시 4,000-토큰 기본값 포함)을 유지합니다. pack --budget N은 여전히 한 요청에 대해 저장소 기본값을 재정의합니다.

추출에 영향을 주는 구성 또는 .atlasignore 정책 변경 후에도 동기화가 필요합니다. Context Atlas는 콘텐츠가 동기화되고 검토될 때 지침-의존성 워터마크를 기록합니다; 해당 경계를 변경하면 이전에 검토된 주장이 불안정해집니다. 워터마크 추적 이전에 생성된 주장은 실패-폐쇄(fail closed)되며 조용히 기존 권한으로 인정되지 않고 동기화와 새로운 인간 검토가 필요합니다.

Codex 플러그인 및 MCP

플러그인 소스 번들은 plugin/context-atlas/에 있습니다. 패키징하거나 설치하기 전에 이 프로젝트를 빌드하고 검증하십시오: 빌드는 plugin/context-atlas/runtime/server.mjs에 자체 포함된 MCP 런타임을 포함하므로, 검증된 복사 마켓플레이스 설치가 이 소스 트리에 의존하지 않습니다. 래퍼는 로컬 소스 개발을 위해 dist/mcp/server.js 폴백을 유지합니다.

MCP 서버는 13개의 읽기 전용 도구를 노출합니다:

• 현재 탐색: atlas_overview, atlas_context_pack, atlas_explain, atlas_history, atlas_health, atlas_search, atlas_evidence.

• 시간적 지식: atlas_assertions, atlas_assertion_history, atlas_assertion_evolution.

• 저장된 팩 검사: atlas_pack_history, atlas_pack_snapshot, atlas_pack_diff.

• 동기화, 제안 생성, 제안 결정, 팩 저장/새로고침, 보존 적용은 의도적으로 MCP를 통해 사용할 수 없습니다. 제안 결정은 CLI 또는 보호된 루프백 대시보드를 통해 명시적인 인간이 필요합니다; 다른 변형은 인간이 운영하는 CLI 워크플로우로 유지됩니다.

• atlas_context_pack은 기존 인간이 만든 CLI 재정의의 ID를 사용할 수 있습니다. 재정의를 생성하거나 변경할 수 없으며, 재정의된 중요한 발견은 구조화된 결과와 텍스트 처리 모두에서 계속 두드러집니다.

모든 도구는 절대 repo 경로를 허용합니다. 직접 MCP 클라이언트는 node <absolute-project-path>/dist/mcp/server.js를 실행하고 CONTEXT_ATLAS_REPO를 초기화된 저장소로 설정할 수도 있습니다.

버전 관리된 HTTP 및 MCP 읽기는 응답을 조립하기 전후에 지식 데이터베이스, 라이브 Git/작업 트리, 원장, 동기화, 지침 정책 경계를 비교합니다; 동시 변경은 이전 데이터에 더 새로운 워터마크를 첨부하는 대신 재시도 가능한 스냅샷 오류로 거부됩니다. 저장된 팩 히스토리 및 diff 도구는 짧은 텍스트 포인터와 함께 하나의 컴팩트한 구조화된 페이로드를 반환하며, 모든 MCP 도구 결과는 2,500,000자 실패-폐쇄 상한을 갖습니다.

신뢰할 수 있는 인프로세스 확장은 공개 context-atlas/extensions 내보내기를 사용할 수 있습니다. 여섯 개의 버전 관리된 포트는 추출기, 분석기, 공급자, 리댁터, 내보내기, 검증기를 다룹니다; 매니페스트와 입력/출력은 스키마 검사되며, 안전하지 않은 출력은 원자적으로 실패하고, 설치된 확장 코드는 명시적으로 신뢰할 수 있는 실행 코드로 취급됩니다. 핵심 라이브러리는 또한 공급자 허용 목록, 리댁션/차단 정책, 토큰/비용 예산, 자격 증명 간접화, 지속적인 시도 영수증, 폐기, 자동 재시도 없음이 있는 정확한 바이트 이그레스 미리보기/동의/권한 부여 게이트웨이를 노출합니다. 이 알파에서는 CLI, 웹 대시보드 또는 MCP 서버에 의해 원격 공급자가 활성화되지 않습니다.

컨텍스트 팩 계약

컨텍스트 팩 스키마 v2는 항상 동일한 15개의 필수 섹션을 나타냅니다: 정체성/권한, 경고, 목표, 컴포넌트, 인터페이스, 규칙, 결정, 제약, 위험, 최근 변경, 테스트, 충돌, 미지, 증거, 제외. 섹션은 명시적으로 present, none, 또는 unknown일 수 있습니다; 빈 지식 영역은 조용히 생략되지 않습니다.

선택은 전체 항목 단위입니다. 경계가 있는 선택기 우주에 허용된 모든 실질 엔티티, 활성 관계, 주장 또는 이벤트는 증거 폐쇄와 함께 전체로 렌더링되거나 정확한 이유와 함께 실질 제외로 나열됩니다; 주변 비-실질 기록은 집계 수로 보고됩니다. 관계는 현재 사용 상태, 이유, 권한, 신뢰도, 증거 검증 메타데이터를 가지며, 검증되지 않은 토폴로지는 확정된 지침으로 제시되지 않습니다. 하드 예산은 Markdown 본문뿐만 아니라 전체 컴팩트 JSON 객체에 적용되며, MCP 어댑터는 또한 도구 결과 봉투를 위해 공간을 예약합니다. 현재 추정치는 공개된 문자-나누기-4 근사치이며, 공급자 토크나이저가 아닙니다. 500토큰만큼 낮은 요청도 입력으로 허용되지만, 필수 봉투가 맞지 않으면 생성은 계산된 최소값으로 거부합니다.

pack-save는 검증된 팩을 불변, 콘텐츠 주소 지정 스냅샷으로 저장합니다. pack-history, pack-diff, pack-refresh는 경계가 있는 히스토리, 구조적 비교, 현재 상태에 대한 재빌드 워크플로우를 제공합니다. 스냅샷은 .context-atlas/packs/ 아래에 있습니다; 저장소는 히스토리를 조용히 삭제하는 대신 257번째 고유 스냅샷을 거부합니다. 새로고침은 원래 작업과 토큰 예산을 보존하고, 이전 안전 재정의를 상속하지 않으며, 저장소 정체성 또는 불안정한 저장소/정책 변경을 거부합니다. 히스토리 읽기는 요청된 표시 제한을 적용하기 전에 보존된 세트를 검증하므로, 256-항목 경계는 안전 상한이지 큰 히스토리 성능 자격이 아닙니다.

현재 지침이 제시되거나 패킹되기 전에 로컬 파일, 도달 가능한 Git 커밋, 저장소 스냅샷, 컴포넌트 스냅샷 로케이터는 표준 경로, 정책, SHA-256 다이제스트에 대해 재검증됩니다. 알 수 없는 외부 로케이터 종류는 검증되지 않은 것으로 보고됩니다; 검증된 증거로 승격되지 않습니다. 개요, 그래프, 검색, 설명, 주장, API, MCP, 팩, 대시보드 경로는 현재 사용 상태/이유/권한/증거 메타데이터를 가지거나 불안정한 검토된 산문을 보류합니다.

기록되는 것

Context Atlas는 로컬 상태를 <repository>/.context-atlas/ 아래에 저장합니다:

• config.json: 스캔 및 신선도 정책;

• atlas.db: 증거, 엔티티, 버전, 관계, 이벤트, 제안;

• ledger.ndjson: 기록된 작업을 다루는 추가 전용 해시 체인;

• backups/: 검증된 SQLite 백업 및 휴대용 지식 스냅샷;

• exports/: 체크섬된 휴대용 JSON 내보내기; 그리고

• packs/: 무시된, 불변 컨텍스트 팩 스냅샷, 하드 256-항목 용량.

전체 원시 diff와 전체 파일 본문은 보존되지 않습니다. Context Atlas는 탐색에 필요한 경계가 있는, 정화된 문서 추출 및 저장소 메타데이터를 보유합니다. 비밀 유사 값과 .env, 자격 증명, 개인 키, 인증서와 같은 민감한 경로는 보류됩니다. 저장소별 제외를 .atlasignore에 추가하십시오; 순서가 있는 glob 규칙은 ! 부정을 지원합니다.

초기화는 .context-atlas/.gitignore를 생성하여 데이터베이스, 내보내기, 백업, 팩, 업그레이드 전 전체 마이그레이션 스냅샷이 실수로 커밋되지 않도록 합니다. 레거시 저장소가 마이그레이션 스냅샷 또는 팩을 쓰기 전에, Context Atlas는 운영자 규칙을 대체하지 않고 누락된 파생 데이터 규칙을 안전하게 추가합니다. 공유되고 검토 가능한 프로젝트 메모리를 원할 때 .context-atlas/config.json, .context-atlas/ledger.ndjson, .context-atlas/.gitignore를 커밋하십시오; 무시된 데이터베이스 자료는 로컬로 유지하거나 검증된 백업 워크플로우를 통해서만 전송하십시오.

안전 모델

Context Atlas는 탐색 보조 도구이지, 소프트웨어가 올바르다는 증명이 아닙니다. 현재 코드와 테스트는 런타임 동작에 대해 여전히 권위를 가집니다. 컨텍스트 팩이 차단된 경우, 나열된 중요 상태 점검을 해결하십시오. 예외적인 pack-override 워크플로우는 명시적 인간 행위자, 근거, 짧은 만료 기간을 요구하며, 결과 팩은 시각적으로 표시된 상태로 유지됩니다.

명령어

전체 명령어 목록은 node dist/cli.js help를 실행하십시오. 주요 워크플로우는 다음과 같습니다:

• 탐색: overview, map, timeline, search, explain, evidence, assertions, assertion-history, assertion-evolution.

• 에이전트 준비: pack <task> [--budget N] [--json], pack-save <task>, pack-history, pack-diff <left> <right>, pack-refresh <snapshot>.

• 메모리 유지: sync, proposals, propose, approve, reject; approve/reject는 보호된 루프백 대시보드에서 인간에게도 제공됩니다.

• 선택된 증거 추가: source-import-preview <file> 다음에 source-import <file> --plan <id> --confirm IMPORT; 대시보드는 브라우저에서 선택한 파일 하나 또는 붙여넣은 요약에 대해 동일한 미리보기/동의 경계를 제공합니다.

• 감사: health, validate, recover-ledger, privacy, retention-preview, 확인된 retention-apply, retention-history (validate는 심각한 발견 시 코드 2로 종료됩니다). 보존 삭제는 적격한 내보내기/백업 파일로 제한되며, 정확한 미리보기 계획 ID, human: 행위자, 근거, --confirm APPLY를 요구합니다.

• 이식성: export, verify-export, import-preview, 전부-아니면-전무 import, rebuild-verify, backup, verify-backup, restore --confirm RESTORE.

• 시각화: 루프백에서 serve.

개발 및 검증

npm.cmd run build
npm.cmd test

현재 로컬 작업 트리는 일반 동작 스위트(693,394 ms에 122/122 테스트)와 커버리지 실행(901,735 ms에 122/122 테스트; 라인 95.40%, 함수 96.07%, 브랜치 76.81%)을 통과했습니다. 엄격한 소스/테스트 TypeScript 컴파일, JavaScript 구문, JSON/YAML 파싱, 릴리스 ID 검증, 취약점 0건이 보고된 온라인 npm audit도 통과했습니다. 이는 로컬 Windows 결과이며, 크로스 플랫폼 또는 호스팅 결과가 아닙니다.

최종 로컬 성능 패스는 또한 개요 계약에서 중복 저장소/증거 작업을 제거했습니다: 9개 엔티티 픽스처에서 실제 /api/v1/overview 요청이 약 8–12초와 58개의 Git 서브프로세스에서 1.48–1.61초와 12개의 Git 서브프로세스로 줄었으며, 전후 스냅샷 검사를 유지했습니다. 이는 집중된 소규모 픽스처 회귀 결과이지, 대규모 저장소 지연 시간 검증이 아닙니다.

플러그인은 이 소스에서 재생성되었습니다: 소스와 번들 런타임은 각각 동일한 13개의 읽기 전용 도구를 노출하며, 플러그인과 스킬 검증기가 통과하고, 독립적인 런타임 및 타사 고지 재생성이 결정적 해시를 생성했으며, 실제 재생성된 런타임은 MCP 회귀 테스트(1/1)를 통과했습니다. 고정된 Actionlint 1.7.12로 워크플로우 검사는 4개 워크플로우 모두를 통과했습니다. 17개의 워크플로우 uses 참조는 모두 전체 SHA 고정이며, 해결되고 검증된 7개의 고유 커밋을 포함합니다. 이러한 검사는 GitHub 호스팅 CI, CodeQL, 의존성 검토, SBOM, 출처 작업을 대체하지 않습니다.

2026-08-23에 렌더링된 인앱 브라우저 QA는 데스크톱 뷰포트와 390×844 및 320×720 레이아웃을 다루었으며, 개요와 완전한 외부 소스 미리보기/동의 흐름을 포함했습니다. 확인이 미리보기 전까지 숨겨져 있는지 검증하고, 로컬 가져오기를 완료하고, 반응형 리플로우와 최소 너비 오버플로를 확인하고, 콘솔 경고나 오류 0건으로 종료했습니다. 이 실행은 조기 확인 표시와 320px 가로 오버플로를 발견하고 수정했습니다. 업데이트된 웹 스위트는 6/6을 통과했습니다. 이전 탐색, 지도, 타임라인, 상태, 검토, 검색, 브리핑, 키보드, Escape, 포커스 복귀 커버리지는 소스 테스트 계약의 일부로 유지되지만, 이는 스크린 리더 결과, WCAG 적합성 주장, 크로스 브라우저 매트릭스, 또는 다른 운영 체제에서의 증명이 아닙니다.

기능 및 렌더링된 UI 수정 후, 124개 파일의 로컬 패키지 후보가 재빌드되어 인벤토리, 금지 파일, 크기, SHA-1, SHA-512 검증을 통과했습니다. 깨끗한 임시 프로젝트가 해당 아카이브와 의존성을 설치하고, 선택된 외부 소스를 가져오고, 대시보드/API와 보호된 검토 API를 로드하고, 공개 확장 서브패스를 가져오고, 개인정보, 오버라이드, MCP 스모크를 통과했습니다. 스모크는 완전한 13개 도구 읽기 전용 인벤토리를 검증하고 대표적인 탐색, pack-history, 증거, 오버라이드 읽기를 실행했습니다. 문서 편집은 새 아카이브 후보를 생성하므로, 최종 핸드오프는 가장 최근의 문서 후 재검증만 기록합니다. 정확한 아카이브 다이제스트와 크기는 이 자기 참조 문서가 아닌 로컬 팩 보고서에 유지됩니다. 이는 여전히 로컬 아티팩트 증거이며, 원격 저장소, 호스팅 검사, 서명/SBOM 증명 아티팩트, 또는 게시된 사전 릴리스가 아닙니다.

빌드는 프로젝트 라이선스를 플러그인에 복사하고, 자체 포함 런타임에 실제로 번들된 의존성에서 타사 고지를 생성하며, 릴리스 워크플로우는 런타임/라이선스/고지 드리프트를 거부하도록 정의됩니다. 로컬 런타임/고지 드리프트 및 릴리스 ID 검사는 후보 태그 입력, 패키지, 잠금 파일, 플러그인 매니페스트, MCP 광고 버전, 날짜가 있는 변경 로그 간의 일치를 포함하여 통과합니다. 최신 로컬 패키지 스모크도 통과하지만, 이러한 통제는 호스팅 실행이나 게시를 증명하지 않으며, 실제 GitHub 사전 릴리스에 선택된 불변 커밋에서 동일한 게이트가 여전히 통과해야 합니다.

구현은 현재 Node의 내장 SQLite API를 사용하며, Node 24는 여전히 이를 실험적이라고 표시합니다. 이 알파는 단일 로컬 저장소와 단일 작성자를 위해 설계되었습니다. 호스팅 협업, IDE 네이티브 패널, 증분 파일 시스템 감시, 공급자 저장소/UI 통합, 더 풍부한 언어 의미 분석, 대규모 저장소 성능 작업은 로드맵 항목으로 남아 있습니다. 저장된 팩의 개인 경로 탐지는 현재 저장소 루트와 인식 가능한 호스트 파일 시스템 루트의 광범위한 집합을 차단하지만, 자유 텍스트는 모든 사용자 정의 POSIX 절대 경로를 API 경로와 완벽하게 구분할 수 없습니다. 보존은 설명자와 ID 검사를 통해 경로 경쟁을 좁히지만, 악의적인 동일 사용자 디렉터리 구성 요소 교체에 대해 경쟁 없는 삭제를 주장하지 않습니다.

상세 계획 및 증거

• docs/PRODUCT_PLAN.md — 사용자, 작업, 범위, 기능 및 비기능 요구사항.

• docs/ARCHITECTURE.md — 시간적 데이터 모델, 신뢰 경계, 수집, 검색 및 배포 설계.

• docs/RISK_REGISTER.md — 실패 모드, 통제, 테스트 및 잔여 위험.

• docs/IMPLEMENTATION_ROADMAP.md — 프로토타입부터 프로덕션 강화까지의 마일스톤.

• docs/REQUIREMENTS_TRACEABILITY.md — 요구사항-통제/테스트 원장.

• docs/IMPLEMENTATION_STATUS.md — 이 알파가 구현한 것과 계획된 것에 대한 정직한 증거.

기여, 지원 및 릴리스

• 변경을 제안하거나 구현하기 전에 CONTRIBUTING.md를 읽으세요. 신뢰 경계 불변식과 검증 표준을 문서화합니다.

• 재현 가능한 버그, 제품 요청 및 문서 문제는 구조화된 GitHub 이슈 양식을 사용하세요.

• 취약점은 SECURITY.md를 사용하여 비공개로 신고하세요. 공개 이슈에 자격 증명, 독점 소스 또는 실제 .context-atlas/ 디렉터리를 절대 넣지 마세요.

• 프로젝트 참여는 CODE_OF_CONDUCT.md를 따릅니다.

• 릴리스 변경 사항과 유지 관리자 절차는 CHANGELOG.md 및 docs/RELEASING.md에 있습니다.

라이선스

MIT