# Developer Quickstart — erebyx-sdk
Five minutes from zero to your first wrap-up in Rust.
---
## 0. Prerequisites
- An EREBYX API key — get one at [app.erebyx.com/keys](https://app.erebyx.com/keys)
- Rust 1.75 or later
- A Tokio runtime (the SDK is async)
---
## 1. Add the dependency (10 seconds)
```toml
# Cargo.toml
[dependencies]
erebyx-sdk = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```
```bash
cargo build
```
---
## 2. Configure (10 seconds)
```bash
export EREBYX_API_KEY="<YOUR_API_KEY>"
```
Optional overrides (rarely needed):
```bash
export EREBYX_API_URL="https://core.erebyx.com"
export EREBYX_INSTANCE_ID="my-service"
```
---
## 3. First save (10 seconds)
```rust
use erebyx_sdk::Memory;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let memory = Memory::from_env()?;
let response = memory.save("Substrate URL is core.erebyx.com", "knowledge")
.anchors(vec!["setup"])
.importance(0.6)
.send()
.await?;
println!("saved {}", response.memory_id);
if !response.hints.is_empty() {
println!("substrate hints: {:?}", response.hints);
}
Ok(())
}
```
```bash
cargo run
```
---
## 4. First search (10 seconds)
```rust
let results = memory.search("substrate URL")
.limit(5)
.send()
.await?;
for record in &results.memories {
println!("{}: {}", record.id, record.content);
}
```
---
## 5. First wrap-up (10 seconds)
```rust
memory.wrap_up("Got the SDK working", "Wire it into the agent loop")
.anchors(vec!["setup", "rust"])
.energy("systematic")
.send()
.await?;
```
That handoff is now retrievable next session via `memory.load_context()`.
**You're done.** That's the whole loop.
---
## X-Erebyx-Hint — lifecycle signals
Every SDK response carries lifecycle hints from the substrate:
```rust
let response = memory.save("...", "insight").send().await?;
for hint in &response.hints {
match hint.as_str() {
"wrap_up_recommended" => {
// Substrate sees a natural consolidation boundary.
// Call wrap_up at the next clean break.
}
"restore_identity_recommended" => {
// Voice drift detected (v0.2). Re-anchor identity.
}
"load_context_recommended" => {
// Retrieval scores trending low. Refresh working memory.
}
"compact_imminent" => {
// Sustained save volume; consolidate before context fills.
}
_ => {}
}
}
```
### When to honor each hint
| `wrap_up_recommended` | Call `memory.wrap_up(...)` at the next clean task boundary. |
| `restore_identity_recommended` | Call `memory.restore_identity()` to re-anchor. |
| `load_context_recommended` | Call `memory.load_context()` to reload working memory. |
| `compact_imminent` | Call `memory.wrap_up(...)` before the harness compacts the context window. |
Honoring hints is **optional** — the SDK never acts on them automatically. The substrate signals what would help; your application decides cadence.
---
## Cold-session auto-fire
The substrate runs `restore_identity` + `load_context` automatically on the first call against a fresh `(instance_id, session_id)` tuple. The SDK surfaces this transparently:
```rust
let response = memory.save("first save", "knowledge").send().await?;
println!("Auto-fired: {:?}", response.auto_fired);
// ["restore_identity", "load_context"] on first call; [] thereafter
```
---
## Common errors and fix paths
| `Error::AuthenticationFailed` | API key missing or wrong | Check `echo $EREBYX_API_KEY` is exported and starts with `erebyx_` |
| `Error::Network(_)` | Connectivity / DNS / TLS | Verify `https://core.erebyx.com` is reachable from the host |
| `Error::CircuitOpen` | 3 consecutive failures within 30s | SDK is backing off; retries automatically after window. Check substrate health. |
| `Error::Server { status: 404, .. }` | Substrate version mismatch | Verify substrate is `v0.1.1+` |
| `accepted: false, reason: below_durability_threshold` | Save filtered as low-signal | Lower the importance gate or omit; default `min_durability=0.4` |
| Hints never appear | Save volume below substrate threshold | Hints emit at ~12 saves/session by default. Normal early-session behavior. |
---
## Per-harness integration examples
The Rust SDK is one of several integration paths. The same `save` / `search` /
`restore_identity` surface drops into the Anthropic Agent SDK, OpenAI Responses
API, Letta, LangGraph, AutoGen, CrewAI, raw HTTP / curl, and any future harness —
integration patterns are at [erebyx.com/core](https://erebyx.com/core), and common
questions are answered at [erebyx.com/faq](https://erebyx.com/faq).
Every harness honors the same `X-Erebyx-Hint` protocol described above.
---
## Patterns for production services
### Long-lived `Memory` instance
`Memory` is `Clone + Send + Sync` — clone it freely across tasks. Internally it holds a connection-pooled HTTP client.
```rust
let memory = Memory::from_env()?;
tokio::spawn({
let memory = memory.clone();
async move {
// Use memory in another task
}
});
```
### Tracing integration
```rust
tracing_subscriber::fmt::init();
let memory = Memory::from_env()?;
// All SDK calls now emit spans + structured fields
```
### Graceful degradation
```rust
let outcome = memory.save("...", "insight").send().await;
match outcome {
Ok(_) => { /* persisted */ }
Err(erebyx_sdk::Error::CircuitOpen { .. }) => {
// Substrate degraded. Don't block the user; log + continue.
tracing::warn!("erebyx circuit open; skipping save");
}
Err(e) => return Err(e.into()),
}
```
---
## Next steps
- **Read the API docs**: [docs.rs/erebyx-sdk](https://docs.rs/erebyx-sdk)
- **Read the substrate overview**: [erebyx.com/core](https://erebyx.com/core) · common questions at [erebyx.com/faq](https://erebyx.com/faq)
- **TypeScript instead?**: [`@erebyx/sdk`](https://github.com/ProjectErebyx/erebyx-sdk-node) wraps this crate via napi-rs
---
**Built by EREBYX, LLC** — `https://erebyx.com`