💬말로 만드는 AI▶ 유튜브
🗂️ 뒷이야기 · 09

09 단계 회사 자료를 파이스에 — 색인과 MCP 창구

이 페이지 목차목적만든 순서1 · 로드맵을 같은 날 두 번 썼다 (8/9)2 · 의미 검색의 첫 판 — 임베딩 모델을 실측으로 골랐다 (8/13~8/14)3 · NAS 를 읽는 길 — 드라이브 글자 대신 윈도우 공유 (8/14)4 · 6천 장에서 198만 장으로 — 커질 때마다 터진 것 (8/14~8/16, 8/28)5 · 카드 창고를 볼트 밖으로, 밤 일과를 순서대로 (8/15~8/16)6 · MCP 창구 — 색인을 Claude 채팅에서 쓴다 (8/28)7 · 색인이 둘이었다 — AI 가 다른 색인만 보고 있었다 (9/21~9/22)8 · 직원에게 열기 — OAuth · 부서 범위 · 이용 기록 (9/24~9/25)9 · 커넥터가 1시간마다 끊기던 원인 — 짐작은 틀렸고 요청 자취로 잡았다 (9/26)💡 설명함정과 배운 것출처

뒷이야기 · 9 / 17단계 · 2026-08-09 ~ 08-28 (+ 09-21 ~ 09-26) · 갈래 회사 자료 AI
이전 단계: 08 사내 앱 — 차량관리와 ERP 시안 · 다음 단계: 10 파이스의 두 번 이사 — PC → 맥북 → 맥미니

핵심 요약

항목내용
이 단계에서 한 일사내 NAS 의 부서 공유 15곳 파일을 "파일 카드"(이름·원본 위치·크기·수정일을 적은 노트 한 장)로 만들고, 로컬 모델 bge-m3 로 뜻을 보고 찾는 색인을 만들었다. 그 색인을 개인 Claude 에서 쓰는 MCP 창구를 8/28 에 열었고, 9월에 직원 로그인(OAuth)과 부서 범위를 달아 직원에게 열었다.
기간2026-08-09 ~ 08-28(색인과 첫 창구) · 09-21 ~ 09-26(범위 · 직원 개방 · 연결 끊김 수리)
규모8/9~8/28 커밋 177개(작성자 cwkim83 165 · PAIS 12) 중 제목 머리표가 index · semantic · vault · mcp · nas-sync · search 인 것 31개. 9/22~9/26 MCP · BYO 머리표 커밋 18개. mcp.js 157줄(8/28) → 1,440줄(10/8), mcp_oauth.js 445줄(9/24) → 635줄
다룬 도구Synology NAS · 윈도우 공유(SMB) · Ollama bge-m3 · 볼트 카드 · MCP(Streamable HTTP) · OAuth · claude.ai 커넥터 · cloudflared
결과색인 노트 6,787장(8/13) → 1,982,826장(10/7) · MCP 도구 2 → 10 · 의미 검색 4~6초 → 0.3초 · 글자 검색 386초 → 0.4초 · 커넥터 토큰 갱신 78번 모두 성공(이용 기록, 10/8)
공개 범위사내(로그인 뒤) — 🔒 항목(NAS 경로 · 고객 자료 · 인사 자료 · 키)은 넣지 않음

한 줄 요약 — 회사 자료를 AI 에 붙이는 첫 일은 "다 읽기"가 아니라 "어디 있는지 찾게 하기"였고, 창구를 넓힐 때마다 범위부터 좁혔다.

9단계 · 회사 자료를 파이스에 — 색인과 MCP 창구

목적

5단계까지 파이스는 몸통과 안전망을 갖췄지만 회사 자료를 찾는 길은 얇았다. 색인 카드는 한 부서 6,619장이 쌓인 정도였다. 8/9 로드맵 첫 판은 몸은 다 만들었는데 그 안이 비어 있다고 적었다.
회사 자료는 NAS(네트워크로 붙는 사내 저장 장치)의 부서 공유 폴더에 흩어져 있었고, 찾으려면 사람이 폴더를 열어야 했다. 이 단계의 목표는 둘이었다. 파이스가 자료 위치를 알게 하는 것, 그리고 그 앎을 파이스 밖(개인 Claude)에서도 쓰게 하는 것.

만든 순서

1 · 로드맵을 같은 날 두 번 썼다 (8/9)

8/9 09:00 첫 판(5f06094)은 Phase 8~11 을 "AI 부서" 계획으로 적었고, 그 안에 "NAS 2만 파일을 증분 색인한다"가 들어 있었다. 10:45 에 전면 개정했다(d7d3731). 상위 사업 「Sejong Data Base 구축」 제안서(v6.1, 8/7)의 실측이 그 전제를 무너뜨렸기 때문이다. ROADMAP 에 옮겨 적은 숫자는 이렇다.

  • 한 부서의 프로젝트 폴더 하나가 파일 82,923개(그 부서 전체는 10만 개 이상)
  • 색인 카드 2,379장 중 요약이 빈 카드 1,301장(55%) — 옛 형식(.hwp .ppt .xls)과 스캔 PDF
  • 색인된 것의 절반 이상이 ~$ 임시 파일이었고 휴지통까지 색인돼 있었다
  • "올해 어느 지역에서 무슨 공사를 했나" 같은 질문에는 지역·연도로 묶을 기준이 없어 답하지 못했다

개정판의 판단은 한 줄이다. 큰 모델을 쓰고도 답을 못 냈으니 모델이 아니라 저장 방식의 문제다. 정리 안 된 자료를 더 빨리 색인하는 것은 쓰레기를 효율적으로 색인하는 일이다. 병목은 프로젝트 코드였다. 코드가 네 종류로 갈려 NAS 폴더 · 플랫폼 레코드 · 색인 카드를 자동으로 잇지 못했다. 양 끝은 이미 돌아가는데 가운데 열쇠가 없다고 적었다.
이 로드맵의 Phase 8(코드 파서 · 폴더 자동 생성 · 명명 검사)에 해당하는 모듈은 src 와 scripts 에서 찾지 못했다. 임시 파일 제외는 nas_walk.js 규칙으로, "코드가 열쇠"라는 생각은 메일 라벨 분류(gmail_label.js: "라벨이 공사번호의 유일한 권위다")로 다른 모습이 되어 남았다. 실제로 먼저 간 길은 색인과 검색이었다.

2 · 의미 검색의 첫 판 — 임베딩 모델을 실측으로 골랐다 (8/13~8/14)

8/13 16:58(202256f)에 vault_semantic.js 가 처음 들어왔다. 노트마다 벡터(글을 숫자 줄로 바꾼 것) 하나를 만들고, 만들 때 정규화해 두면 검색은 내적(곱셈 합) 한 번이다. 외부 벡터 DB 를 쓰지 않았다. 패키지 0 원칙을 지켰다. 6,787장 전체 색인에 366초가 걸렸다.
임베딩을 해 줄 곳이 문제였다. 커밋 메시지에 남은 실측은 이렇다.

  • voyage: 결제수단이 없으면 분당 3회·1만 토큰 제한 — 6,787장에 4시간 넘게 걸리고 429(요청 한도 초과 응답)
  • gemini-embedding-001: 그날 할당량이 이미 소진
  • nvidia nv-embedqa: 통과했다. 그런데 8/14 11:44 에 한국어 6문제로 재 보니 1문제만 맞고 나머지는 모두 같은 노트를 답으로 냈다. 영어 질의응답 전용 모델이었다.
  • gemini 직결: 6문제 모두 맞았지만 키당 하루 1,000회 한도에 6,734장 중 1,800장에서 멈췄다
  • 12:04 에 이 PC 의 Ollama bge-m3 를 직접 돌렸다. 전체가 2.4분. 실제 노트 240장 시험에서 1위 4/5, 3위 안 5/5(gemini 768차원은 4/5, 4/5)

bge-m3 로 정한 이유는 세 가지다. 품질이 낫고, 하루 한도가 없고, 자료가 PC 밖으로 나가지 않는다. 시방서·검사기록 같은 회사 문서의 경로가 남의 서버로 가지 않는 점이 속도보다 컸다고 커밋에 적었다. 같은 때 고친 버그가 셋 있다. 폴더 하나만 색인하면 폴더 밖 벡터가 지워졌고(21장 → 10장), 글자 수로 토큰 상한을 맞추려던 계산이 계속 틀려서 "걸리면 60%로 줄여 재시도"로 바꿨고, 429 한 번에 색인 전체가 죽던 것을 물러섰다 재시도하게 했다.

3 · NAS 를 읽는 길 — 드라이브 글자 대신 윈도우 공유 (8/14)

NAS 를 훑는 일에서 사고가 연달아 났다.

  • 드라이브 글자(Z:)로 붙이는 연결 프로그램은 읽은 것을 제 메모리에 쌓고 윈도우가 회수하지 못했다. 6,700장을 색인하니 그 프로세스가 19GB 가 됐고 여유 메모리가 0.99GB 로 떨어져 앱들이 멈췄다. 처음엔 Ollama 탓으로 짐작했지만 아니었다. 윈도우 공유(UNC) 경로로 직접 읽도록 바꿨다(761438d, 8/14 15:49). 윈도우 자체 파일 캐시는 메모리가 모자라면 알아서 버린다.
  • 색인 카드를 한 폴더에 평면으로 쌓고 있었다. 이름이 같은 파일(첨부1.pdf 같은 것)이 서로 덮어써서 조용히 사라졌다. 원본 폴더 구조 그대로 카드를 쌓도록 고쳤다(3323908).
  • 어느 공유는 파일 1,759개가 전부 CAD 라 색인이 0장이었다. 도면 확장자 27종을 넣어 1,612장이 됐다(b912749). 내용을 못 읽어도 파일명과 폴더 경로로는 찾을 수 있어야 한다는 이유였다. 9/18 실측으로 DWG 카드는 224,306장이다. 도면 안쪽(표제란 · 주기) 읽기는 별개의 추가 단계로 남아 있다.
  • 한 부서 폴더의 "개인 자료" 하위 폴더 하나가 335,200장이었다. 그 부서 전체의 61%. 회사 지식이 아니고 검색 결과를 개인 파일로 덮는다며 색인에서 뺐다. crazy4eu(cwkim83)의 지시였다(eb17e9e).
nas to claude · 크게 보기 ↗

4 · 6천 장에서 198만 장으로 — 커질 때마다 터진 것 (8/14~8/16, 8/28)

8/13~8/16 나흘 동안 커밋이 70개였고 그중 19개가 vault_semantic.js 를 건드렸다. 커질 때마다 다른 곳이 터졌다.

  • 80만 장이면 벡터 파일이 3.3GB 다. 한 덩어리(Buffer)로 넘기면 Node 의 크기 한계에 걸려 4시간 임베딩이 마지막 쓰기에서 실패하는 구조였다. 256MB 씩 흘려 쓰게 했다(ff1e7b1, 8/14 20:42). 100만 장(4GB 를 두 벌)이면 합치기에서 메모리가 모자라 5시간 임베딩이 통째로 날아갈 상황이었다. 새 벡터만 메모리에 두고 파일로 합치며, 임시 파일에 다 쓴 뒤 이름을 바꿔치기해서 도중에 죽어도 옛 색인이 살게 했다(eb17e9e).
  • 8/15 06:13 에 색인을 못 읽자 처음부터 다시 만들어 밤새 돌린 37만 장을 날렸다. 색인이 1.68GB(431,602장)로 커져 읽기가 실패했는데, 오류를 삼키는 읽기 함수가 null 을 돌려주자 "색인이 없구나" 하고 0부터 시작했다. 없는 것과 못 읽는 것은 다르다. 이제는 파일이 있는데 못 읽으면 던지고 멈춘다(a56640d).
  • 8/16 00:43. 벡터 4.36GB 를 동기로 읽자 파이스의 이벤트 루프(요청을 돌리는 한 줄짜리 일꾼)가 수십 초 멈췄고 질문이 network error 로 끊겼다. 32MB 씩 흘려 읽으며 묶음마다 양보하게 해서 메모리 4.36GB → 1.9GB, 최대 멈춤 1.2초가 됐다(f186a9b).
  • 8/16 01:33. 276MB 목록을 검색마다 다시 파싱하고 있었다. 답이 중간에 끊긴 원인이었다. 사용자가 "왜 말하다가 말지?" 하고 다시 물으면 에이전트가 처음부터 다 돌았고, 커밋은 사용량이 빨리 닳은 원인을 이 되풀이로 적었다(c717e2b).
  • 8/16 08:33. 볼트 전체를 훑는 데 117만 장이면 100초가 걸린다. 그동안 감시기가 3분 무응답으로 파이스를 죽였다. 사람이 쓴 노트만 훑게 해서 100초가 0.02초가 됐다(b407b02).
  • 글자 검색은 111만 장에서 386초였다. 매번 파일을 훑고(90초) 파일을 하나도 빠짐없이 열어서 찾았기 때문이다. 색인이 이미 가진 노트 목록을 쓰고 경로와 이름부터 맞춰 보게 해서 0.4초가 됐다(481fc0d, 8/15 18:19).
  • 8/28 새벽에는 목록 파일이 196만 장 · 518MB 가 되어 문자열 상한에 걸렸다. JSONL(한 줄에 항목 하나씩 적는 파일 형식) 조각으로 바꿨다(d3ddff7).

5 · 카드 창고를 볼트 밖으로, 밤 일과를 순서대로 (8/15~8/16)

index_folder 는 부를 때 한 번 훑을 뿐이라 그 뒤 NAS 에 올라온 파일은 아무도 몰랐다. 8/15 17:52 에 nas-sync.mjs 가 공유 15곳을 훑어 새 파일만 카드로 만들게 했다(0a181d3). 매일 02:00 에 NAS 를 따라잡고 05:30 에 임베딩을 한다. 순서가 이래야 그날 밤에 검색까지 붙는다. 임베딩은 같은 스크립트에서 하지 않았다. GPU 를 두 작업이 다투지 않게 하려는 것이다. 05:30 예약이 파이스를 죽이고 있어서 색인 갱신은 파이스 밖에서 돌게 했다(73fa3e8).
옵시디언이 켜질 때마다 117만 장을 세느라 흰 화면으로 몇십 분 멈췄다. NAS 카드 117만 장을 볼트 밖 창고 폴더로 옮겼다(dbbd8f0, 8/16 09:32). 볼트는 108장이 됐다. 색인 파일은 손대지 않고 읽을 때 볼트를 먼저 보고 없으면 창고를 보게 해서 7시간짜리 임베딩을 다시 하지 않았다. 실측으로 폴더 이동 0.4초, 색인 1,170,561장 그대로, 의미 검색 1.7~2.4초로 같았다.

6 · MCP 창구 — 색인을 Claude 채팅에서 쓴다 (8/28)

8/28 10:30(d7299f5)에 src/mcp.js 157줄이 들어왔다. MCP(Claude 같은 AI 앱이 바깥 도구를 부르는 공통 규약)의 웹 통신 방식(Streamable HTTP)을 패키지 없이 최소로 구현했다. 도구는 둘이었다. vault_search(의미 검색)와 vault_note(노트 읽기). 같은 검색을 토큰 인증으로 여는 REST 길(웹 주소로 바로 부르는 창구)도 같이 냈다.
문을 열 때는 울타리부터 세웠다. 도구는 읽기 둘뿐이고 셀프체크가 목록을 못박았다. 주소가 곧 열쇠다(무작위 48자, 비밀 파일은 권한 0600 에 저장소 밖). 유출이 의심되면 그 파일을 지우고 재시작하면 새 주소가 나온다. 볼트 밖으로 나가는 경로는 거부하고, resources 와 prompts 는 지원하지 않아 면적을 늘리지 않았다. 셀프체크는 60항목이 됐다.
도구는 그 뒤 늘었다. 9/22 에 셋(규격 검색 · NAS 표 목록 · SELECT 한 문장 — 표를 읽기만 하는 SQL 질의)이 붙어 다섯, 9/25 에 원본 읽기와 기록 세기, 9/29 에 파일 찾기, 10/1 에 폴더 색인 상태와 폴더 펼쳐 보기 — 10/8 현재 10종이다. 개인 Claude 는 클라우드를 지나므로 안쪽보다 더 좁게 연다. 반출금지 도면이 든 '비밀' 범위와 인사 자료 범위(super)는 목록에서 뺀다. 모든 부서를 한 번에 넣는 값은 쓰지 않고 부서를 하나씩 적는다. 그 값이 들어가는 순간 인사 폴더가 개인 Claude 로 나가기 때문이다.

7 · 색인이 둘이었다 — AI 가 다른 색인만 보고 있었다 (9/21~9/22)

9/21 에 사용자가 물었다. 재무부 자료까지 전부 옵시디언에 태웠는데 왜 AI 는 없다고 하느냐고. 자료가 없던 게 아니었다. AI 의 검색 길은 코드북(ASME · KGS 규격) 조각 41,807개의 색인만 봤고, 사용자가 태운 것은 노트 217만 장 · 8.9GB 의 다른 색인이었다(ba30c05).
붙이면서 범위를 경로로 정했다(vault_scope.js). 지시는 이랬다. 각 부서는 자기 부서 폴더 + 전체 공유 + 규격 + 표준 + 회사 공통 자료를 보고, super 는 전부 본다. 표에 없는 경로는 null 이고 null 은 주지 않는다. 기본이 닫혀 있다(fail-closed). 인사·노무 폴더는 super 만 보는 새 범위 값을 만들었다. 끝에서 끝까지 네 갈래를 실측했다. 전사 범위만 준 경우와 생산부는 재무부 자료가 안 보였고, 재무부와 모든부서(super)는 보였다.
할 수 있는 것과 없는 것도 분명히 했다. 볼트 색인은 파일 카드라서 "올해 ○○ 대장이 어디 있나"에는 경로를 답하고, "그 안의 숫자가 얼마냐"는 파일을 열지 않으므로 답하지 못한다. 지침에 그렇게 박았다.
속도는 질문 하나에 4~6초였다. 재 보니 CPU 가 아니라 디스크였다. 8.9GB 를 질문마다 통째로 읽고 있어서 초당 약 1.8GB 가 이 맥의 디스크 대역폭 그대로였다. 읽을 양을 줄였다. 부호만 1비트로 남긴 사본(266MB, 32배 작다)으로 후보 1,500여 개를 추리고, 후보만 원본에서 골라 읽어 정확히 다시 잰다. 검색 한 번 0.31~0.34초. 최종 점수와 순서는 전수 계산과 같았다(8824cad).
다음 날 사용자가 "수압시험이 3배라니, 보통 1.5배지" 하고 잡아냈다. 정답 조각은 3위 0.698 에 멀쩡히 있었는데 볼트 결과와 한 목록에 섞여 점수순으로 잘리면서 밀려났다. 두 색인은 점수 눈금이 달라 섞어 자르면 안 된다. 몫을 가르고 한쪽이 모자라면 다른 쪽이 채우게 했다(1b0ea2e).

8 · 직원에게 열기 — OAuth · 부서 범위 · 이용 기록 (9/24~9/25)

옛 창구는 주소가 열쇠라서 그 주소를 아는 사람은 누구나 관리자 범위(전 부서)로 읽었다. 그래서 한 사람만 쓸 수 있었다. 직원에게 열려면 사람마다 자기 로그인으로 붙고 자기 부서만 봐야 했다. 9/24 22:24 에 mcp_oauth.js 445줄이 들어왔다(0c9b94f). OAuth 2.1 + PKCE + 동적 등록이고, 로그인은 플랫폼 로그인을 그대로 쓴다(구글 콘솔 작업이 없다). 직원 자기 구독이 모델을 대고 회사는 자료와 권한만 댄다. 울타리는 다섯이다. 콜백 주소(로그인 뒤 돌아갈 주소) 허용 목록, 허용은 흐름을 시작한 그 브라우저에서만, 토큰은 해시(원래 값으로 되돌릴 수 없게 바꾼 값)로만 저장, 범위는 자기 부서 + 전사, 갱신 때마다 사용자 정보 재조회.

oauth connect · 크게 보기 ↗

9/25 에 관리자 계정으로 claude.ai 에 붙여 허용하자 토큰이 나왔고 list_tables 가 돌았다. 이때 같이 잡은 것이 있다. 도구 칸 이름이 한글(문서 · 줄)이면 Anthropic API 가 오류 없이 그 도구를 목록에서 빼 버린다. 규격 검색과 표 질의가 9/22 부터 claude.ai 에서 한 번도 돌지 않았다. 9/22 의 실측은 함수를 직접 불러 잰 것이라 몰랐다. 칸 이름을 영문(doc · rows)으로 고치고 셀프체크가 이름을 아스키로 검사하게 했다(c4c120e).
이용 기록(c22cbb9)은 시각 · 누구 · 부서 · 도구 · 됐나 · ms 만 남기고 검색어와 SQL 은 남기지 않는다. 이 기록이 다음 문제를 풀었다. 관리자의 Claude 가 "NAS 가 연결 안 돼 원본을 못 읽는다"고 답했는데, 이용 기록에는 vault_note 3번이 0ms 로 실패한 흔적이 있었다. NAS 는 붙어 있었고 Claude 의 오해였다. 원인은 카드가 두 곳(볼트 · NAS 거울)에 있는데 노트 읽기가 볼트만 봤다는 것, 그리고 카드에는 이름과 경로뿐이라 원본을 여는 도구가 따로 필요하다는 것이었다. 그래서 read_source 를 만들었다(d21bdfa). 표에 있는 폴더만, 도면 냄새가 나는 경로(도면 · dwg · p&id · 반출 …)는 열지 않고, 글이 되는 형식만, 30MB 까지.
같은 날 직원에게도 부서 파일 검색과 원본 읽기를 열었다(28b5e92). 부서 폴더 안의 개인 자료는 본인만 본다. super 도 예외가 아니다. 열자마자 구멍 하나를 맥 실측에서 찾았다. 색인 카드 경로의 한글이 분해형(NFD)이라 "개인 자료" 정규식이 걸리지 않았고, 개인 자료 주인 판정이 전부 null — 같은 부서 직원에게 남의 개인 자료가 검색에 나올 참이었다. 직원 연결이 0명일 때 잡았다. 비교하기 전에 NFC 로 맞추도록 고쳤다(0735053). 이용 기록은 10/8 낮 12시 기준 196줄이다. 도구 호출 117건(read_source 59 · find_files 41 · vault_search 7 · search_docs 5 · vault_note 3 · list_tables 1 · count_records 1)과 토큰 갱신 78번, 연결 허용 1번.

9 · 커넥터가 1시간마다 끊기던 원인 — 짐작은 틀렸고 요청 자취로 잡았다 (9/26)

관리자의 OAuth 커넥터가 출입 토큰(1시간) 만료 뒤 "서버가 오류를 돌려줬다"는 말만 내고 끊겼다. 서버에는 갱신 요청(/oauth/token)이 오지 않았다. 갱신 토큰(30일)은 살아 있었다.

  • 06:22~06:24. 갱신 시도와 토큰 창구 실패(받은 형식)를 이용 기록에 남기게 했다. 갱신이 서버에 닿았는지 가를 길이 없었다.
  • 08:19. 만료된 토큰의 401 응답에 error="invalid_token" 이 없었다. 규약(RFC 6750)은 토큰을 들고 왔는데 만료·무효면 붙이라고 한다. 붙이자 2분 뒤(08:21) 첫 갱신 기록이 왔다(2fd77f9).
  • 08:24. 그 갱신이 사용자 정보를 플랫폼 데이터베이스(Firestore)에서 읽다가 읽기 한도(429)로 던져 500 이 났다. 못 읽으면 갱신 토큰에 적어 둔 부서 범위로 내게 했다(b07551e).
  • 그래도 「다시 연결」이 돌기만 했다. 09:53 에 들어온 OAuth 요청의 자취를 값 없이 남기자(7a9dfe0) 허용 단계(/oauth/approve)에서 500 이 나고 있었다. 사용자 정보를 못 읽었다는 429 였다. 그날 08시부터 하루 읽기 한도가 차 있었다.
  • 09:59. Firestore 를 못 읽으면 전날 17:20 맥 백업 사본(읽기 0)에서 사용자를 찾게 했다. 36시간 넘은 사본은 믿지 않는다(f7e470a). 10:01:22 에 재연결이 됐다(이용 기록의 「연결 허용」).

처음엔 데스크톱 앱이 허가 창을 못 연다고 짐작했다. 틀렸다. 자취를 켜고서야 보였다. 이후 11:49 와 13:02 에 claude.ai 가 스스로 갱신했고, 이용 기록의 토큰 갱신 78번이 모두 성공이다. 다시 연결을 누를 때마다 손님 등록이 하나씩 쌓이던 것(9/26 하루 10개)은 7일 넘은 손님을 자동으로 지우게 했다(62ee6f3).

💡 설명

  • 색인(인덱스): 책 뒤의 찾아보기처럼, 파일을 일일이 열지 않고 빨리 찾게 미리 만들어 둔 목록.
  • 파일 카드: 원본을 옮기지 않고 이름 · 위치 · 크기 · 수정일만 적은 노트 한 장. 원본은 NAS 에 그대로 있다.
  • 임베딩 · 벡터 · 의미 검색: 글의 뜻을 숫자 줄(벡터)로 바꿔 두고, 낱말이 달라도 뜻이 가까운 글을 찾는 방법.
  • bge-m3: 한국어도 잘 다루는 임베딩 모델. 이 PC 와 맥미니에서 직접 돌려 자료가 밖으로 나가지 않는다.
  • MCP: Claude 같은 AI 앱이 바깥의 도구와 자료를 부를 때 쓰는 공통 규약. 파이스가 그 도구를 내놓는 쪽이다.
  • OAuth · PKCE: 비밀번호를 건네지 않고 "이 앱에 이만큼만 허용" 하는 로그인 방식. PKCE 는 허용 코드를 가로채도 못 쓰게 묶는 장치.
  • fail-closed: 표에 없으면 열지 않는 기본값. 빠뜨려서 새는 것보다 못 보는 쪽이 낫다는 설계.
  • NFC · NFD: 한글 글자를 저장하는 두 방식. 눈에는 같아도 컴퓨터는 다른 글자로 비교한다. 맥 파일 이름은 NFD 다.
  • 1비트 사본(미리 거르기): 벡터의 부호만 남긴 작은 사본으로 후보를 먼저 추린 뒤 원본으로 정확히 다시 재는 방법.
  • 이벤트 루프: 파이스가 요청을 하나씩 처리하는 한 줄짜리 일꾼. 오래 걸리는 일을 한 번에 하면 그동안 모든 요청이 멈춘다.
  • 커넥터: claude.ai 에서 바깥 도구를 붙이는 연결 한 개.

함정과 배운 것

  • 없는 것과 못 읽는 것은 다르다. 읽기 실패를 "없음"으로 처리하면 밤새 만든 37만 장이 사라진다. 읽기 오류는 던져서 멈춘다.
  • 드라이브 글자로 NAS 를 붙이는 연결 프로그램은 메모리를 쥐고 놓지 않는다. 운영체제의 공유 경로(UNC)로 직접 읽는다.
  • "AI 가 없다고 한다"면 자료가 없는 게 아니라 다른 색인을 보고 있을 수 있다. 색인이 둘이라는 사실부터 확인한다.
  • 점수 눈금이 다른 색인 결과를 한 목록에 섞어 자르지 않는다. 몫을 가른다.
  • 한글이 들어가는 비교(경로 · 도구 칸 이름 · 정규식)는 먼저 NFC 로 맞추고, 칸 이름은 아스키만 쓴다. API 는 한글 칸 이름을 가진 도구를 오류 없이 뺀다. 직접 함수를 불러 시험하면 통과하고 실제 길에서만 안 도는 종류다.
  • 합성 데이터 시험은 통과하고 실제 자료에서만 드러나는 고장이 많다. 사람이 쓰는 길로 한 번은 끝까지 돌려 본다.
  • 짐작으로 고치기 전에 자취를 남겨 잰다. 허용 단계가 하루 읽기 한도(429)로 죽고 있었다는 건 자취를 켜고서야 보였다.
  • 새 문을 열 때 기본은 닫혀 있게 한다. 표에 없으면 주지 않고, 개인 자료는 본인만, 도면 냄새가 나면 읽지 않는다.
  • 도면 얘기가 나오면 "이미 파일명 · 경로로 색인됨, 안쪽 읽기만 없음"부터 말한다. 같은 사실을 두 번 잊어서 기억 노트 맨 위에 적었다.

출처

커밋 5f06094 · d7d3731 · 202256f · a8dcdf3 · 535c7f0 · 761438d · 3323908 · b912749 · eb17e9e · ff1e7b1 · a56640d · f186a9b · c717e2b · b407b02 · 481fc0d · 0a181d3 · dbbd8f0 · d3ddff7 · d7299f5 · 2769f39 · ba30c05 · 8824cad · 1b0ea2e · 0c9b94f · c4c120e · c22cbb9 · d21bdfa · 28b5e92 · 0735053 · 2fd77f9 · b07551e · 7a9dfe0 · f7e470a · 62ee6f3. 문서: ROADMAP.md Phase 8~11 절 · 저장소의 src/mcp.js · src/mcp_oauth.js · src/vault_semantic.js. 기억 노트: sejong-vault-index · pais-mcp-connector · one-bit-prefilter · ascii-only-places.


← 08 사내 앱 — 차량관리와 ERP 시안 · 10 파이스의 두 번 이사 — PC → 맥북 → 맥미니 →