letta-filesystem-to-memfs

Letta Filesystem 到 MemFS

当用户需要旧版 Letta Filesystem 的行为时使用此技能：上传文档、将其分块、关联到 Agent，并让 Agent 搜索和打开这些文档。

MemFS 并非同一款产品。它是基于 git 的 Markdown 记忆。要模拟旧工作流，请使用捆绑的 CLI：

1. 将 PDF/文档提取为 Markdown 文本。
2. 将文本分块，保存为 documents/<corpus>/<doc>/chunks/ 下稳定的 Markdown 文件。
3. 在 system/filesystem/<corpus>.md 下编写一个简短的固定索引。
4. 仅将语料库分块文件编入 QMD 索引，以便进行语义搜索。
5. 检查 MemFS 的 git diff。仅在用户要求时提交。

快速工作流

# Set this to the skill directory shown in the skill load header.
SKILL_DIR="/path/to/letta-filesystem-to-memfs"

# From any directory. MEMORY_DIR should point at the target agent's memfs repo.
uv run --with pymupdf \
  "$SKILL_DIR/scripts/letta_fs_to_memfs.py" ingest \
  --memory-dir "$MEMORY_DIR" \
  --corpus product-docs \
  --source ./docs/ \
  --source ./guide.pdf \
  --source https://arxiv.org/pdf/2310.08560

cd "$MEMORY_DIR"
git status --short
git diff --stat

以词法方式搜索分块语料库：

uv run "$SKILL_DIR/scripts/letta_fs_to_memfs.py" search \
  --memory-dir "$MEMORY_DIR" \
  --corpus product-docs \
  "memory hierarchy" \
  -n 5

使用 QMD 进行语义搜索。CLI 会仅针对分块文件创建一个限定语料库范围的 QMD 集合：

uv run "$SKILL_DIR/scripts/letta_fs_to_memfs.py" qmd setup \
  --memory-dir "$MEMORY_DIR" \
  --corpus product-docs

uv run "$SKILL_DIR/scripts/letta_fs_to_memfs.py" qmd query \
  --memory-dir "$MEMORY_DIR" \
  --corpus product-docs \
  "memory hierarchy" \
  -n 5

更改语料库文件后使用 qmd reindex；需要仅按关键词搜索或仅按向量搜索时，使用 qmd search / qmd vsearch。

布局

摄取脚本会写入：

system/filesystem/<corpus>.md
  Pinned index and operating instructions for the corpus.

documents/<corpus>/manifest.md
  Corpus manifest.

documents/<corpus>/<doc-slug>/manifest.md
  Per-document metadata and chunk table.

documents/<corpus>/<doc-slug>/chunks/chunk-0001.md
  Chunk content with frontmatter metadata.

documents/<corpus>/chunks.jsonl
  Machine-readable chunk export for custom indexing or debugging.

旧 API 对照

旧版 Filesystem	MemFS 模拟方式
folders.create	--corpus <name> 会创建 documents/<corpus>/
folders.files.upload	letta_fs_to_memfs.py ingest --source <file-or-directory-or-url>
OCR/分块/嵌入任务	在本地提取并分块；使用 qmd setup / qmd reindex 进行语义搜索
agents.folders.attach	启用 MemFS，然后在适当时检查并同步仓库更改
open_file	按路径读取分块 Markdown 文件
grep_file	rg 或 letta_fs_to_memfs.py search
search_file	使用 letta_fs_to_memfs.py qmd query 搜索语料库分块集合

启发式规则

• 仅将 system/filesystem/<corpus>.md 用作简短的常驻可见索引。
• 不要将完整文档固定放入 system/；这会使提示词变得臃肿。
• 将分块保存在 system/ 之外，通常放在 documents/<corpus>/... 下。
• 向 --source 传入目录会递归摄取支持的文件（.pdf、.md、.txt、.json、.csv、.html、.xml）。
• 对于杂乱的目录，使用 --glob / --exclude。默认排除 .git、node_modules、.venv 和 __pycache__。
• URL 下载默认使用 --max-download-mb 100；设为 0 表示不限制。
• 重新摄取相同文档 slug 时，会替换该文档旧的分块目录，因此更改分块大小后不会残留过期分块。
• 分块大小建议设为 2,000-4,000 个字符，重叠部分为 200-500 个字符。
• 用户需要对大量分块进行语义搜索时，使用 CLI 的 qmd 子命令。
• 在生成的文件中保留源 URL、校验和、页标记、分块编号和语料库名称。

CLI 参考

uv run --with pymupdf "$SKILL_DIR/scripts/letta_fs_to_memfs.py" ingest --help
uv run "$SKILL_DIR/scripts/letta_fs_to_memfs.py" search --help
uv run "$SKILL_DIR/scripts/letta_fs_to_memfs.py" qmd setup --help
uv run "$SKILL_DIR/scripts/letta_fs_to_memfs.py" qmd query --help

仍保留兼容旧示例的包装器：

uv run --with pymupdf "$SKILL_DIR/scripts/ingest_documents.py" --memory-dir "$MEMORY_DIR" --corpus docs --source ./docs
uv run "$SKILL_DIR/scripts/search_corpus.py" --memory-dir "$MEMORY_DIR" --corpus docs --query "refund policy"

PDF 说明

摄取脚本遇到 PDF 时会使用 PyMuPDF。请使用 uv run --with pymupdf ... 运行。

对于扫描版 PDF 或复杂表格，请先使用 tools/extracting-pdf-text 技能，然后用此技能摄取提取出的 Markdown/文本文件。

设计说明和边缘情况请参阅 references/design.md。