SurrealDB を「AI Agents組織の記憶、集合知」として使う運用 — 7000+ records 蓄積と月次棚卸し
TL;DR
- LLM との協働で失われがちな「以前の判断」を、SurrealDB の構造化データ + FULLTEXT 検索に残す運用を紹介する
- tags、
is_current、preview、review_log / output_log を分けると、7000+ records でも recall が破綻しにくい - ベクトル検索を最初から入れなくても、日本語 NGRAM FULLTEXT とタグ検索の組み合わせで実務上は十分に使える
- 定着の鍵は DB の高度さより、
surreal-query.shのような登録・検索の摩擦を下げる小さな CLI だった
概要
SurrealDB をローカルの「組織記憶」として使い、AI エージェントとの作業履歴・設計判断・レビュー結果を蓄積する運用事例です。Markdown 管理やベクトル DB と比較しながら、なぜ SurrealDB の構造化 + FULLTEXT 検索を選んだかを整理します。
対象読者は、Claude Code などの LLM 開発支援を継続利用していて、セッションをまたぐ判断履歴や知見をどう残すかに悩んでいる開発者です。
目次
- 状況 / 課題
- 候補 / トレードオフ
- 採用案と理由
- 実装抜粋
- 運用上の学び
- 振り返り
- まとめ
- 参考
状況 / 課題
AI エージェントとの協働が日常化すると、「以前どう決めたか」「あのエラーはなぜ起きたか」「このアーキテクチャ選定の根拠は何だったか」という問いが頻繁に浮かぶ。しかし LLM のコンテキストウィンドウはセッションをまたぐと消える。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."
— Introducing SurrealDB 3.0 — the future of AI agent memory | SurrealDB Blog
| 項目 | 内容 |
|---|---|
| ワークロード特性 | 1 日 5〜20 件の知見登録。検索は Claude Code セッション起動時と作業中随時 |
| SLA / 可用性 | ローカル常駐 (systemd user service + linger)。ネットワーク不要 |
| コスト制約 | OSS ローカル運用。サーバーコスト ゼロ |
| 期限 | 段階的に拡張。最初の 100 records は 1 ヶ月で到達 |
候補 / トレードオフ
候補 A: Markdown ファイルによる知識管理
- 特徴: CLAUDE.md や memory/*.md に知見を書き溜める。Git 管理のため変更履歴が残る
- 長所: ツール不要。エディタで即編集可能。LLM が直接読み込める
- 短所: ファイル数が増えると「どのファイルに何が書いてあるか」が不明になる。全文検索は grep 頼みで遅い。タグ管理が人手
- 見積コスト: ゼロ。ただしメンテ負荷が線形増加
候補 B: ベクトル DB (PostgreSQL pgvector 等) による意味検索
- 特徴: テキストを埋め込みベクトルに変換し、意味的類似検索でナレッジを引く
- 長所: 「似たような質問」をベクトル距離で引き当てられる。自然言語クエリが通る
- 短所: 埋め込みモデルの管理が必要。PostgreSQL の起動コストが高い。ローカル単体で軽量に動かしにくい。タグ・日時などの構造化フィールドと組み合わせた複合検索が煩雑
- 見積コスト: 埋め込み API コスト + PostgreSQL 運用コスト
候補 C: SurrealDB による構造化 + FULLTEXT 検索
- 特徴: マルチモデル DB (document + graph + KV)。FULLTEXT と構造化フィールドを同一クエリで組み合わせられる
- 長所: NGRAM アナライザーによる日本語部分一致検索。tags フィールドと FULLTEXT の複合検索。EVENT による is_current 自動管理。組み込みモードで軽量起動可能
- 短所: SurrealQL の学習コスト。PostgreSQL ほどエコシステムが成熟していない
- 見積コスト: OSS。サーバーコスト ゼロ
採用案と理由
採用: 候補 C
理由:
- FULLTEXT + 構造化の複合検索: tags でプロジェクト・技術キーワードを絞り込みつつ、content の FULLTEXT 検索を組み合わせることで精度の高い recall が実現できる
-
EVENT による is_current 自動管理: 同一 topic に新しい知見を登録すると、旧レコードが自動的に
is_current=falseに更新される。陳腐化した知見を手動でアーカイブする手間がない -
ローカル軽量起動:
systemd user service + lingerで WSL 起動時に自動起動。ネットワーク不要でオフライン環境でも動作する
SurrealDB の EVENT 機能は DB トリガーに相当し、レコードの変更を検知して自動的に後処理を実行する。
我々はシビュラシステムを手に入れようとしている…
"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
COLUMNS content FULLTEXT ANALYZER agents_analyzer BM25 HIGHLIGHTS;
FULLTEXT インデックスの構文は公式ドキュメントで定義されている。
"DEFINE INDEX userNameIndex ON TABLE user COLUMNS name FULLTEXT ANALYZER example_ascii BM25 HIGHLIGHTS;"
BM25 は関連度スコアリングアルゴリズム、HIGHLIGHTS はキーワードハイライト表示を有効にするオプションだ。
-- is_current 自動管理の EVENT 定義
DEFINE EVENT knowledge_is_current_manager ON TABLE knowledge
WHEN $event = "CREATE"
THEN {
UPDATE knowledge
SET is_current = false
WHERE topic = $after.topic
AND id != $after.id
AND is_current = true;
};
-- tags + FULLTEXT 複合検索クエリ例 (S4-1: 構造化優先)
SELECT topic, preview, tags FROM knowledge
WHERE is_current = true
AND tags CONTAINSANY ['surrealdb', 'knowledge-management']
ORDER BY created_at DESC LIMIT 10;
-- FULLTEXT スコア付き検索 (S3)
SELECT *, search::score(1) AS score FROM knowledge
WHERE content @1@ 'FULLTEXT NGRAM'
ORDER BY score DESC LIMIT 10;
-- 月次棚卸しクエリ (M1: 陳腐化確認)
SELECT topic, is_current, created_at FROM knowledge
WHERE is_current = true
ORDER BY created_at ASC LIMIT 30;
-- M2: 重複検出
SELECT topic, count() FROM knowledge GROUP BY topic
ORDER BY count DESC LIMIT 10;
運用上の学び
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 ヘルパーの進化
生 curl を叩いていた時期は認証ヘッダーを毎回手打ちする必要があった。ヘルパースクリプト化することで --knowledge-create --knowledge-search 等の操作を一行で完結させられるようになり、登録コストが大幅に下がった。
振り返り (ディレクター視点)
- 判断時に重視した軸: 「記録コスト < recall 便益」になるまでの摩擦をいかに下げるか。ヘルパースクリプトの整備が転換点だった
- どこを譲歩したか: ベクトル検索 (意味的類似) は諦めた。NGRAM FULLTEXT で「キーワードが含まれるもの」を引き当てる方式は完全な意味検索ではないが、tags との組み合わせで実用上十分な精度が出ている
-
もう一度判断するなら: 早い段階で
previewフィールドを設けるべきだった。後から追加すると既存レコードのバックフィルが必要になる
まとめ
- SurrealDB の NGRAM FULLTEXT + tags 複合検索は、日本語を含む知見の recall に実用的な精度を持つ
- EVENT による
is_current自動管理で、陳腐化した知見の手動アーカイブ作業をゼロにできる - 「記録コスト < recall 便益」になるための摩擦低減 (ヘルパースクリプト化) が定着の鍵
- 7000+ records を蓄積しても月次棚卸しクエリ 4 本 (M1-M4) で管理コストを一定に保てている
- SurrealDB はローカル OSS 運用でサーバーコストゼロ。AI エージェントの組織記憶として活用事例が増えている
参考
公式 1 次資料
- 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)