# 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
```bash
# Via Claude Code CLI
claude plugin add laris-co/oracle-mcp
```
### Manual Setup
```bash
# 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`:
```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.
```json
{
"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.
```json
{
"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.
```json
{
"pattern": "Always verify before destructive operations",
"source": "Retrospective 2025-01-15",
"concepts": ["safety", "verification"]
}
```
### oracle_list
Browse documents without search (pagination supported).
```json
{
"type": "learning",
"limit": 10,
"offset": 0
}
```
### oracle_reflect
Get random wisdom for reflection.
```json
{}
```
## 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
```bash
# 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](https://github.com/thedotmack/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
