개체는 사람만이 아니다 — 개념을 1급 개체로 올려야 그래프가 생긴다

▶ 동영상 개요 — 개체는 사람만이 아니다 — 개념을 1급 개체로 올려야 그래프가 생긴다

4분 42초 — 디렉토리 화이트리스트에 없는 경로를 가리킨 링크는 오류 없이 조용히 버려진다 — 문서 3,275개에 링크가 68곳 있었는데 인식된 엣지가 1개였던 이유 — NotebookLM 동영상 개요로 생성

🎧 오디오 개요 — 개체는 사람만이 아니다 — 개념을 1급 개체로 올려야 그래프가 생긴다

14분 7초 — 디렉토리 화이트리스트에 없는 경로를 가리킨 링크는 오류 없이 조용히 버려진다 — 문서 3,275개에 링크가 68곳 있었는데 인식된 엣지가 1개였던 이유. 화면은 이 글의 인포그래픽 한 장 고정 — NotebookLM 오디오 개요로 생성

개인 문서 3,275개를 지식 그래프 도구에 통째로 넣어 봤다. 문서마다 링크를 꽤 달아 뒀다고 생각했다. 위키링크 표기가 68곳, 다른 문서의 .md 파일을 가리키는 마크다운 링크가 들어 있는 파일이 209개였다. 그런데 색인이 끝나고 그래프를 열었더니 엣지가 1개였다.

버그가 아니었다. 링크가 없어서도 아니었다. 내가 링크를 어디로 걸었는지가 문제였다. 이 글은 그 하루에서 건진 하나의 교훈이다 — 그래프 설계의 대부분은 "개체(entity)를 무엇으로 잡을 것인가"에서 이미 끝나 있다.

개체 어휘는 도구가 이미 정해 놓았다

개체란 그래프에서 노드가 되는 대상이다. 사람, 회사, 제품처럼 "이름을 부를 수 있는 것"이라고 생각하면 쉽다. 그래프 도구는 문서 본문에서 링크를 찾을 때 아무 링크나 받지 않고, 미리 정해진 최상위 디렉토리 목록에 속한 대상만 개체로 인정한다.

내가 쓴 도구(gbrain)의 목록은 이랬다.

people | companies | meetings | concepts | deal | civic |
project | projects | source | media | finance | personal | entities

목록을 처음 봤을 때 나는 "사람과 회사 중심이구나, 내 노트에는 안 맞겠다"고 판단했다. 그게 틀렸다. concepts(개념), projects(프로젝트), source(출처), media(책·영상), personal(개인)이 이미 같은 자격으로 들어 있다. 개념을 개체로 만드는 길은 처음부터 열려 있었다.

내 노트의 최상위 디렉토리는 달력·블로그·강의·생활 같은 주제별 분류였다. 링크는 전부 그 안을 가리켰고, 목록에 없으니 파서가 조용히 버렸다. 링크가 없어서가 아니라 어휘가 달라서 1개가 된 것이다.

개념을 개체로 올리면 무엇이 달라지나

예를 들어 "증분 색인"이라는 개념이 여러 문서에 흩어져 등장한다고 하자. 그때까지 내 노트는 이런 모양이었다. 각 문서가 자기 안에서 그 개념을 설명하고 끝난다.

다이어그램 설명. 같은 개념이 세 문서에 각각 따로 적혀 있는 상태다. 사람이 읽으면 "아, 다 같은 얘기네" 하고 알지만 도구는 모른다. 세 문서 사이에 아무 연결도 없어서 "증분 색인을 다룬 문서 전부"를 부를 방법이 없다. 여기서 흔히 하는 선택이 검색에 기대는 것인데, 검색은 비슷한 문서를 순위로 돌려줄 뿐 목록을 확정해 주지 않는다.

개념 페이지를 하나 만들고 세 문서가 그것을 가리키게 하면 구조가 바뀐다.

다이어그램 설명. 흩어져 있던 설명이 "concepts/증분-색인" 한 곳으로 모이고, 세 문서는 그 개체를 가리키는 관계로 바뀐다. 이제 그 개념 페이지의 역링크를 부르면 세 문서가 빠짐없이 나온다. 순위가 아니라 집합이다. 여기서 놓치기 쉬운 점 하나 — 개념 페이지가 대단한 문서일 필요가 없다. 제목과 두세 문장짜리 스텁이어도 허브 역할은 그대로 한다. 내용을 채우는 건 나중 일이고, 지금 필요한 건 부를 이름이다.

가장 자주 걸리는 함정 — 대상 페이지가 없으면 링크는 사라진다

여기서 내가 실제로 시간을 버린 지점이 있다. 문서에 [[concepts/증분-색인]]이라고 적고 추출을 돌렸는데 엣지가 0개였다. 표기는 정확했다. 문제는 가리킨 개념 페이지가 아직 없었다는 것이다.

이유는 데이터 구조에 박혀 있다. 링크 테이블의 정의가 이렇다.

CREATE TABLE links (
  from_page_id  INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
  to_page_id    INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
  link_type     TEXT NOT NULL DEFAULT '',
  context       TEXT NOT NULL DEFAULT ''
);

코드 설명. 출발지와 도착지가 모두 pages 테이블의 실제 행을 가리키는 외래 키(foreign key — 다른 테이블에 그 행이 실제로 있어야만 값을 넣을 수 있게 강제하는 제약)다. 즉 도착지 문서가 존재하지 않으면 엣지를 만들 방법 자체가 없다. 표기가 맞아도 조용히 버려진다. 이건 이 도구만의 특성이 아니라 관계형 데이터베이스로 그래프를 저장하는 방식이면 대체로 같다.

실제로 확인해 봤다. 대상 페이지 두 개를 만들기 전에는 엣지가 0개, 만들고 다시 추출하니 2개가 생겼다. 문서는 손도 대지 않았다. 그래서 순서가 중요하다.

다이어그램 설명. 링크를 적는 행위와 엣지가 생기는 사건이 같지 않다는 걸 보여준다. "가리킨 개체 페이지가 이미 있는가?"라는 관문을 통과해야만 엣지가 된다. 통과하지 못했을 때 오류가 나면 차라리 낫겠지만 아무 말 없이 버려지는 것이 실무에서 가장 성가신 부분이다. 링크를 열심히 달았는데 그래프가 비어 있다면 표기법을 의심하기 전에 대상 페이지가 있는지부터 본다. 그래서 실무 순서는 "개체 페이지 먼저, 링크 나중"이다.

개체는 파일 단위다 — 이미 뭉쳐 놓은 문서와 부딪힌다

여기서 더 큰 벽을 만났다. 내 기록에는 사람 수십 명이 표로 정리된 명부 문서가 있었다. 기수별 동기 명단, 팀 구성원 표 같은 것들이다. 그래프 도구는 그 문서를 노드 하나로 본다. 안에 든 사람들은 보이지 않는다.

이건 도구를 잘못 쓴 게 아니다. 여러 대상을 한 문서에 모으는 건 MOC(Map of Content, 특정 주제의 항목을 한 곳에 모아 색인처럼 쓰는 노트 정리 방식)라는 표준 패턴이고, 사람이 읽기에는 표가 훨씬 낫다. 다만 그래프가 요구하는 입도와 정면으로 어긋난다.

확인해 보니 개체를 담는 테이블은 하나뿐이었고 그 행은 파일 하나에 대응했다. 문서 안의 특정 줄이나 표의 한 행을 가리킬 방법은 없었다. 파일 하나가 노드 하나라는 뜻이다.

다이어그램 설명. 같은 정보를 담고 있어도 파일을 나눴는지에 따라 그래프가 완전히 달라진다. 명부를 그대로 두면 "이 기수와 얽힌 문서"까지만 물을 수 있고, 사람마다 파일을 나눠야 "이 사람이 참석한 모임 전부"를 물을 수 있다. 여기서 흔한 오해가 하나 있다 — 명부를 지워야 한다고 생각하기 쉬운데 그럴 필요가 없다. 명부는 남겨 두고 그 안에서 개인 파일을 가리키게 하면 명부가 자연스럽게 허브가 된다.

그래서 판단은 "쪼갤 것인가"가 아니라 "어떤 질문을 할 것인가"가 된다. 기수 단위 질의로 충분하면 명부 한 장으로 끝이고, 개인 단위 질의가 필요하면 개인 파일이 반드시 있어야 한다. 우회로는 없다.

다만 처음부터 전부 쪼갤 필요는 없었다. 내가 쓴 도구는 이름을 문서로 찾지 못하면 해석하지 못한 이름 목록을 따로 뱉어 줬다. 그게 곧 "실제로 불리고 있는 사람" 명단이다. 명부에 든 서른 명 중 여러 문서에 반복해서 등장하는 사람은 대개 소수다. 그 몇 명만 파일로 승격하면 된다. 전부 쪼개고 시작하는 대신 불리는 이름만 나중에 승격하는 순서가 훨씬 쌌다.

조용히 버려지는 두 번째 이유 — 파일 이름

대상 페이지를 다 만들었는데도 엣지가 0개인 경우를 한 번 더 만났다. 이번엔 파일 이름이 원인이었다.

회의 기록을 주간 설계 회의.md처럼 공백이 든 이름으로 저장해 두고 있었다. 그런데 링크를 찾는 정규식은 대상 경로에서 공백을 허용하지 않았다. 공백을 만나는 순간 경로가 거기서 끊긴 것으로 보고 링크 전체를 버린다. 95개를 걸었는데 하나도 남지 않았다.

공백을 %20으로 인코딩해 봤더니 이번엔 링크는 인식되는데 엣지가 여전히 안 생겼다. 문서의 식별자는 파일 경로에서 자동으로 만들어지는데(공백은 하이픈으로, 대문자는 소문자로), 인코딩한 문자열은 그 식별자와 달라 아무 문서에도 닿지 못했기 때문이다.

결국 파일 이름 자체를 식별자와 같은 형태로 바꿨다. 주간 설계 회의.md를 weekly-design-meeting.md로. 그러자 95개가 전부 살아났다.

여기서 규칙 하나가 나온다. 파일 이름을 식별자와 같은 모양으로 유지한다. 공백 대신 하이픈, 대문자 대신 소문자다. 사람이 읽을 제목은 문서 안의 제목 줄이나 메타데이터에 따로 두면 되고, 파일 이름까지 예쁠 필요는 없다. 이 규칙을 지키지 않으면 링크는 문법적으로 완벽한데 그래프만 비어 있는, 원인을 찾기 어려운 상태가 된다.

구체적으로 어떻게 적나

내가 정착한 규칙은 단순하다. 디렉토리 접두어는 도구가 아는 영어 단어를 쓰고, 이름은 우리말 그대로 쓴다.

[[concepts/증분-색인]]           개념
[[tech/pgvector]]                기술·라이브러리
[[projects/사진-정리-자동화]]     프로젝트
[[source/데이터-중심-애플리케이션-설계]]  책·논문 등 출처
[[people/이수민]]                사람

코드 설명. 앞의 concepts·tech·projects·source·people만 도구가 아는 어휘이고, 슬래시 뒤의 이름은 유니코드 제한이 없어 한글을 그대로 쓸 수 있다. 처음에 나는 [[개념/증분-색인]]처럼 접두어까지 우리말로 바꾸려다 전부 인식되지 않는 걸 확인했다. 접두어는 도구와 맺는 약속이고 이름은 내 것이라고 나누어 생각하면 헷갈리지 않는다.

개체의 종류를 고를 때 도움이 된 기준이 하나 있다. "이것을 주어로 삼는 문장을 여러 문서에서 쓰게 될까?" 쓰게 된다면 개체다. "증분 색인은 …", "pgvector는 …"처럼 여러 문서가 같은 주어를 반복한다면 그건 이미 개체로 살고 있는데 이름표만 없는 상태다. 반대로 한 문서 안에서만 쓰이는 표현이면 개체로 올릴 이유가 없다.

왜 검색으로 대신할 수 없나

이 대목이 가장 자주 나오는 반문이다. 요즘 의미 검색(문장의 뜻이 비슷한 문서를 찾아 주는 방식)은 꽤 잘 동작한다. 내 경우에도 본문과 표현이 완전히 다른 질문에 0.9대 점수로 정답 문서를 1위로 올려 줬다. 그러면 굳이 링크를 달 이유가 있을까?

있다. 두 도구가 답하는 질문의 종류가 다르기 때문이다.

의미 검색은 "이것과 비슷한 것"을 순위로 준다. 상위 몇 개를 볼지는 내가 정하고, 어디서 끊든 그 아래에도 관련 문서가 남아 있을 수 있다. 반면 링크는 "이것과 관계있는 것 전부"를 집합으로 준다. 빠짐이 없다는 보장이 붙는다.

그래서 "증분 색인을 다룬 문서 중에 아직 정리 안 한 게 뭐지?" 같은 질문은 링크의 영역이다. 순위 목록으로는 "전부"를 말할 수 없다. 반대로 "예전에 캐시 무효화 관련해서 뭔가 적었던 것 같은데"처럼 이름조차 기억나지 않는 탐색은 검색의 영역이다. 둘은 대체재가 아니라 서로 다른 질문에 답하는 도구다.

정리 — 어휘를 먼저 정하고, 이름부터 만든다

그래프가 비어 있던 이유는 링크를 게을리해서가 아니라 도구의 어휘와 내 분류 체계가 어긋나 있었기 때문이었다. 그리고 그 어휘는 생각보다 넓었다 — 사람과 회사만이 아니라 개념·기술·프로젝트·출처가 처음부터 1급 개체였다.

새로 시작한다면 이 순서를 권한다. 먼저 도구가 인정하는 개체 종류를 확인한다. 그중 내 기록에서 여러 문서가 주어로 반복해서 쓰는 것을 골라 개체 페이지를 만든다. 한 문단짜리 스텁으로 충분하다. 그다음에야 문서에서 그것을 가리킨다. 순서를 뒤집으면 링크는 조용히 버려지고, 그래프가 왜 비어 있는지 한참을 헤매게 된다.

---

참고한 공개 자료:

• gbrain — 개인 지식 브레인 오픈소스: https://github.com/garrytan/gbrain
• PostgreSQL 외래 키 제약 문서: https://www.postgresql.org/docs/current/ddl-constraints.html
• Obsidian 내부 링크(위키링크) 표기법: https://help.obsidian.md/Linking+notes+and+files/Internal+links

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.