simple_oracle

Overview

simple_oracle is a persistent memory and development intelligence platform for AI-assisted software development. It solves the fundamental problem of AI context limits by providing Claude (or any AI assistant) with a durable external memory that survives across sessions.

Core insight: When Claude's context window compresses, the oracle remembers everything. Run oracle-cli boot at session start and you're back to full context instantly.

Part of the simple_* ecosystem of focused, single-purpose Eiffel libraries. Built with Design by Contract principles and SCOOP compatibility.

Quick Start

Boot Sequence (Every Session)

oracle-cli boot

This single command:

Injects Eiffel expertise (SCOOP, DBC, void safety, patterns)
Shows last session's handoff (what you were working on)
Provides current ecosystem context (libraries, recent activity)
Reports any problems (failing tests, build issues)

Common Commands

# Query the knowledge base
oracle-cli query "what libraries use inline C?"
oracle-cli query "show failing tests"

# Compile and test
oracle-cli compile simple_json
oracle-cli test simple_json

# Track git activity
oracle-cli git simple_json 10
oracle-cli commits

# End of session
oracle-cli handoff "task" "wip" "next" "blockers"

Commands Reference

Session Management

Command	Description
`boot`	Full boot sequence - expertise + context injection
`handoff`	Record/view session handoff for context continuity
`check`	Show guidance (when told "see oracle")

Knowledge Base

Command	Description
`query <question>`	Natural language search of knowledge base
`learn <cat> <title> <content>`	Add knowledge entry (pattern, rule, gotcha, decision)
`ingest [path]`	Ingest docs from directory into knowledge base

Development Tracking

Command	Description
`compile <lib>`	Run ec.exe and log result
`compiles`	Show recent compile history
`test <lib>`	Run tests and log result
`tests`	Show recent test history

Git Integration

Command	Description
`git <lib> [count]`	Scan and log commits to oracle
`commits`	Show recent commits across all libraries

Ecosystem

Command	Description
`status`	Ecosystem health check
`stats [period]`	Metrics for period (today, week, month, all)
`scan`	Rescan filesystem for libraries

Features

Persistent Memory

SQLite database survives sessions. Never lose context again.

Knowledge Base

FTS5 full-text search. Store patterns, rules, gotchas, decisions.

Session Handoffs

Record what you're working on. Resume seamlessly next session.

Compile/Test Tracking

Log all builds and test runs. Track success/failure patterns.

Git Integration

Scan and store commit history. Track changes across libraries.

Ecosystem Scanner

Discover libraries, classes, features. Extract DBC contracts.

Why simple_oracle?

AI assistants have limited context windows. After extended sessions, context compresses and loses important state. simple_oracle provides the persistent memory needed for effective long-term collaboration.

Instant Context - boot command restores full awareness
Searchable Knowledge - FTS5 for natural language queries
Activity Tracking - Compiles, tests, git history logged automatically
Session Handoffs - Explicit continuity between sessions

API Overview

make

Initialize oracle with default database location.

full_boot: STRING_32

Complete boot sequence with expertise injection + context brief.

query (a_question: STRING_32): STRING_32

Natural language search of knowledge base using FTS5.

Contracts

require: not a_question.is_empty

ensure: Result /= Void

log_compile (a_library, a_target: STRING_32; a_success: BOOLEAN; a_duration: REAL_64)

Record compilation result to history.

record_handoff (a_task, a_wip, a_next, a_blockers: detachable STRING_32)

Record session handoff for context continuity.

Claude Code Integration

Auto-boot Hook

Add to .claude/hooks/session-start.ps1:

$ORACLE_CLI = "D:\prod\simple_oracle\oracle-cli.exe"
if (Test-Path $ORACLE_CLI) {
    $BOOT_OUTPUT = & $ORACLE_CLI boot 2>&1
    Write-Output "=== ORACLE AUTO-BOOT ==="
    Write-Output $BOOT_OUTPUT
    Write-Output "=== END ORACLE BOOT ==="
}
exit 0

CLAUDE.md Integration

Add to your project's CLAUDE.md file:

## ORACLE BOOT SEQUENCE

**On every new session, run:**
oracle-cli boot

**When Larry says "consult oracle", run:**
oracle-cli check