From 28917c1212067f5473ca1e9bf340acea45998ca8 Mon Sep 17 00:00:00 2001 From: Robert Bartel Date: Sat, 14 Feb 2026 16:06:32 +0000 Subject: [PATCH 1/2] Document SEDIMENT_DB and SEDIMENT_EMBEDDING_MODEL env vars Add environment variables section to CLI help (after_long_help) and populate the MCP instructions field so LLMs are aware of SEDIMENT_DB for ephemeral/isolated storage and the CLI interface. --- src/main.rs | 10 +++++++++- src/mcp/protocol.rs | 2 ++ src/mcp/server.rs | 14 ++++++++++++++ 3 files changed, 25 insertions(+), 1 deletion(-) diff --git a/src/main.rs b/src/main.rs index 69d29bb..4259e85 100644 --- a/src/main.rs +++ b/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, diff --git a/src/mcp/protocol.rs b/src/mcp/protocol.rs index fa20911..1e603ff 100644 --- a/src/mcp/protocol.rs +++ b/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, } /// Tool definition diff --git a/src/mcp/server.rs b/src/mcp/server.rs index bb137e9..d1e368b 100644 --- a/src/mcp/server.rs +++ b/src/mcp/server.rs @@ -231,6 +231,19 @@ fn handle_request(rt: &Runtime, ctx: &ServerContext, line: &str) -> Option) -> 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) -> Response { name: "sediment".to_string(), version: env!("CARGO_PKG_VERSION").to_string(), }, + instructions: Some(instructions), }; // InitializeResult is a simple struct; serialization is infallible. From be11e36d62b3ae96fe77b68ebb3e32a86374f4a7 Mon Sep 17 00:00:00 2001 From: Robert Bartel Date: Sat, 14 Feb 2026 16:10:17 +0000 Subject: [PATCH 2/2] Add env var docs to CLAUDE.md and README --- CLAUDE.md | 9 +++++++++ README.md | 16 ++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 6c6503c..d22fe7b 100644 --- a/CLAUDE.md +++ b/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 diff --git a/README.md b/README.md index 4f2d710..36e20d0 100644 --- a/README.md +++ b/README.md @@ -154,6 +154,22 @@ sediment forget # 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