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 的启发，借鉴了其进程管理模式、工作服务架构和钩子系统的概念。