smfs：一个为 AI Agent 量身打造的「记忆文件系统」

背景：Agent 为什么需要「记忆」？

用过 AI 编程工具（Cursor、Copilot、Claude Code）的开发者或多或少会遇到这个痛点：每次开启新对话，AI 对你项目结构、代码风格、技术债务一无所知，必须从头解释上下文。更进一步的自主 Agent（如 AutoGPT、BabyAGI）更需要跨越多轮对话持久化积累知识，但传统方案——把对话历史存 JSON、在向量数据库建索引、手写检索逻辑——要么维护成本高，要么和现有工具链格格不入。

smfs（SuperMemoryFS） 的思路极其直接：把 Supermemory 的云端记忆容器，直接挂载成你电脑上的一个本地文件夹。从此访问 AI 记忆，不需要任何特殊 API 或 SDK——ls、cat、grep，用什么命令就用什么命令。

smfs banner

smfs 是什么：Supermemory 官方出品的命令行工具，将云端记忆容器通过 FUSE（Linux）或 NFS（macOS）挂载为本地虚拟文件系统，支持语义搜索（semantic grep），兼容所有现有 Unix 工具。

技术架构：Rust 核心 + 三层抽象

smfs 的代码仓库是一个 Cargo Workspace，包含两个核心 crate：

核心层：crates/smfs-core

smfs-core 是整个项目的「引擎」，按职责拆分为 6 大模块：

模块	职责	关键技术
`vfs`	虚拟文件系统 trait + MemFs 实现	自定义 FileSystem trait，POSIX 兼容接口
`mount`	FUSE/NFS 挂载适配	`fuser`（Linux）、`nfsserve`（macOS）纯 Rust 实现
`sync`	本地缓存与 Supermemory API 双向同步	推（push）/拉（pull）引擎，30 秒轮询
`api`	Supermemory 后端 HTTP 客户端	`reqwest`（Rust HTTP 库），TLS 支持
`cache`	SQLite 本地持久缓存	`rusqlite`（bundled），WAL 模式，chunk 存储
`daemon`	长期运行守护进程 + Unix Socket IPC	`tokio` 异步运行时，fork dance 守护化

CLI 层：crates/smfs

薄薄的命令行调度层，所有用户命令（login、mount、unmount、sync、grep）都定义在这里。核心逻辑委托给 smfs-core，不做任何业务处理。

云端适配层：bash/

一个 TypeScript 包 @supermemory/bash，专门为「没有本地文件系统的运行环境」设计：Cloudflare Workers、AWS Lambda、Vercel Edge Functions。drop 一个 run_bash 工具进去，Agent 就能通过 bash 命令操作 Supermemory 记忆，和本地 mount 体验一致。

核心功能详解

1. 一键挂载，像访问本地文件一样访问 AI 记忆

# 首次登录（存 API Key）
smfs login

# 挂载名为 agent_memory 的容器到本地
smfs mount agent_memory

# 之后和普通文件夹一样操作
ls agent_memory/
cat agent_memory/memory/notes.md
vim agent_memory/notes/plan.md

挂载后，Supermemory 容器「变成」了你当前目录下的一个真实文件夹。VSCode 能直接打开，git 能追踪，编辑器能全屏，而不是困在某个 AI 工具的侧边栏里。写入操作会在后台自动推送到 Supermemory 云端，支持离线写入，联网后自动同步。

2. 语义搜索：让 grep 理解「意思」而不是「字面」

cd agent_memory/

# 语义搜索（理解意图）
grep "OAuth refresh tokens"

# 限定目录 + 语义搜索
grep "design review notes" work/

# 精确字面匹配（任何 flag 都让 grep 回退到原生）
grep -F "exact string" notes.md

smfs 提供了一个 shell wrapper：当你处于 smfs mount 的目录内，无 flag 的 grep 自动路由到 Supermemory 的语义检索 API；带 flag 时回退到原生 grep。这个设计非常聪明——不需要学任何新命令，不需要配置 Agent 的 tool 列表，直接用 grep 就行。

3. 记忆生成路径控制

通过 --memory-paths 精确控制哪些路径的内容会被处理为可检索记忆：

# 只处理 /notes/ 和 /journal.md
smfs mount agent_memory --memory-paths "/notes/,/journal.md"

# 纯存储，不生成记忆
smfs mount agent_memory --memory-paths ""

4. 离线 + 增量同步

smfs 的 sync 模块维护了一个本地 SQLite 缓存（~/.supermemory/）。即使断网，本地写入也会进入队列；联网后自动 drain 推送到云端。远程有更新时，默认每 30 秒 pull 一次。mount/unmount 操作均有 drain 机制，确保数据不丢失。

部署分析

容器化支持

✅ Dockerfile：存在，多阶段构建（Rust builder + Debian slim runtime）
❌ docker-compose：无
❌ Kubernetes：无

跨平台支持

✅ macOS（arm64、x64）：使用 NFS 后端（无需 macFUSE）
✅ Linux（arm64、x64）：使用 FUSE 后端（需要 libfuse3）
❌ Windows：不支持

安装方式

# 方式一：一键脚本（推荐）
curl -fsSL https://smfs.ai/install | bash

# 方式二：Docker
docker run -it --device /dev/fuse --privileged supermemoryai/smfs

Docker 运行需要 --device /dev/fuse --privileged，FUSE 本身要求特权模式，所以在 Docker 里体验并不理想。

硬件需求

几乎零门槛——不需要 GPU，不需要大内存。smfs 本体是编译好的 Rust 二进制，运行时内存占用仅 512MB 左右，本地 SQLite 缓存按文件大小弹性增长。

技术亮点

纯 Rust 实现，无运行时依赖：从编译产物到 SQLite 缓存，全部静态链接，安装包就是一个可执行文件。性能优异，内存占用极低。
FUSE + NFS 跨平台虚拟文件系统：Linux 用 fuser（成熟的 FUSE 绑定），macOS 用 nfsserve（纯 Rust NFS 服务端），两套方案分别针对不同内核能力优化，避免 macFUSE 的安装噩梦。
SQLite WAL 持久缓存：rusqlite 内置 SQLite，WAL 模式保证并发安全，parking_lot::Mutex 序列化所有写操作。本地缓存让离线写入成为可能。
Unix Socket IPC 守护进程：daemon 模块用 tokio + Unix Domain Socket 实现控制通道，CLI 通过 socket 通信，操作即插即用，不污染全局进程空间。
Shell wrapper 零侵入设计：不需要修改 Agent 的 tool 调用逻辑，不需要配置 API，grep 进去就自动变语义搜索。这是本项目最有创造力的 UX 设计。

局限与挑战

强依赖 Supermemory 云端服务：smfs 本身是「客户端」，所有语义能力来自 Supermemory API，没有本地 embedding 模型。如果没有网络或 Supermemory 服务不可用，语义搜索完全失效，只能当普通网盘用。
需要 FUSE 权限：Linux 上 mount FUSE 通常需要 root 或 CAP_SYS_ADMIN 权限。在某些受限环境（共享主机、容器非特权模式）无法使用。
仅支持 macOS/Linux：Windows 用户无法使用，目前没有 WSL2 或其他替代方案的计划。
Docker 体验不理想：虽然有 Dockerfile，但运行时需要特权模式和 FUSE 设备，在大多数容器环境（K8s、ECS）中无法使用。

项目质量评估

维度	评分	说明
代码质量	★★★★★	纯 Rust（`#![forbid(unsafe_code)]`），完整类型系统，模块边界清晰
文档质量	★★★★☆	README 详细，配有多平台安装说明，但高级用法文档较少
测试覆盖	★★★★☆	各子模块有测试文件，GitHub Actions CI
活跃度	★★★★☆	2024 年中发布，持续更新，issues 反馈积极
许可	MIT	非常宽松，商业可用

总结

smfs 的核心价值主张非常清晰：让 AI Agent 的记忆系统变成一个本地文件夹，从而天然兼容整个 Unix 工具链。它不需要你改任何 Agent 代码，不需要配置复杂的向量数据库，install 之后 mount 就能用。

对于有自主 Agent 开发需求的团队，smfs 提供了一种极低摩擦的持久化方案——把需要跨会话积累的上下文（项目背景、技术债务、需求变更）全部写进 Supermemory，Agent 每次新对话都能自然地 grep 到相关内容。

不过，它的前提是接受 Supermemory 的云端服务——如果你的数据有严格本地化要求，或网络不可靠，smfs 的语义能力就成了无本之木。这是选择它之前必须权衡的核心问题。

适合场景：AI 编程助手开发者、自定义 Agent 框架、团队知识管理、长期多轮对话系统。 不适合场景：网络受限环境、Windows 用户、需要完全本地化部署的场景。

smfs：一个为 AI Agent 量身打造的「记忆文件系统」

背景：Agent 为什么需要「记忆」？

smfs banner

技术架构：Rust 核心 + 三层抽象

smfs 的代码仓库是一个 Cargo Workspace，包含两个核心 crate：

核心层：crates/smfs-core

smfs-core 是整个项目的「引擎」，按职责拆分为 6 大模块：

模块	职责	关键技术
`vfs`	虚拟文件系统 trait + MemFs 实现	自定义 FileSystem trait，POSIX 兼容接口
`mount`	FUSE/NFS 挂载适配	`fuser`（Linux）、`nfsserve`（macOS）纯 Rust 实现
`sync`	本地缓存与 Supermemory API 双向同步	推（push）/拉（pull）引擎，30 秒轮询
`api`	Supermemory 后端 HTTP 客户端	`reqwest`（Rust HTTP 库），TLS 支持
`cache`	SQLite 本地持久缓存	`rusqlite`（bundled），WAL 模式，chunk 存储
`daemon`	长期运行守护进程 + Unix Socket IPC	`tokio` 异步运行时，fork dance 守护化

CLI 层：crates/smfs

薄薄的命令行调度层，所有用户命令（login、mount、unmount、sync、grep）都定义在这里。核心逻辑委托给 smfs-core，不做任何业务处理。

云端适配层：bash/

核心功能详解

1. 一键挂载，像访问本地文件一样访问 AI 记忆

# 首次登录（存 API Key）
smfs login

# 挂载名为 agent_memory 的容器到本地
smfs mount agent_memory

# 之后和普通文件夹一样操作
ls agent_memory/
cat agent_memory/memory/notes.md
vim agent_memory/notes/plan.md

2. 语义搜索：让 grep 理解「意思」而不是「字面」

cd agent_memory/

# 语义搜索（理解意图）
grep "OAuth refresh tokens"

# 限定目录 + 语义搜索
grep "design review notes" work/

# 精确字面匹配（任何 flag 都让 grep 回退到原生）
grep -F "exact string" notes.md

3. 记忆生成路径控制

通过 --memory-paths 精确控制哪些路径的内容会被处理为可检索记忆：

# 只处理 /notes/ 和 /journal.md
smfs mount agent_memory --memory-paths "/notes/,/journal.md"

# 纯存储，不生成记忆
smfs mount agent_memory --memory-paths ""

4. 离线 + 增量同步

部署分析

容器化支持

✅ Dockerfile：存在，多阶段构建（Rust builder + Debian slim runtime）
❌ docker-compose：无
❌ Kubernetes：无

跨平台支持

✅ macOS（arm64、x64）：使用 NFS 后端（无需 macFUSE）
✅ Linux（arm64、x64）：使用 FUSE 后端（需要 libfuse3）
❌ Windows：不支持

安装方式

# 方式一：一键脚本（推荐）
curl -fsSL https://smfs.ai/install | bash

# 方式二：Docker
docker run -it --device /dev/fuse --privileged supermemoryai/smfs

Docker 运行需要 --device /dev/fuse --privileged，FUSE 本身要求特权模式，所以在 Docker 里体验并不理想。

硬件需求

几乎零门槛——不需要 GPU，不需要大内存。smfs 本体是编译好的 Rust 二进制，运行时内存占用仅 512MB 左右，本地 SQLite 缓存按文件大小弹性增长。

技术亮点

纯 Rust 实现，无运行时依赖：从编译产物到 SQLite 缓存，全部静态链接，安装包就是一个可执行文件。性能优异，内存占用极低。
FUSE + NFS 跨平台虚拟文件系统：Linux 用 fuser（成熟的 FUSE 绑定），macOS 用 nfsserve（纯 Rust NFS 服务端），两套方案分别针对不同内核能力优化，避免 macFUSE 的安装噩梦。
SQLite WAL 持久缓存：rusqlite 内置 SQLite，WAL 模式保证并发安全，parking_lot::Mutex 序列化所有写操作。本地缓存让离线写入成为可能。
Unix Socket IPC 守护进程：daemon 模块用 tokio + Unix Domain Socket 实现控制通道，CLI 通过 socket 通信，操作即插即用，不污染全局进程空间。
Shell wrapper 零侵入设计：不需要修改 Agent 的 tool 调用逻辑，不需要配置 API，grep 进去就自动变语义搜索。这是本项目最有创造力的 UX 设计。

局限与挑战

强依赖 Supermemory 云端服务：smfs 本身是「客户端」，所有语义能力来自 Supermemory API，没有本地 embedding 模型。如果没有网络或 Supermemory 服务不可用，语义搜索完全失效，只能当普通网盘用。
需要 FUSE 权限：Linux 上 mount FUSE 通常需要 root 或 CAP_SYS_ADMIN 权限。在某些受限环境（共享主机、容器非特权模式）无法使用。
仅支持 macOS/Linux：Windows 用户无法使用，目前没有 WSL2 或其他替代方案的计划。
Docker 体验不理想：虽然有 Dockerfile，但运行时需要特权模式和 FUSE 设备，在大多数容器环境（K8s、ECS）中无法使用。

项目质量评估

维度	评分	说明
代码质量	★★★★★	纯 Rust（`#![forbid(unsafe_code)]`），完整类型系统，模块边界清晰
文档质量	★★★★☆	README 详细，配有多平台安装说明，但高级用法文档较少
测试覆盖	★★★★☆	各子模块有测试文件，GitHub Actions CI
活跃度	★★★★☆	2024 年中发布，持续更新，issues 反馈积极
许可	MIT	非常宽松，商业可用