engram 딥다이브
— AI의 기억을 데이터베이스로 설계하는 법

1프로젝트 한줄 요약

engram은 코딩 에이전트가 해결한 버그, 선택한 설계, 프로젝트 관례를 구조화된 메모리로 저장하는 프로그램입니다. 에이전트는 MCP 도구로 기록하고, 사람은 CLI나 TUI로 열람할 수 있습니다. 기본 저장 위치는 ~/.engram/engram.db이며, 핵심 저장 계층은 internal/store입니다.

이 저장소에서 배울 핵심은 AI의 기억도 결국 소유권·중복·검색·재시도를 설계해야 하는 데이터라는 점입니다. 모델의 가중치를 바꾸는 학습이 아니라, 필요한 기록을 다음 대화의 입력에 다시 넣는 방식입니다. 저장된 내용이 있어도 에이전트가 검색해서 읽지 않으면 그 대화에 활용되지 않습니다.

1-1. 기억 하나의 생애

1. 선별: 에이전트가 다시 쓸 가치가 있는 버그 원인이나 결정을 고릅니다.
2. 기록: mem_save가 프로젝트를 확인하고 저장 계층을 호출합니다.
3. 보존: SQLite의 observations와 검색 색인이 함께 갱신됩니다.
4. 회수: 다음 세션에서 mem_context·mem_search로 후보를 찾습니다.
5. 상세 조회: mem_get_observation으로 필요한 기록만 자세히 읽습니다.

# 설치된 실행 파일로 사용하는 CLI 예시
engram save '로그인 재시도 원인' \
  'What: 토큰 갱신 경합 수정. Why: 동시 요청이 갱신을 중복 실행. Where: auth/refresh.go. Learned: 갱신을 직렬화한다.' \
  --type bugfix --project study-app --topic auth/refresh-race

engram search '토큰 갱신' --project study-app --match all
engram context --project study-app

cmd/engram/main.go의 parseSaveArgs()에서 제목과 본문은 위치 인자입니다. 토픽 옵션 이름은 --topic입니다. 내부의 topic_key 필드와 CLI 옵션의 이름이 다르므로 문서와 실제 파서를 함께 읽어야 합니다.

2왜 주목받는가

2-1. 순위보다 먼저 볼 문제

긴 개발 작업에서는 에이전트를 바꾸거나 대화를 압축할 때 이전 결정의 근거가 빠지기 쉽습니다. 같은 프로젝트의 테스트 관례나 실패한 접근을 계속 설명해야 한다면, 기록을 대화 밖으로 분리할 이유가 생깁니다. engram은 이 문제를 특정 모델의 내부 기능 대신 별도 저장소와 공통 도구 인터페이스로 다룹니다.

2026-10-23 GitHub Trending Go Weekly #7, 스타 7,554개라는 수치는 관심의 크기를 보여줍니다. 다만 순위만으로 유입 원인이나 성능 우위를 알 수는 없습니다. 다음 세 가지는 구현에서 읽을 수 있는 매력에 대한 해석입니다.

• 로컬 도입 비용: 기본 메모리 기능에는 별도 데이터베이스 서버나 임베딩 서버가 필요하지 않습니다.
• 에이전트 간 재사용: MCP 도구와 공통 저장 계층 덕분에 특정 대화 UI에 기억이 갇히는 일을 줄입니다.
• 확장 경로: 로컬 사용에서 시작해 파일 청크 공유와 선택형 클라우드 복제로 넓힐 수 있습니다.

에이전트와 기억 저장소를 분리하면, 사용하는 에이전트가 바뀌어도 기록의 수명을 유지할 수 있습니다. 단, 도구를 연결하는 것과 에이전트가 적절한 시점에 도구를 쓰는 것은 별개입니다. 저장 규칙을 안내하는 프로토콜과 플러그인도 함께 봐야 합니다.

2-2. 비슷한 접근과 비교하면 무엇이 보이나

마지막 행은 docs/COMPARISON.md에 실린 engram 저자의 비교 관점입니다. 그 문서의 “웹 UI” 행은 engram을 TUI 중심으로만 설명하지만, 현재 소스에는 Cloud 대시보드도 있습니다. 따라서 비교 문서 전체를 최신 경쟁 제품 평가표로 받아들이기보다, 설계 철학을 설명하는 자료로 읽는 편이 정확합니다.

2-3. “의존성 없음”을 정확히 읽기

README의 “single binary, zero dependencies”는 기본 로컬 실행에 별도 Node.js·Python·Docker가 필요 없다는 설명입니다. go.mod에는 SQLite 드라이버, MCP SDK, TUI 라이브러리 등 다수의 빌드 의존성이 있습니다. Cloud 서버는 PostgreSQL을 쓰고, 선택적 의미 비교는 외부 에이전트 CLI를 호출합니다.

3기술 스택 전체 지도

3-1. 백엔드와 데이터 계층

v1.58.0은 Go 드라이버 모듈의 버전입니다. SQLite 엔진 버전과 같은 번호라고 읽으면 안 됩니다. FTS5는 이 저장소에서 사용하는 SQLite의 전문 검색 기능이며, 검색을 위해 외부 벡터 데이터베이스를 띄우지 않습니다.

3-2. 프론트엔드는 두 종류다

캐럿(^)이 붙은 값은 허용 범위이며, 정확히 그 버전이 설치된다는 뜻은 아닙니다. Pi의 * 피어 의존성도 고정 버전이 아닙니다. 웹 대시보드에는 React SPA를 빌드하는 루트 package.json이 없고, 플러그인별 Node.js 생태계가 따로 있습니다.

3-3. 인프라·빌드·검증

스택을 읽을 때는 사용자가 실행하는 부품과, 개발·배포할 때만 필요한 도구를 분리해야 합니다. CI의 Node.js 24를 보고 모든 engram 사용자가 Node.js를 설치해야 한다고 해석하면 구조를 놓칩니다.

.github/workflows/ci.yml은 make templ 뒤 생성된 *_templ.go의 차이를 검사합니다. 이어 go test ./...와 실행 파일의 빠른 자체 검증을 구성합니다. 이 설정은 검증 의도를 보여주며, 특정 환경의 실제 통과 결과나 성능 수치를 대신하지는 않습니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조

실행 진입점은 cmd/engram/main.go입니다. engram mcp는 표준 입력·출력으로 통신하는 서버이고, engram serve는 기본 127.0.0.1:7437의 로컬 JSON API입니다. engram cloud serve는 PostgreSQL과 웹 대시보드를 가진 별도 실행 모드입니다.

파일 첫머리의 오래된 사용법 주석에는 serve가 “HTTP + MCP”라고 적혀 있지만, 실제 분기는 cmdServe()와 cmdMCP()로 나뉩니다. 실행 경로를 확인할 때는 요약 주석보다 명령 분기와 핸들러 등록을 우선해야 합니다.

4-2. 패턴 ① 얇은 입구와 공통 저장 규칙

internal/mcp/mcp.go의 NewServerWithConfig()와 registerToolsWithQueue()는 MCP 도구와 핸들러를 묶습니다. handleSave()는 인자를 해석하고 프로젝트·세션을 확인한 뒤 Store.AddObservation()을 호출합니다. CLI의 cmdSave()도 같은 저장 계층으로 이어집니다.

입구마다 JSON·명령행 인자·키보드 메시지의 모양은 다르지만, 제목 검증, 비공개 구간 제거, 토픽 갱신, 중복 판정, 동기화 변경 기록은 internal/store가 맡습니다. 이런 구조를 어댑터와 도메인 분리라는 관점으로 읽을 수 있습니다.

// internal/store/runner.go의 실제 인터페이스
type SemanticRunner interface {
    Compare(ctx context.Context, prompt string) (SemanticVerdict, error)
}

internal/server/server.go에는 SemanticRunnerFactory와 SemanticPromptBuilder가 있습니다. 서버가 LLM 구현 패키지를 직접 소유하지 않고, cmd/engram에서 필요한 함수를 주입합니다. 기능을 공유하되 패키지 순환 참조를 피하는 구체적인 사례입니다.

4-3. 패턴 ② 트랜잭션 장부로 재시도와 동기화를 묶기

AddObservationWithResult()는 저장 전에 프로젝트를 정규화하고, stripPrivateTags()와 prepareStoredContent()로 본문을 정리합니다. 제목·본문을 검증한 다음 withWriteTimings()의 트랜잭션 안에서 다음 분기를 처리합니다.

recordObservationSaveOperationTx()는 선택적으로 observation_save_operations에 작업 ID·fingerprint·기록 ID를 쓰고, enqueueSyncMutationTx()로 전송 대상 변경을 기록하는 경로를 호출합니다. 다만 enqueueSyncMutationWithSourceTx()는 isProjectEnrolledTx()로 복제 등록 여부를 검사합니다. 미등록 프로젝트는 로컬 저장만 유지하고 Cloud 변경 행을 쌓지 않으며, 등록할 때 현재 상태를 백필합니다. 등록된 프로젝트에서 저장과 변경 예약의 틈을 줄이는 트랜잭션 아웃박스로 해석할 수 있습니다.

복제에 등록된 프로젝트에서는 기억 본문과 전송할 변경이 같은 트랜잭션에서 함께 확정됩니다. 클라우드 전송 자체가 이 트랜잭션 안에서 끝난다는 뜻은 아닙니다. 네트워크 실패는 나중에 재시도하고, 로컬 기록은 먼저 확정합니다.

세 장치는 같은 문제가 아닙니다. 토픽 갱신은 내용을 바꾸고, 중복 제거는 중복 횟수를 올리지만, 동일 작업의 재시도는 원래 결과를 돌려주며 같은 변경을 반복하지 않도록 합니다. 작업 ID를 주지 않는 호출에는 장부 기반 보장이 적용되지 않습니다. 현재 MCP의 handleSave()는 저장 매개변수에 OperationID를 넘기지 않으므로, 저장 계층의 기능을 모든 MCP 저장의 재실행 보장으로 확대하면 안 됩니다.

4-4. 패턴 ③ 인덱스와 원본을 동기화하는 검색 투영

원본은 observations, 검색용 구조는 observations_fts입니다. FTS 테이블은 content='observations'와 content_rowid='id'로 원본에 연결되며, 삽입·수정·삭제 트리거가 색인을 갱신합니다. migrateFTS()는 스키마와 트리거를 점검합니다.

-- internal/store/store.go의 검색 테이블 선언
CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
    title, content, tool_name, type, project, topic_key,
    tokenize='trigram',
    content='observations',
    content_rowid='id'
);

SearchContext()와 MCP용 SearchPreviewsContext()는 세 글자 미만 검색어가 있으면 hasShortFTSTerm()을 통해 LIKE 경로로 보냅니다. 나머지는 FTS5로 검색합니다. 세 글자는 바이트 길이가 아니라 utf8.RuneCountInString()으로 셉니다.

buildSearchFTSQueryWithColumns()의 BM25 가중치는 제목 5.0, 본문 1.0, 토픽 3.0입니다. 고정(pinned) 여부·최근성·수정 및 중복 횟수로 정렬값도 보정합니다. FTS5의 BM25는 더 작은 음수 값이 좋은 결과이며, 코드도 보정한 값의 오름차순으로 정렬합니다.

정렬에 쓰는 복합 값과 결과의 rank 필드는 구분해야 합니다. SQL은 rank에 원래 BM25 값을 실어 주고, ORDER BY에는 보정한 식을 씁니다. 숫자 하나만 보고 최종 순위를 설명하면 틀릴 수 있습니다.

MCP의 handleSearch()는 기본적으로 미리보기를 조회합니다. SQL의 substr(o.content, 1, 300)으로 본문 일부만 가져오고, 필요할 때 상세 도구를 호출하게 합니다. 이 300은 SQLite 문자열 기준의 문자 수이며, 저장 본문 제한의 바이트 수와 다릅니다.

4-5. 패턴 ④ 전송 인터페이스로 파일 공유와 Cloud 복제 연결

internal/sync/transport.go의 Transport는 저장 매체를 네 메서드로 추상화합니다. 파일 구현은 FileTransport, 원격 청크 구현은 internal/cloud/remote/transport.go의 RemoteTransport입니다. 동기화 알고리즘이 파일 경로와 HTTP 요청을 직접 모두 알 필요를 줄입니다. 백그라운드 복제는 internal/cloud/autosync의 별도 CloudTransport 계약으로 변경을 주고받으며, cmd/engram/main.go에서 MutationTransport를 어댑터로 연결합니다.

// internal/sync/transport.go의 실제 계약
type Transport interface {
    ReadManifest() (*Manifest, error)
    WriteManifest(m *Manifest) error
    WriteChunk(chunkID string, data []byte, entry ChunkEntry) error
    ReadChunk(chunkID string) ([]byte, error)
}

FileTransport.WriteChunk()는 청크를 gzip으로 압축해 저장합니다. chunkcodec.ChunkID()는 SHA-256 결과의 앞 8개 16진수 문자를 ID로 사용합니다. 콘텐츠에서 ID를 만들지만 전체 SHA-256을 ID로 보관하는 설계는 아니며, 이 짧은 ID를 보안 인증값으로 해석하면 안 됩니다.

주석과 확장자는 .jsonl.gz라고 표현합니다. 그러나 internal/sync/sync.go의 내보내기는 jsonMarshalChunk(chunk)를 호출하고, 기본 함수는 json.Marshal입니다. 실제 청크는 세션·기록·변경을 묶은 JSON 객체이므로, “한 줄마다 메모리 하나”라고 단정해서 파서를 만들면 안 됩니다.

4-6. 동시성과 복구: 위 패턴이 실제로 버티게 하는 장치

storeDSN()은 _txlock=immediate를 지정합니다. 읽은 뒤 쓰기로 전환하다가 다른 쓰기와 충돌하는 일을 줄이기 위해 트랜잭션 시작에 쓰기 예약을 잡습니다. WAL과 5초 잠금 대기, 저장 계층의 잠금 오류 재시도도 함께 사용합니다.

db.SetMaxOpenConns(1)은 각 Store의 연결 풀을 하나로 제한합니다. MCP 프로세스가 여러 개면 데이터베이스 전체 연결이 하나인 것은 아닙니다. internal/mcp/write_queue.go는 기본 크기 32의 채널로 쓰기를 직렬화하고, 가득 차면 재시도를 안내합니다.

최근 커밋의 diagnostic.BuildRepairPlan()은 vetoProjectAliasMoves()로 현재 별칭과 저장된 디렉토리 증거를 다시 읽습니다. 별칭이 이동 대상과 충돌하면 project_alias_contradicts_reclassification 사유로 제외합니다. 별칭은 잘못된 이동을 막는 증거이며, 그것만으로 과거 기록의 소유자를 바꾸도록 허가하지는 않습니다.

5디렉토리 구조 해부

5-1. 처음 읽는 사람의 경로

파일을 처음부터 끝까지 읽기보다, 사용자 행동 하나를 골라 입구에서 저장소까지 따라가면 구조가 보입니다. 특히 internal/store/store.go는 약 14,444줄입니다. 첫 정독 대상으로 삼기보다 함수명과 호출 경로를 기준으로 나눠 읽는 편이 낫습니다.

5-2. 언어별 코드 규모

커밋 ab461b9의 Git 추적 파일을 확장자별로 구분한 물리적 줄 수입니다. 빈 줄과 주석을 포함하며, 문서·이미지·JSON은 아래 합계에 넣지 않았습니다. 생성 코드는 따로 표시했습니다. 압축된 JS·CSS는 한 줄에 많은 코드가 들어갈 수 있습니다.

테스트가 많다는 사실은 읽을 수 있는 동작 사례가 많다는 뜻입니다. 테스트 줄 수만으로 결함 수, 커버리지, 운영 안정성을 추정할 수는 없습니다. 코드 줄 수는 개발 이력의 길이나 장기간 기여 비율을 알려주지 않습니다.

6학습 포인트 (기술별)

6-1. Go: 인터페이스는 필요한 쪽의 계약이다

Transport는 파일 시스템과 HTTP라는 구현보다 “청크를 읽고 쓴다”는 요구를 먼저 드러냅니다. SemanticRunner는 외부 CLI 이름 대신 비교 결과의 형태를 계약으로 고정합니다. Go에서는 구현체에 별도의 implements 선언이 없어도 메서드가 맞으면 인터페이스를 만족합니다.

• 배울 것: 구조체, 메서드, 인터페이스, 오류 감싸기, context.Context의 취소 전달.
• 작은 실습: 메모리 안의 맵을 사용하는 Transport 모형을 별도 연습 코드로 설계합니다.
• 완료 기준: 동기화 로직에 로컬 경로나 HTTP 상태 코드를 넣지 않고도 실패를 표현할 수 있어야 합니다.

소스의 if err != nil은 장식이 아닙니다. “파일이 없다”와 “읽을 권한이 없다”를 모두 빈 데이터로 취급하면 복구 동작이 위험해집니다. FileTransport.ReadManifest()가 이 둘을 구분하는 방식을 확인해 보세요.

6-2. SQLite: 같은 트랜잭션에 넣어야 할 것을 고르기

withWriteTimings()는 시작·본문 실행·커밋을 공통으로 감싸고 실패하면 롤백합니다. 핵심은 문법보다 묶음의 범위입니다. 기록과 선택적 작업 장부, 복제 등록된 프로젝트의 동기화 변경을 같은 묶음으로 다룹니다.

• 배울 것: 외래 키, 트랜잭션, WAL, 쓰기 잠금, 소프트 삭제, 마이그레이션.
• 작은 실습: 메모리 본문을 쓴 뒤 장부 삽입을 실패시키는 상황을 종이에 그립니다.
• 완료 기준: 롤백 뒤 남아도 되는 것과 남으면 안 되는 것을 표로 설명합니다.

observations.deleted_at은 기록을 숨기는 소프트 삭제에 쓰입니다. 검색 SQL에 o.deleted_at IS NULL이 들어가는 이유를 원본 보존과 사용자 노출의 분리로 읽어 보세요.

6-3. 검색: 좋은 제목과 언어별 경계 조건

기본 검색은 임베딩 유사도가 아니라 FTS5의 문자열 기반 검색입니다. 제목과 토픽의 가중치가 높으므로 “버그 수정”보다 “토큰 갱신 경합으로 중복 요청 발생”처럼 원인을 담은 제목이 유용합니다. 검색 품질은 랭킹 식뿐 아니라 기록 품질에도 달려 있습니다.

• 배울 것: 역색인, trigram, BM25, AND/OR, SQL 매개변수, 미리보기와 상세 조회.
• 작은 실습: 토큰·토큰갱신·갱신토큰의 검색 경로와 결과 차이를 예측합니다.
• 완료 기준: 두 글자 검색의 지원 여부와 FTS 랭킹 사용 여부를 따로 답합니다.

escapeLIKE()는 %와 _를 이스케이프합니다. SQL 매개변수 바인딩은 SQL 구조 삽입을 막는 문제이고, 와일드카드 이스케이프는 검색 의미를 보존하는 문제입니다. 둘 중 하나만 해서는 같은 효과를 얻지 못합니다.

6-4. MCP·HTTP: 같은 데이터, 다른 계약

MCP는 모델이 호출할 도구의 이름·인자·결과를 제공합니다. ResolveTools()는 프로필 이름과 도구 이름의 쉼표 목록을 해석합니다. 모든 도구가 항상 필요하지 않은 환경에서는 도구 집합도 구성 요소가 됩니다.

# 필요한 도구만 노출하는 stdio 서버 구성 예시
engram mcp --project study-app --tools=mem_search,mem_get_observation

HTTP에서는 경로·메서드·상태 코드·인증이 별도의 계약이 됩니다. internal/server/server.go의 routes()와 internal/cloud/cloudserver의 경계를 섞지 말고 읽어야 합니다. 같은 실행 파일에 들어 있어도 로컬 API와 Cloud API가 같은 권한 모델인 것은 아닙니다.

도구를 연결하는 문제와 도구가 다룰 데이터의 소유권을 확인하는 문제는 각각 설계해야 합니다. 저장 계층의 UpdateObservationForProject()·DeleteObservationForProject()는 호출자가 주장한 프로젝트와 실제 소유 프로젝트를 트랜잭션 안에서 비교합니다. 이 일관성 확인만으로 사용자를 인증하는 것은 아닙니다.

6-5. 화면: TUI의 메시지 루프와 웹의 HTML 조각

internal/tui/model.go의 Init()는 초기 명령을 반환하고, internal/tui/update.go의 Update()는 입력이나 검색 결과 메시지로 상태를 바꿉니다. internal/tui/view.go의 View()는 현재 상태를 문자열 화면으로 표현합니다.

웹 쪽에서는 dashboard.Mount()가 전체 페이지와 부분 응답의 경로를 등록합니다. internal/cloud/dashboard/embed.go의 go:embed static은 CSS·HTMX를 실행 파일에 포함합니다. TUI와 웹 모두 “현재 상태를 어디서 관리하고, 어떤 입력이 상태를 바꾸는가”라는 질문으로 읽을 수 있습니다.

• 작은 실습: TUI의 검색 성공과 실패를 각각 메시지 순서도로 그립니다.
• 비교 실습: 웹의 브라우저 목록 경로와 관찰 기록 부분 응답 경로를 짝지어 봅니다.
• 완료 기준: 화면을 그리는 코드 안에 데이터베이스 쓰기를 넣지 않아야 하는 이유를 설명합니다.

6-6. 테스트·배포: 정상 결과보다 경계 조건을 읽기

저장·검색·동시성 테스트는 internal/store/에, MCP·진단 테스트는 internal/의 각 패키지에 있습니다. CI의 검증 구성과 배포 대상 6개 조합을 함께 보면, “내 컴퓨터에서 동작”을 여러 운영체제의 제품으로 넓히는 비용이 보입니다.

7하드웨어 / 시스템 요구사항

공식 문서에는 CPU 코어 수, 최소 RAM, 처리량에 대한 정량 보장이 없습니다. 기본 저장·FTS 검색에 GPU를 요구하는 모델 실행 경로는 없습니다. 에이전트 모델 자체의 실행 환경은 engram 로컬 저장소의 요구사항과 별도로 판단해야 합니다.

실행 파일은 가벼운 배포 형태이지만, 데이터 용량과 동시 쓰기 비용까지 사라지는 것은 아닙니다. DefaultConfig()의 본문 잘림 기준은 50000바이트입니다. 이를 넘으면 UTF-8 문자 경계에서 자른 뒤 “... [truncated]”를 덧붙이므로 저장 문자열은 기준보다 길어질 수 있습니다. 한국어 5만 글자를 뜻하지 않으며, 검색 색인·버전 이력·WAL·백업은 추가 디스크를 사용합니다.

7-1. 용량은 이렇게 나누어 생각한다

기록 10,000개에 본문이 평균 2,000바이트라면 본문 합계만 약 20MB입니다. 모두 50,000바이트를 채우면 본문만 약 500MB입니다. 이는 곱셈으로 구한 본문 크기 예시이며, 실제 DB 파일 크기나 메모리 사용량의 측정값이 아닙니다.

• 크기를 늘리는 요소: 제목·세션·프롬프트·관계·검색 색인·이전 버전·동기화 청크.
• 응답 시간을 바꾸는 요소: 기록 수, 긴 본문, 짧은 질의의 LIKE 경로, 동시에 저장하는 프로세스 수.
• 측정 항목: DB와 WAL 크기, 프로세스 메모리, 검색·저장 지연의 중앙값과 상위 구간.

7-2. SQLite 파일 위치도 시스템 설계다

ENGRAM_DATA_DIR의 비어 있지 않은 값은 절대 경로여야 합니다. 저장소의 파일 시스템 검사와 설치 문서는 알려진 NFS·SMB/CIFS 위치를 거부하도록 합니다. 여러 기기의 공유는 DB 파일을 네트워크 드라이브에 놓는 방식보다 청크·Cloud 복제 경로를 이해하고 사용해야 합니다.

8직접 해볼 수 있는 실습 과제

실행 과제는 설치된 engram과 실제 기록이 없는 전용 실습 데이터 디렉토리를 전제로 합니다. 변경하는 과제는 별도 연습용 사본에서 진행하고, 우선 소스와 테스트만 읽어 예상 결과를 적어도 좋습니다.

# POSIX 셸 예시: 실습 디렉토리 안에서 시작
mkdir -p engram-lab
cd engram-lab
export ENGRAM_DATA_DIR="$PWD/data"

engram save '인증 정책' '만료된 토큰은 한 번 갱신한다.' \
  --project study-app --topic auth/policy
engram save '인증 정책' '동시 갱신은 하나로 합친다.' \
  --project study-app --topic auth/policy
engram search '인증 정책' --project study-app

engram save '검증 기록' '테스트용 동일 본문' --project study-app
engram save '검증 기록' '테스트용 동일 본문' --project study-app

engram search '토큰' --project study-app
engram search '토큰갱신' --project study-app
engram search '토큰 정책' --project study-app --match all
engram search '토큰 정책' --project study-app --match any

9관련 기술 심화 학습 로드맵

주마다 “읽기 → 작은 모형 → 실패 사례 → 설명”을 한 번씩 반복합니다. 처음부터 모든 플러그인이나 Cloud 인증을 구현할 필요는 없습니다. 한 경로의 입력·저장·응답을 끝까지 설명하는 것이 우선입니다.

진도를 나가는 기준은 읽은 파일 수보다, 실패했을 때 남는 상태를 스스로 예측할 수 있는지입니다. 예측이 어긋난 지점이 다음에 읽어야 할 함수입니다. 결과만 맞히기보다 “어느 트랜잭션과 검증이 그 결과를 보장하는가”까지 연결해 보세요.

9-1. 관심사에 따라 이어갈 갈래

• 백엔드: 연결 풀과 여러 프로세스의 잠금 차이 → SQLite 재시도 → PostgreSQL 트랜잭션으로 확장합니다.
• 검색·RAG: 어휘 검색의 실패 사례를 먼저 수집한 뒤, 동의어·임베딩·혼합 검색이 필요한 상황을 정의합니다.
• 에이전트: 도구 스키마 → 저장 시점 규칙 → 검색 결과 분량 → 에이전트가 실제로 기억을 활용하는지 평가합니다.
• 화면: TUI 메시지 루프와 HTMX 부분 갱신을 비교하고, 로딩·오류·빈 결과의 상태를 설계합니다.
• 운영: 백업·복구 계획·감사 기록 → 현재 증거 재확인 → 프로젝트별 권한 경계로 넓혀 갑니다.

10핵심 키워드 사전

scope=personal이나 프로젝트 소유권 검사가 디스크 암호화를 의미하지는 않습니다. 기능의 이름이 무엇을 약속하는지, 실제 저장·조회 조건이 무엇인지 나누어 이해해야 합니다.

11참고 링크

11-1. 공식 저장소와 사용 문서

• 공식 GitHub 저장소 — 설치·릴리스·전체 기능의 출발점.
• v3.5.2 릴리스 — 2026-10-21 공개된 최신 릴리스.
• 명령·MCP·HTTP·데이터 구조 참조 — 커밋 기준의 전체 사용 계약.
• 코드베이스 안내 — 계층별 읽기 경로.
• 설치와 파일 시스템 제약 — 기본 실행과 소스 빌드 요구를 함께 확인.
• 에이전트별 연결 설정 — 도구 연결과 플러그인 동작.
• Engram Cloud 문서 — 선택형 복제와 운영 범위.
• 저자가 쓴 claude-mem 비교 — 설계 철학 설명으로 읽고 현재 기능과 대조.

11-2. 본문의 핵심 코드 근거

• go.mod — Go 1.25.10과 직접·간접 모듈 버전.
• 명령 진입점 — cmdSave()·cmdSearch()·로컬 런타임 조립.
• SQLite 저장·검색 구현 — AddObservationWithResult()·SearchContext()·storeDSN().
• MCP 도구와 응답 — handleSave()·handleSearch()·도구 프로필.
• MCP 쓰기 큐 — 포화·취소·작업자 처리.
• 로컬 HTTP 서버 — routes()와 기본 루프백 바인딩.
• 전송 인터페이스 · 청크 동기화 구현 — 파일 전송과 변경 승인 경계.
• 청크 ID·정규화 — SHA-256 축약 ID와 데이터 검증.
• 진단 복구 계획 · 별칭 안전 조건 테스트 — 최근 수정의 핵심.
• 대시보드 레이아웃 — 서버 HTML과 저장소에 포함된 정적 자원.
• CI 워크플로 · 릴리스 구성 — 생성 코드 검사와 다중 플랫폼 빌드.

11-3. 관련 기술 공식 학습 자료

• A Tour of Go · database/sql 문서 — Go 문법과 연결·트랜잭션 기초.
• SQLite FTS5 · SQLite WAL — 검색과 동시성의 바탕.
• modernc.org/sqlite v1.58.0 — 실제 사용한 드라이버 모듈.
• MCP 공식 명세 · mcp-go v0.44.0 — 프로토콜과 SDK 구분.
• Bubble Tea v1.3.10 — 메시지로 상태를 바꾸는 TUI 설계.
• templ 공식 안내 · HTMX 공식 문서 — 서버 렌더링과 HTML 부분 갱신.
• PostgreSQL 16 문서 — 선택형 Cloud 데이터 계층.

현재 상태 (2026-10-23 확인)