人間とAIエージェント両方のために設計されたワークスペース全体を対象としたローカルファースト検索「zg」

zg(zvec-grep)はAlibaba製のベクトルデータベース「zvec」を基盤とする、ripgrep・BM25・ベクトル検索を統合したローカルファーストな検索レイヤーです。ターミナルから直接使うことも、AIエージェントから利用することも可能です。

GitHub - zvec-ai/zvec-grep: Local-first search across your workspace, built for humans and AI agents. · GitHub
https://github.com/zvec-ai/zvec-grep

◆特徴
zgの主な特徴は以下の通りです。

・人間とエージェントの両方に対応：一度インストールしてインデックスを作成すれば、CLIとエージェントの双方から同一のワークスペースを利用できる
・高度な検索機能：キーワード検索にとどまらず、「意味による発見」「関連性によるランキング」が可能で、必要に応じて正確なテキストや正規表現による検証を行うことができる
・マルチフォーマット対応：ソースコード・ドキュメント・構造化データなど多様なフォーマットの検索に対応し、有用な構造とソース位置情報を保持したまま検索できる
・効率的な結果提示：ランキングされソースにリンクされた検索結果により、ツールの呼び出し回数・トークン数・ノイズを削減しつつ適切な証拠を抽出できる
・ローカルファースト設計：基本的にファイル・インデックス・ローカルモデルはユーザーのマシン上に保持され、リモート埋め込みモデルへのデータ送信はユーザーの許可があった場合のみ行う

◆ベンチマーク
以下のグラフは「pylint」「matplotlib」「django」に対してzgを使用した場合の効果に関するベンチマーク結果です。

左のグラフは以下の指標に関する節約量を示していますが、いずれも大幅に節約されていることがわかります。

・青：入力トークン数
・紫：ツール呼び出し数
・橙：実時間

右のグラフはLLMによる回答の質を示していますが、pylintにおいては顕著な改善が見られ、他のライブラリでもわずかながら改善が見られることが確認できます。

◆導入とインデックス作成
では実際に導入して動作を確認してみます。Node.js 22以降が必要とのことなので導入済みのUbuntu上で以下のコマンドを実行し、zgのインストールを行います。

npm install -g @zvec/zvec-grep

次に検索用のサンプルとして「不思議の国のアリス」と「シャーロック・ホームズの思い出」のテキストをダウンロードし、zgでインデックスを作成します。

curl --retry 3 --retry-all-errors --progress-bar -fL \
  -o alice-in-wonderland.txt https://raw.githubusercontent.com/GITenberg/Alice-s-Adventures-in-Wonderland_11/master/11.txt \
  -o sherlock-holmes.txt https://raw.githubusercontent.com/GITenberg/The-Memoirs-of-Sherlock-Holmes_834/master/834.txt
zg index --embedding local/potion-retrieval-32m

◆人間による検索
人間向けの直接検索は以下の要領で行います。ちなみに問い合わせた内容は日本語だと「目に見えない生き物がいくつかの痕跡を残していた。探偵はそこから何を推測したのだろうか？」です。

zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3

出力結果は以下の通りとなりました。パラメーターで「--limit 3」と指定しているため、「creature」や「marks」といったキーワードを含む3個所のブロックを出力しているのがわかります。

Context: /****/****/****/******** workspace index
Query: An unseen creature left a few marks. What did the detective infer?
Routes: fts:An unseen creature left a few marks. What did the detective infer?, vector:An unseen creature left a few marks. What did the detective infer?
Coverage: ranked_sample
Groups: 1
Files: 1
Hits: 3

Group: Q1 [primary]
Query: An unseen creature left a few marks. What did the detective infer?
Hits: 3

File: sherlock-holmes.txt
Hits: 3

  #1 indexed_entity matchedBy=fts+vector score=0.0323
  Range: 5463-5505  Status: fresh
  Source:
    5463        the lawn coming from the road. I was able to obtain five very clear
    5464        impressions of his foot-marks: one in the roadway itself, at the point
    5465        where he had climbed the low wall, two on the lawn, and two very faint
    5466        ones upon the stained boards near the window where he had entered.
    5467        He had apparently rushed across the lawn, for his toe-marks were much
    5468        deeper than his heels. But it was not the man who surprised me. It was
    5469        his companion."
    5470
    5471        "His companion!"
    5472
    5473        Holmes pulled a large sheet of tissue-paper out of his pocket and
    5474        carefully unfolded it upon his knee.
    5475
    5476        "What do you make of that?" he asked.
    5477
    5478        The paper was covered with the tracings of the foot-marks of some small
    5479        animal. It had five well-marked foot-pads, an indication of long nails,
    5480        and the whole print might be nearly as large as a dessert-spoon.
    5481
    5482        "It's a dog," said I.
    5483
    5484        "Did you ever hear of a dog running up a curtain? I found distinct
    5485        traces that this creature had done so."
    5486
    5487        "A monkey, then?"
    5488
    5489        "But it is not the print of a monkey."
    5490
    5491        "What can it be, then?"
    5492
    5493        "Neither dog nor cat nor monkey nor any creature that we are familiar
    5494        with. I have tried to reconstruct it from the measurements. Here are
    5495        four prints where the beast has been standing motionless. You see that
    5496        it is no less than fifteen inches from fore-foot to hind. Add to that
    5497        the length of neck and head, and you get a creature not much less than
    5498        two feet long--probably more if there is any tail. But now observe this
    5499        other measurement. The animal has been moving, and we have the length
    5500        of its stride. In each case it is only about three inches. You have an
    5501        indication, you see, of a long body with very short legs attached to it.
    5502        It has not been considerate enough to leave any of its hair behind it.
    5503        But its general shape must be what I have indicated, and it can run up a
    5504        curtain, and it is carnivorous."
    5505

  #2 indexed_entity matchedBy=fts+vector score=0.0296
  Range: 5500-5539  Status: fresh
  Source:
    5500        of its stride. In each case it is only about three inches. You have an
    5501        indication, you see, of a long body with very short legs attached to it.
    5502        It has not been considerate enough to leave any of its hair behind it.
    5503        But its general shape must be what I have indicated, and it can run up a
    5504        curtain, and it is carnivorous."
    5505
    5506        "How do you deduce that?"
    5507
    5508        "Because it ran up the curtain. A canary's cage was hanging in the
    5509        window, and its aim seems to have been to get at the bird."
    5510
    5511        "Then what was the beast?"
    5512
    5513        "Ah, if I could give it a name it might go a long way towards solving
    5514        the case. On the whole, it was probably some creature of the weasel and
    5515        stoat tribe--and yet it is larger than any of these that I have seen."
    5516
    5517        "But what had it to do with the crime?"
    5518
    5519        "That, also, is still obscure. But we have learned a good deal, you
    5520        perceive. We know that a man stood in the road looking at the quarrel
    5521        between the Barclays--the blinds were up and the room lighted. We know,
    5522        also, that he ran across the lawn, entered the room, accompanied by a
    5523        strange animal, and that he either struck the Colonel or, as is equally
    5524        possible, that the Colonel fell down from sheer fright at the sight of
    5525        him, and cut his head on the corner of the fender. Finally, we have the
    5526        curious fact that the intruder carried away the key with him when he
    5527        left."
    5528
    5529        "Your discoveries seem to have left the business more obscure that it
    5530        was before," said I.
    5531
    5532        "Quite so. They undoubtedly showed that the affair was much deeper than
    5533        was at first conjectured. I thought the matter over, and I came to
    5534        the conclusion that I must approach the case from another aspect. But
    5535        really, Watson, I am keeping you up, and I might just as well tell you
    5536        all this on our way to Aldershot to-morrow."
    5537
    5538        "Thank you, you have gone rather too far to stop."
    5539

  #3 indexed_entity matchedBy=fts+vector score=0.0296
  Range: 5439-5467  Status: fresh
  Source:
    5439        could have seen his wife making a murderous attack upon him. Nor was
    5440        the fact of the wound being on the back of his head a fatal objection to
    5441        this, as he might have turned to avoid the blow. No information could
    5442        be got from the lady herself, who was temporarily insane from an acute
    5443        attack of brain-fever.
    5444
    5445        "From the police I learned that Miss Morrison, who you remember went out
    5446        that evening with Mrs. Barclay, denied having any knowledge of what it
    5447        was which had caused the ill-humor in which her companion had returned.
    5448
    5449        "Having gathered these facts, Watson, I smoked several pipes over them,
    5450        trying to separate those which were crucial from others which were
    5451        merely incidental. There could be no question that the most distinctive
    5452        and suggestive point in the case was the singular disappearance of the
    5453        door-key. A most careful search had failed to discover it in the room.
    5454        Therefore it must have been taken from it. But neither the Colonel
    5455        nor the Colonel's wife could have taken it. That was perfectly clear.
    5456        Therefore a third person must have entered the room. And that third
    5457        person could only have come in through the window. It seemed to me that
    5458        a careful examination of the room and the lawn might possibly reveal
    5459        some traces of this mysterious individual. You know my methods, Watson.
    5460        There was not one of them which I did not apply to the inquiry. And it
    5461        ended by my discovering traces, but very different ones from those which
    5462        I had expected. There had been a man in the room, and he had crossed
    5463        the lawn coming from the road. I was able to obtain five very clear
    5464        impressions of his foot-marks: one in the roadway itself, at the point
    5465        where he had climbed the low wall, two on the lawn, and two very faint
    5466        ones upon the stained boards near the window where he had entered.
    5467        He had apparently rushed across the lawn, for his toe-marks were much

◆エージェントによる検索
エージェント向けの検索はOpenCodeを経由するようなので、以下のコマンドでOpenCodeのインストールを行います。

npm install -g @opencode/cli

以下のコマンドでOpenCodeを経由した検索を実行します。問い合わせ内容は人間向け検索の時とほぼ同一です。

opencode run --model opencode/nemotron-3-ultra-free \
  "An unseen creature left a few marks. What did the detective infer? Cite local evidence."

以下が出力結果です。特にモデルは指定しませんでしたが「NVIDIA Nemotron 3 Ultra (free)」を使用していることが確認できます。

> build · nemotron-3-ultra-free
✱ Glob "**/*" 2 matches
> build · nemotron-3-ultra-free
→ Read alice-in-wonderland.txt
→ Read sherlock-holmes.txt
> build · nemotron-3-ultra-free
✱ Grep "marks?|tracks?|creature|unseen" in sherlock-holmes.txt · 100 matches
> build · nemotron-3-ultra-free
→ Read sherlock-holmes.txt [offset=5460, limit=100]
> build · nemotron-3-ultra-free
✱ Grep "creature|marks?|tracks?|detective|infer" in alice-in-wonderland.txt · 63 matches
> build · nemotron-3-ultra-free
→ Read sherlock-holmes.txt [limit=50, offset=860]
> build · nemotron-3-ultra-free
✱ Grep "unseen.*mark|mark.*unseen|creature.*mark" in sherlock-holmes.txt · 0 matches
> build · nemotron-3-ultra-free
→ Read sherlock-holmes.txt [limit=100, offset=5560]
> build · nemotron-3-ultra-free
→ Read sherlock-holmes.txt [offset=5660, limit=100]
> build · nemotron-3-ultra-free
→ Read sherlock-holmes.txt [offset=5820, limit=100]
> build · nemotron-3-ultra-free
The riddle refers to **"The Adventure of the Crooked Man"** (in the Sherlock Holmes file). The "unseen creature" was a **mongoose** (called "Teddy") that left foot-marks on a sheet of tissue paper and ran up a curtain.

**What the detective inferred:**

From the foot-marks alone, Holmes deduced the creature was:
- A small carnivorous animal with **five well-marked foot-pads and long nails** (≈ dessert-spoon sized)
- **Long body, very short legs** (stride only ~3 inches, but 15 inches from fore-foot to hind)
- Able to **run up a curtain** (targeting a canary's cage)
- Likely **"some creature of the weasel and stoat tribe—but larger than any of these that I have seen"**

**Local evidence (citations from sherlock-holmes.txt):**

| Inference | Evidence (line numbers) |
|-----------|-------------------------|
| Small animal, 5 foot-pads, long nails, dessert-spoon print | 5478–5480 |
| Ran up a curtain | 5484–5485 |
| Long body, short legs (15″ fore-to-hind, 3″ stride) | 5495–5501 |
| Carnivorous (went for a canary) | 5508–5509 |
| Weasel/stoat tribe, but larger | 5513–5515 |
| **Revealed identity: mongoose (ichneumon) named Teddy** | 5835–5844 |

Holmes reconstructed the creature entirely from its "few marks" on the paper before ever seeing it—Watson later identifies it on sight as a mongoose (line 5840).

回答内容については「このなぞなぞは『背中の曲がった男』について言及したものです。『姿の見えない生き物』とはティッシュペーパーに足跡を残しカーテンを駆け上がった、『テディ』という名前のマングースのことでした」と、かなり具体的なものとなっています。

◆まとめ
zgは人間とAIエージェントのために構築された、ワークスペース全体を対象とするローカルファースト検索のソリューションです。導入は比較的簡単に行え、使い方もわかりやすいので興味のある方は是非試してみてください。