stemedb/quickstart.md

Quick Start

Get StemeDB running and validated in under 5 minutes.

Prerequisites

• Rust 1.75+ (rustup update stable)
• curl (for validation)

1. Validate It Works

# Clone and enter
git clone <repo-url>
cd stemedb

# Run end-to-end validation (builds, starts server, asserts, queries, shuts down)
make validate

Expected output:

==========================================
  StemeDB Validation
==========================================

[PASS] Build complete
[PASS] Server is healthy
[PASS] Health check passed
[PASS] Assertion created: abc123...
[PASS] Query returned correct data
[PASS] Lens query (Recency) works

==========================================
  All validation checks passed!
==========================================

If you see "All validation checks passed!" - StemeDB is working correctly.

2. Start the Server

cargo run --package stemedb-api

The server starts on http://localhost:3000.

3. Explore the API

Open the Swagger UI for interactive documentation:

http://localhost:3000/swagger-ui

Or check health via curl:

curl http://localhost:3000/v1/health
# {"status":"healthy","version":"0.1.0","assertions_count":0}

4. Create Your First Assertion

Using the Go SDK (recommended):

cd sdk/go/examples/basic
go run main.go

Or via curl (requires generating Ed25519 signatures):

# Generate a signed assertion
cargo run --package stemedb-api --example gen_test_assertion > /tmp/assertion.json

# Submit it
curl -X POST http://localhost:3000/v1/assert \
  -H "Content-Type: application/json" \
  -d @/tmp/assertion.json

5. Query It Back

# Query by subject and predicate
curl "http://localhost:3000/v1/query?subject=StemeDB_Validation&predicate=test_status"

# Query with a lens (conflict resolution)
curl "http://localhost:3000/v1/query?subject=StemeDB_Validation&predicate=test_status&lens=Recency"

6. See Conflict in Action (The "Git for Truth" Moment)

Episteme stores Claims, not Facts. When multiple agents assert conflicting values, the Skeptic endpoint shows you all competing claims instead of picking a winner.

Create Conflicting Assertions

Using the Go SDK, create assertions with different claims about the same subject:

cd sdk/go/examples/conflict
go run main.go

Query with Skeptic

The Skeptic endpoint reveals disagreement instead of hiding it:

curl "http://localhost:3000/v1/skeptic?subject=GLP1_Agonists&predicate=cardiovascular_benefit"

Response shows all competing claims:

{
  "status": "Contested",
  "conflict_score": 0.72,
  "claims": [
    {"value": {"type": "Boolean", "value": true}, "weight_share": 0.48, "assertion_count": 1},
    {"value": {"type": "Boolean", "value": false}, "weight_share": 0.52, "assertion_count": 1}
  ],
  "candidates_count": 2
}

Key insight: Instead of silently picking a winner, you see the disagreement. This is critical for health/finance domains where hiding conflict is dangerous.

7. Authority Tiers (Source-Class Resolution)

Different sources have different authority. A regulatory filing (FDA) outweighs an anecdotal tweet. The Layered endpoint shows per-tier consensus.

Query with Layered Consensus

The conflict example creates assertions with different source_class values (Clinical vs Anecdotal). The Layered endpoint shows how each tier resolves independently:

curl "http://localhost:3000/v1/layered?subject=GLP1_Agonists&predicate=cardiovascular_benefit"

Response shows tier-by-tier resolution:

{
  "tiers": [
    {"tier": 1, "source_class": "Clinical", "winner": {"object": {"type": "Boolean", "value": true}}, "conflict_score": 0.0},
    {"tier": 5, "source_class": "Anecdotal", "winner": {"object": {"type": "Boolean", "value": false}}, "conflict_score": 0.0}
  ],
  "overall_winner": {"object": {"type": "Boolean", "value": true}},
  "overall_conflict_score": 0.85
}

Key insight: Clinical tier (peer-reviewed research) wins despite Anecdotal tier (social media) disagreeing. The overall_conflict_score tells you the tiers disagree.

What's Next?

Goal	Resource
Understand the vision	vision.md
See real use cases	use-cases/README.md
Use the Go SDK	sdk/go/steme/README.md
Build AI agents	sdk/go/adk/README.md
Understand architecture	architecture.md
API reference	crates/stemedb-api/README.md

Common Issues

Build fails

rustup update stable
cargo clean
cargo build --workspace

Server won't start (port in use)

# Use a different port
STEMEDB_BIND_ADDR=127.0.0.1:3001 cargo run --package stemedb-api

Validation script fails

Check the server log in the temp directory:

cat tmp/validate-*/server.log

Query returns empty results

The ingestion worker runs asynchronously. If you're writing directly to the WAL (not via API), wait ~500ms before querying.

Environment Variables

Variable	Default	Description
STEMEDB_BIND_ADDR	127.0.0.1:3000	HTTP server address
STEMEDB_WAL_DIR	data/wal	Write-ahead log directory
STEMEDB_DB_DIR	data/db	KV store directory