DOCSEARCHbyAlgolia
Submit Docs

smfs (Supermemory Filesystem)

repository·main·Indexed 19 days ago

https://github.com/supermemoryai/smfs

smfs allows users to expose Supermemory containers as local filesystems, enabling developers and AI agents to read, write, and perform semantic searches using standard Unix tools like grep, cat, and ls. It includes a CLI for mounting containers and virtual bash environment packages (@supermemory/bash for TypeScript and supermemory-bash for Python) that provide a virtualized shell with a custom sgrep command for semantic search, designed for integration with LLM tools.

Tokens
36K
Snippets
121
Records
161
Agent score
66%

What's inside smfs

  1. Configure memory generation paths

    main

    By default, all files in a mount are stored as durable storage. However, only files matching the container's memory paths are processed by the Supermemory pipeline for semantic search and structured fact extraction.

    You can override these paths during a mount using the --memory-paths flag. The paths are provided as a comma-separated list:

    • Trailing slash (e.g., /notes/): Matches any file inside that folder recursively.
    • No trailing slash (e.g., journal.md): Matches that exact file only.
    • Empty string (""): Disables memory generation entirely (mount becomes pure storage).
    • Omit flag: Uses the existing server configuration for that container.

    Note: The flag writes the configuration to the container tag, so the scope persists across subsequent mounts until changed.

    # Scope memory generation to specific paths
smfs mount agent_memory --memory-paths "/notes/,/journal.md,/work/"

# Disable memory generation entirely
smfs mount agent_memory --memory-paths ""

# Use existing server config
smfs mount agent_memory

  2. Quickstart with supermemory-bash

    main

    Use create_bash to initialize a virtual bash environment. The returned object provides a bash instance with an .exec(cmd) method to run shell commands. The environment supports standard shell commands, persistent file storage across sessions, and a semantic search command sgrep.

    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:
    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)

asyncio.run(main())

  3. Quickstart: Mount a Supermemory container

    main

    To use your Supermemory container as a local directory, follow these steps:

    1. Login: Authenticate once to store your API key locally.
    2. Mount: Mount a specific container tag to a local folder. By default, the folder name matches the tag and is created in your current directory.
    3. Access: Use standard filesystem commands (ls, cat, grep, etc.) to interact with your memory.
    4. Unmount: When finished, unmount the container to drain pending writes.

    Note: Writes are uploaded in the background, and remote changes are pulled every 30 seconds by default.

    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

smfs unmount agent_memory

  4. Quickstart with createBash()

    main

    Use createBash to initialize a virtual bash environment. It returns a bash object for executing commands and a toolDescription string designed for LLM tool definitions. The environment provides standard shell commands and a custom sgrep command for semantic search. Files persist across sessions.

    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:
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);

  5. Use semantic search with the grep wrapper

    main

    You can perform semantic searches using the standard grep command by installing the smfs shell wrapper. Once installed, grep behaves differently depending on whether you are inside an smfs mount:

    1. Inside a mount: Flagless grep performs a semantic search (finding files by topic). If you provide flags (like -F for fixed strings), it falls back to a literal substring search.
    2. Outside a mount: grep behaves normally.

    To enable this, run smfs init once.

    If you need to run a semantic search from outside a mount, use the explicit command: smfs grep "query" --tag <container_tag>.

    # Setup
smfs init

# Inside a mount
cd agent_memory/

# Semantic search (finds files about the topic)
grep "OAuth refresh tokens"

# Scoped semantic search
grep "design review notes" work/

# Literal substring search (using flags)
grep -F "exact string" notes.md
    smfs init

cd agent_memory/

# Semantic search
grep "OAuth refresh tokens"

# Literal search
grep -F "exact string" notes.md

  7. Run smfs in Docker

    main

    To run smfs inside a Docker container, you must use the fuse backend. This requires granting the container access to /dev/fuse and the SYS_ADMIN capability.

    Using the development image

    docker build -t smfs:dev .
docker run --rm smfs:dev --help

    Mounting a container in Docker

    docker run --rm -it \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  -e SUPERMEMORY_API_KEY="$SUPERMEMORY_API_KEY" \
  smfs:dev mount agent_memory --path /mnt/memory

    Using the official release image

    docker run --rm -it \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  -e SUPERMEMORY_API_KEY="$SUPERMEMORY_API_KEY" \
  ghcr.io/supermemoryai/smfs:latest mount agent_memory --path /mnt/memory

  9. Hand the bash tool to your LLM

    main
    To provide the bash environment to an AI agent, use the toolDescription returned by createBash (or the exported TOOL_DESCRIPTION constant) in your tool's description field. This ensures the agent understands the persistence semantics, the sgrep command, and the limitations of the environment.

  10. Integrate supermemory-bash with LLM tools

    main

    To provide the bash environment to an AI agent, use the tool_description field from the create_bash result (or the TOOL_DESCRIPTION constant) as the tool's description. This ensures the agent understands the sgrep command, persistence semantics, and limitations.

    In your tool-use loop, execute the agent's requested command using await result.bash.exec(cmd) and return the output to the model.

    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"],
            },
        },
    }],
)

  11. Understand the Supermemory Bash environment capabilities

    main

    The Supermemory bash environment provides a persistent filesystem within your Supermemory container. Files written here persist across sessions and are searchable by other tools.

    Key Environment Details

    • Default Working Directory: /
    • Profile Context: /profile.md is a read-only file containing memories synthesized from your files. Use cat /profile.md to understand the current context.
    • Persistence: Files are persistent and searchable.
    • Consistency Model: Writes are immediately visible to local self-reads via cache. However, sgrep (semantic search) and other sessions see new content only after server ingestion (typically 5–30 seconds for indexing; semantic extraction may take longer). If sgrep fails to find recently written content, wait a few seconds and retry.

    Supported and Unsupported Operations

    • Supported: Standard shell commands (pwd, cd, ls, cat, stat, mkdir, rm, rmdir, mv, cp, echo, grep, head, tail, wc, sort, sed, awk, find, pipes, redirects, variables, conditionals, loops).
    • Unsupported: chmod, utimes, symlinks, /dev/null redirects, and large binary uploads. These will result in errors.

  12. Use the smfs CLI to mount Supermemory containers

    main

    The smfs binary is a CLI dispatch layer that allows you to mount a Supermemory container as a local filesystem. While typically invoked indirectly via supermemory mount, it can be used directly. The core logic is handled by the smfs_core library.

    To use the CLI, you invoke the smfs command followed by a subcommand (such as mount).

    # Example of direct usage (subcommand details depend on cmd module)
smfs mount ./mnt