# Personal research wiki and knowledge graph, kept by your agents

> How researchers and analysts use Cozy as a hosted wiki that their own AI agents maintain: sources kept separate, cited claims, typed links, and lint for stale or unsourced pages.

Updated 2026-11-09. Canonical: https://cozy.cloud/use-cases/researchers

> 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](/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 plus `index.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.

1. Upload files in the browser: up to 1 MB per file and 25 files per selection.
2. 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.
3. 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_context` returns a page with its typed neighbors, excerpts, evidence and warnings in one call.
- `cozy_backlinks` shows 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](/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`, `status` and `as_of` describe 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 into `sources/` become `cites`.

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](/wiki-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](https://obsidian.md/pricing). 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](/compare/obsidian).
- Notion has richer databases and team project management. Its [hosted MCP](https://developers.notion.com/guides/mcp/get-started-with-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](/llm-wiki).

## 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](/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](/compare/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.
