SMFS

https://github.com/supermemoryai/smfs
Admin
SMFS is a Supermemory container exposed as a filesystem, enabling you to read, write, and search...
Tokens:14,887
Snippets:97
Trust Score:9.2
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install @supermemory/bash

Source: https://github.com/supermemoryai/smfs/blob/main/bash/README.md

Install the package using npm or bun. Ensure you have a Supermemory API key.

```bash
npm install @supermemory/bash
# or
bun add @supermemory/bash
```

--------------------------------

### Install supermemory-bash

Source: https://github.com/supermemoryai/smfs/blob/main/bash-py/README.md

Install the library using pip or uv. Requires a Supermemory API key from supermemory.ai.

```sh
pip install supermemory-bash
# or
uv add supermemory-bash
```

--------------------------------

### Quickstart: Create and Use Bash Environment

Source: https://github.com/supermemoryai/smfs/blob/main/bash-py/README.md

Initialize a bash environment, execute shell commands, and perform semantic searches. Files persist across sessions.

```python
import asyncio
from supermemory_bash import create_bash

async def main():
    result = await create_bash(
        api_key="sm-ப்படாத",
        container_tag="user_42",
    )
    bash = result.bash

    # Run any shell command:
    r = await bash.exec("echo 'hello' > /a.md && cat /a.md")
    print(r.stdout)  # "hello\n"

    # Files persist across sessions, even from a fresh process:
    r2 = await bash.exec("cat /a.md")
    print(r2.stdout)  # "hello\n"

    # Semantic search across the whole container:
    r3 = await bash.exec("sgrep 'authentication tokens'")
    print(r3.stdout)
    # /work/auth.md:OAuth implementation handles token refresh and session management.
    # /notes/security.md:Two-factor authentication via TOTP is required for admin accounts.

asyncio.run(main())
```

--------------------------------

### Install smfs CLI

Source: https://github.com/supermemoryai/smfs/blob/main/README.md

Installs the smfs command-line interface. Supports macOS and Linux (arm64, x64). Requires a Supermemory API key.

```sh
curl -fsSL https://smfs.ai/install | bash
```

--------------------------------

### Quickstart: Create and Use Bash Environment

Source: https://github.com/supermemoryai/smfs/blob/main/bash/README.md

Initialize the bash environment and execute shell commands. Files persist across sessions, and 'sgrep' enables semantic search.

```typescript
import { createBash } from "@supermemory/bash";

const { bash, toolDescription } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
});

// Run any shell command:
const r = await bash.exec("echo 'hello' > /a.md && cat /a.md");
console.log(r.stdout);  // "hello\n"

// Files persist across sessions, even from a fresh process:
const r2 = await bash.exec("cat /a.md");
console.log(r2.stdout);  // "hello\n"

// Semantic search across the whole container:
const r3 = await bash.exec("sgrep 'authentication tokens'");
console.log(r3.stdout);
// /work/auth.md:OAuth implementation handles token refresh and session management.
// /notes/security.md:Two-factor authentication via TOTP is required for admin accounts.
```

--------------------------------

### Install Semantic Grep Shell Wrapper

Source: https://context7.com/supermemoryai/smfs/llms.txt

Installs a shell wrapper that enables `grep` within SMFS mounts to perform semantic searches by default. Flagged `grep` commands will fall back to the standard grep behavior.

```sh
smfs init   # adds the wrapper to your shell profile; re-open your shell

# Inside a mount:
cd agent_memory/
grep "authentication strategy"          # semantic — finds topically related files
grep "design review notes" work/        # semantic, scoped to a subdirectory
grep -F "exact literal string" notes/   # any flag → real grep, not semantic
grep -rF "literal" .                    # also real grep
# Outside any mount: grep is completely unchanged.
```

--------------------------------

### Install SMFS CLI

Source: https://context7.com/supermemoryai/smfs/llms.txt

Installs the SMFS CLI using a curl script. Supports macOS and Linux. Can also be built from source with Rust 1.80+.

```sh
curl -fsSL https://smfs.ai/install | bash
# Supports macOS arm64/x64 and Linux arm64/x64.
# Build from source (requires Rust 1.80+):
cargo build --release
./target/release/smfs --help
```

--------------------------------

### smfs Command Reference

Source: https://github.com/supermemoryai/smfs/blob/main/README.md

Lists available smfs commands for managing Supermemory containers, including login, mount, unmount, list, status, logs, sync, grep, init, install, and logout.

```sh
smfs login                      one-time auth, stores API key locally
smfs whoami                     show current user, org, API endpoint
smfs mount <tag>                mount a container tag
smfs unmount <tag>              unmount and drain pending pushes
smfs list                       show all running mounts
smfs status <tag>               daemon health and queue depth
smfs logs <tag>                 tail the daemon log
smfs sync <tag>                 force a sync cycle now
smfs grep "query" [path]        semantic search inside a container
smfs init                       install the grep shell wrapper
smfs install                    self-install the binary to ~/.local/bin
smfs logout                     remove stored credentials
```

--------------------------------

### Build SMFS from Source

Source: https://github.com/supermemoryai/smfs/blob/main/README.md

Build the Supermemory AI File System (SMFS) project using Cargo. Ensure you have Rust 1.80 or newer installed.

```sh
cargo build --release
./target/release/smfs --help
```

--------------------------------

### Integrate Anthropic SDK with Supermemory Bash (Python)

Source: https://context7.com/supermemoryai/smfs/llms.txt

This snippet demonstrates how to use the Supermemory bash package with the Anthropic SDK to allow an LLM agent to execute bash commands and access persistent memory. Ensure the 'supermemory-bash' package is installed.

```python
import asyncio
import json
from anthropic import AsyncAnthropic
from supermemory_bash import create_bash

async def main():
    result = await create_bash(api_key="sm-...", container_tag="user_42")

    client = AsyncAnthropic()
    tools = [{
        "name": "bash",
        "description": result.tool_description,
        "input_schema": {
            "type": "object",
            "properties": {"cmd": {"type": "string"}},
            "required": ["cmd"],
        },
    }]

    messages = [{"role": "user", "content": "Find my notes about deployment and list them."}]

    for _ in range(8):
        response = await client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            for block in response.content:
                if hasattr(block, "text"):
                    print(block.text)
            break

        tool_results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            cmd = block.input["cmd"]
            print(f"[bash] $ {cmd}")
            r = await result.bash.exec(cmd)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": r.stdout + (f"\n[stderr]{r.stderr}" if r.stderr else ""),
            })
        messages.append({"role": "user", "content": tool_results})

asyncio.run(main())
```

--------------------------------

### Using Pre-built Bash Tool Description

Source: https://context7.com/supermemoryai/smfs/llms.txt

Demonstrates how to use the pre-built `TOOL_DESCRIPTION` string from `@supermemory/bash` in raw tool schemas for various LLM providers. Also shows that `createBash` returns the same description string.

```typescript
import { TOOL_DESCRIPTION } from "@supermemory/bash";

// Use in any raw tool schema (OpenAI, Anthropic, etc.)
const toolSchema = {
  name: "bash",
  description: TOOL_DESCRIPTION,
  parameters: {
    type: "object",
    properties: { cmd: { type: "string" } },
    required: ["cmd"],
  },
};

// Or access the same string from createBash's return value
const { toolDescription } = await createBash({ apiKey: "sm-...", containerTag: "user_42" });
console.log(toolDescription === TOOL_DESCRIPTION); // true
```

--------------------------------

### createBash(opts)

Source: https://context7.com/supermemoryai/smfs/llms.txt

Initializes a virtual bash shell backed by a Supermemory container. Returns a `bash` executor, a raw `volume` handle, and a `toolDescription` string.

```APIDOC
## createBash(opts)

### Description
Initializes a virtual bash shell backed by a Supermemory container. Returns a `bash` executor, a raw `volume` handle, and a `toolDescription` string ready to paste into any LLM tool schema.

### Parameters
#### Path Parameters
- **opts** (object) - Required - Configuration options for creating the bash environment.
  - **apiKey** (string) - Required - Supermemory API key.
  - **containerTag** (string) - Required - Identifier for the Supermemory container.
  - **baseURL** (string) - Optional - Override API base URL.
  - **eagerLoad** (boolean) - Optional - Warm path index at construction (default true).
  - **eagerContent** (boolean) - Optional - Warm content cache (default true; set false for 10k+ docs).
  - **cacheTtlMs** (number) - Optional - Cache TTL in milliseconds; null = never expires (single-writer); 0 = no cache.
  - **cwd** (string) - Optional - Starting working directory.
  - **env** (object) - Optional - Environment variables to set in the bash environment.
  - **includeDocIds** (boolean) - Optional - If true, sgrep output includes [doc:<uuid>] annotations.

### Returns
- **bash** (object) - An executor for running bash commands.
- **volume** (object) - A raw handle to the virtual filesystem volume.
- **toolDescription** (string) - A string describing the tool for LLM integration.
- **configureMemoryPaths** (function) - Function to set which paths feed the memory pipeline.
- **refresh** (function) - Function to force-refresh the path index.

### Example
```typescript
import { createBash } from "@supermemory/bash";

const { bash, volume, toolDescription, configureMemoryPaths, refresh } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
  // Optional:
  baseURL: undefined,
  eagerLoad: true,
  eagerContent: true,
  cacheTtlMs: 150_000,
  cwd: "/home/user",
  env: { MY_VAR: "hello" },
  includeDocIds: false,
});

// Execute any shell command
const r = await bash.exec("mkdir -p /notes && echo 'Hello world' > /notes/hello.md");
console.log(r.stdout);   // ""
console.log(r.exitCode); // 0

// Files persist across sessions — even in a fresh process
const r2 = await bash.exec("cat /notes/hello.md");
console.log(r2.stdout);  // "Hello world\n"

// Pipes, conditionals, redirects all work
const r3 = await bash.exec("ls /notes/ | grep '.md' | wc -l");
console.log(r3.stdout);  // "1\n"

// Force-refresh the path index after another process writes to the container
await refresh();

// Set which paths feed the memory pipeline
await configureMemoryPaths(["/notes/", "/journal.md"]);
```
```

--------------------------------

### Integration with OpenAI (Python)

Source: https://context7.com/supermemoryai/smfs/llms.txt

Demonstrates how to integrate the Supermemory Bash environment with OpenAI's chat completions API, allowing GPT models to execute bash commands.

```APIDOC
## Integration with OpenAI (Python)

```python
import asyncio
from openai import AsyncOpenAI
from supermemory_bash import create_bash

async def main():
    result = await create_bash(api_key="sm-ப்படாத", container_tag="user_42")

    client = AsyncOpenAI()
    messages = [{"role": "user", "content": "Search my notes for authentication and summarize."}]

    tools = [{
        "type": "function",
        "function": {
            "name": "bash",
            "description": result.tool_description,
            "parameters": {
                "type": "object",
                "properties": {"cmd": {"type": "string"}},
                "required": ["cmd"],
            },
        },
    }]

    while True:
        response = await client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=tools,
        )
        msg = response.choices[0].message
        messages.append(msg)

        if not msg.tool_calls:
            print(msg.content)
            break

        for tc in msg.tool_calls:
            import json
            cmd = json.loads(tc.function.arguments)["cmd"]
            print(f"[bash] $ {cmd}")
            r = await result.bash.exec(cmd)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": r.stdout + (f"\n[stderr]{r.stderr}" if r.stderr else ""),
            })

asyncio.run(main())
```
```

--------------------------------

### createBash Options

Source: https://github.com/supermemoryai/smfs/blob/main/bash/README.md

Configure the bash environment with options like API key, container tag, base URL, caching behavior, working directory, environment variables, and execution limits.

```typescript
createBash({
  apiKey: string,
  containerTag: string,         // one container per user / project
  baseURL?: string,             // SDK override
  eagerLoad?: boolean,          // default: true (warm pathIndex at construction)
  eagerContent?: boolean,       // default: true (also warm content cache)
  cacheTtlMs?: number | null,   // default: 150_000 (2.5 min). null = never expires (single-writer). 0 = no cache.
  cwd?: string,                 // default: "/home/user"
  env?: Record<string, string>,
  executionLimits?: ExecutionLimits,  // pass-through to just-bash
  logger?: BashLogger,                // pass-through to just-bash
});
```

--------------------------------

### Create Virtual Bash Environment with createBash

Source: https://context7.com/supermemoryai/smfs/llms.txt

Initializes a virtual bash shell backed by a Supermemory container. Returns a bash executor, a raw volume handle, and a toolDescription string.

```typescript
import { createBash } from "@supermemory/bash";

const { bash, volume, toolDescription, configureMemoryPaths, refresh } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
  // Optional:
  baseURL: undefined,            // override API base URL
  eagerLoad: true,               // warm path index at construction (default true)
  eagerContent: true,            // also warm content cache (default true; set false for 10k+ docs)
  cacheTtlMs: 150_000,           // cache TTL ms; null = never expires (single-writer); 0 = no cache
  cwd: "/home/user",             // starting working directory
  env: { MY_VAR: "hello" },
  includeDocIds: false,          // if true, sgrep output includes [doc:<uuid>] annotations
});

// Execute any shell command
const r = await bash.exec("mkdir -p /notes && echo 'Hello world' > /notes/hello.md");
console.log(r.stdout);   // ""
console.log(r.exitCode); // 0

// Files persist across sessions — even in a fresh process
const r2 = await bash.exec("cat /notes/hello.md");
console.log(r2.stdout);  // "Hello world\n"

// Pipes, conditionals, redirects all work
const r3 = await bash.exec("ls /notes/ | grep '.md' | wc -l");
console.log(r3.stdout);  // "1\n"

// Force-refresh the path index after another process writes to the container
await refresh();

// Set which paths feed the memory pipeline
await configureMemoryPaths(["/notes/", "/journal.md"]);
```

--------------------------------

### Configure create_bash options

Source: https://github.com/supermemoryai/smfs/blob/main/bash-py/README.md

Customize the bash environment with options like base URL, eager loading, cache TTL, working directory, and environment variables.

```python
await create_bash(
    api_key="sm-ப்படாத",
    container_tag="user_42",        # one container per user / project
    base_url=None,                  # API override
    eager_load=True,                # default: True (warm path_index at construction)
    eager_content=True,             # default: True (also warm content cache)
    cache_ttl_ms=150_000,           # default: 150_000 (2.5 min). None = never expires (single-writer). 0 = no cache.
    cwd="/",                        # default working directory
    env=None,                       # extra environment variables
)
```

--------------------------------

### Create Virtual Bash Environment (Python)

Source: https://context7.com/supermemoryai/smfs/llms.txt

Use `create_bash` to initialize a Python virtual shell. Configure options like API keys, container tags, caching, and environment variables. The result includes a `bash` object for execution and methods to refresh and configure memory paths.

```Python
import asyncio
from supermemory_bash import create_bash

async def main():
    result = await create_bash(
        api_key="sm-ாலத்தில்",
        container_tag="user_42",
        # Optional:
        base_url=None,          # API override
        eager_load=True,        # warm path_index at construction
        eager_content=True,     # also warm content cache
        cache_ttl_ms=150_000,   # None = never expires (single-writer), 0 = no cache
        cwd="/",                # starting working directory
        env={"MY_VAR": "hello"},
    )

    bash = result.bash

    # Write a file
    r = await bash.exec("echo 'Hello, Supermemory!' > /notes/hello.md")
    assert r.exit_code == 0

    # Read it back
    r2 = await bash.exec("cat /notes/hello.md")
    print(r2.stdout)  # "Hello, Supermemory!\n"

    # Files persist in a fresh session
    r3 = await bash.exec("ls /notes/")
    print(r3.stdout)  # "hello.md\n"

    # Read /profile.md — auto-generated memory summary for the container
    r4 = await bash.exec("cat /profile.md")
    print(r4.stdout)

    # Refresh path index after external writes
    await result.refresh()

    # Configure memory generation paths
    await result.configure_memory_paths(["/notes/", "/journal.md"])

asyncio.run(main())
```

--------------------------------

### Integrate with OpenAI Chat Completions

Source: https://github.com/supermemoryai/smfs/blob/main/bash-py/README.md

Provide the bash tool description to OpenAI's chat completions API. The agent can then use the 'bash' function to execute commands.

```python
from openai import AsyncOpenAI
from supermemory_bash import create_bash

result = await create_bash(api_key="sm-ப்படாத", container_tag="user_42")

client = AsyncOpenAI()
response = await client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Search my notes for authentication."}],
    tools=[{
        "type": "function",
        "function": {
            "name": "bash",
            "description": result.tool_description,
            "parameters": {
                "type": "object",
                "properties": {"cmd": {"type": "string"}},
                "required": ["cmd"],
            },
        },
    }],
)

# In your tool-use loop, call `await result.bash.exec(cmd)` and feed the result back.
```

--------------------------------

### SMFS Authentication Commands

Source: https://context7.com/supermemoryai/smfs/llms.txt

Handles authentication by storing API keys locally. `whoami` displays the current user, organization, and API endpoint.

```sh
smfs login                  # prompts for API key from supermemory.ai
smfs whoami                 # → user: alice@example.com  org: acme
smfs logout                 # removes stored credentials
```

--------------------------------

### Integrate with OpenAI for Bash Command Generation (Python)

Source: https://context7.com/supermemoryai/smfs/llms.txt

Combine Supermemory bash execution with OpenAI's chat models. Define a tool for the OpenAI client that uses the bash environment, allowing the model to generate and execute bash commands based on user prompts.

```Python
import asyncio
from openai import AsyncOpenAI
from supermemory_bash import create_bash

async def main():
    result = await create_bash(api_key="sm-ாலத்தில்", container_tag="user_42")

    client = AsyncOpenAI()
    messages = [{"role": "user", "content": "Search my notes for authentication and summarize."}]

    tools = [{
        "type": "function",
        "function": {
            "name": "bash",
            "description": result.tool_description,
            "parameters": {
                "type": "object",
                "properties": {"cmd": {"type": "string"}},
                "required": ["cmd"],
            },
        },
    }]

    while True:
        response = await client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=tools,
        )
        msg = response.choices[0].message
        messages.append(msg)

        if not msg.tool_calls:
            print(msg.content)
            break

        for tc in msg.tool_calls:
            import json
            cmd = json.loads(tc.function.arguments)["cmd"]
            print(f"[bash] $ {cmd}")
            r = await result.bash.exec(cmd)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": r.stdout + (f"\n[stderr]{r.stderr}" if r.stderr else ""),
            })

asyncio.run(main())
```

--------------------------------

### Integrate Bash Tool with Vercel AI SDK

Source: https://github.com/supermemoryai/smfs/blob/main/bash/README.md

Configure the bash tool with its description and an execution function for use with the Vercel AI SDK's 'generateText' function.

```typescript
import { generateText, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import { createBash } from "@supermemory/bash";

const { bash, toolDescription } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
});

const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Search my notes for authentication.",
  tools: {
    bash: tool({
      description: toolDescription,
      inputSchema: z.object({ cmd: z.string() }),
      execute: async ({ cmd }) => bash.exec(cmd),
    }),
  },
  maxSteps: 8,
});
```

--------------------------------

### Integrate Bash Tool with Anthropic SDK

Source: https://github.com/supermemoryai/smfs/blob/main/bash/README.md

Set up the bash tool for use with the Anthropic SDK, providing its name, description, and input schema for message creation.

```typescript
import Anthropic from "@anthropic-ai/sdk";
import { createBash } from "@supermemory/bash";

const { bash, toolDescription } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
});

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  tools: [{
    name: "bash",
    description: toolDescription,
    input_schema: { type: "object", properties: { cmd: { type: "string" } }, required: ["cmd"] },
  }],
  messages: [{ role: "user", content: "Find my notes about authentication and summarize." }],
});

// In your tool-use loop, call bash.exec(cmd) and feed the result back.
```

--------------------------------

### Full Tool-Use Loop with Anthropic SDK and Bash

Source: https://context7.com/supermemoryai/smfs/llms.txt

Implements a streaming-compatible tool-use loop with the Anthropic SDK and the bash tool. Requires Anthropic and SuperMemory API keys. Handles multi-turn interactions and tool result reporting.

```typescript
import Anthropic from "@anthropic-ai/sdk";
import { createBash } from "@supermemory/bash";

const { bash, toolDescription } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "agent_memory",
});

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const tools: Anthropic.Tool[] = [{
  name: "bash",
  description: toolDescription,
  input_schema: {
    type: "object",
    properties: { cmd: { type: "string", description: "The bash command to execute." } },
    required: ["cmd"],
  },
}];

const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "Create /notes/summary.md with a summary of all files in /work/" },
];

for (let step = 0; step < 8; step++) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-5-20250929",
    max_tokens: 1024,
    tools,
    messages,
  });

  messages.push({ role: "assistant", content: response.content });

  if (response.stop_reason !== "tool_use") {
    const text = response.content
      .filter((b): b is Anthropic.TextBlock => b.type === "text")
      .map((b) => b.text)
      .join("\n");
    console.log(`[assistant] ${text}`);
    break;
  }

  const toolResults: Anthropic.ToolResultBlockParam[] = [];
  for (const block of response.content) {
    if (block.type !== "tool_use") continue;
    const { cmd } = block.input as { cmd: string };
    console.log(`[bash] $ ${cmd}`);
    const r = await bash.exec(cmd);
    toolResults.push({
      type: "tool_result",
      tool_use_id: block.id,
      content: [r.stdout, r.stderr ? `[stderr]\n${r.stderr}` : null, `[exit ${r.exitCode}]`]
        .filter(Boolean).join("\n"),
      is_error: r.exitCode !== 0,
    });
  }
  messages.push({ role: "user", content: toolResults });
}
```

--------------------------------

### Configure Memory Generation Paths

Source: https://github.com/supermemoryai/smfs/blob/main/README.md

Mounts a Supermemory container and configures which paths within the container should be processed for memory generation. Use a trailing slash for recursive matching, no trailing slash for exact file matches, or an empty string to disable memory generation.

```sh
# Scope memory generation to specific paths
# Trailing slash = match any file inside that folder recursively
# No trailing slash = exact file match
smfs mount agent_memory --memory-paths "/notes/,/journal.md,/work/"

# Disable memory generation entirely (mount becomes pure storage)
smfs mount agent_memory --memory-paths ""

# Omit the flag entirely to leave the existing server config alone
smfs mount agent_memory
```

--------------------------------

### Generate Text with Vercel AI SDK and Bash Tool

Source: https://context7.com/supermemoryai/smfs/llms.txt

Integrates the bash tool with Vercel's `generateText` function. Requires API keys for SuperMemory and the chosen model provider. Use for agent loops where bash commands are needed.

```typescript
import { generateText, tool } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import { createBash } from "@supermemory/bash";

const { bash, toolDescription } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
});

// With Anthropic
const result = await generateText({
  model: anthropic("claude-sonnet-4-5-20250929"),
  prompt: "Search my notes for anything about OAuth and summarize what you find.",
  tools: {
    bash: tool({
      description: toolDescription,
      inputSchema: z.object({ cmd: z.string().describe("The bash command to execute.") }),
      execute: async ({ cmd }) => {
        console.log(`[bash] $ ${cmd}`);
        const r = await bash.exec(cmd);
        return { stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode };
      },
    }),
  },
  maxSteps: 8,
});
console.log(result.text);

// With OpenAI
const result2 = await generateText({
  model: openai("gpt-4o"),
  prompt: "List all markdown files in /notes/ and show their sizes.",
  tools: {
    bash: tool({
      description: toolDescription,
      inputSchema: z.object({ cmd: z.string() }),
      execute: async ({ cmd }) => bash.exec(cmd),
    }),
  },
  maxSteps: 5,
});
```

--------------------------------

### Virtual Bash Tool for AI Agents

Source: https://github.com/supermemoryai/smfs/blob/main/README.md

The `@supermemory/bash` package provides a virtual bash environment for AI agents, enabling them to use Unix commands and semantic search (`sgrep`) in environments without a local filesystem. Initialize the bash tool with your API key and a container tag.

```ts
import { createBash } from "@supermemory/bash";

const { bash, toolDescription } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "user_42",
});

await bash.exec("echo 'hello' > /a.md && cat /a.md");
await bash.exec("sgrep 'authentication tokens'");
```

--------------------------------

### Mounting Agent Memory with Specific Paths

Source: https://context7.com/supermemoryai/smfs/llms.txt

Mounts agent memory, specifying exact file and directory paths to include. A trailing slash indicates a directory.

```bash
smfs mount agent_memory --memory-paths "/notes/,/journal.md,/work/"
```

--------------------------------

### Manage SMFS Mounts

Source: https://context7.com/supermemoryai/smfs/llms.txt

Provides commands to inspect running mounts, check daemon health, view queue depth, and tail daemon logs.

```sh
smfs list                    # show all active mounts
smfs status agent_memory     # daemon health + pending write queue depth
smfs logs agent_memory       # tail the background daemon log
```

--------------------------------

### Login and Mount Supermemory Container

Source: https://github.com/supermemoryai/smfs/blob/main/README.md

Logs in to Supermemory using an API key and mounts a specified container tag as a local directory. Files within the mount can be edited and will sync to Supermemory.

```sh
smfs login                  # one-time, stores your API key
smfs mount agent_memory     # mounts the container tag at ./agent_memory/
ls agent_memory/
cat agent_memory/memory/notes.md
```

--------------------------------

### create_bash(...) — Create a virtual bash environment

Source: https://context7.com/supermemoryai/smfs/llms.txt

Asynchronously creates a Python virtual shell backed by Supermemory. It returns a dataclass containing the bash shell, volume, tool description, and configuration functions.

```APIDOC
## `create_bash(...)` — Create a virtual bash environment (Python)

Async factory that initializes the Python virtual shell backed by Supermemory. Returns a `CreateBashResult` dataclass with `bash` (Shell), `volume` (SupermemoryVolume), `tool_description`, `configure_memory_paths`, and `refresh`.

```python
import asyncio
from supermemory_bash import create_bash

async def main():
    result = await create_bash(
        api_key="sm-ப்படாத",
        container_tag="user_42",
        # Optional:
        base_url=None,          # API override
        eager_load=True,        # warm path_index at construction
        eager_content=True,     # also warm content cache
        cache_ttl_ms=150_000,   # None = never expires (single-writer), 0 = no cache
        cwd="/",                # starting working directory
        env={"MY_VAR": "hello"},
    )

    bash = result.bash

    # Write a file
    r = await bash.exec("echo 'Hello, Supermemory!' > /notes/hello.md")
    assert r.exit_code == 0

    # Read it back
    r2 = await bash.exec("cat /notes/hello.md")
    print(r2.stdout)  # "Hello, Supermemory!\n"

    # Files persist in a fresh session
    r3 = await bash.exec("ls /notes/")
    print(r3.stdout)  # "hello.md\n"

    # Read /profile.md — auto-generated memory summary for the container
    r4 = await bash.exec("cat /profile.md")
    print(r4.stdout)

    # Refresh path index after external writes
    await result.refresh()

    # Configure memory generation paths
    await result.configure_memory_paths(["/notes/", "/journal.md"])

asyncio.run(main())
```
```

--------------------------------

### bash.exec(cmd)

Source: https://context7.com/supermemoryai/smfs/llms.txt

Runs a bash command string against the virtual filesystem. Supports standard Unix builtins, pipes, redirects (`>`, `>>`, `<`), `&&`/`||`, loops, and the custom `sgrep` semantic search command.

```APIDOC
## bash.exec(cmd)

### Description
Runs a bash command string against the virtual filesystem. Supports standard Unix builtins, pipes, redirects (`>`, `>>`, `<`), `&&`/`||`, loops, and the custom `sgrep` semantic search command.

### Parameters
#### Path Parameters
- **cmd** (string) - Required - The bash command string to execute.

### Returns
- **stdout** (string) - The standard output of the command.
- **stderr** (string) - The standard error of the command.
- **exitCode** (number) - The exit code of the command.

### Example
```typescript
import { createBash } from "@supermemory/bash";

const { bash } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "project_notes",
});

// Write and read files
await bash.exec("echo '# Meeting notes' > /notes/2024-01-15.md");
await bash.exec("echo 'Discussed auth strategy' >> /notes/2024-01-15.md");
const { stdout } = await bash.exec("cat /notes/2024-01-15.md");
// stdout: "# Meeting notes\nDiscussed auth strategy\n"

// Directory operations
await bash.exec("mkdir -p /archive/2023 && mv /notes/old.md /archive/2023/");
await bash.exec("cp -r /notes/ /backup/");
await bash.exec("rm -rf /tmp/scratch/");

// Text processing with pipes
const summary = await bash.exec(
  "find /notes/ -name '*.md' | xargs wc -l | sort -n | tail -5"
);

// Conditional logic
const { exitCode } = await bash.exec(
  "[ -f /config/settings.json ] && echo 'exists' || echo 'missing'"
);

// sed in-place editing
await bash.exec("sed -i 's/old-api-url/new-api-url/g' /config/settings.json");

// Error handling — FsErrors surface as exitCode 1, not thrown exceptions
const result = await bash.exec("cat /nonexistent.txt");
console.log(result.stderr);   // "cat: /nonexistent.txt: No such file or directory\n"
console.log(result.exitCode); // 1
```
```

--------------------------------

### Execute Shell Command with bash.exec

Source: https://context7.com/supermemoryai/smfs/llms.txt

Runs a bash command string against the virtual filesystem. Supports standard Unix builtins, pipes, redirects, conditionals, and sgrep.

```typescript
import { createBash } from "@supermemory/bash";

const { bash } = await createBash({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  containerTag: "project_notes",
});

// Write and read files
await bash.exec("echo '# Meeting notes' > /notes/2024-01-15.md");
await bash.exec("echo 'Discussed auth strategy' >> /notes/2024-01-15.md");
const { stdout } = await bash.exec("cat /notes/2024-01-15.md");
// stdout: "# Meeting notes\nDiscussed auth strategy\n"

// Directory operations
await bash.exec("mkdir -p /archive/2023 && mv /notes/old.md /archive/2023/");
await bash.exec("cp -r /notes/ /backup/");
await bash.exec("rm -rf /tmp/scratch/");

// Text processing with pipes
const summary = await bash.exec(
  "find /notes/ -name '*.md' | xargs wc -l | sort -n | tail -5"
);

// Conditional logic
const { exitCode } = await bash.exec(
  "[ -f /config/settings.json ] && echo 'exists' || echo 'missing'"
);

// sed in-place editing
await bash.exec("sed -i 's/old-api-url/new-api-url/g' /config/settings.json");

// Error handling — FsErrors surface as exitCode 1, not thrown exceptions
const result = await bash.exec("cat /nonexistent.txt");
console.log(result.stderr);   // "cat: /nonexistent.txt: No such file or directory\n"
console.log(result.exitCode); // 1
```

--------------------------------

### Mount Supermemory Container as Directory

Source: https://context7.com/supermemoryai/smfs/llms.txt

Mounts a Supermemory container tag as a local folder. Writes uploads in the background and pulls remote changes periodically. Supports various options for path, backend, foreground execution, ephemeral mounts, cleaning cache, custom sync intervals, and inline API keys.

```sh
# Basic mount — creates ./agent_memory/
smfs mount agent_memory

# Override mount path
smfs mount agent_memory --path /mnt/memory

# FUSE on Linux (default), NFS on macOS (default); override:
smfs mount agent_memory --backend nfs

# Run in foreground (don't daemonize)
smfs mount agent_memory --foreground

# Ephemeral — nothing persists after unmount
smfs mount agent_memory --ephemeral

# Wipe local cache before mounting
smfs mount agent_memory --clean

# Custom sync interval (seconds), disable pull, or set push drain timeout
smfs mount agent_memory --sync-interval 60 --no-sync --drain-timeout 10

# Inline API key (bypasses stored credentials)
smfs mount agent_memory --key sm-xxxxxxxx

ls agent_memory/
cat agent_memory/notes/ideas.md
echo "New thought" >> agent_memory/notes/ideas.md
```

--------------------------------

### Integrate with Anthropic Messages API

Source: https://github.com/supermemoryai/smfs/blob/main/bash-py/README.md

Provide the bash tool description to Anthropic's messages API. The agent can then use the 'bash' tool to execute commands.

```python
from anthropic import AsyncAnthropic
from supermemory_bash import create_bash

result = await create_bash(api_key="sm-ப்படாத", container_tag="user_42")

client = AsyncAnthropic()
response = await client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    tools=[{
        "name": "bash",
        "description": result.tool_description,
        "input_schema": {
            "type": "object",
            "properties": {"cmd": {"type": "string"}},
            "required": ["cmd"],
        },
    }],
    messages=[{"role": "user", "content": "Find my notes about authentication and summarize."}]
)

# In your tool-use loop, call `await result.bash.exec(cmd)` and feed the result back.
```

--------------------------------

### smfs Mount Flags

Source: https://github.com/supermemoryai/smfs/blob/main/README.md

Lists available flags for the `smfs mount` command, controlling path, backend, foreground execution, memory paths, cache persistence, sync intervals, and API credentials.

```sh
--path <DIR>             override the mount path (default: ./<tag>/)
--backend fuse|nfs       defaults: fuse on Linux, nfs on macOS
--foreground             run in foreground instead of detaching
--memory-paths "<csv>"   which paths produce memories (see above)
--ephemeral              in-memory cache; nothing persists after unmount
--clean                  wipe local cache before mounting
--sync-interval <secs>   pull interval, default 30
--no-sync                disable the pull side; local writes still push
--drain-timeout <secs>   max wait at unmount to drain the push queue, default 30
--key <KEY>              API key (otherwise resolved from stored credentials)
--api-url <URL>          override the API base URL
```

--------------------------------

### Manage Documents with `SupermemoryVolume`

Source: https://context7.com/supermemoryai/smfs/llms.txt

The `SupermemoryVolume` class provides low-level access to Supermemory's document store for CRUD operations, indexing, and search. It requires a Supermemory client instance and a container name.

```typescript
import { SupermemoryVolume } from "@supermemory/bash";
import Supermemory from "supermemory";

const client = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY! });
const volume = new SupermemoryVolume(client, "my_container");

// Add or update a document
const { id, status } = await volume.addDoc("/notes/ideas.md", "# Ideas\n- Build something great");
console.log(id, status); // "doc-uuid-..." "processing"

// Read a document (with cache)
const doc = await volume.getDoc("/notes/ideas.md");
if (doc) {
  console.log(doc.content); // "# Ideas\n- Build something great"
  console.log(doc.status);  // "done"
}

// Stat a path
const stat = await volume.statDoc("/notes/ideas.md");
// { id: "...", isFile: true, isDirectory: false, size: 34, mtime: Date, status: "done" }

// List all docs under a prefix (with content warm)
const summaries = await volume.listByPrefix("/notes/", { withContent: true });
// [{ id, filepath, status, size, mtime, content }, ...]

// Rename a file
await volume.moveDoc("/notes/ideas.md", "/notes/ideas-v2.md");

// Copy a whole directory tree
await volume.copyTree("/notes/", "/backup/notes/");

// Delete a single doc
await volume.removeDoc("/notes/old.md");

// Bulk delete everything under a prefix
const { deleted, errors } = await volume.removeByPrefix("/tmp/");
console.log(deleted); // 12

// Semantic search
const resp = await volume.search({ q: "authentication strategy", filepath: "/work/" });
for (const r of resp.results) {
  console.log(`${r.filepath} (${r.similarity.toFixed(2)}): ${r.memory}`);
}

// Fetch the synthesized memory profile for the container
const profile = await volume.fetchProfile();
console.log(profile);
// # Memory Profile
// ## Core Knowledge
// - User prefers TypeScript with strict mode enabled
// ## Recent Context
// - Working on OAuth token refresh implementation

// Configure which paths feed the memory pipeline
await volume.configureMemoryPaths(["/notes/", "/journal.md"]);
```

--------------------------------

### Execute Shell Commands (Python)

Source: https://context7.com/supermemoryai/smfs/llms.txt

Use `bash.exec()` to run bash commands within the virtual environment. Supports pipes, redirects, chaining, and built-in commands. Error handling is available via the `exit_code` attribute of the result.

```Python
import asyncio
from supermemory_bash import create_bash

async def main():
    result = await create_bash(api_key="sm-ாலத்தில்", container_tag="project_notes")
    bash = result.bash

    # Pipe and text processing
    r = await bash.exec("echo -e 'apple\nbanana\napple\ncherry' | sort | uniq -c")
    print(r.stdout)
    # "  2 apple\n  1 banana\n  1 cherry\n"

    # Directory tree operations
    await bash.exec("mkdir -p /archive/2024/q1 && cp -r /notes/ /archive/2024/q1/")

    # sed in-place
    await bash.exec("sed -i 's/TODO/DONE/g' /notes/tasks.md")

    # find with name filter
    r2 = await bash.exec("find /notes/ -name '*.md'")
    for path in r2.stdout.strip().split("\n"):
        print(path)

    # Conditional: only write if file doesn't exist
    await bash.exec("[ -f /config/init.md ] || echo 'initialized' > /config/init.md")

    # Error handling via exit_code
    bad = await bash.exec("cat /does/not/exist.txt")
    print(bad.stderr)    # "cat: /does/not/exist.txt: No such file or directory\n"
    print(bad.exit_code) # 1

asyncio.run(main())
```

--------------------------------

### Mounting Agent Memory Without Server Config Changes

Source: https://context7.com/supermemoryai/smfs/llms.txt

Mounts agent memory while leaving the existing server configuration unchanged by omitting the relevant flag.

```bash
smfs mount agent_memory
```

--------------------------------

### sgrep — Semantic search command

Source: https://context7.com/supermemoryai/smfs/llms.txt

The 'sgrep' command performs hybrid semantic and keyword search across the Supermemory container. It outputs results similar to 'grep', with each line showing the filepath and matched passage, ranked by similarity.

```APIDOC
## `sgrep` — Semantic search command

### Description
A custom shell command available inside the virtual bash that performs hybrid semantic + keyword search across the entire Supermemory container. Output mirrors grep: `filepath:matched_passage`, one result per line, ranked by similarity.

### Usage Examples

1.  **Basic semantic search:**
    ```bash
    sgrep 'authentication tokens'
    ```
    *Output Example:*
    ```
    /work/auth.md:OAuth implementation handles token refresh and session management.
    /notes/security.md:Two-factor authentication via TOTP is required for admin accounts.
    ```

2.  **Scope to a specific directory:**
    ```bash
    sgrep 'deployment process' /work/
    ```
    *Output Example:*
    ```
    /work/deploy.md:Blue-green deployment with zero-downtime rolling updates.
    ```

3.  **Scope to an exact file:**
    ```bash
    sgrep 'retry logic' /notes/backend.md
    ```

4.  **Using the `-p` flag:**
    ```bash
    sgrep -p /notes/ 'database indexing'
    ```

5.  **Multi-word query:**
    ```bash
    sgrep what is our rate limiting strategy
    ```

6.  **With document IDs enabled:**
    ```bash
    sgrep --include-doc-ids 'authentication tokens'
    ```
    *Output Example:*
    ```
    /work/auth.md [doc:abc-123]:OAuth implementation handles token refresh and session management.
    ```
```

--------------------------------

### Scope Memory Generation with --memory-paths

Source: https://context7.com/supermemoryai/smfs/llms.txt

Controls which file paths within a mount contribute to Supermemory's memory pipeline for fact extraction and semantic indexing. Other paths function as standard durable storage.

```sh
# Trailing slash = all files recursively under that folder
```

--------------------------------

### Semantic Search with SMFS Grep

Source: https://context7.com/supermemoryai/smfs/llms.txt

Performs semantic search across a Supermemory container from any location. Can be scoped to a specific tag and path. Results include file paths and relevant lines.

```sh
smfs grep "OAuth refresh tokens" --tag agent_memory
# → /work/auth.md:OAuth implementation handles token refresh and session management.
# → /notes/security.md:Two-factor authentication via TOTP is required for admin accounts.

# Scope to a subpath
smfs grep "deployment notes" --tag agent_memory --path /work/
```
Tokens:
Raw