letta-filesystem-to-memfs

Letta Filesystem から MemFS への移行

ユーザーが以前の Letta Filesystem の動作を求めている場合に、このスキルを使用します。ドキュメントをアップロードし、チャンクに分割してエージェントに添付し、エージェントが検索・オープンできるようにします。

MemFS は同じ製品ではありません。Git ベースの Markdown メモリーです。以前のワークフローを再現するには、同梱の CLI を使用します。

1. PDF／ドキュメントから Markdown テキストを抽出します。
2. テキストをチャンクに分割し、documents/<corpus>/<doc>/chunks/ に安定した Markdown ファイルとして保存します。
3. system/filesystem/<corpus>.md に、簡潔で固定されたインデックスを作成します。
4. QMD でコーパスのチャンクファイルのみをインデックス化し、セマンティック検索に使用します。
5. MemFS の Git 差分を確認します。求められた場合にのみコミットします。

クイックワークフロー

# 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 を指定します。
• 同じドキュメントスラッグを再取り込みすると、そのドキュメントの古いチャンクディレクトリが置き換えられるため、チャンクサイズの変更後に古いチャンクが残りません。
• チャンクサイズは約 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 や複雑な表を含む PDF では、まず tools/extracting-pdf-text スキルを使用し、その後、抽出した Markdown／テキストファイルをこのスキルで取り込んでください。

設計上の注意点と特殊なケースについては、references/design.md を参照してください。