SurrealDB를 'AI Agent 조직의 기억, 집단지성'으로 사용하는 운용 — 7000+ records 축적과 월간 재고 조사

• LLM과의 협업에서 상실되기 쉬운 '이전의 판단'을, SurrealDB의 구조화 데이터(Structured Data) + FULLTEXT 검색으로 남기는 운용법을 소개한다
• tags, is_current, preview, review_log / output_log를 분리하면, 7000+ records에서도 recall(재현율)이 무너지지 않는다 - 벡터 검색(Vector Search)을 처음부터 도입하지 않더라도, 일본어 NGRAM FULLTEXT와 태그 검색의 조합으로 실무상 충분히 사용할 수 있다
• 정착의 열쇠는 DB의 고도화보다, surreal-query.sh와 같이 등록·검색의 마찰을 줄여주는 작은 CLI였다

SurrealDB를 로컬의 '조직 기억'으로 사용하여, AI 에이전트와의 작업 이력·설계 판단·리뷰 결과를 축적하는 운용 사례입니다. Markdown 관리 및 벡터 DB와 비교하며, 왜 SurrealDB의 구조화(Structured) + FULLTEXT 검색을 선택했는지 정리합니다.

대상 독자는 Claude Code 등의 LLM 개발 지원을 지속적으로 이용하면서, 세션을 넘나드는 판단 이력이나 지식을 어떻게 남길지 고민하고 있는 개발자입니다.

• 상황 / 과제
• 후보 / 트레이드오프 (Trade-off)
• 채택안과 이유
• 구현 발췌
• 운용상의 배움
• 회고
• 요약
• 참고

AI 에이전트와의 협업이 일상화되면, "이전에 어떻게 결정했는가", "그 에러는 왜 발생했는가", "이 아키텍처 선정의 근거는 무엇이었는가"라는 질문이 빈번하게 떠오른다. 하지만 LLM의 컨텍스트 윈도우(Context Window)는 세션을 넘어가면 사라진다. Markdown 파일에 계속 써두어도, 파일 수가 늘어나면 검색성이 저하된다.

이 문제에 대해 SurrealDB를 로컬에 상주시키고, 지식·리뷰 결과·성과물·대화를 4개의 테이블로 나누어 축적하는 '조직 기억' 운용을 구축했다. 현재 7000+ records를 축적하고 있으며, Claude Code의 세션 기동 시 자동으로 recall할 수 있는 상태가 되어 있다.

SurrealDB 자체도 이 유스케이스를 공식적으로 위치시키고 있다.

"SurrealDB 3.0 moves beyond storing data — it becomes the foundation for agent memory and intelligence."

항목	내용
워크로드 특성	1일 5~20건의 지식 등록. 검색은 Claude Code 세션 기동 시와 작업 중 수시
...	-
특징: CLAUDE.md나 memory/*.md에 지식을 써둔다. Git 관리로 인해 변경 이력이 남는다 -
장점: 별도 도구가 필요 없다. 에디터에서 즉시 편집 가능하다. LLM이 직접 읽을 수 있다 -
단점: 파일 수가 늘어나면 '어느 파일에 무엇이 적혀 있는지' 알 수 없게 된다. 전체 텍스트 검색은 grep에 의존해야 해서 느리다. 태그 관리가 수동이다 -
예상 비용: 제로. 단, 유지보수 부하가 선형적으로 증가

특징: 텍스트를 임베딩 벡터(Embedding Vector)로 변환하여, 의미적 유사도 검색으로 지식을 불러온다 -
장점: '비슷한 질문'을 벡터 거리(Vector Distance)로 찾아낼 수 있다. 자연어 쿼리가 통한다 -
단점: 임베딩 모델 관리가 필요하다. PostgreSQL의 기동 비용이 높다. 로컬 단독으로 가볍게 돌리기 어렵다. 태그·일시 등의 구조화된 필드와 조합한 복합 검색이 번거롭다 -
예상 비용: 임베딩 API 비용 + PostgreSQL 운용 비용

특징: 멀티 모델 DB (document + graph + KV). FULLTEXT와 구조화된 필드를 동일한 쿼리에서 조합할 수 있다 -
장점: NGRAM 분석기를 통한 일본어 부분 일치 검색. tags 필드와 FULLTEXT의 복합 검색. EVENT를 통한 is_current 자동 관리. 내장 모드(Embedded mode)로 가볍게 기동 가능 -
단점: SurrealQL의 학습 비용. PostgreSQL만큼 생태계가 성숙하지 않았다 -
예상 비용: OSS. 서버 비용 제로

채택: 후보 C

이유:

• FULLTEXT + 구조화된 검색의 복합 활용: tags로 프로젝트 및 기술 키워드를 좁히면서 content의 FULLTEXT 검색을 결합함으로써 정밀도 높은 Recall (재현율)을 실현할 수 있음
• EVENT를 통한 is_current 자동 관리: 동일한 topic에 새로운 지식을 등록하면, 기존 레코드가 자동으로 is_current=false로 업데이트됨. 노후화된 지식을 수동으로 아카이브하는 번거로움이 없음
• 로컬 경량 기동: systemd user service + linger를 통해 WSL 기동 시 자동 실행. 네트워크가 필요 없어 오프라인 환경에서도 동작함

SurrealDB의 EVENT 기능은 DB 트리거 (Trigger)에 해당하며, 레코드의 변경을 감지하여 자동으로 후처리를 실행한다.

"The DEFINE EVENT statement can be used to create events which can be triggered after any change or modification to the data in a record."

$before / $after 변수로 레코드의 변경 전후를 참조할 수 있기 때문에, "동일 topic의 신규 CREATE 시 기존 레코드를 업데이트한다"는 로직을 순수한 SurrealQL로 기술할 수 있다.

-- knowledge 테이블의 FULLTEXT 인덱스 정의
DEFINE ANALYZER agents_analyzer TOKENIZERS class FILTERS ngram(2,8);
DEFINE INDEX knowledge_content_idx ON TABLE knowledge
...

FULLTEXT 인덱스의 구문은 공식 문서에 정의되어 있다.

"DEFINE INDEX userNameIndex ON TABLE user COLUMNS name FULLTEXT ANALYZER example_ascii BM25 HIGHLIGHTS;"

BM25는 관련도 스코어링 (Scoring) 알고리즘이며, HIGHLIGHTS는 키워드 하이라이트 표시를 활성화하는 옵션이다.

-- is_current 자동 관리를 위한 EVENT 정의
DEFINE EVENT knowledge_is_current_manager ON TABLE knowledge
WHEN $event = "CREATE"
...

-- tags + FULLTEXT 복합 검색 쿼리 예시 (S4-1: 구조화 우선)
SELECT topic, preview, tags FROM knowledge
WHERE is_current = true
...

-- 월간 재고 조사 쿼리 (M1: 노후화 확인)
SELECT topic, is_current, created_at FROM knowledge
WHERE is_current = true
...

7000+ records 축적 후 밝혀진 사실

• 축적 초기 (100 records 이하)에는 "전문을 읽으면 된다"는 생각에 검색성의 혜택을 느끼기 어렵다. 200~300 records를 넘어가는 시점부터 tags + FULLTEXT 검색의 가치가 역전되었다.
• preview 필드 (500자)를 별도로 관리함으로써, 검색 결과 목록에서는 content를 불러올 필요가 없어 쿼리 속도를 유지할 수 있다.

중복 레코드 탐지

SELECT topic, count() FROM knowledge GROUP BY topic ORDER BY count DESC를 월간 단위로 실행하여, 동일한 topic에 여러 개의 is_current=true 레코드가 존재하지 않는지 확인한다. EVENT 설계에 누락이 있으면 중복이 발생할 수 있다.

surreal-query.sh 헬퍼의 진화

생(raw) curl을 호출하던 시기에는 인증 헤더 (Authentication Header)를 매번 직접 입력해야 했다. 헬퍼 스크립트로 만듦으로써 --knowledge-create, --knowledge-search 등의 작업을 한 줄로 완결할 수 있게 되었고, 등록 비용이 대폭 낮아졌다.

• 판단 시 중시한 축: 「기록 비용 < recall (회상) 편익」이 될 때까지의 마찰을 어떻게 낮출 것인가. 헬퍼 스크립트 (Helper Script) 정비가 전환점이었다.

• 양보한 부분: 벡터 검색 (Vector Search, 의미적 유사성)은 포기했다. NGRAM FULLTEXT 방식으로 「키워드가 포함된 것」을 찾아내는 방식은 완전한 의미 검색은 아니지만, tags와의 조합으로 실용상 충분한 정밀도가 나오고 있다.

• 다시 판단한다면: 빠른 단계에서 preview 필드를 마련했어야 했다. 나중에 추가하면 기존 레코드의 백필 (Backfill)이 필요해진다.

• SurrealDB의 NGRAM FULLTEXT + tags 복합 검색은 일본어를 포함한 지식의 recall (회상)에 실용적인 정밀도를 가진다.

• EVENT를 통한 is_current 자동 관리로, 진부해진 지식의 수동 아카이브 작업을 제로로 만들 수 있다.

• 「기록 비용 < recall (회상) 편익」이 되기 위한 마찰 저감 (헬퍼 스크립트화)이 정착의 열쇠다.

• 7000+ records를 축적해도 월간 재고 조사 쿼리 4개 (M1-M4)로 관리 비용을 일정하게 유지할 수 있다.

• SurrealDB는 로컬 OSS 운용으로 서버 비용이 제로다. AI 에이전트의 조직 기억으로서 활용 사례가 늘고 있다.

• DEFINE INDEX statement | SurrealQL | SurrealDB Docs — FULLTEXT ANALYZER / BM25 / HIGHLIGHTS의 공식 구문 레퍼런스

• DEFINE EVENT statement | SurrealQL | SurrealDB Docs — EVENT 트리거 ($before/$after/$event)의 공식 문서

• DEFINE ANALYZER statement | SurrealQL | SurrealDB Docs — NGRAM 필터 (min/max 파라미터)의 공식 레퍼런스

• Using SurrealDB as a Full Text Search Database | SurrealDB Docs — FULLTEXT 검색 모델의 개요 문서

• Introducing SurrealDB 3.0 — the future of AI agent memory | SurrealDB Blog — SurrealDB가 AI 에이전트 메모리 기반으로서 자사를 위치시키는 공식 블로그

• Agent Memory | Use Cases | SurrealDB — 에이전트 메모리의 유스케이스 공식 해설

• Agents with memory: how Agno and SurrealDB enable reliable AI systems | SurrealDB Blog — Agno 에이전트 프레임워크와 SurrealDB를 결합한 구현 사례

• Create a Search Engine with SurrealDB Full-Text Search | SurrealDB Blog — SurrealDB FULLTEXT 검색을 사용한 검색 엔진 구축 튜토리얼

• From Personal Knowledge Management to the Second Brain to the Personal AI Companion | ACM DL — PKM에서 AI 컴패니언으로의 진화를 논한 학술 논문 (ACM GROUP 2025)