HereVault

基于 Obsidian Vault 的 AI Agent 记忆与知识库系统，通过 MCP 协议驱动

English Documentation

HereVault 是为 AI Agent 打造的长期记忆与知识库系统，基于 Obsidian Vault 构建。支持通过 MCP（Model Context Protocol）协议和 RESTful HTTP API 进行交互，使用 LanceDB 向量数据库和语义搜索技术，为 AI Agent 提供持久化的记忆存储与知识检索能力。

核心特性

• 双模式支持: 同时支持 MCP 协议 (stdio) 和 RESTful HTTP API
• 记忆管理: 保存、检索、删除 AI Agent 的记忆 (偏好、习惯、事实、对话、技能、上下文)
• 知识库: 构建和管理结构化知识库，支持语义搜索
• 智能搜索: 基于 BGE-M3 嵌入模型和可配置 Reranker 的混合搜索 (向量 + BM25 + RRF 重排序)
• Obsidian 集成: 原生支持 Obsidian Vault 格式，Markdown 文件存储
• 高性能: 支持模型池化、后台索引、增量同步
• 自动同步: 监控文件变化，自动同步到向量数据库

安装

环境要求

• Node.js >= 18.0.0
• 支持的操作系统: Windows, macOS, Linux

从 NPM 安装

npm install -g herevault

模型下载

herevault 需要以下 ONNX 模型文件：

1. 嵌入模型: bge-m3-ONNX-int8 - 用于生成文本向量嵌入
2. 重排序模型: ms-marco-MiniLM-L6-v2 (默认) 或 bge-reranker-v2-m3-ONNX-int8 - 用于搜索结果重排序

首次启动服务时，模型会自动下载到 <vault>/.herevault/models/ 目录，无需手动准备。你也可以提前将模型文件放置在该目录下，或通过配置指定自定义模型路径。

支持的 Reranker 模型

| 模型 | 类型 | 大小 | 说明 | |------|------|------|------| | ms-marco-MiniLM-L6-v2 | Cross-Encoder | ~80MB | 默认 - 轻量级、推理速度快、准确率高 | | bge-reranker-v2-m3-ONNX-int8 | BGE-Reranker | ~1GB | 更高准确率，内存占用较大 |

rerankerType 配置选项控制模型加载方式：

• 'auto' (默认): 自动检测模型架构
• 'bge': 强制使用 BGE-Reranker 模式
• 'cross-encoder': 强制使用 Cross-Encoder 模式

自定义模型路径示例

支持绝对路径和相对路径（相对于 Vault 根目录）：

方式一：配置文件 (config.yml)

# 绝对路径
model:
  dir: /home/user/models

# 或相对路径（相对于 Vault 根目录）
model:
  dir: ./models

方式二：环境变量

# 绝对路径
export HEREVAULT_MODEL_DIR=/home/user/models

# 或相对路径（相对于 Vault 根目录）
export HEREVAULT_MODEL_DIR=./models

路径解析规则：

• 绝对路径：直接使用指定路径，如 /home/user/models、C:\Models
• 相对路径：基于 Vault 根目录解析，如 ./models 解析为 <vault>/models

快速开始

命令行使用

herevault 提供三类 CLI 命令：Vault 初始化命令、服务器命令 和 直接操作命令。

Vault 初始化

# 初始化新的 vault，创建所需目录和配置文件
herevault init --vault /path/to/your/vault

# 下载 ONNX 模型（嵌入模型 + 重排序模型）
herevault download-models --vault /path/to/your/vault

# 跳过重排序模型下载
herevault download-models --vault /path/to/your/vault --skip-rerank

# 使用特定模型
herevault download-models --vault /path/to/your/vault \
  --embed-model bge-m3-ONNX-int8 \
  --rerank-model ms-marco-MiniLM-L6-v2

启动服务器

# 启动服务器（默认 MCP 模式）
herevault serve --vault /path/to/your/vault

# 带配置文件启动
herevault serve --vault /path/to/your/vault --config /path/to/config.yml

# 跳过启动同步
herevault serve --vault /path/to/your/vault --no-sync

# 禁用文件监控
herevault serve --vault /path/to/your/vault --no-watch

# 设置日志级别
herevault serve --vault /path/to/your/vault --log-level debug

# 禁用重排序模型（跳过 reranker 模型下载和加载）
herevault serve --vault /path/to/your/vault --reranker false

# HTTP 模式
herevault serve --vault /path/to/your/vault --mode http --port 3000

# MCP + HTTP 双模式
herevault serve --vault /path/to/your/vault --mode both --port 3000

直接操作命令（无需启动服务器）

无需启动服务器，直接从命令行执行记忆和知识库操作：

# 保存记忆
herevault memory-save --vault /path/to/your/vault \
  --type fact \
  --name "my-memory" \
  --content "## 重要笔记\n\n这是一条测试记忆。" \
  --tags "test,important"

# 搜索记忆
herevault memory-recall --vault /path/to/your/vault \
  --query "重要笔记" \
  --limit 5

# 删除记忆
herevault memory-forget --vault /path/to/your/vault \
  --id "550e8400-e29b-41d4-a716-446655440000"

# 添加知识
herevault knowledge-add --vault /path/to/your/vault \
  --title "API 设计指南" \
  --content "## REST API 设计\n\n### 原则\n- 使用名词表示资源" \
  --tags "api,design"

# 搜索知识
herevault knowledge-search --vault /path/to/your/vault \
  --query "REST API" \
  --limit 10

# 删除知识
herevault knowledge-remove --vault /path/to/your/vault \
  --id "660e8400-e29b-41d4-a716-446655440001"

# 从源目录同步知识
herevault knowledge-sync --vault /path/to/your/vault \
  --source "Source"

# 完整同步（源目录 + 知识库扫描 + 记忆扫描）
# 在手动修改或删除 vault 中的文件后使用此命令
herevault sync --vault /path/to/your/vault

# 统一搜索（记忆 + 知识）
herevault search --vault /path/to/your/vault \
  --query "机器学习" \
  --type all \
  --limit 10

sync 与 knowledge-sync 的区别：

• knowledge-sync：只从源目录同步到知识库（第 1 步）
• sync：执行完整的启动同步，包括源目录同步 + 知识库目录扫描 + 记忆目录扫描（第 1-3 步）。当你手动修改或删除了 vault 中的文件，需要更新向量索引时使用 sync。

注意：直接操作命令会独立初始化存储和模型上下文。文件保存是同步的，但向量索引在后台异步完成。

环境变量配置

# 必需
export HEREVAULT_VAULT_PATH=/path/to/your/vault

# 可选配置
export HEREVAULT_HTTP_ENABLED=true
export HEREVAULT_HTTP_PORT=3000
export HEREVAULT_HTTP_HOST=127.0.0.1
export HEREVAULT_MODEL_DIR=/path/to/models
export HEREVAULT_SYNC_MEMORIES=true
export HEREVAULT_USE_AS_KNOWLEDGE_BASE=true
export HEREVAULT_LOG_LEVEL=info
export HEREVAULT_ENABLE_RERANKER=true

MCP 配置示例 (Claude Desktop)

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "herevault": {
      "command": "herevault",
      "args": [
        "--vault",
        "/path/to/your/vault"
      ],
      "env": {
        "HEREVAULT_HTTP_ENABLED": "false",
        "HEREVAULT_ENABLE_RERANKER": "true"
      }
    }
  }
}

配置文件

配置文件位于 <vault>/.herevault/config.yml，首次启动会自动创建默认配置：

vault:
  path: /path/to/your/vault
  memoriesDir: Memories
  knowledgeBaseDir: Knowledge
  sourceDirs:
    - Source

obsidian:
  useAsKnowledgeBase: true
  syncMemories: true
  knowledgeSearchScope: knowledge

index:
  embeddingDim: 1024
  chunkStrategy: heading
  chunkSize: 1000
  chunkOverlap: 150

model:
  dir: /path/to/models
  embedModel: bge-m3-ONNX-int8
  rerankModel: ms-marco-MiniLM-L6-v2
  rerankerType: auto
  enableReranker: true
  interOpNumThreads: 1
  intraOpNumThreads: 4

search:
  searchLimit: 10
  includeFullContent: false
  maxContentLength: 500
  bm25K1: 1.5
  bm25B: 0.75
  rrfK: 60
  vectorSearchLimit: 50
  bm25SearchLimit: 50
  rrfFusionLimit: 20
  contextWindowSize: 1

sync:
  startupSync: true
  watchChanges: true
  interval: 300000
  debounceMs: 500

log:
  level: info

mode: mcp

http:
  port: 3000
  host: 127.0.0.1

配置优先级

配置值按以下优先级合并（从高到低）：

1. 命令行参数: --reranker false
2. 环境变量: HEREVAULT_ENABLE_RERANKER=false
3. 配置文件: model.enableReranker: false
4. 默认值: true

重排序控制

enableReranker 选项控制是否使用重排序模型：

• true (默认): 完整的混合搜索（向量 + BM25 + Reranker 重排序）
• false: 不使用重排序的混合搜索（仅向量 + BM25），跳过 reranker 模型下载和加载

禁用重排序的适用场景：

• 更快的启动速度（无需下载/加载 reranker 模型）
• 更低的内存占用
• 向量 + BM25 的搜索质量已满足需求
• 在资源受限的环境中运行

MCP 工具集

herevault 提供以下 MCP 工具供 AI Agent 调用：

记忆管理工具

memory_save

保存记忆到 Obsidian Vault

参数：

• type (required): 记忆类型 - preference, habit, fact, conversation, skill, context
• content (required): 记忆内容 (Markdown 格式)
• name (required): 文件名 (kebab-case)
• tags (optional): 标签数组
• expiresAt (optional): 过期时间 (ISO 8601 格式)

示例：

{
  "type": "preference",
  "name": "user-coding-style",
  "content": "## 用户编码偏好\n\n### 风格\n- 使用 TypeScript\n- 偏好函数式编程\n- 注重代码可读性",
  "tags": ["coding", "preference"]
}

memory_recall

通过语义搜索检索记忆

参数：

• query (required): 搜索查询
• type (optional): 按记忆类型过滤
• tags (optional): 按标签过滤
• limit (optional): 返回结果数量限制

示例：

{
  "query": "用户的编程偏好",
  "type": "preference",
  "limit": 5
}

memory_forget

删除指定记忆

参数：

• memoryId (required): 记忆 ID

示例：

{
  "memoryId": "550e8400-e29b-41d4-a716-446655440000"
}

知识库工具

knowledge_add

添加知识到知识库

参数：

• title (required): 知识标题
• content (optional): 知识内容
• tags (optional): 标签数组
• sourcePath (optional): 源文件路径 (仅用于元数据)
• overwrite (optional): 是否覆盖已有文件

示例：

{
  "title": "FastAPI 最佳实践",
  "content": "## FastAPI 最佳实践\n\n### 项目结构\n...",
  "tags": ["python", "fastapi", "backend"]
}

knowledge_search

搜索知识库

参数：

• query (required): 搜索查询
• tags (optional): 按标签过滤
• limit (optional): 返回结果数量限制

示例：

{
  "query": "FastAPI 项目结构",
  "tags": ["fastapi"],
  "limit": 10
}

knowledge_remove

删除知识文档

参数：

• documentId (required): 文档 ID

示例：

{
  "documentId": "550e8400-e29b-41d4-a716-446655440000"
}

knowledge_sync

从源目录同步知识

参数：

• sourceDir (optional): 指定源目录 (必须在配置的 sourceDirs 中)

示例：

{
  "sourceDir": "Source"
}

RESTful API

当 http.enabled: true 时，herevault 会启动 HTTP API 服务器。

基础信息

• Base URL: http://127.0.0.1:3000/api/v1
• Health Check: GET /health

状态接口

获取系统状态

GET /api/v1/status

响应示例：

{
  "success": true,
  "data": {
    "vault": {
      "path": "/path/to/vault",
      "memoriesDir": "Memories",
      "knowledgeBaseDir": "Knowledge",
      "sourceDirs": ["Source"]
    },
    "features": {
      "useAsKnowledgeBase": true,
      "syncMemories": true
    },
    "mode": "mcp",
    "http": {
      "port": 3000,
      "host": "127.0.0.1"
    },
    "models": {
      "embedderReady": true,
      "rerankerReady": true,
      "enableReranker": true
    },
    "stats": {
      "totalMemories": 50,
      "totalKnowledge": 100
    }
  }
}

记忆接口

保存记忆

POST /api/v1/memories
Content-Type: application/json

{
  "type": "preference",
  "content": "## 用户偏好\n\n喜欢使用深色主题",
  "name": "user-theme-preference",
  "tags": ["ui", "preference"]
}

响应：

{
  "success": true,
  "data": {
    "memoryId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "preference",
    "tags": ["ui", "preference"],
    "createdAt": "2024-01-15T10:30:00+08:00",
    "updatedAt": "2024-01-15T10:30:00+08:00",
    "checksum": "abc123...",
    "filePath": "/path/to/vault/Memories/user-theme-preference.md",
    "status": "saved"
  }
}

检索记忆

GET /api/v1/memories?query=用户偏好&type=preference&limit=5

响应：

{
  "success": true,
  "data": {
    "query": "用户偏好",
    "total": 3,
    "results": [
      {
        "memoryId": "550e8400-e29b-41d4-a716-446655440000",
        "type": "preference",
        "score": 0.95,
        "content": "喜欢使用深色主题",
        "filePath": "Memories/user-theme-preference.md",
        "tags": ["ui", "preference"],
        "createdAt": "2024-01-15T10:30:00+08:00",
        "matchedChunks": [
          {
            "chunkId": "chunk-1",
            "content": "喜欢使用深色主题",
            "score": 0.95
          }
        ]
      }
    ]
  }
}

删除记忆

DELETE /api/v1/memories/{memoryId}

响应：

{
  "success": true,
  "data": {
    "memoryId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "deleted",
    "message": "Memory permanently removed from vault and index"
  }
}

知识库接口

添加知识

POST /api/v1/knowledge
Content-Type: application/json

{
  "title": "React Hooks 指南",
  "content": "## React Hooks\n\n### useState\n用于在函数组件中添加状态...",
  "tags": ["react", "javascript", "frontend"]
}

响应：

{
  "success": true,
  "data": {
    "documentId": "660e8400-e29b-41d4-a716-446655440001",
    "type": "knowledge",
    "title": "React Hooks 指南",
    "tags": ["react", "javascript", "frontend"],
    "createdAt": "2024-01-15T11:00:00+08:00",
    "updatedAt": "2024-01-15T11:00:00+08:00",
    "checksum": "def456...",
    "filePath": "/path/to/vault/Knowledge/react-hooks-guide.md",
    "status": "saved"
  }
}

搜索知识

GET /api/v1/knowledge?query=React Hooks&tags=react&limit=10

响应：

{
  "success": true,
  "data": {
    "query": "React Hooks",
    "total": 5,
    "results": [
      {
        "documentId": "660e8400-e29b-41d4-a716-446655440001",
        "documentType": "knowledge",
        "title": "React Hooks 指南",
        "score": 0.92,
        "filePath": "Knowledge/react-hooks-guide.md",
        "tags": ["react", "javascript", "frontend"],
        "createdAt": "2024-01-15T11:00:00+08:00",
        "matchedChunks": [
          {
            "chunkId": "chunk-1",
            "headlinePath": "React Hooks > useState",
            "content": "用于在函数组件中添加状态",
            "score": 0.92
          }
        ]
      }
    ]
  }
}

删除知识

DELETE /api/v1/knowledge/{documentId}

响应：

{
  "success": true,
  "data": {
    "documentId": "660e8400-e29b-41d4-a716-446655440001",
    "status": "deleted",
    "filePath": "Knowledge/react-hooks-guide.md",
    "message": "Knowledge permanently removed from vault and index"
  }
}

同步知识

POST /api/v1/knowledge/sync
Content-Type: application/json

{
  "sourceDir": "Source"
}

响应：

{
  "success": true,
  "data": {
    "added": 5,
    "updated": 3,
    "skipped": 10,
    "message": "Sync completed successfully"
  }
}

搜索接口

全局搜索

GET /api/v1/search?query=机器学习&limit=10

响应：

{
  "success": true,
  "data": {
    "query": "机器学习",
    "total": 8,
    "results": [
      {
        "documentId": "...",
        "documentType": "knowledge",
        "title": "机器学习基础",
        "score": 0.88,
        "filePath": "Knowledge/ml-basics.md",
        "matchedChunks": [...]
      }
    ]
  }
}

Vault 目录结构

your-vault/
├── .herevault/              # herevault 数据和配置
│   ├── config.yml           # 配置文件
│   ├── db/                  # LanceDB 数据库
│   ├── models/              # ONNX 模型文件
│   └── server.pid           # 进程 ID 文件
├── Memories/                # 记忆存储目录
│   ├── preference/
│   ├── habit/
│   ├── fact/
│   ├── conversation/
│   ├── skill/
│   └── context/
├── Knowledge/               # 知识库存储目录
│   ├── topic-a.md
│   └── topic-b.md
└── Source/                  # 源文件目录 (可选)
    └── external-docs/

许可证

本软件为专有软件，未经授权的复制、分发或使用均被严格禁止。

详见 LICENSE 文件。