isaachinman/encephalon

Encephalon은 코딩 에이전트에게 지속적이고, 리포지토리 로컬의 지식을 제공합니다. 작은 JSON 레코드는 Git과 함께 코드에 저장되며; 일회용 SQLite 전체 텍스트 인덱스는 이를 CLI와 동기식 JavaScript API를 통해 검색할 수 있게 만듭니다.

이 도구는 결정, 아키텍처, 컨벤션 및 작업 간에 손실될 수 있는 반복 가능한 워크플로우에 사용됩니다. 이 도구는 계정, 호스팅 서비스, 원격 측정(telemetry), 임베딩(embeddings), 백그라운드 데몬 또는 런타임 네트워크 접근 기능을 갖추고 있지 않습니다. 또한 사용자를 대신하여 Git 명령을 실행하지도 않습니다.

이 README는 Encephalon 0.4.0에 대해 설명합니다. 이전 버전의 경우, 일치하는 Git 태그에서 문서를 사용하십시오. 연결된 메인 브랜치 계약(main-branch contract)은 현재 개발 상황을 추적합니다.

Node.js 24.15.0 이상 버전을 Linux, macOS 또는 Windows에서 사용하십시오. 패키지 관리자 레이아웃을 사용하여 Git 리포지토리 루트에 설치하고 node_modules/encephalon 경로를 노출해야 합니다.

워크스페이스 로컬(Workspace-local) 또는 임시(ephemeral) 설치 및 Yarn Plug'n'Play는 지원되지 않습니다. 설치된 패키지는 런타임 의존성이 없고, 설치 라이프사이클 스크립트가 없으며, Bun 요구 사항이 없습니다.

npm install --save-dev encephalon
npx --no-install encephalon init

init은 최대 세 개의 기본 레코드를 생성하고, 캐시를 준비하며, 루트 AGENTS.md와 CLAUDE.md에 가역적인 관리 블록을 추가합니다. 이 블록은 에이전트에게 설치된 스킬로 안내합니다. 기록된 레코드와 지침 변경 사항을 프로젝트와 함께 커밋하십시오.

기본값에는 제한된 패키지 메타데이터, 패키지 관리자 증거(evidence), 워크스페이스 패턴, 스크립트 진입점, 최상위 레이아웃 및 워크플로우 파일 이름이 포함됩니다. 소스 디렉토리를 탐색하거나 언어 또는 파일 수를 세지는 않습니다. 에이전트는 프로젝트를 검사하고 유용한 컨텍스트를 별도로 추가할 수 있습니다.

다음 예제들은 초기화된 리포지토리 루트에서 실행하십시오. 명시적인 레코드 ID는 워크스루(walkthrough)를 재현 가능하게 만드므로, 자체 지식을 기록할 때는 새로운 ID를 사용하거나 --id 옵션을 생략하십시오.

컴팩트 검색으로 시작한 다음, show를 사용하여 레코드를 검사합니다.

. 검색은 리터럴 유니코드 텍스트입니다: 용어들은 AND로 결합되며, 구두점은 쿼리 연산자를 도입할 수 없습니다. 페이로드와 searchText는 계속 검색 가능합니다. 스니펫은 제한된 메타데이터/요약 미리보기에서 가져오며; 다른 곳의 일치 항목은 안정적인 대체품을 사용합니다. 전체 search는 완전한 레코드를 반환합니다.

gather

배치 검색을 수행하고 순서와 중복 발생을 유지하며 보여줍니다. 중복 결과는 독립적인 변경 가능한 값으로 남아 있습니다. 읽기는 필요할 때 일회용 캐시를 자동으로 준비합니다. 누락된 show 결과는 null이며; 빈 검색은 []를 반환합니다.

대체품을 추가하기 전에 주제에 대해 검색하십시오. 대체품은 동일한 종류와 주제를 가진 모든 활성 헤드를 대체해야 합니다:

npx --no-install encephalon add --id auth-tokens-v2 --kind decision --subject api.authentication --source agent --supersedes auth-tokens --data '{"summary":"Use short-lived signed bearer tokens"}' --text 'authentication tokens'
npx --no-install encephalon search --compact --include-superseded authentication

권장되는 종류는 decision, architecture, convention, workflow, incident 그리고 context입니다. 기존 레코드는 추가 전용(append-only)입니다: 바이트를 보존하고 변경된 지식을 새 레코드로 표현합니다.

encephalon/
<kind>/<id>.json
_artifacts/<kind>/<id>/...

정준(canonical) 레코드와 참조된 아티팩트를 커밋합니다. 일회용 캐시는 node_modules/.cache/encephalon/에 보관합니다.

Git 외부에서. 변경 불가능한 지원 파일을 첨부하려면, 먼저 레코드 ID를 선택하고 해당 파일을 일치하는 _artifacts/<kind>/<id>/ 디렉터리에 배치한 다음, add --artifact로 뇌 상대 경로(brain-relative path)를 전달하세요.

Encephalon은 파일을 검증하며, 임의의 소스 파일들을 아카이브에 복사하지 않습니다.

다른 브랜치에서 지식을 병합한 후에는 validate를 실행하세요.

여러 활성 헤드(active heads)가 충돌하는 경우, 이들을 모두 대체하는 해결 레코드(resolving record)를 추가하세요. 그 전까지는 읽기 작업이 모든 충돌하는 헤드를 활성으로 반환하며 다른 주제에 대한 추가 작업은 여전히 작동합니다. 충돌을 수정하기 위해 역사를 절대 삭제하지 마세요.

• 목록 및 검색은 기본적으로 20개의 결과를 반환합니다; --limit은 1–1,000까지 수용할 수 있습니다. - 하나의 gather는 16개 검색과 64개 표시를 수용합니다. - 검색 입력은 1,024 UTF-8 바이트와 32개의 리터럴 용어를 수용합니다. - 완전하고, 압축되며, 완벽한 gather 응답 각각은 최대 1 MiB/레코드로 구성된 1,000개 레코드와 8 MiB의 레코드 JSON을 가지며, 독립적인 4 MiB 예산이 있습니다. 중복 항목은 발생할 때마다 계산됩니다. 크기가 큰 결과는 조용히 잘리는 대신 실패합니다.

응답이 예산을 초과하는 경우 더 좁은 쿼리(narrower queries)를 사용하거나, 압축 검색(compact search) 또는 더 작은 제한을 사용하세요. Public 계약(Public contract)은 모든 필드, 페이로드, 코퍼스, 경로 및 응답의 제한 사항과 그 회계 규칙을 정의합니다.

npx --no-install encephalon validate
npx --no-install encephalon prepare
npx --no-install encephalon hydrate

validate는 캐시를 신뢰하지 않고 표준 레코드, 대체(supersession), 참조된 아티팩트를 검사합니다. prepare는 유효한 새 캐시를 재사용하거나 다시 구축합니다; hydrate는 강제로 재구축을 수행합니다. 복구 가능한 캐시 손상이나 구식 캐시 형식은 일반적으로 자동으로 재구축됩니다. 외부 저장소의 캐시나 안전하지 않은 파일 시스템 레이아웃은 닫힘 실패(fails closed)를 일으킵니다.

표준(canonical) 유효성 검사 실패의 경우, 보고된 레코드 또는 아티팩트를 검사하고 원인을 조정(reconcile)한 후 다시 빌드하십시오. 안전하지 않은 캐시 레이아웃인 경우, 링크, 권한 또는 예상치 못한 파일 유형을 수정하고 프로세스를 재시작한 다음 다시 시도하십시오. 다른 프로세스가 리포지토리를 사용 중일 때 캐시 파일을 맹목적으로 삭제하지 마십시오. 캐시 복구는 표준 레코드나 아티팩트를 삭제하는 것을 결코 정당화할 수 없습니다.

초기화(Initialisation) 과정은 다음 단계가 실패하기 전에 일부 레코드나 명령어 변경 사항을 커밋할 수 있습니다. details.initProgress.recoveryAction을 따르십시오.

: 요청 시 커밋된 작업을 검사하고, 캐시 실패 후에는 prepare와 validate를 실행한 다음 동일한 init 옵션을 반복하십시오. add 오류가 canonicalCommitted: true를 보고하는 경우, 해당의 recordId를 검사하고 유효성을 검사하며, 이를 맹목적으로 다시 추가하지 마십시오. 오직 보고된 복구 경로는 해당 실패 작업에 속한다고 식별됩니다. 커밋 및 복구 보장(guarantees)에 대해서는 계약서(contract)를 참조하십시오.

예상치 못한 실패를 조사하려면, 먼저 보고된 모든 복구 조치를 따르십시오. 그런 다음, 명령을 반복하는 것이 안전하다면 ENCEPHALON_DEBUG=1로 설정하여 다시 실행하십시오. 예를 들어, canonicalCommitted: true를 보고한 add를 반복하면 원래의 원인 대신 RECORD_EXISTS가 반환됩니다. 이 변수를 설정하면 CLI는 일반적인 JSON 오류와 함께 에러 스택과 원인 체인을 stderr에 출력합니다. 출력에는 로컬 경로가 포함될 수 있으므로 공유하기 전에 검토하십시오.

패키지 툴링 또는 최상위 레이아웃을 변경한 후 생성된 팩트(facts)를 새로 고치십시오:

npx --no-install encephalon init --refresh-baseline

새로 고침은 변경된 생성 레코드를 추가하고 이전 헤드(heads)를 대체합니다. 변경되지 않은 팩트는 아무것도 추가하지 않으며, 오래된 레코드는 계속 읽을 수 있습니다. 관리되는 명령어 블록만 제거하려면:

npx --no-install encephalon init --remove

제거(Removal)는 캐노니컬 기록(canonical records), 아티팩트(artifacts), 캐시(cache) 및 설치된 패키지를 보존합니다. 기존의 명령어 파일은 NUL 바이트가 없고 유효한 UTF-8을 포함하는 일반적인 심볼릭 링크가 아닌 파일이어야 하며, 각각 최대 1 MiB여야 합니다. 관련 없는 명령어 바이트는 보존됩니다.

import { searchCompactRecords } from 'encephalon';
const decisions = searchCompactRecords({
root: process.cwd(),
...

루트 패키지는 initEncephalon, addRecord, prepare, hydrate, validateRecords, listRecords, showRecord, searchRecords, searchCompactRecords, gatherRecords, 그리고 EncephalonError와 그 공개 TypeScript 타입을 내보냅니다. 이를 가져오는 것은 저장소를 발견하거나, 파일 시스템을 건드리거나, SQLite를 여는 행위를 하지 않습니다. 호출은 반환 값을 반환하며 절대 출력하거나 종료하지 않으며; 예상되는 실패는 안정적인 code와 제한된 details를 가진 EncephalonError를 발생시킵니다.

명시적인 root가 있습니다. 이것이 없으면, 호출은 현재 디렉토리에서 가장 가까운 Git 저장소를 발견합니다. 실행하는 패키지는 루트 설치와 일치해야 합니다. 전체 입력, 결과 형태, 순서, CLI 플래그 및 오류에 대한 공개 계약을 참조하십시오.

Encephalon은 사용자가 추가한 지식과 위에서 설명된 제한된 기준선(baseline)만을 저장합니다. 초기화 과정은 소스 본문, README 내용, 환경 파일, 레지스트리 구성, Git 기록, Git 원격 또는 워크플로우 내용을 의미론적으로 검사하지 않습니다. 이는 오직 블록 관리를 위해 AGENTS.md와 CLAUDE.md만을 읽습니다. 관련 없는 명령어 텍스트는 저장되거나 인덱싱되거나 출력되지 않습니다.

기록이나 아티팩트에 의도적으로 넣은 모든 것은 Git과 함께 이동할 수 있습니다. 비밀번호, 자격 증명, 개인 데이터 및 임시 로그는 여기에 포함하지 마십시오. Encephalon은 암호화 또는 접근 제어 시스템이 아닙니다.

다가오는 경량 런타임(lean runtime)은 유효한 0.3 캐노니컬 기록, 아티팩트 및 관리되는 명령어를 유지합니다. 생성된 기준선에는 더 이상 소스 파일 인벤토리가 포함되지 않으며, 압축 스니펫/순위는 다를 수 있지만 페이로드 용어는 계속 검색 가능합니다. 폐기 가능한 캐시는 호환되지 않을 때 재구축됩니다.

Bun을 사용하여 Encephalon을 구축하고 테스트합니다; 런타임 소비자들은 Node를 사용합니다. 해당 저장소의 기여자 체크 및 성능 가이드에는 로컬 명령어, CI 선택, exact-candidate 처리, 그리고 수동 게시 경계가 나열되어 있습니다.

Public 계약은 규범적 행동 참조(normative behaviour reference)입니다. 변경 로그(Changelog)는 릴리스 이력을 보존합니다. 역사적인 설계와 오래된 벤치마크 보고서는 현재의 요구사항이 아닌, 불변의 Encephalon 아티팩트로 유지됩니다.

MIT