How to move or mirror an Obsidian vault into Cozy

Updated · By the Cozy team

You can import an Obsidian vault into Cozy two ways. Upload Markdown files in the browser (1 MB per file, 25 files per selection), or push them with the ingest API using a stable id per note. Both keep the files as plain Markdown with wikilinks intact, and you can keep using Obsidian next to Cozy.

An Obsidian vault is a folder of Markdown files, and Cozy stores Markdown. That makes the move simple in principle. This page covers what to expect, the two ways to get files in, and how to run both tools side by side.

Before you start

Obsidian is the better tool for some jobs. It runs locally, works offline, has a large plugin ecosystem, and the core app is free per its pricing page. Cozy is a hosted wiki and file space that gives your AI agents one hosted MCP endpoint per account. If you want agents to read a vault from any machine without a tunnel or an always-on laptop, that is the gap Cozy fills. The Obsidian comparison goes through the tradeoffs in more detail.

Cozy accepts Markdown, text, JSON and CSV. Curated pages in wiki/ can be up to 90,000 bytes. Imported sources can be up to 1,500,000 bytes. Attachments such as images and PDFs in your vault are not in that list, so plan to leave them in Obsidian.

What carries over

Cozy builds its graph from Markdown conventions every time a page is saved. Your existing notes already use most of them.

If your vault already uses aliases in frontmatter, those names help Cozy resolve links the way Obsidian does. See typed links for the relation syntax you can add later.

Option 1: browser upload

Use this for a one-time move or a small vault.

  1. Sign in at cozy.cloud with an email code, Google or Apple.
  2. Open the workspace you want, such as My wiki.
  3. Select Markdown files from your vault folder. The limit is 1 MB per file and 25 files per selection.
  4. Upload, then open a few pages and follow their links.

For a larger vault, upload in batches of 25, or use the API below.

Option 2: the ingest API

Use this for large vaults, repeat runs, or a scheduled mirror. Create a bearer credential under Agents, then post documents. The request is JSON with up to 25 documents per request and up to 1.5 MB each.

curl -X POST "https://cozy.cloud/api/wiki/workspaces/$COZY_WORKSPACE/ingest" \
  -H "Authorization: Bearer $COZY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents":[{"id":"obsidian/Projects/Launch.md","content":"# Launch\n\nSee [[Roadmap]]."}]}'

You can also send one file as raw text or Markdown with the id in the query string.

cd "$HOME/Vault"
find . -name '*.md' | while read -r f; do
  id="obsidian/${f#./}"
  curl -s -X POST \
    "https://cozy.cloud/api/wiki/workspaces/$COZY_WORKSPACE/ingest?id=$(printf %s "$id" | jq -sRr @uri)" \
    -H "Authorization: Bearer $COZY_TOKEN" \
    -H "Content-Type: text/markdown" \
    --data-binary @"$f"
done

Documents go to the built-in Inbox by default. They arrive as imported sources, which Cozy treats as evidence from an importer and as untrusted data. Your own agent can then turn the useful ones into curated pages with the cozy_ingest and cozy_write tools. The Markdown import guide covers the same flow for files that do not come from Obsidian.

Why stable ids matter

A stable id makes a re-push update the same source instead of creating a copy. If you build the id from the file path inside the vault, you can run the script again after editing and only changed content is replaced. One rule to know: sources you delete in Cozy are never re-imported, so a repeat run will not bring them back.

Keep using Obsidian alongside Cozy

You do not have to pick one. A workable setup looks like this.

Changes made in Cozy do not flow back into your vault on their own. If an agent edits a page in Cozy, copy the result back yourself, or treat Cozy as the place agents write and Obsidian as the place you write. Decide which side owns each folder before you start so you do not edit the same note in both places.

What to check after importing

Obsidian-specific syntax, such as embeds, callouts and plugin queries, is not part of the conventions Cozy reads, so open a few notes that use them and see how they look. Links to notes you did not import will show as broken.

Run Health to see the full list. It reports broken links, duplicate titles and aliases, orphans, pages missing a type or description, oversized pages and other issues, then lists fixes in priority order. The wiki health guide explains the scoring.

Which option to pick

SituationPick
Under 25 notes, one timeBrowser upload
Large vault or many foldersIngest API
You keep editing in ObsidianIngest API on a schedule
Notes over 1 MB eachIngest API, up to 1.5 MB

Cozy runs no model itself, so any agent that follows the import and cleanup steps is one you bring. Cozy is operated by Coral Sourcing LLC and is not affiliated with Cozy Cloud (cozy.io) or Cozi.

Frequently asked questions

Do my wikilinks still work after importing an Obsidian vault?

Cozy resolves wikilinks by path, file stem, title or alias, ignoring case and accents, so most links resolve. Links to notes you did not import show as broken, and Health lists them.

Can I keep using Obsidian after I import?

Yes. Many people write in Obsidian and push copies to Cozy with the ingest API. Changes in Cozy do not sync back to your vault automatically, so decide which side owns each folder.

What are the file limits for importing?

Browser upload takes up to 1 MB per file and 25 files per selection. The ingest API takes 25 documents per request and 1.5 MB each. Cozy accepts Markdown, text, JSON and CSV.

Will running the import twice create duplicates?

Not if you send a stable id for each note. A re-push with the same id updates that source. Sources you deleted in Cozy are never re-imported.

Where do imported notes appear in Cozy?

Ingested documents go to the built-in Inbox by default as imported sources. Your agent can then promote them into curated pages in wiki/. See Markdown import for details.

Give your agents a memory worth keeping

Cozy gives every account a private wiki that Claude, Codex, ChatGPT and other MCP clients can read and maintain.

Start your wiki