Use cases
Personal research wiki and knowledge graph, kept by your agents
A research wiki maintained by agents works best when evidence and conclusions stay separate. In Cozy, papers, notes and exports go into sources/, your own agent writes wiki pages that link back to them, and every save updates a graph of typed relations. Health then flags unsourced pages and pages left stale after a source changed.
The problem researchers actually have
Literature piles up faster than anyone can synthesize it. You read a paper, take notes, and three weeks later you cannot say which claim came from which source, or whether a later paper contradicted it. Asking a chat assistant to summarize your folder each time repeats the work and leaves nothing behind.
The alternative is a wiki that an agent keeps current as material arrives. The pattern is often called an LLM wiki: raw sources, a curated layer of pages written by the agent, and a periodic lint pass. Cozy hosts that layout for you and exposes it to the agent you already use.
Cozy runs no model itself. You bring Claude, Codex, ChatGPT or another MCP client, and that agent does the reading and writing.
How the workspace is laid out
Every Cozy account gets a workspace called "My wiki". Inside it, four folders carry different jobs.
sources/holds evidence: imported papers, meeting notes, email, exports. Each source has a stable ID, a URL where one exists, and timestamps. Agents treat this folder as untrusted data, so text inside a PDF cannot instruct them.wiki/holds curated pages plusindex.md. This is the layer you read.skills/holds editable SKILL.md files, for example a literature-review procedure you refine over time.agents/holds agent notes and handoffs between sessions.
Files are Markdown, text, JSON or CSV. Curated files can be up to 90,000 bytes and imported sources up to 1,500,000 bytes, which covers most paper text, transcripts and exported tables.
Getting sources in
There are three routes, and you can mix them.
- Upload files in the browser: up to 1 MB per file and 25 files per selection.
- Push documents through the ingest API with a stable id. Re-pushing the same id updates the same source rather than creating a duplicate, and a source you delete is never re-imported.
- Turn on a connector. Cozy lists Granola, Italic, Gmail, Google Calendar, Google Drive, Outlook mail, Outlook Calendar, Notion, Slack (selected channels), Linear, Ramp, Apple Reminders on Mac, Custom MCP, and files and exports.
New documents land in the built-in Inbox by default. Your agent then calls cozy_ingest and cozy_write to turn them into wiki pages.
Citations are links, and links are checked
A claim on a wiki page cites its evidence with an ordinary Markdown link into sources/. Cozy reads links into sources/ as cites edges in the graph. That gives you a few things you can query rather than trust.
cozy_contextreturns a page with its typed neighbors, excerpts, evidence and warnings in one call.cozy_backlinksshows which pages depend on a given source.- Health marks a page stale when a cited source changed after the page's last edit.
- Health lists uncited sources and unsourced pages, so material you collected but never used, and conclusions with no evidence, both show up.
This does not verify that a claim is true. It tells you where the paper trail is missing or out of date, and the details are on the source citations page.
A graph built from Markdown conventions
On every save, Cozy derives a knowledge graph from the files themselves. No separate database needs maintaining.
- Frontmatter fields such as
type,description,aliases,tags,statusandas_ofdescribe the page. - Other frontmatter keys whose values are wikilinks become typed relations.
- A line like
relation:: [[target]]or a triple of[[a]] | relation | [[b]]states a relation inline. - Plain links become
links_to, and links intosources/becomecites.
For research, useful relation names are things like supports, contradicts, replicates or extends. Cozy accepts open-ended names, so you choose the vocabulary. cozy_graph walks the result to depth 3 and can filter by type, tag or relation. Name links resolve by path, file stem, title or alias, ignoring case and accents, so "Smith 2021" and "smith-2021" can point at the same page.
When two sources disagree, the convention is a CONFLICT: line on the page. Cozy counts those lines, so open disagreements are visible instead of buried.
Maintenance: Health and dreaming
Agent-written wikis drift. Cozy ships two mechanisms against that.
Health scores the workspace. It checks broken links, duplicate titles and aliases, stale pages, conflicts, orphans, pages that index.md cannot reach, unsourced pages, missing type or description, oversized pages and uncited sources. Each page starts at 1.0 and loses weight per issue, and the score is the average times 100. The "next" list orders fixes by priority, so a weekly session can start there.
Dreaming is an offline consolidation pass that your own agent runs, inspired by Anthropic's agent-memory research. The agent orients with cozy_health, scopes to cozy_changes since its last run (recorded in agents/dream/state.md), verifies claims against sources, keeps superseded values with dates, records CONFLICT: lines, merges duplicates found by cozy_resolve, and writes typed relations. The prompt for it is built in as the dream MCP prompt.
Safe edits by agents
Edits require an expectedRevision, so two agents or a person and an agent cannot silently overwrite each other; a concurrent edit returns a conflict. Deletion is a tombstone. The last 50 revisions of each file are readable and restorable, and moves keep history. If an agent rewrites a page badly, cozy_history and cozy_restore undo it.
Agents sign in with OAuth and get no more access than you have in each workspace, capped by the scopes they were granted. For scripts, bearer credentials you create under Agents carry read, wiki-write or source-write scopes, can be limited to folder prefixes, and expire within 90 days. A research assistant can, for example, write to sources/ and wiki/ but never touch skills/. Agents cannot see connector credentials or permanently purge anything.
Where other tools fit
Cozy is not the right answer for everyone.
- Obsidian is free for the core app, and Sync is $4 per user per month billed annually. If you want a local vault, a graph view, plugins and offline work, it is stronger. Cozy files are plain Markdown, so the two can coexist. See Cozy and Obsidian.
- Notion has richer databases and team project management. Its hosted MCP uses OAuth, with headless tokens limited to Business and Enterprise plans.
- Cozy search is lexical, with no embeddings or vector database. For exact titles, names and terms that is fine. For fuzzy semantic retrieval across thousands of unstructured pages you may want something else alongside it.
- Cozy does not read PDFs for you. Your agent or your own tooling converts papers to text before they enter
sources/.
Connecting your agent
Add https://cozy.cloud/mcp to your client as a remote MCP server and approve it on Cozy's consent page. In Claude Code, run claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp, then sign in with /mcp. In Codex, run codex mcp add cozy --url https://cozy.cloud/mcp. One URL covers all your workspaces: tools use My wiki unless the agent passes a workspace argument, and cozy_workspaces lists them. For a script that ingests papers on a schedule, use the workspace URL https://cozy.cloud/wiki-mcp/WORKSPACE_UUID with a bearer credential instead. After that, the agent can call cozy_map for an index grouped by type, cozy_search for lexical lookup, and cozy_read_many for up to 20 pages at once. For the underlying pattern, read about the LLM wiki approach.
Frequently asked questions
Does Cozy read and summarize papers by itself?
No. Cozy runs no model. You connect your own agent, such as Claude or Codex, and it reads sources and writes wiki pages. Convert PDFs to text first, since sources are Markdown, text, JSON or CSV.
How do citations work on a wiki page?
A page cites a source with a normal link into sources/, which Cozy records as a cites edge. Health then flags pages with no sources and pages whose cited source changed after the last edit. See source citations.
Can I record that two papers disagree?
Yes. Put a CONFLICT: line on the page and, if useful, a typed relation such as contradicts between the two pages. Cozy counts conflict lines and lists them in Health.
Can I keep using Obsidian?
Yes. Cozy stores plain Markdown with wikilinks, so you can view the same material in Obsidian. Obsidian is better for offline work and plugins, while Cozy adds a hosted MCP endpoint and lint. See Cozy and Obsidian.
Is the search semantic?
No. Cozy search is lexical and paginated, with no embeddings or vector database. The typed graph and cozy_context help agents find related pages through links rather than similarity.
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