Oracle V2

🚀 Oracle Nightly - MCP Memory Layer

Oracle Nightly - MCP Memory Layer 是一個用於對 Oracle 哲學進行語義搜索的 TypeScript MCP 服務器，它採用了 SQLite FTS5 和 ChromaDB 的混合搜索方式，同時提供 HTTP API 和 Vault CLI 工具。

🚀 快速開始

本項目提供了多種啟動方式，你可以根據自己的需求選擇合適的方法。

安裝

bunx（推薦）

本項目通過 GitHub 進行分發，無需在 npm 上發佈：

# MCP 服務器（標準輸入輸出，適用於 Claude Code）
bunx --bun oracle-v2@github:Soul-Brews-Studio/oracle-v2#main

# Vault CLI（輔助二進制文件 — 使用 --package）
bunx --bun --package oracle-v2@github:Soul-Brews-Studio/oracle-v2#main oracle-vault --help

添加到 Claude Code

claude mcp add oracle-v2 -- bunx --bun oracle-v2@github:Soul-Brews-Studio/oracle-v2#main

或者在 ~/.claude.json 中添加以下內容：

{
  "mcpServers": {
    "oracle-v2": {
      "command": "bunx",
      "args": ["--bun", "oracle-v2@github:Soul-Brews-Studio/oracle-v2#main"]
    }
  }
}

從源代碼安裝

git clone https://github.com/Soul-Brews-Studio/oracle-v2.git
cd oracle-v2 && bun install
bun run dev          # MCP 服務器
bun run server       # 在端口 47778 上啟動 HTTP API

curl -sSL https://raw.githubusercontent.com/Soul-Brews-Studio/oracle-v2/main/scripts/install.sh | bash

✨ 主要特性

• 混合搜索：結合 SQLite FTS5 和 ChromaDB 進行語義搜索。
• HTTP API：提供豐富的 API 接口，方便進行各種操作。
• Vault CLI：全局 CLI 工具，用於管理 Oracle 知識庫。
• 多工具支持：提供 22 種工具，可通過 Claude Code 使用。

📦 安裝指南

系統要求

• Bun 運行時（>=1.2.0）
• SQLite + FTS5 用於全文搜索
• ChromaDB 用於向量/語義搜索
• Drizzle ORM 用於類型安全的查詢
• Hono 用於 HTTP API
• MCP 協議用於 Claude 集成

安裝步驟

見上文快速開始部分的安裝說明。

💻 使用示例

MCP 工具

本項目提供了 22 種工具，可通過 Claude Code 使用：

Vault CLI

全局 CLI 工具，用於管理 Oracle 知識庫：

oracle-vault init <owner/repo>    # 使用 GitHub 倉庫初始化 Vault
oracle-vault status               # 顯示配置和待處理的更改
oracle-vault sync                 # 提交併推送到 GitHub
oracle-vault pull                 # 將 Vault 文件拉取到本地 ψ/
oracle-vault migrate              # 從 ghq 倉庫中導入 Vault

API 端點

HTTP API 在端口 47778 上運行（bun run server）：

📚 詳細文檔

項目架構

oracle-v2 (一個包，兩個二進制文件)
├── bunx oracle-v2                          → MCP 服務器 (src/index.ts)
├── bunx --package oracle-v2 oracle-vault   → Vault CLI (src/vault/cli.ts)
├── bun run server                          → HTTP API (src/server.ts)
└── bun run index                           → 索引器 (src/indexer.ts)

oracle-studio (單獨的倉庫)
└── bunx oracle-studio                      → React 儀表盤

項目結構

oracle-v2/
├── src/
│   ├── index.ts          # MCP 服務器入口
│   ├── server.ts         # HTTP API (Hono)
│   ├── indexer.ts        # 知識索引器
│   ├── vault/
│   │   └── cli.ts        # Vault CLI 入口
│   ├── tools/            # MCP 工具處理程序
│   ├── trace/            # 跟蹤系統
│   ├── db/
│   │   ├── schema.ts     # Drizzle 模式
│   │   └── index.ts      # 數據庫客戶端
│   └── server/           # HTTP 服務器模塊
├── scripts/              # 設置和實用腳本
├── docs/                 # 文檔
└── drizzle.config.ts     # Drizzle 配置

配置

數據庫操作

Drizzle ORM 與 SQLite 結合使用：

bun db:push       # 將模式推送到數據庫
bun db:generate   # 生成遷移文件
bun db:migrate    # 應用遷移
bun db:studio     # 打開 Drizzle Studio GUI

測試

bun test              # 運行所有測試
bun test:unit         # 運行單元測試
bun test:integration  # 運行集成測試
bun test:e2e          # 運行 Playwright E2E 測試
bun test:coverage     # 運行測試並生成覆蓋率報告

🔧 技術細節

• 運行時：使用 Bun 運行時（>=1.2.0），提供高效的開發和運行環境。
• 搜索技術：採用 SQLite FTS5 進行全文搜索，ChromaDB 進行向量/語義搜索，結合兩者的優勢，提供更準確的搜索結果。
• ORM：使用 Drizzle ORM 進行類型安全的數據庫查詢，確保代碼的健壯性。
• HTTP API：使用 Hono 構建 HTTP API，提供簡潔高效的接口。
• MCP 協議：通過 MCP 協議與 Claude 集成，實現更強大的功能。

📄 許可證

文檔未提及相關許可證信息。

🔗 參考資料

• TIMELINE.md - 完整的演變歷史
• docs/API.md - API 文檔
• docs/architecture.md - 架構細節
• Drizzle ORM
• MCP SDK

🙏 致謝

本項目受到了 Alex Newman 的 claude-mem 的啟發，借鑑了其進程管理模式、工作服務架構和鉤子系統的概念。