如何用 SMFS 把 Supermemory 容器挂载为本地目录并配置 memory paths

如何用 SMFS 把 Supermemory 容器挂载为本地目录并配置 memory paths

【免费下载链接】supermemoryMemory and context engine + app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory

SMFS 是 Supermemory 提供的文件系统工具：它把一个 Supermemory 容器（container）挂载成本地目录，之后就能用ls、cat、grep这些标准 shell 命令读写记忆，不需要引入 SDK。这篇文章覆盖从安装二进制、登录、执行挂载，到用--memory-paths指定哪些文件会被 Supermemory 提炼为记忆（memories）的完整路径，以及挂载后的验证与常见状态排查。适用环境为 macOS（arm64、x64）和 Linux（arm64、x64）；Windows 暂不支持，官方文档明确将其排除在 v0 roadmap 之外。macOS 上挂载走 NFSv3，Linux 上走 FUSE，两者都由 SMFS 自动处理，不需要额外安装。

准备条件

1. 一个 Supermemory API key。文档中的获取入口是 console.supermemory.ai，登录时会被要求输入。
2. 一个 container tag。它是你组织里用来划分记忆边界的字符串标识（如agent_memory、user_alex），命名规则在 Container Tags 文档中有定义：不超过 100 个字符，只允许字母、数字、-、_、:。挂载时传给smfs mount的就是这个 tag。

安装二进制

一条命令完成安装，二进制会被放到~/.local/bin：

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

装完后如果smfs不在PATH里，把~/.local/bin加进 shell profile，然后重开终端。

登录

登录是一次性操作，key 会被存到全局凭据里：

smfs login

它交互式提示输入 Supermemory API key。也可以在脚本里直接传 key：

smfs login --key sm_...

其中sm_...需要替换成你自己的 API key（文档原文即以此占位）。

挂载容器

smfs mount agent_memory

agent_memory是示例中的 container tag，替换成你自己的 tag。执行后 SMFS 会在当前目录下创建一个与 tag 同名的文件夹（agent_memory/）并把容器挂载在那里。挂载以后台守护进程运行，并在挂载根写入标记文件.smfs，供其他工具（以及语义化grepwrapper）识别挂载位置。

想在其他位置挂载就用--path：

smfs mount agent_memory --path ~/memory

验证挂载成功

文档给出的验证方式就是用普通文件系统命令读挂载点：

ls agent_memory/ cat agent_memory/profile.md

每个挂载的根目录都有一个虚拟文件profile.md，由 Supermemory 自动生成、只读，内容是容器内记忆的实时摘要——cat profile.md可以在不遍历所有文件的情况下拿到容器概览。能读到内容即说明挂载可用。

再确认守护进程状态：

smfs status

它会显示该挂载的连接状态（connectivity）、队列深度（queue depth）和最近一次同步时间。进入挂载目录内部时可以省略 tag，SMFS 会自动通过最近的.smfs标记解析；也可以用smfs status --json拿结构化输出，或smfs list列出本机所有 SMFS 挂载。

配置 memory paths

这一节是容易踩坑的地方：SMFS 不是普通文件系统，它会在指定路径的文件上生成 memories——这些文件会被 Supermemory 提取、摘要并索引。挂载点内其他路径的文件仍然可被语义检索，默认通过SuperRAG索引，不会丢失。

默认行为

默认情况下，名为user.md或memory.md的文件会被当作 memory path。把这些文件放到挂载点任意位置，Supermemory 就会自动从它们生成 memories。

用--memory-paths自定义

在挂载时传入--memory-paths来控制哪些文件成为 memories：

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

文档给出的规则：

• 路径是绝对路径，以挂载根为锚点，必须以/开头；
• 结尾带/表示递归匹配该目录下的所有文件（/notes/覆盖/notes/foo.md、/notes/2026/march.md等）；
• 结尾不带斜杠只匹配单个精确文件（/journal.md）；
• 多个路径用逗号分隔；
• 传空字符串（--memory-paths ""）会完全关闭 memory 生成；
• 省略该 flag 时，保留容器 tag 上已有的配置，没有则回退到user.md和memory.md。

也就是说，memory paths 只在挂载时设置，想改路径需要 unmount 后带新的--memory-paths重新挂载。

同步模式与相关 flag

挂载默认是双向同步：本地读命中缓存，本地写入排队后在后台推送到 Supermemory，远端变更按轮询拉取。多写者（你、另一个 agent、dashboard）场景用默认模式即可。可选分支：

# 关闭远端变更轮询，写入仍会推送；适合 agent 是唯一写者、需要稳定读视图的场景 smfs mount agent_memory --no-sync # 缓存只在内存里，unmount 后不保留；适合 CI、一次性沙箱等短生命周期场景 smfs mount agent_memory --ephemeral

其他常用 flag（完整列表见 Mount 文档）：

随时强制同步一次（推送未完成写入并拉取远端变更）：

smfs sync agent_memory

拆掉沙箱前用一次比较稳妥。

卸载与收尾

smfs unmount agent_memory

卸载会按--drain-timeout冲刷完挂起的写入再退出守护进程，未冲刷完的部分在下次挂载时恢复。在挂载目录内部执行时 tag 可省略（smfs unmount）。smfs logout只会移除凭据，活动挂载仍在运行，直到你显式 unmount。

排查

文档针对当前场景给出了三个明确的排查路径：

1. 感觉缓存过期或不同步：卸载后用--clean重新挂载，它会清掉本地 SQLite 缓存并从 API 拉取最新数据，服务端内容不变：

   smfs unmount agent_memory smfs mount agent_memory --clean

2. 挂载行为异常 / 二进制疑似损坏：smfs install会把当前二进制重新复制进~/.local/bin并重置权限。

3. 挂载内语义grep不生效：smfs mount首次挂载时会自动安装 shell wrapper（写入~/.zshrc）。如果升级二进制后失效，跑一次smfs init强制重装，然后重开终端或source ~/.zshrc。注意 wrapper 只在挂载内（检测到.smfs标记）生效，传任何 flag（grep -r、grep -i等）会回落到真正的grep。

限制与边界

• 同一台设备上，同一个 container tag 不能同时挂载两次，一台设备一个 tag 只保留一个挂载；不同设备挂同一个 tag 完全支持。同一台设备上可以并行挂载多个不同容器。
• 同一台机器上的多个 agent 可以共用一个挂载点，读写的约束就是"每个容器每个设备一个挂载"。
• 挂载只覆盖 macOS 和 Linux 的 arm64/x64；Windows 场景官方文档指向 Bash Tool（@supermemory/bash/supermemory-bash）作为替代方案，见 Bash Tool 文档。

更多示例可参考 SMFS 概览 和 安装文档。

【免费下载链接】supermemoryMemory and context engine + app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory