Oracle MCP - AI Knowledge Management Server

"The Oracle Keeps the Human Human" - queryable via MCP

A Model Context Protocol (MCP) server for semantic search and knowledge management. Store principles, patterns, and learnings with hybrid keyword + vector search.

Installation

As Claude Code Plugin

# Via Claude Code CLI
claude plugin add laris-co/oracle-mcp

Manual Setup

# Clone and install
git clone https://github.com/laris-co/oracle-mcp
cd oracle-mcp
npm install

# Run MCP server
npm run dev

Configuration

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/oracle-mcp",
      "env": {
        "ORACLE_DATA_DIR": "/path/to/data"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
`ORACLE_DATA_DIR`	`~/.oracle-mcp/`	Data directory for SQLite + ChromaDB

MCP Tools

oracle_search

Hybrid search (keywords + semantic) across knowledge base.

{
  "query": "how should I handle file deletion?",
  "type": "principle",
  "mode": "hybrid",
  "limit": 5
}

mode: hybrid (default), fts (keywords only), vector (semantic only)
type: principle, pattern, learning, retro, all

oracle_consult

Get guidance on a decision based on stored principles.

{
  "decision": "Should I amend this commit?",
  "context": "I just made a commit but forgot to add a file"
}

oracle_learn

Add new patterns or learnings to knowledge base.

{
  "pattern": "Always verify before destructive operations",
  "source": "Retrospective 2025-01-15",
  "concepts": ["safety", "verification"]
}

oracle_list

Browse documents without search (pagination supported).

{
  "type": "learning",
  "limit": 10,
  "offset": 0
}

oracle_reflect

Get random wisdom for reflection.

{}

Data Storage

All data stored in ORACLE_DATA_DIR (default: ~/.oracle-mcp/):

~/.oracle-mcp/
├── oracle.db       # SQLite database (FTS5 + metadata)
├── chroma_data/    # ChromaDB vector embeddings
└── learnings/      # Markdown files from oracle_learn

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Run production
npm start

# Run with pm2
pm2 start ecosystem.config.cjs

Architecture

Claude Code → MCP Server → SQLite (FTS5) + ChromaDB (vectors)
                               ↓
                         oracle.db + chroma_data/

Following claude-mem patterns:

Hybrid search (FTS5 keywords + vector semantic)
Graceful degradation (works without ChromaDB)
Local embeddings via ChromaDB
SQLite as source of truth

License

MIT

Created: 2025-12-29 Architecture: claude-mem inspired

Oracle MCP