diff --git a/agentfs/quickstart.mdx b/agentfs/quickstart.mdx
index 666c9cb..e2ce2d4 100644
--- a/agentfs/quickstart.mdx
+++ b/agentfs/quickstart.mdx
@@ -38,10 +38,9 @@ Let's build a simple agent that maintains conversation history and generates fil
     ```typescript
     import { AgentFS } from 'agentfs-sdk';
 
-    // Initialize AgentFS with a local database
-    const agent = await AgentFS.open(
-      './my-agent.db'
-    );
+    // Initialize AgentFS with persistent storage
+    const agent = await AgentFS.open({ id: 'my-agent' });
+    // Creates: .agentfs/my-agent.db
 
     // Store agent configuration
     await agent.kv.set('agent:id', 'assistant-001');
@@ -103,7 +102,7 @@ Let's build a simple agent that maintains conversation history and generates fil
   </Tab>
   <Tab title="Rust">
     ```rust
-    use agentfs::AgentFS;
+    use agentfs::{AgentFS, AgentFSOptions};
     use serde::{Serialize, Deserialize};
     use chrono::Utc;
 
@@ -117,10 +116,11 @@ Let's build a simple agent that maintains conversation history and generates fil
     #[tokio::main]
     async fn main() -> Result<(),
       Box<dyn std::error::Error>> {
-        // Initialize AgentFS with a local database
+        // Initialize AgentFS with persistent storage
         let agent = AgentFS::open(
-          "./my-agent.db"
+          AgentFSOptions::with_id("my-agent")
         ).await?;
+        // Creates: .agentfs/my-agent.db
 
         // Store agent configuration
         agent.kv.set("agent:id", "assistant-001").await?;
diff --git a/agentfs/sdk/rust.mdx b/agentfs/sdk/rust.mdx
index ab78053..5eeed4f 100644
--- a/agentfs/sdk/rust.mdx
+++ b/agentfs/sdk/rust.mdx
@@ -21,13 +21,17 @@ serde_json = "1"
 ## Quick Start
 
 ```rust
-use agentfs::AgentFS;
+use agentfs::{AgentFS, AgentFSOptions};
 use anyhow::Result;
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    // Open or create an agent filesystem
-    let agent = AgentFS::open("./agent.db").await?;
+    // Persistent storage with identifier
+    let agent = AgentFS::open(AgentFSOptions::with_id("my-agent")).await?;
+    // Creates: .agentfs/my-agent.db
+
+    // Or use ephemeral in-memory database
+    let ephemeral = AgentFS::open(AgentFSOptions::ephemeral()).await?;
 
     // Use the three main APIs
     agent.kv.set("key", "value").await?;              // Key-value store
@@ -44,24 +48,38 @@ async fn main() -> Result<()> {
 
 The main entry point for all AgentFS operations.
 
-#### `AgentFS::open(path: impl AsRef<Path>)`
+#### `AgentFS::open(options: AgentFSOptions)`
 
 Creates or opens an AgentFS database.
 
 ```rust
 use agentfs::{AgentFS, AgentFSOptions};
 
-// Simple open
-let agent = AgentFS::open("./my-agent.db").await?;
-
-// With options
-let agent = AgentFS::open_with_options(
-    "./agent.db",
-    AgentFSOptions {
-        readonly: false,
-        create_if_missing: true,
-    }
-).await?;
+// Persistent storage with identifier
+let agent = AgentFS::open(AgentFSOptions::with_id("my-agent")).await?;
+// Creates: .agentfs/my-agent.db
+
+// Ephemeral in-memory database
+let ephemeral = AgentFS::open(AgentFSOptions::ephemeral()).await?;
+```
+
+**AgentFSOptions Configuration:**
+
+```rust
+pub struct AgentFSOptions {
+    /// Optional unique identifier for the agent.
+    /// - If Some(id): Creates persistent storage at `.agentfs/{id}.db`
+    /// - If None: Uses ephemeral in-memory database
+    pub id: Option<String>,
+}
+
+impl AgentFSOptions {
+    /// Create options for a persistent agent with the given ID
+    pub fn with_id(id: impl Into<String>) -> Self;
+
+    /// Create options for an ephemeral in-memory agent
+    pub fn ephemeral() -> Self;
+}
 ```
 
 #### Fields
diff --git a/agentfs/sdk/typescript.mdx b/agentfs/sdk/typescript.mdx
index adbbb75..7f8c9f5 100644
--- a/agentfs/sdk/typescript.mdx
+++ b/agentfs/sdk/typescript.mdx
@@ -17,8 +17,12 @@ bun add agentfs-sdk
 ```typescript
 import { AgentFS } from 'agentfs-sdk';
 
-// Open or create an agent filesystem
-const agent = await AgentFS.open('./agent.db');
+// Persistent storage with identifier
+const agent = await AgentFS.open({ id: 'my-agent' });
+// Creates: .agentfs/my-agent.db
+
+// Or use ephemeral in-memory database
+const ephemeralAgent = await AgentFS.open();
 
 // Use the three main APIs
 // Key-value store
@@ -35,21 +39,26 @@ await agent.tools.record(...);
 
 The main entry point for all AgentFS operations.
 
-#### `AgentFS.open(path: string, options?: AgentFSOptions)`
+#### `AgentFS.open(options?: AgentFSOptions)`
 
 Creates or opens an AgentFS database.
 
 ```typescript
 interface AgentFSOptions {
-  // Optional configuration
-  readonly?: boolean;  // Open in read-only mode
+  /**
+   * Optional unique identifier for the agent.
+   * - If provided: Creates persistent storage at `.agentfs/{id}.db`
+   * - If omitted: Uses ephemeral in-memory database
+   */
+  id?: string;
 }
 
-const agent = await AgentFS.open('./my-agent.db');
-const readOnlyAgent = await AgentFS.open(
-  './agent.db',
-  { readonly: true }
-);
+// Persistent storage
+const agent = await AgentFS.open({ id: 'my-agent' });
+// Creates: .agentfs/my-agent.db
+
+// Ephemeral in-memory database
+const ephemeralAgent = await AgentFS.open();
 ```
 
 #### Properties
@@ -354,7 +363,7 @@ AgentFS works in browser environments using WebAssembly:
   <script type="module">
     import { AgentFS } from 'https://unpkg.com/agentfs-sdk/dist/browser.js';
 
-    const agent = await AgentFS.open('browser-agent.db');
+    const agent = await AgentFS.open({ id: 'browser-agent' });
 
     // All APIs work the same in browser
     await agent.kv.set('browser:data', { platform: 'web' });