docs: SMFS documentation — providers, Python bash tool, examples#889
docs: SMFS documentation — providers, Python bash tool, examples#889Prasanna721 wants to merge 17 commits intomainfrom
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| 🔵 In progress View logs |
supermemory-mcp | 911f5ab | Apr 27 2026, 05:53 AM |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
supermemory-app | 20f897e | Commit Preview URL Branch Preview URL |
Apr 28 2026, 07:34 AM |
|
Claude finished @Prasanna721's task in 1m 12s —— View job Review: docs: SMFS documentation
Overview: This PR adds comprehensive documentation for SMFS (Supermemory File System), including installation, mount commands, and the Bash Tool for serverless environments. Issues found: None — this looks good to ship. The documentation is well-structured and follows good practices:
Score: 10/10 Clean documentation PR with no bugs, security issues, or technical inaccuracies. |
![vorflux[bot]](https://avatars.githubusercontent.com/in/2483280?s=60&v=4){kind=small}
| ## 1. Install the binary | ||
|
|
||
| ```bash | ||
| curl -fsSL smfs.ai/install | sh |
There was a problem hiding this comment.
Broken install command — wrong URL and wrong shell.
The documented command is:
curl -fsSL smfs.ai/install | shBut the actual published installer lives at https://files.supermemory.ai/install.sh, and the script itself uses Bash-specific syntax (#!/bin/bash, [[ ... ]]). Piping to sh will fail on any system where /bin/sh is not Bash (Debian/Ubuntu, Alpine, etc.).
Suggested fix:
curl -fsSL https://files.supermemory.ai/install.sh | bashA first-time user following the docs as written will fail before smfs is even installed.
| ``` | ||
| </Accordion> | ||
|
|
||
| <Accordion title="smfs grep" icon="search"> |
There was a problem hiding this comment.
smfs grep examples fail in the exact scenario the text describes.
The accordion says smfs grep works "without being inside the mount", but the examples omit the required container tag:
smfs grep "deadline"
smfs grep "deadline" /notes/When run outside a mount, the CLI resolves the container tag from the nearest .smfs marker file. If there is no marker (i.e. the user is not inside a mount, as the text explicitly describes), the command exits with "No container tag found". The --tag <container> flag is required in this context.
Suggested fix — add the tag to the out-of-mount examples:
smfs grep --tag agent_memory "deadline"
smfs grep --tag agent_memory "deadline" /notes/Or note that these examples assume the user is inside the mount and the tag is auto-detected.
|
|
||
| Trailing `/` matches recursively. No slash matches an exact file. Pass `[]` to disable memory generation. | ||
|
|
||
| The container also exposes a virtual `profile.md` at the root: a live digest of everything in the container. Read it once at the start of a session to give the model context without walking every file. |
There was a problem hiding this comment.
/profile.md is documented as working but is not implemented in @supermemory/bash.
The docs recommend:
const { stdout } = await bash.exec("cat /profile.md");However, the @supermemory/bash package's virtual filesystem only backs reads/writes with document list/update/search API calls. There is no code path that materialises /profile.md the way the native SMFS mount does. Users copying this example will get ENOENT.
Either remove this section until the feature is implemented in the package, or add a note that /profile.md is only available via the native smfs mount binary and is not yet supported by @supermemory/bash.
…loudflare - Add smfs/providers/daytona.mdx with full tutorial (mount + bash tool patterns) - Add smfs/providers/e2b.mdx with sandbox integration guide - Add smfs/providers/vercel.mdx with AI SDK tool-calling examples - Add smfs/providers/cloudflare.mdx with Workers + Containers guide - Update docs.json navigation with Providers group under SMFS - Update smfs/overview.mdx with provider cards
- E2B: add FUSE permission fixes (chmod /dev/fuse, user_allow_other) - E2B: add background mount pattern with foreground flag - E2B: add custom template with pre-installed SMFS - Daytona: reorder to recommend bash tool pattern first - Daytona: add note about potential TLS restrictions
- E2B: fix Python example in section 3 to use bash tool pattern (matching TS tab) - E2B: add sudo write example and note about FUSE mount ownership - Daytona: fix Python example in section 3 to use bash tool pattern (matching TS tab) - Daytona: add Warning to 'Alternative: Mount' section about TLS restrictions
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
supermemory-mcp | 20f897e | Apr 28 2026, 07:33 AM |
- E2B/Daytona: Python tabs now show mount pattern (not @supermemory/bash which is TypeScript-only) - E2B/Daytona: section intros updated to explain per-language approach - Daytona: removed redundant 'Alternative: Mount' section (Python tab already covers the mount pattern with TLS warning) - E2B/Daytona: Python install commands no longer list supermemory package
install.sh uses bash syntax ([[ ]]) that sh doesn't support. Also adds https:// prefix to smfs.ai/install URL.
All four guides now show the mount pattern as the primary approach: mount SMFS inside the sandbox, then run a Claude agent with bash tool access so it reads/writes memory using standard commands. - E2B: tested end-to-end (install, login, mount, read, write, grep) - Daytona: mount pattern with TLS warning - Vercel AI SDK: SMFS mounted on host, bash tool for the agent - Cloudflare: Container with SMFS pre-installed in Dockerfile
All four provider guides now: - Run the Claude agent INSIDE the sandbox (not from orchestrating code) - Use the Claude Agent SDK consistently (not Vercel AI SDK) - Agent script is written into the sandbox and executed there - Agent uses Bash/Read/Write tools on the SMFS mount
All four providers tested. Clean separation: agent code (runs inside sandbox) vs orchestration code (creates sandbox, mounts SMFS). E2B: fully working — install, login, mount, read, write, Claude agent Vercel/local: fully working — mount, read, write, Claude agent Cloudflare: Docker build verified, SMFS + Claude SDK install in container Daytona: honest Warning about api.supermemory.ai being unreachable Also fixed: install script needs explicit version (0.0.1-rc2) since all GitHub releases are pre-releases, and PATH fix for Docker builds.
- Mermaid: replace literal \\n with <br/> in node labels (didn't render) - e2b: clarify FUSE chmod / sleep comments; use Path().read_text(); move sudo Note above Pattern B - daytona: extract shared SMFS_INSTALL snippet; upload agent.py in Pattern A (was missing); reword PATH tip; reconcile warning + note - vercel: scope Pattern A to self-hosted Node (Vercel Functions can't hold a FUSE mount); switch Pattern B to @supermemory/bash for serverless deployments - cloudflare: switch wrangler.toml -> wrangler.jsonc with proper Container Durable Object binding + migrations; define Container subclass and pass secrets via envVars; use containerFetch + getContainer; add /exec security warning; switch Flask dev server to gunicorn
- Wrap quickstart and memory snippets in asyncio.run(main()) so they run as standalone scripts (top-level await is a SyntaxError). - Drop `volume` from CreateBashResult listing (not used in any snippet) and match the more direct phrasing used in the TS doc. - Use `bash = result.bash` consistently in the Memory section to match the Quickstart style. - Drop `messages: list[dict]` annotations — type is obvious from context.
vorflux
Bot
changed the title
2 participants
SMFS Documentation
Comprehensive SMFS documentation covering provider guides, Python bash tool, and example apps.
1. Provider Guides (Mermaid + Both Patterns)
Each provider guide documents two patterns:
@supermemory/bashfor serverlessContainerclass,getContainer,wrangler.jsonc)api.supermemory.aiunreachable from datacenter IPs — documented with WarningKey changes:
Containerclass, Durable Object bindings,envVarsfor secrets/execendpoint2. Python Bash Tool Documentation
New page
smfs/bash-tool-python.mdxdocumenting thesupermemory-bashPython package:pip install supermemory-bash/uv add supermemory-bashcreate_bash(api_key=..., container_tag=...)configure_memory_paths,profile.md)3. Examples Page
Updated page
smfs/examples.mdxlinking to thesupermemoryai/examplesrepo with three web-based demo apps:@supermemory/bash+ Vercel AI SDK (upload docs, chat with AI)supermemory-bash+ vanilla HTML/JS (notes + AI chat)See supermemoryai/examples#1 for the full example apps.
Files changed
apps/docs/smfs/providers/e2b.mdx(rewritten)apps/docs/smfs/providers/daytona.mdx(rewritten)apps/docs/smfs/providers/vercel.mdx(rewritten)apps/docs/smfs/providers/cloudflare.mdx(rewritten)apps/docs/smfs/bash-tool-python.mdx(new)apps/docs/smfs/examples.mdx(new, updated for web-based apps)apps/docs/docs.json(modified — nav entries)apps/docs/smfs/overview.mdx(modified — cards for bash tool + examples)apps/docs/smfs/install.mdx(modified —| bashinstead of| sh)Known issues
smfs.ai/installrequires explicit version (bash -s -- 0.0.1-rc2) — all GitHub releases are pre-releasesbashnotsh(uses[[ ]]syntax)sudo chmod 666 /dev/fuseat runtime; mount files owned by rootapi.supermemory.aiblocked from datacenter IPs~/.local/bin/which needsENV PATH="/root/.local/bin:$PATH"supermemory-bashPython package not yet published to PyPI (onpython-sdkbranch ofsupermemoryai/smfs)Testing
This is a documentation-only change (MDX files). Testing consisted of:
Live provider testing (done in earlier session iterations):
Review cycle: simplify + review subagents identified issues across all files. A build subagent addressed all high/medium priority items. Key fixes: Mermaid
\nto<br/>, Cloudflare Containers API correction, Vercel serverless scoping, Daytona file upload bug, security warning on exec endpoint, top-levelawaitfix in Python quickstart,shellQuotehelper in TS example.Manual verification: confirmed Mermaid syntax matches existing patterns in the repo (
search/overview.mdx,connectors/overview.mdx),@supermemory/bashAPI matchesbash-tool.mdxreference, Python SDK API verified againstsupermemoryai/smfssource.