mfs

---

Modern AI agents run on a huge amount of context — and it's sprawling, scattered, and siloed across dozens of sources and formats. That makes it hard to manage and harder to locate: for any given task, which slice of all that context is the part that actually matters? It piles up in:

• Code & repos — every repo the agent reads or writes
• Memory & skills — past-session transcripts, memory .md files, reusable SKILL.md skills
• Docs & knowledge — PDFs, design specs, Notion, crawled web pages
• Chat & mail — Slack, Discord, Gmail, Feishu
• Issues & CRM — Jira, Linear, HubSpot, Zendesk
• Databases & object stores — Postgres, Mongo, BigQuery, Snowflake, S3, Drive

MFS gathers it under one shell: every source becomes a file-like tree under a stable URI, driven by two skills your agent loads:

• 🗂️ mfs-ingest — the skill that bundles the commands for bringing sources in: mfs add registers and indexes any connector (re-run to re-sync), and mfs connector lists, inspects, and removes them.
• 🔎 mfs-find — the skill that bundles the commands for finding across what's ingested, in two families:
  • Search — search and grep find things fast across huge volumes.
  • Browse — ls, cat, tree, head, tail give progressive, precise navigation down to the exact bytes.

🚀 Quick start

Start the server

Server — start it in one terminal:

• Option A — uv tool (no clone; installs from PyPI, reads local paths directly)

uv tool install mfs-server && mfs-server run

Wait until the server logs show Application startup complete before switching to the client terminal.

• Option B — Docker Compose (isolated; builds the image from source)

git clone https://github.com/zilliztech/mfs.git && cd mfs

docker compose -f deployments/compose/docker-compose.yml up --build

The first build takes a few minutes. The ~600 MB embedding model downloads on the first mfs add and is cached in the mfs-data volume.

Install the CLI

Client — in another terminal, install the CLI and point it at the server:

cargo install mfs-cli

Set environment variables

# server address
export MFS_API_URL=http://127.0.0.1:13619

# option A: reads ~/.mfs/server.token automatically — no export needed
# option B: read the token the container auto-generated
export MFS_API_TOKEN="$(docker compose -f deployments/compose/docker-compose.yml exec -T mfs-server cat /data/server.token)"

Create a tiny sample tree:

mkdir -p /tmp/hello-mfs
echo "Print a greeting to the user." > /tmp/hello-mfs/greet.txt

Then index and search it:

mfs add --upload /tmp/hello-mfs
# --upload bundles + sends the tree to the container
# (omit it under option A: the server reads the path in place)
mfs search "where the greeting is printed" /tmp/hello-mfs

macOS: run xattr -d com.apple.quarantine $(which mfs) once if prompted about an unidentified developer.

Skill install

Install the skills once:

# every project + every supported agent (drop -g for the current project only)
npx skills add zilliztech/mfs --all -g

Pass one or more -a <agent>:

npx skills add zilliztech/mfs -a claude-code -a codex -g

<agent> can be claude-code, codex, cursor, windsurf, github-copilot, gemini-cli, opencode, zed, cline, continue — 70+ agents in all.

npx skills check
npx skills update

For project-level installs, re-run the npx skills add command to update.

📥 Then open your agent (Claude Code, Codex, …) and ask in plain language. First, ingest something:

Use the mfs-ingest skill to spin up a tiny hello-world project in /tmp/hello-mfs
and ingest it

🔍 Then search and read across it:

Use the mfs-find skill to find where the greeting is printed in the hello-mfs
project, and show me the exact lines

🎉 That's it — you're up and running. From here, point MFS at your real sources.

🛠️ The first run is a one-time setup, and the agent walks you through it: it installs the mfs CLI, helps you start a local server, and downloads a ~600 MB local embedding model into ~/.mfs/. Give it a minute. After that the whole stack runs locally and offline — no API key, no GPU, no cloud account.

Don't want the model download? If you already have an embedding-service API key (OpenAI, …), point the server at it instead — see Configure the server.

💡 Use cases

🧠 Your agent's memory and skills

Past-session memory files (.md, .jsonl) and reusable skills become one searchable namespace — the prompt you tuned last week or a decision logged three sessions ago, one query away.

The mfs line is the CLI; the trailing # comment is the same request to an agent (/mfs-ingest or /mfs-find — Codex uses $mfs-ingest / $mfs-find instead of /).

mfs add path/to/memory     # /mfs-ingest index my session memory
mfs add path/to/skills     # /mfs-ingest index my skills
mfs search "the prompt I tuned for refund disputes" --all   # /mfs-find the refund-dispute prompt

file://local/.agents/memory/2026-05-31.jsonl  score=0.88
  {"role":"note","text":"refund-dispute prompt: lead with the order ID, then ..."}

file://local/.agents/skills/support-triage/SKILL.md  score=0.74
  ## Refund disputes — confirm the order ID first, then check the gateway log ...

Open the hit — mfs cat file://local/.agents/memory/2026-05-31.jsonl:

{"role":"note","text":"refund-dispute prompt: lead with the order ID, then ask
for the gateway transaction id; never promise a timeline before the dispute
window is confirmed."}

💻 Your codebases

Index the repos your agent reads or writes and grep them by meaning — find the helper by what it does, not the name you've forgotten.

mfs add path/to/repo   # /mfs-ingest index my repos
mfs search "where do we retry failed webhook deliveries?" path/to/repo   # /mfs-find our webhook retry logic

file://local/repos/payments/webhooks/deliver.go  score=0.84
  87  // cap exponential backoff at 6 attempts, then dead-letter
  88  func (d *Dispatcher) retryDelivery(ev Event) error {

file://local/repos/payments/webhooks/deliver_test.go  score=0.69
  TestRetryDelivery_DeadLettersAfterMaxAttempts ...

Open the matching lines — mfs cat file://local/repos/payments/webhooks/deliver.go --range 80:110:

// retryDelivery re-sends a webhook with capped exponential backoff.
func (d *Dispatcher) retryDelivery(ev Event) error {
    for attempt := 1; attempt <= maxAttempts; attempt++ {
        if err := d.post(ev); err == nil {
            return nil
        }
        time.Sleep(backoff(attempt))
    }
    return d.deadLetter(ev)   // give up after maxAttempts
}

📄 Documents, images, any format

PDFs, Word docs, Markdown, screenshots — MFS converts each to text locally (PDF / docx → Markdown, no API key), and with a vision model on it describes images too. One search spans every format.

mfs add path/to/docs           # /mfs-ingest index my design docs
mfs add path/to/screenshots    # /mfs-ingest index my screenshots
mfs search "audit-log retention and the dashboards that show it" --all   # /mfs-find audit-log retention + dashboards

file://local/design-docs/data-governance.pdf  score=0.86
  ... Audit logs are retained for 400 days, then moved to cold storage; access
  beyond 90 days requires a break-glass approval ...

file://local/screenshots/grafana-2026-06-02.png  score=0.71
  A Grafana dashboard; the p99 latency panel climbs to ~800 ms around 14:10,
  well above the 200 ms band on the other panels ...

Open the hit — mfs cat file://local/design-docs/data-governance.pdf:

# Data Governance — Audit Logs

Audit logs are retained for **400 days**, then moved to cold storage. Access
beyond 90 days requires a break-glass approval recorded in the change log.

☁️ Cloud drives and buckets

Mount a Google Drive or S3 bucket; its files become searchable text alongside your local ones — no syncing, no downloads.

mfs add gdrive://my-drive --config ./gdrive.toml   # /mfs-ingest add my google drive
mfs add s3://acme-exports --config ./s3.toml       # /mfs-ingest add our s3 exports bucket
mfs search "the Q3 board deck" --all               # /mfs-find the Q3 board deck

gdrive://my-drive/Board/2026-Q3-review.pdf  score=0.87
  ... Q3 highlights: net revenue retention 118%, two enterprise logos closed ...

s3://acme-exports/finance/2026-q3-summary.csv  score=0.70
  quarter,net_revenue,nrr,churn  2026Q3,4.2M,1.18,1.4% ...

Open the hit — mfs cat gdrive://my-drive/Board/2026-Q3-review.pdf:

# 2026 Q3 Board Review

- Net revenue retention: 118%
- New enterprise logos: Globex, Initech
- Gross margin: 79% (+2 pts QoQ)

🌍 Online sources

Crawl a docs site or mount a GitHub repo with its issues — remote content lands in the same namespace as your local files.