jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
04ed854954
stemedb/README.md
jml 9bfa626203 docs: reorganize documentation structure for clarity 
Major documentation restructure to improve discoverability and reduce duplication.

## Changes

**Deleted (Archived/Consolidated)**:
- Removed duplicate getting started guides
- Archived outdated planning documents
- Consolidated corpus and configuration docs
- Removed obsolete vision/spec files (superseded by vision.md)
- Cleaned up scrapyard and old PDFs

**New Structure**:
- docs/about/ - Project overview and introduction
- docs/guides/ - User guides (moved from root)
- docs/specs/ - Technical specifications
- docs/sdk/ - SDK documentation (Go)
- docs/references/ - API references
- docs/archive/ - Archived historical docs
- applications/aphoria/docs/advanced/ - Advanced topics
- applications/aphoria/docs/reference/ - CLI reference
- applications/aphoria/docs/archive/ - Archived aphoria docs

**Updated**:
- README.md - New root README with clear navigation
- CONTRIBUTING.md - Contribution guidelines
- CLAUDE.md - Updated paths to new structure
- roadmap.md - Added recent completions

## Files Changed
- 57 files changed
- 1,977 insertions(+)
- 961 deletions(-)

**Net change**: +1,016 lines (added CONTRIBUTING.md, README.md, reorganized content)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-11 07:33:40 +00:00

174 lines
5.9 KiB
Markdown
Raw Blame History

# 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)**
Reference in New Issue View Git Blame Copy Permalink