# Episteme (StemeDB)

**A probabilistic knowledge graph database that stores Claims, not Facts.**

Append-only Merkle DAG with read-time resolution via Lenses. Think of it as "Git for Truth" - conflicting assertions coexist, resolved at query time through Consensus, Recency, Authority, or custom Lenses.

---

## Quick Start

```bash
# Get running in under 5 minutes
make validate

# Start the server
cargo run --package stemedb-api

# Open API docs
open http://localhost:18180/swagger-ui
```

**[→ Full Quick Start Guide](./quickstart.md)**

---

## Understanding Episteme

- **[What is Episteme?](./what-is-episteme.md)** - Concept overview and real-world examples
- **[Vision](./vision.md)** - Product philosophy and "Git for Truth" principles
- **[Architecture](./architecture.md)** - Technical design and data structures
- **[Use Cases](./use-cases/README.md)** - Consumer health, financial due diligence, AI agents

---

## Documentation

- **[📚 Full Documentation Index](./docs/README.md)** - Complete documentation hub
- **[App Development Guide](./docs/app-concepts/index.md)** - Build applications on Episteme
- **[Go SDK](./docs/sdk/go-sdk.md)** - Client library and examples
- **[ADK-Go Integration](./docs/references/go-adk/reference-guide.md)** - AI agent integration
- **[RFCs & Specs](./docs/rfcs/README.md)** - Technical specifications

---

## For Developers

### Getting Started
- **[Development Setup](./.claude/guides/local/setup.md)** - Local environment setup
- **[Testing Guide](./.claude/guides/local/testing.md)** - Running tests
- **[Coding Guidelines](./.claude/guides/coding-guidelines.md)** - Rust standards and patterns
- **[Quality Checks](./.claude/guides/local/quality-checks.md)** - Pre-commit hooks and CI

### Project Management
- **[Roadmap](./roadmap.md)** - Current and planned work
- **[Roadmap Archive](./roadmap-archive.md)** - Completed phases
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute

### Architecture Deep Dives
- **[Data Structures](./docs/data-structures.md)** - Core types and design
- **[Consistency Model](./docs/consistency-model.md)** - Conflict resolution
- **[Distributed Architecture](./docs/research/distributed-write-path.md)** - Clustering and sharding
- **[Storage Engine](./docs/research/wal-crash-recovery-research.md)** - WAL and recovery

---

## Applications

Episteme powers multiple applications:

- **[Aphoria](./applications/aphoria/README.md)** - Code-level truth linter and continuous learning system
- **[Admin Dashboard](./applications/stemedb-dashboard/)** - Web UI for cluster management
- **[Disputed](./applications/disputed/)** - Claim disagreement visualization

---

## For AI Agents

- **[CLAUDE.md](./CLAUDE.md)** - Claude Code agent instructions
- **[GEMINI.md](./GEMINI.md)** - Gemini CLI agent instructions

---

## Core Principles

**ZERO TOLERANCE FOR MEDIOCRITY:** We build enterprise-grade products that must survive in production. Panics are UNACCEPTABLE. Broken pipe errors are UNACCEPTABLE. Sloppy testing is UNACCEPTABLE. Every line of code ships to paying customers who depend on it. Test everything. Handle every error. No shortcuts. No excuses.

### Technical Principles

- **Append-Only**: NEVER mutate existing Assertions. Create new ones.
- **Content-Addressed**: Assertion ID = BLAKE3 hash of content
- **No Unwrap**: NEVER use `unwrap()` or `expect()` in production code
- **Defensive Writes**: All writes go through WAL with fsync
- **Structured Logging**: Use `tracing` (info!, warn!, error!)

**[→ Full Coding Guidelines](./.claude/guides/coding-guidelines.md)**

---

## Port Scheme (181XX)

| Service | Port | Env Var |
|---------|------|---------|
| HTTP API | 18180 | `STEMEDB_BIND_ADDR` |
| Cluster Gateway | 18181 | `STEMEDB_NODE_API_ADDR` |
| Cluster RPC | 18182 | `STEMEDB_NODE_RPC_ADDR` |
| SWIM Gossip | 18183 | via `SwimConfig` |
| StemeDB Dashboard | 18188 | - |
| Aphoria Dashboard | 18189 | - |

---

## Quick Reference

```bash
# Build
cargo build --workspace

# Test
cargo test --workspace --lib      # Unit tests (~3min)
cargo nextest run                 # Parallel runner (~5min)

# Lint (must pass before commit)
cargo clippy --workspace -- -D warnings
cargo fmt --check

# Run server
cargo run --package stemedb-api

# Run cluster node
cargo run --package stemedb-cluster --bin stemedb-node
```

---

## Community & Support

- **Issues**: [GitHub Issues](https://github.com/orchard9/stemedb/issues)
- **Discussions**: [GitHub Discussions](https://github.com/orchard9/stemedb/discussions)
- **License**: See LICENSE file

---

## What Makes Episteme Different?

Traditional databases force you to pick "the right answer." Episteme holds all the answers, tracks who said them and why, and lets you decide how to resolve disagreements at query time.

| Traditional DB | Episteme |
|----------------|----------|
| One canonical truth | Multiple competing claims |
| Update overwrites | Append-only history |
| Consensus enforced at write | Resolution deferred to read |
| Time-travel via backups | Built-in temporal queries |
| Source tracking via app logic | First-class provenance |

**When a Reddit community reports gastroparesis months before the FDA adds a warning label, both claims coexist in Episteme. You can query by authority tier (FDA wins), by recency (Reddit was first), or by consensus (see the disagreement).**

**This is critical for domains where truth is contested, evolving, or depends on perspective: health, finance, research, intelligence.**

---

## Getting Help

| Question | Resource |
|----------|----------|
| How do I... | [Documentation Index](./docs/README.md) |
| Why did you... | [Architecture](./architecture.md) + [Vision](./vision.md) |
| Can I use this for... | [Use Cases](./use-cases/README.md) |
| It's not working... | [GitHub Issues](https://github.com/orchard9/stemedb/issues) |
| I want to contribute... | [Contributing Guide](./CONTRIBUTING.md) |

---

**[Get Started →](./quickstart.md)**