Document SEDIMENT_DB and SEDIMENT_EMBEDDING_MODEL env vars

CLAUDE.md

@@ -72,6 +72,15 @@ Sediment is a semantic memory system for AI agents, running as an MCP (Model Con
 4. **Consolidation** (background): Queue candidates → >=0.95 similarity: merge (delete old, transfer edges, SUPERSEDES edge) → 0.85-0.95: link (RELATED edge)
 5. **Clustering** (periodic): Triangle detection in graph → CLUSTER_SIBLING edges
 
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SEDIMENT_DB` | `~/.sediment/data` | Override database path. Also available as `--db` CLI flag. Useful for ephemeral/isolated storage: `SEDIMENT_DB=/tmp/task sediment store "..."` |
+| `SEDIMENT_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Override embedding model. Options: `all-MiniLM-L6-v2`, `bge-small-en-v1.5` |
+
+Priority: `--db` flag > `SEDIMENT_DB` env var > default `~/.sediment/data`.
+
 ### Key Design Decisions
 
 - **Two-database hybrid**: LanceDB for vectors, SQLite for graph relationships + mutable counters

README.md

@@ -154,6 +154,22 @@ sediment forget <id>              # Delete an item by ID
 
 All commands support `--json` for machine-readable output.
 
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SEDIMENT_DB` | `~/.sediment/data` | Override database path. Useful for ephemeral or isolated storage. |
+| `SEDIMENT_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Override embedding model (`all-MiniLM-L6-v2`, `bge-small-en-v1.5`). |
+
+Example — use a throwaway database for a task:
+
+```bash
+SEDIMENT_DB=/tmp/task-xyz sediment store "temporary context"
+SEDIMENT_DB=/tmp/task-xyz sediment recall "context"
+```
+
+The `--db` CLI flag takes the same value and overrides the env var if both are set.
+
 ## How It Works
 
 ### Two-Database Hybrid

src/main.rs

@@ -15,8 +15,16 @@ use tracing_subscriber::{EnvFilter, fmt};
 #[command(name = "sediment")]
 #[command(about = "Semantic memory for AI agents - local-first, MCP-native")]
 #[command(version)]
+#[command(after_long_help = "\
+Environment variables:
+  SEDIMENT_DB              Override database path (default: ~/.sediment/data).
+                           Useful for ephemeral/isolated storage:
+                             SEDIMENT_DB=/tmp/task-xyz sediment store \"...\"
+  SEDIMENT_EMBEDDING_MODEL Override embedding model (default: all-MiniLM-L6-v2).
+                           Options: all-MiniLM-L6-v2, bge-small-en-v1.5
+")]
 struct Cli {
-    /// Database path (defaults to ~/.sediment/data)
+    /// Database path [default: ~/.sediment/data]
     #[arg(long, global = true, env = "SEDIMENT_DB")]
     db: Option<PathBuf>,
 

src/mcp/protocol.rs

@@ -96,6 +96,8 @@ pub struct InitializeResult {
     pub protocol_version: String,
     pub capabilities: ServerCapabilities,
     pub server_info: ServerInfo,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub instructions: Option<String>,
 }
 
 /// Tool definition

src/mcp/server.rs

@@ -231,6 +231,19 @@ fn handle_request(rt: &Runtime, ctx: &ServerContext, line: &str) -> Option<Respo
 
 /// Handle initialize request
 fn handle_initialize(id: Option<Value>) -> Response {
+    let instructions = "\
+Sediment is a local-first semantic memory system. All data stays on disk — no API keys required.
+
+Environment variables (set before starting the server or CLI):
+- SEDIMENT_DB: Override database path (default: ~/.sediment/data). \
+Useful for ephemeral or isolated storage, e.g. SEDIMENT_DB=/tmp/task-xyz sediment store \"...\".
+- SEDIMENT_EMBEDDING_MODEL: Override embedding model (default: all-MiniLM-L6-v2). \
+Options: all-MiniLM-L6-v2, bge-small-en-v1.5.
+
+Sediment is also available as a CLI: sediment store, sediment recall, sediment list, sediment forget. \
+Run `sediment --help` for details."
+        .to_string();
+
     let result = InitializeResult {
         protocol_version: MCP_VERSION.to_string(),
         capabilities: ServerCapabilities {
@@ -242,6 +255,7 @@ fn handle_initialize(id: Option<Value>) -> Response {
             name: "sediment".to_string(),
             version: env!("CARGO_PKG_VERSION").to_string(),
         },
+        instructions: Some(instructions),
     };
 
     // InitializeResult is a simple struct; serialization is infallible.