# 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