mcpField
G
grepai-storage-gob

grepai-storage-gob

github.com/yoanbernabeu开发20675 次安装38 周前更新
代码仓库

关于 grepai-storage-gob

为 GrepAI 提供 GOB 本地文件存储用法指南，适合单人开发和中小型代码库。索引无需外部服务，便于备份，但不适合大型代码库或并发共享。

主要功能

  1. 01单文件保存向量嵌入与元数据
  2. 02使用 grepai 命令创建和检查索引
  3. 03复制文件备份或迁移
  4. 04说明内存占用与扩展限制

适用场景

  1. 01为本地开发项目建立代码索引
  2. 02备份或重建 .grepai 索引
  3. 03评估何时迁移到 PostgreSQL 或 Qdrant

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/yoanbernabeu/grepai-skills --skill grepai-storage-gob

安装后在 Claude Code 中输入/grepai-storage-gob确认已加载。

详细介绍

使用 GOB 进行 GrepAI 存储

本技能介绍如何使用 GOB（Go Binary）作为 GrepAI 的存储后端，这是默认且最简单的选项。

何时使用此技能

  • 单人开发项目
  • 小型到中型代码库
  • 无需外部依赖的简单设置
  • 本地开发环境

什么是 GOB 存储？

GOB 是 Go 的原生二进制序列化格式。GrepAI 使用它来存储：

  • 向量嵌入
  • 文件元数据
  • 代码块信息

所有内容都存储在单个本地文件中。

优势

优势描述
🚀 简单无需外部服务
⚡ 设置快速开箱即用
📁 便于移植单个文件，易于备份
💰 免费无基础设施成本
🔒 私密数据保留在本地

局限性

局限性描述
📏 可扩展性不适合超大型代码库
👤 单用户不支持并发访问
🔄 无法共享无法在多台机器间共享索引
💾 内存搜索时会将数据加载到 RAM

配置

默认配置

GOB 是默认后端。最简配置：

# .grepai/config.yaml
store:
  backend: gob
显式配置
store:
  backend: gob
  # Index stored in .grepai/index.gob (automatic)

存储位置

GOB 存储会在项目的 .grepai/ 目录中创建文件：

.grepai/
├── config.yaml    # Configuration
├── index.gob      # Vector embeddings
└── symbols.gob    # Symbol index for trace

文件大小

.grepai/index.gob 的大致大小：

代码库文件数代码块数索引大小
小型100500~5 MB
中型1,0005,000~50 MB
大型10,00050,000~500 MB

操作

创建索引
# Initialize project
grepai init

# Start indexing (creates index.gob)
grepai watch
检查索引状态
grepai status

# Output:
# Index: .grepai/index.gob
# Files: 245
# Chunks: 1,234
# Size: 12.5 MB
# Last updated: 2025-01-28 10:30:00
备份索引
# Simple file copy
cp .grepai/index.gob .grepai/index.gob.backup
清除索引
# Delete and re-index
rm .grepai/index.gob
grepai watch
迁移到新机器
# Copy entire .grepai directory
cp -r .grepai /path/to/new/location/

# Note: Only works if using same embedding model

性能注意事项

内存使用量

GOB 会在搜索时将整个索引加载到 RAM：

索引大小RAM 使用量
10 MB~20 MB
50 MB~100 MB
500 MB~1 GB
搜索速度

对于常见规模的代码库，GOB 可提供快速搜索：

代码库大小搜索时间
小型（100 个文件）<50ms
中型（1K 个文件）<200ms
大型（10K 个文件）<1s
何时升级

满足以下情况时，可考虑使用 PostgreSQL 或 Qdrant：

  • 索引超过 1 GB
  • 需要并发访问
  • 希望在团队间共享索引
  • 代码库包含 50K+ 个文件

.gitignore 配置

将 .grepai/ 添加到 .gitignore：

# GrepAI (machine-specific index)
.grepai/

原因： 索引与机器有关，因为它：

  • 包含二进制嵌入
  • 与所用的嵌入模型绑定
  • 每台机器都应生成自己的索引

共享索引（不推荐）

虽然可以复制索引文件，但不推荐这样做，因为：

  1. 必须使用完全相同的嵌入模型
  2. 文件路径是绝对路径
  3. 不同机器上的代码版本可能不同

更好的做法： 每位开发者都运行自己的 grepai watch。

迁移到其他后端

迁移到 PostgreSQL
  1. 更新配置：
store:
  backend: postgres
  postgres:
    dsn: postgres://user:pass@localhost:5432/grepai
  1. 重新建立索引：
rm .grepai/index.gob
grepai watch
迁移到 Qdrant
  1. 更新配置：
store:
  backend: qdrant
  qdrant:
    endpoint: localhost
    port: 6334
  1. 重新建立索引：
rm .grepai/index.gob
grepai watch

常见问题

❌ 问题： 索引文件太大
✅ 解决方案： 添加更多忽略规则，或迁移到 PostgreSQL/Qdrant

❌ 问题： 大型代码库搜索缓慢
✅ 解决方案： 迁移到 Qdrant 以获得更好的性能

❌ 问题： 索引损坏
✅ 解决方案： 删除索引并重新建立：

rm .grepai/index.gob .grepai/symbols.gob
grepai watch

❌ 问题： 出现“未找到索引”错误
✅ 解决方案： 运行 grepai watch 创建索引

最佳实践

  1. 用于小型/中型项目： 最多约 10K 个文件
  2. 添加到 .gitignore： 不要提交索引
  3. 重大更改前先备份： 试验前复制 index.gob
  4. 更改模型后重新建立索引： 如果更改嵌入模型
  5. 监控文件大小： 索引超过 1GB 时迁移

输出格式

GOB 存储状态：

✅ GOB Storage Configured

   Backend: GOB (local file)
   Index: .grepai/index.gob
   Size: 12.5 MB

   Contents:
   - Files: 245
   - Chunks: 1,234
   - Vectors: 1,234 × 768 dimensions

   Performance:
   - Search latency: <100ms
   - Memory usage: ~25 MB

评论

支持 Markdown