a776744889
- Rust workspace with stemedb-core crate - Full .claude/ configuration (agents, skills, commands, guides) - ai-lookup/ for token-efficient fact storage - Quality gates: clippy, fmt, jscpd duplication detection - Pre-commit hook with 5-phase quality checks - CLAUDE.md router and CODING_GUIDELINES.md standards Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# Episteme (StemeDB)
|
|
|
|
A probabilistic knowledge graph database that stores Claims, not Facts. Append-only Merkle DAG with read-time resolution via Lenses.
|
|
|
|
**Core Concept:** "Git for Truth" - conflicting assertions coexist, resolved at query time through Consensus, Recency, Authority, or custom Lenses.
|
|
|
|
## Find Your Guide
|
|
|
|
| If you need to... | Read this |
|
|
|-------------------|-----------|
|
|
| **Understand the vision** | [vision.md](./vision.md) |
|
|
| **Understand architecture** | [architecture.md](./architecture.md) |
|
|
| **See the roadmap** | [roadmap.md](./roadmap.md) |
|
|
| **Write Rust code** | [.claude/guides/backend/rust-guidelines.md](.claude/guides/backend/rust-guidelines.md) |
|
|
| **Set up local dev** | [.claude/guides/local/setup.md](.claude/guides/local/setup.md) |
|
|
| **Run tests** | [.claude/guides/local/testing.md](.claude/guides/local/testing.md) |
|
|
| **Work on storage/DAG** | Load skill: `stemedb-core` |
|
|
| **Implement a Lens** | Load skill: `stemedb-lens` |
|
|
| **Plan a milestone** | `/plan-milestone` command |
|
|
|
|
## Critical Rules
|
|
|
|
- **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.
|
|
- **Zero-Copy:** Use `rkyv` for serialization.
|
|
|
|
## Quick Reference
|
|
|
|
```bash
|
|
# Build
|
|
cargo build --workspace
|
|
|
|
# Test
|
|
cargo test --workspace
|
|
|
|
# Lint (must pass before commit)
|
|
cargo clippy --workspace -- -D warnings
|
|
cargo fmt --check
|
|
```
|
|
|
|
## Specialized Agents
|
|
|
|
| Domain | Agent | When to use |
|
|
|--------|-------|-------------|
|
|
| General Rust | `primary-developer` | Feature implementation, refactoring |
|
|
| Code Quality | `rust-quality-engineer` | Reviews, test coverage, clippy |
|
|
| Storage | `storage-engine-architect` | WAL, LSM, crash recovery |
|
|
| Graph Engine | `rust-graph-engine-architect` | Lock-free structures, cache optimization |
|
|
| Defensive | `defensive-systems-architect` | Rate limiting, circuit breakers, hostile input |
|
|
| Lenses | `stemedb-lens-architect` | Query resolution, ranking algorithms |
|
|
| Planning | `stemedb-planner` | Milestone planning, roadmap |
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
Write Path (Spine): Read Path (Cortex):
|
|
[Agent] -> [Ingestion] [Agent] <- [Lens Engine]
|
|
| |
|
|
v |
|
|
[WAL/Fsync] [Index Lookup]
|
|
| |
|
|
v |
|
|
[KV Store] <--------------------+
|
|
```
|
|
|
|
## Crates
|
|
|
|
| Crate | Purpose |
|
|
|-------|---------|
|
|
| `stemedb-core` | Assertion struct, types, storage traits |
|
|
| `stemedb-wal` | Write-ahead log (planned) |
|
|
| `stemedb-index` | Subject/Predicate indexing (planned) |
|
|
| `stemedb-lens` | Lens trait and implementations (planned) |
|