qfs (Juanbermudez)

QFS-快速文件搜索

一个设备上的搜索引擎，可以找到你需要记住的一切。为你的笔记、代码、文档和知识库建立索引。使用关键字或语义相似性进行搜索。非常适合您的代理流。

QFS结合了BM25全文搜索、向量语义搜索和使用交互排名融合（RRF）的混合排名，所有这些都在本地运行。内置Rust，以最小的依赖性实现速度。

快速开始

# Install from source
cargo install --path qfs-cli

# Create collections for your notes, docs, and code
qfs add notes ~/notes --patterns "**/*.md"
qfs add docs ~/Documents --patterns "**/*.md" "**/*.txt"
qfs add code ~/projects --patterns "**/*.rs" "**/*.ts" "**/*.py"

# Add context to help with search results
qfs context add notes "Personal notes and ideas"
qfs context add docs "Work documentation"
qfs context add code "Source code and projects"

# Generate embeddings for semantic search (first run downloads model)
qfs embed

# Search across everything
qfs search "project timeline"              # Fast keyword search
qfs search "how to deploy" --mode vector   # Semantic search
qfs search "quarterly planning" --mode hybrid  # Hybrid (best quality)

# Get a specific document
qfs get "notes/meeting-2024-01-15.md"

# Get a document by docid (shown in search results)
qfs get "#abc123"

# Get multiple documents by glob pattern
qfs multi-get "notes/2025-05*.md"

# Search within a specific collection
qfs search "API" -c code

与AI代理一起使用

QFS --format json 输出是为代理工作流设计的：

# Get structured results for an LLM
qfs search "authentication" --format json -n 10

# List all relevant files above a threshold
qfs search "error handling" --min-score 0.3 --format json

# Retrieve full document content
qfs get "docs/api-reference.md"

# Get multiple documents for context
qfs multi-get "docs/*.md" --format json

MCP 服务器

QFS公开了一个MCP（模型上下文协议）服务器，用于与AI代理进行更紧密的集成。

暴露的工具：

• qfs_search -快速BM25关键字搜索（支持集合过滤）
• qfs_vsearch -语义向量搜索（支持集合过滤）
• qfs_query -RRF融合混合搜索（支持收集过滤）
• qfs_get -按路径或docid检索文档（带模糊匹配建议）
• qfs_multi_get -按glob模式、列表或docid检索多个文档
• qfs_status -索引健康和收集信息

Claude桌面配置 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "qfs": {
      "command": "qfs",
      "args": ["serve"]
    }
  }
}

Claude代码配置 (~/.claude/settings.json):

{
  "mcpServers": {
    "qfs": {
      "command": "qfs",
      "args": ["serve"]
    }
  }
}

建筑

┌─────────────────────────────────────────────────────────────────────────────┐
│                         QFS Hybrid Search Pipeline                          │
└─────────────────────────────────────────────────────────────────────────────┘

                              ┌─────────────────┐
                              │   User Query    │
                              └────────┬────────┘
                                       │
              ┌────────────────────────┼────────────────────────┐
              ▼                        │                        ▼
     ┌─────────────────┐               │               ┌─────────────────┐
     │   BM25 Search   │               │               │  Vector Search  │
     │   (SQLite FTS5) │               │               │ (libsql native) │
     └────────┬────────┘               │               └────────┬────────┘
              │                        │                        │
              │  rank 1: doc_a         │         rank 1: doc_b  │
              │  rank 2: doc_b         │         rank 2: doc_a  │
              │  rank 3: doc_c         │         rank 3: doc_d  │
              │                        │                        │
              └────────────────────────┼────────────────────────┘
                                       │
                                       ▼
                          ┌───────────────────────┐
                          │      RRF Fusion       │
                          │        k=60           │
                          │  1/(k + rank) scores  │
                          └───────────┬───────────┘
                                      │
                                      ▼
                              Final ranking:
                              1. doc_a (0.033)
                              2. doc_b (0.032)
                              3. doc_c (0.016)
                              4. doc_d (0.016)

向量搜索

矢量搜索使用libsql的原生矢量索引 vector_top_k() 对于O（log n）近似最近邻搜索。嵌入存储为F32_BLOB（384），并使用余弦距离度量进行索引。

评分规整

搜索后端

分数解释

需求

• 锈蚀1.70+
• SQLite 3.35+（捆绑）

安装

# From source
git clone https://github.com/yourusername/qfs.git
cd qfs
cargo build --release
cp target/release/qfs /usr/local/bin/

# Or install directly
cargo install --path qfs-cli

用法

收集管理

# Add a collection with glob patterns
qfs add notes ~/notes --patterns "**/*.md"

# Add with multiple patterns
qfs add code ~/projects --patterns "**/*.rs" "**/*.ts" "**/*.py"

# List all collections
qfs list

# Remove a collection
qfs remove notes

# List files in a collection
qfs ls notes
qfs ls notes/subfolder

列出集合和文件

# List all collections
qfs ls

# List files in a collection
qfs ls notes

# List files with a path prefix
qfs ls notes/2025
qfs ls qfs://notes/api

# JSON output for scripting
qfs ls notes --format json

索引

# Index all collections (builds FTS5 full-text index)
qfs index

# Index a specific collection
qfs index notes

# Show index status
qfs status

生成嵌入

嵌入支持矢量和混合搜索模式。第一次运行会下载模型（约90MB）。

# Generate embeddings for all indexed documents
qfs embed

# Generate for a specific collection
qfs embed notes

# Force re-generation of all embeddings
qfs embed --force

# Show embedding status
qfs status

嵌入模型是 all-MiniLM-L6-v2 （384尺寸）通过紧固件。嵌入以libsql的原生F32_BLOB格式存储，以实现高效的向量索引。

上下文管理

Context为集合和路径添加描述性元数据，帮助搜索理解您的内容。上下文显示在每个文档旁边的搜索结果中。

# Add context to a collection
qfs context add notes "Personal notes and ideas"
qfs context add docs/api "API documentation"

# Add global context (applies to all collections)
qfs context add / "Knowledge base for my projects"

# List all contexts
qfs context list

# Check for collections without context
qfs context check

# Remove context
qfs context rm notes/old

文档ID（docid）

每个文档都有一个唯一的短ID（docid），即其内容哈希的前6个字符。文档在搜索结果中显示为 #abc123 并且可以与 get 和 multi-get:

# Search returns docid in results
qfs search "query" --format json
# Output includes: {"docid": "abc123", "score": 0.85, "path": "docs/readme.md", ...}

# Get document by docid
qfs get "#abc123"
qfs get abc123              # Leading # is optional

# Docids also work in multi-get comma-separated lists
qfs multi-get "#abc123, #def456"

搜索命令

┌──────────────────────────────────────────────────────────────────┐
│                        Search Modes                              │
├──────────┬───────────────────────────────────────────────────────┤
│ bm25     │ BM25 full-text search only (default)                  │
│ vector   │ Semantic vector similarity only                       │
│ hybrid   │ BM25 + Vector with RRF fusion                         │
└──────────┴───────────────────────────────────────────────────────┘

# Full-text search (fast, keyword-based)
qfs search "authentication flow"

# Vector search (semantic similarity)
qfs search "how to login" --mode vector

# Hybrid search (best quality)
qfs search "user authentication" --mode hybrid

# Search within a date range
qfs search "meeting notes" --from-date 2025-01-01 --to-date 2025-01-31

# Search documents modified after a date
qfs search "project updates" --from-date 2025-06-01

获取和多获取

# Get a document by path
qfs get notes/meeting.md

# Get a document by docid (from search results)
qfs get "#abc123"

# Get document starting at line 50
qfs get notes/meeting.md:50

# Get document with line range
qfs get notes/meeting.md --from 50 --lines 100

# Add line numbers to output
qfs get notes/meeting.md --line-numbers

# Get multiple documents by glob pattern
qfs multi-get "notes/2025-05*.md"

# Get multiple documents by comma-separated list (supports docids)
qfs multi-get "doc1.md, doc2.md, #abc123"

# Limit multi-get to files under 20KB
qfs multi-get "docs/*.md" --max-bytes 20480

# Limit lines per file
qfs multi-get "docs/*.md" --max-lines 100

# Output multi-get as JSON for agent processing
qfs multi-get "docs/*.md" --format json

选项

# Search options
-n, --limit         # Number of results (default: 20)
-m, --mode         # bm25, vector, hybrid (default: bm25)
-c, --collection   # Restrict to a collection
--from-date        # Filter by modified date (ISO 8601, e.g., 2025-01-01)
--to-date          # Filter by modified date (ISO 8601, e.g., 2025-12-31)
--min-score         # Minimum score threshold (default: 0.0)
--include-binary         # Include binary files in results
-o, --format     # text, json (default: text)

# Get options
qfs get 
[:line]    # Get document, optionally starting at line
--from              # Start from line number (1-indexed)
-l, --lines         # Maximum lines to return
--line-numbers           # Add line numbers to output

# Multi-get options
--max-bytes         # Skip files larger than N bytes (default: 10KB)
-l, --max-lines     # Maximum lines per file
-o, --format     # text, json (default: text)

输出格式

默认输出为彩色CLI格式：

docs/guide.md:42 #a1b2c3
Title: Software Craftsmanship
Context: Work documentation
Score: 89%

This section covers the **craftsmanship** of building
quality software with attention to detail.

notes/meeting.md:15 #d4e5f6
Title: Q4 Planning
Context: Personal notes and ideas
Score: 67%

Discussion about code quality and craftsmanship
in the development process.

• 路径：集合相对路径（例如。， docs/guide.md)
• 文档编号：短散列标识符（例如。， #a1b2c3)-配合使用 qfs get #a1b2c3
• 标题：从文档中提取（第一个标题或文件名）
• 上下文：路径上下文（如果通过配置） qfs context add
• 得分：相关性得分（百分比）
• 片段：与突出显示的查询词匹配的上下文

代理的JSON输出：

qfs search "craftsmanship" --format json

{
  "results": [
    {
      "path": "notes/meeting.md",
      "docid": "d4e5f6",
      "score": 0.89,
      "title": "Q4 Planning",
      "context": "Personal notes and ideas",
      "snippet": "Discussion about code quality and **craftsmanship**..."
    }
  ],
  "total": 1,
  "query": "craftsmanship",
  "mode": "bm25"
}

索引维护

# Show index status and collections
qfs status

# Re-index all collections
qfs index

# Re-index a specific collection
qfs index notes

数据存储

索引存储在： ~/.cache/qfs/index.sqlite

模式

collections     -- Indexed directories with name and glob patterns
path_contexts   -- Context descriptions by virtual path (qfs://...)
documents       -- File content with metadata and docid (6-char hash)
documents_fts   -- FTS5 full-text index
embeddings      -- Vector embeddings for semantic search

环境变量

与QMD的差异

Claude代码插件

QFS作为Claude Code插件提供，可实现无缝集成：

qfs-plugin/
├── .claude-plugin/plugin.json  # Plugin manifest
├── .mcp.json                   # MCP server configuration
└── skills/qfs-agent/           # Agent skill with guidance

安装

1. 安装QFS CLI（必须在PATH中）：

cargo install --path qfs-cli

1. 安装插件：

# Local installation
claude --plugin-dir ./qfs-plugin

# Or via marketplace (when published)
/plugin install qfs

该插件提供：

• MCP工具: qfs_search, qfs_vsearch, qfs_query, qfs_get, qfs_multi_get, qfs_status
• 技能：有效使用QFS的代理指南

分销选项

看 qfs-plugin/README.md 有关详细的分发说明。

许可证

麻省理工学院