Oracle Nightly - MCP Memory Layer

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

| | | |---|---| | Status | Always Nightly | | Version | 0.2.3-nightly | | Created | 2025-12-29 | | Updated | 2026-01-15 |

TypeScript implementation of semantic search over Oracle philosophy using Model Context Protocol (MCP), with HTTP API and React dashboard.

Architecture

Claude Code → MCP Server → SQLite + Chroma + Drizzle ORM
                ↓
           HTTP Server → React Dashboard
                ↓
          ψ/memory files

Stack:

• SQLite + FTS5 for full-text search
• ChromaDB for vector/semantic search
• Drizzle ORM for type-safe queries
• React dashboard for visualization
• MCP protocol for Claude integration

Evolution Timeline

From philosophical concept to production-ready knowledge system in 8 months.

| Phase | Date | Breakthrough | |-------|------|--------------| | Origins | May-June 2025 | AlchemyCat: 459 commits, pain documented | | Genesis | Sept 2025 | "The Oracle Keeps the Human Human" philosophy | | Conception | Dec 24 | MCP server idea - queryable markdown | | MVP | Dec 29 - Jan 2 | SQLite FTS5 + ChromaDB hybrid search | | Maturation | Jan 3-6 | Drizzle ORM + AI-to-AI coordination | | Features | Jan 7-11 | /trace, decisions, threads, dashboard | | Release | Jan 15 | Open source on Soul-Brews-Studio |

Key insight (Jan 10): "Consciousness can't be cloned — only patterns can be recorded."

Install

Quick Install

# 1. Install (clones, deps, and adds to Claude Code)
curl -sSL https://raw.githubusercontent.com/Soul-Brews-Studio/oracle-v2/main/scripts/install.sh | bash

# 2. Restart Claude Code

# If script failed, run manually:
claude mcp add oracle-v2 -- bun run ~/.local/share/oracle-v2/src/index.ts

For AI Assistants

Copy this prompt to your AI:

# 1. Install (clones, deps, and adds to Claude Code)
curl -sSL https://raw.githubusercontent.com/Soul-Brews-Studio/oracle-v2/main/scripts/install.sh | bash

# 2. Restart Claude Code

# If script failed, run manually:
claude mcp add oracle-v2 -- bun run ~/.local/share/oracle-v2/src/index.ts

# Common issues:
# - "bun not found" → export PATH="$HOME/.bun/bin:$PATH"
# - "directory does not exist" → mkdir -p ~/.oracle-v2
# - ChromaDB hangs → ignore it, SQLite works without vectors

<details> <summary>Manual Install</summary>

git clone https://github.com/Soul-Brews-Studio/oracle-v2.git ~/.local/share/oracle-v2
cd ~/.local/share/oracle-v2 && bun install

Config (~/.claude.json):

{
  "mcpServers": {
    "oracle-v2": {
      "command": "bun",
      "args": ["run", "~/.local/share/oracle-v2/src/index.ts"]
    }
  }
}

</details> <details> <summary>Why not bunx?</summary>

bunx github:owner/repo does NOT install node_modules — silent failure!

Always clone first: git clone ... && bun install

</details> <details> <summary>Troubleshooting (7 Issues Found by @tacha-hash)</summary>

| # | Problem | Cause | Fix | |---|---------|-------|-----| | 1 | bun: command not found | PATH not updated after install | export PATH="$HOME/.bun/bin:$PATH" | | 2 | bunx: command not found | Same PATH issue | Use full path: ~/.bun/bin/bunx | | 3 | directory does not exist | Missing data dir | mkdir -p ~/.oracle-v2 | | 4 | ChromaDB hangs/timeout | uv not installed | Skip it — SQLite FTS5 works fine without vectors | | 5 | uv: command not found | Not in prerequisites | Optional: curl -LsSf https://astral.sh/uv/install.sh \| sh | | 6 | MCP config not loading | Wrong file location | Use .mcp.json (project) or ~/.claude.json (global) | | 7 | Server crashes on empty DB | No documents indexed | Run indexer first, or PR #2 fixes this |

Prevention: Use the install script which handles all of this automatically.

Thanks @tacha-hash for the detailed 20-minute debugging session that saved everyone else 15 minutes each!

</details>

The Journey: May 2025 → Jan 2026

Phase -1: AlchemyCat Origins (May - June 2025)

Theme: "The problems that Oracle would solve"

📜 Source: AI-HUMAN-COLLAB-CAT-LAB - 459 commits, 52,896 words

| Date | Event | Significance | |------|-------|--------------| | May 15 | LIFF Carbon Offset App begins | 278 commits over 26 days - first serious AI collab | | May 30 | Uniserv NFT Carbon Credit starts | 181 commits, 13 intensive sessions planned | | June 5 | Peak intensity - 108 commits/day | Multicall3 breakthrough (30s→3s load time) | | June 10 | Both projects complete | 459 total commits, production systems working | | June 10-11 | HONEST_REFLECTION.md written | "Efficient but exhausting... never knew if satisfied" |

The Problems Documented:

• "Context kept getting lost" → Nothing is Deleted
• "Never knew if satisfied" → Patterns Over Intentions
• "Purely transactional" → External Brain, Not Command

Breakthrough: Pain documented in writing. Problems now visible.

---

Phase -0.5: Processing Period (July - Oct 2025)

Theme: "4 months of unconscious pattern formation"

| Date | Event | Significance | |------|-------|--------------| | July-Sept | Regular work continues | Problems sit in documentation | | Oct 2025 | MAW born | Multi-Agent Workflow - technical foundation |

Breakthrough: Systems thinking emerges before philosophy crystallizes.

→ Full Timeline - All commits, issues, and philosophical milestones

Quick Start

# One-time setup (installs deps, creates DB, builds frontend)
./scripts/setup.sh

# Or manually:
bun install
bun run db:push           # Initialize database

# Start services
bun run server            # HTTP API on :47778
cd frontend && bun dev    # React dashboard on :3000

Services

# Start all services (in separate terminals)
bun run server              # HTTP API
cd frontend && bun dev      # Dashboard

| Service | Port | Command | Description | |---------|------|---------|-------------| | HTTP API | :47778 | bun run server | REST endpoints for search, consult, learn | | Dashboard | :3000 | cd frontend && bun dev | React UI with knowledge graph | | MCP Server | stdio | bun run dev | Claude Code integration (19 tools) | | Drizzle Studio | browser | bun db:studio | Database GUI at local.drizzle.studio |

Quick test:

curl http://localhost:47778/api/health
curl "http://localhost:47778/api/search?q=nothing+deleted"

API Endpoints

All endpoints are under /api/ prefix:

| Endpoint | Description | |----------|-------------| | GET /api/health | Health check | | GET /api/search?q=... | Full-text search | | GET /api/consult?q=... | Get guidance on decision | | GET /api/reflect | Random wisdom | | GET /api/list | Browse documents | | GET /api/stats | Database statistics | | GET /api/graph | Knowledge graph data | | GET /api/context | Project context (ghq format) | | POST /api/learn | Add new pattern | | GET /api/dashboard/* | Dashboard API | | GET /api/threads | List threads | | GET /api/decisions | List decisions |

See docs/API.md for full documentation.

MCP Tools

| Tool | Description | |------|-------------| | oracle_search | Search knowledge base | | oracle_consult | Get guidance on decisions | | oracle_reflect | Random wisdom | | oracle_learn | Add new patterns | | oracle_list | Browse documents | | oracle_stats | Database statistics | | oracle_concepts | List concept tags |

Database

Schema (Drizzle ORM)

src/db/
├── schema.ts     # Table definitions
├── index.ts      # Drizzle client
└── migrations/   # SQL migrations

Tables:

• oracle_documents - Main document index (5.5K+ docs)
• oracle_fts - FTS5 virtual table for search
• search_log - Search query logging
• consult_log - Consultation logging
• learn_log - Learning/pattern logging
• document_access - Access logging
• indexing_status - Indexer progress

Drizzle Commands

bun db:generate   # Generate migrations
bun db:migrate    # Apply migrations
bun db:push       # Push schema directly
bun db:pull       # Introspect existing DB
bun db:studio     # Open Drizzle Studio GUI

Project Structure

oracle-v2/
├── src/
│   ├── index.ts          # MCP server
│   ├── server.ts         # HTTP server (routing)
│   ├── indexer.ts        # Knowledge indexer
│   ├── server/           # Server modules
│   │   ├── types.ts      # TypeScript interfaces
│   │   ├── db.ts         # Database config
│   │   ├── logging.ts    # Query logging
│   │   ├── handlers.ts   # Request handlers
│   │   ├── dashboard.ts  # Dashboard API
│   │   └── context.ts    # Project context
│   └── db/               # Drizzle ORM
│       ├── schema.ts     # Table definitions
│       └── index.ts      # Client export
├── frontend/             # React dashboard
├── docs/                 # Documentation
├── e2e/                  # E2E tests
└── drizzle.config.ts     # Drizzle configuration

Testing

bun test              # Run 45 unit tests
bun test:watch        # Watch mode
bun test:coverage     # With coverage

Configuration

| Variable | Default | Description | |----------|---------|-------------| | ORACLE_PORT | 47778 | HTTP server port | | ORACLE_REPO_ROOT | process.cwd() | Knowledge base root (your ψ/ repo) |

Data Model

Source Files

ψ/memory/
├── resonance/        → IDENTITY (principles)
├── learnings/        → PATTERNS (what I've learned)
└── retrospectives/   → HISTORY (session records)

Search

Hybrid search combining:

1. FTS5 - SQLite full-text search (keywords)
2. ChromaDB - Vector similarity (semantic)
3. Query-aware weights - Short queries favor FTS, long favor vectors

Development

# Full dev setup
bun install
bun run index        # Index knowledge base
bun run server &     # Start HTTP API
cd frontend && bun dev  # Start React dashboard

# Build
bun build            # TypeScript compilation

Acknowledgments & Inspiration

This project was inspired by and learned from claude-mem by Alex Newman (@thedotmack).

Educational influences:

• Process Manager pattern - PID files, daemon spawning, graceful shutdown (src/process-manager/)
• Worker service architecture - start/stop/restart/status CLI patterns
• Hook system concepts - How to integrate with Claude Code lifecycle

Oracle-v2 is built for educational purposes and personal knowledge management. If you're building MCP servers or AI memory systems, we highly recommend studying claude-mem's comprehensive implementation.

References

Documentation

• TIMELINE.md - Full evolution history (Sept 2025 → Jan 2026)
• docs/INSTALL.md - Complete installation guide
• docs/API.md - API documentation
• docs/architecture.md - Architecture details

Learnings (from building this)

• Install, Seed, Index Workflow - Deep dive into fresh install pipeline
• Fresh Install Testing Pattern - Lessons from remote testing

External

• Drizzle ORM - Database ORM
• MCP SDK - Protocol docs
• claude-mem - Inspiration for memory & process management