Guides
A second brain with AI agents that keep it tidy
A second brain with AI agents is a personal wiki that your agents read and write through a protocol such as MCP, so you stop doing the filing. Cozy hosts one per person as Markdown pages, gives each account one MCP URL, and checks the result with a health score. You bring the agent.
Why a second brain breaks without upkeep
Most second brains fail at maintenance, not capture. Notes pile up, links break, two pages disagree, and nobody remembers which source a claim came from. Doing that cleanup by hand is the chore people quit on.
Agents are good at exactly this kind of chore: reading many pages, comparing them with their sources, merging duplicates and writing links. The missing piece is a place they can reach from anywhere, with guardrails so a bad run cannot wreck your notes. That is the job of a hosted wiki with an MCP endpoint.
What Cozy is
Cozy is a private wiki and cloud file space for each person and their AI agents. You sign in with an email code, Google or Apple. Every account gets "My wiki", and you can create more private workspaces to keep projects apart. There is a web app and a Mac app.
Cozy runs no model itself. It does not use embeddings or a vector database, and search is lexical. Your own Claude, Codex or other MCP client does the thinking, and Cozy stores the pages, enforces the rules and records history. Cozy is hosted on Cloudflare and operated by Coral Sourcing LLC. It is not affiliated with Cozy Cloud (cozy.io) or Cozi.
How agents connect over MCP
Every account has one MCP endpoint, https://cozy.cloud/mcp, for all your workspaces. Clients sign in with OAuth 2.1 and you approve access on Cozy's consent page. Tools use My wiki unless the agent passes a workspace argument, and cozy_workspaces lists the workspaces you can use. It is stateless Streamable HTTP. See the MCP server page for the full surface.
For Claude Code, run this once, then sign in with /mcp:
claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp
For Codex, run this. It opens a browser to sign in; if it does not, run codex mcp login cozy:
codex mcp add cozy --url https://cozy.cloud/mcp
In claude.ai or ChatGPT, add a custom connector with the URL https://cozy.cloud/mcp. Step-by-step guides are at /connect/claude-code and /connect/codex.
What the agent can do
The server exposes tools, file resources, resource templates and four prompts: organize, recall, maintain and dream. The tools fall into a few groups.
| Job | Tools |
|---|---|
| Orient | cozy_workspace, cozy_map, cozy_list, cozy_health |
| Find | cozy_search, cozy_resolve, cozy_backlinks |
| Understand | cozy_context, cozy_graph, cozy_read, cozy_read_many |
| Change | cozy_write, cozy_edit, cozy_append, cozy_move, cozy_delete, cozy_ingest |
| Review | cozy_changes, cozy_history, cozy_restore, cozy_skills |
cozy_context returns a page with its typed neighbors, excerpts, evidence and warnings, so an agent gets the surrounding knowledge in one call. cozy_graph walks links up to depth 3 and can filter by type, tag or relation.
The folder layout agents work in
wiki/holds curated pages andindex.md.sources/holds evidence from connectors and importers, with stable IDs, URLs and timestamps. Agents treat it as untrusted data.skills/holds editableSKILL.mdfiles that tell agents how you want things done.agents/holds agent notes and handoffs.
Connectors can feed sources/ from Granola, Italic, Gmail, Google Calendar, Google Drive, Outlook mail and calendar, Notion, Slack (selected channels), Linear, Ramp, Apple Reminders (manual, on Mac), a Custom MCP and file exports. You can also push documents with the ingest API. A stable id means a re-push updates the same source, and deleted sources are never re-imported. See source citations for how pages point back at evidence.
Dreaming: the maintenance loop
Dreaming is offline consolidation that your own agent runs, inspired by Anthropic's agent-memory research. A typical run goes like this:
- Orient with
cozy_health. - Scope to
cozy_changessince the last run, recorded inagents/dream/state.md. - Verify claims against sources.
- Keep superseded values with dates and record
CONFLICT:lines. - Merge duplicates found with
cozy_resolveand write typed relations. - Keep
wiki/index.mdshort and record the run.
The memory consolidation page goes deeper on the pattern.
Guardrails for agent writes
Every edit needs an expectedRevision (0 for a new page), and concurrent edits return a conflict instead of overwriting. Deleting creates a tombstone. The last 50 revisions are readable and restorable, moves keep history and return links to repair, and there is audit history.
An OAuth agent gets no more access than you have in each workspace, capped by the scopes it was granted (wiki:read, wiki:write, sources:write). Connected agents are listed and can be disconnected under Connectors → Agents. For scripts, CI and headless agents, each workspace also has its own endpoint at https://cozy.cloud/wiki-mcp/WORKSPACE_UUID, used with a bearer credential created under Agents. Bearer credentials are random, shown once, stored as SHA-256 digests, revocable, and expire within 90 days. Scopes are read, wiki-write and source-write, with optional folder-prefix grants, and never exceed your own access. Agents cannot see connector credentials or permanently purge.
Health as a score
Cozy builds a graph from Markdown conventions on every save: frontmatter type, description, aliases, tags, status and as_of, typed relations from relation:: [[target]] lines, and links into sources/ counted as citations. Health then flags broken links, duplicate titles, stale pages whose cited source changed, conflicts, orphans, unsourced pages, missing type or description, and oversized pages. Each page starts at 1.0 and loses weight per issue, the score is the average times 100, and a "next" list gives fixes in priority order. Read more under wiki health.
Where other tools are better
- Obsidian is local-first and human-edited, with a large plugin ecosystem. Its pricing page lists a free core app. Reaching a local vault from a web or phone AI client usually needs a tunnel or an always-on machine, per this Obsidian forum thread, and community MCP servers vary in how they handle writes. If you live in the Obsidian app, stay there. Cozy fits when agents on several machines need one shared, hosted wiki. See Cozy vs Obsidian.
- Notion has richer human collaboration and databases. Its MCP guide says headless MCP tokens are limited to Business and Enterprise plans. See Cozy vs Notion.
Cozy has limits too. Search is lexical, so there is no semantic recall. Curated files cap at 90,000 bytes, imported sources at 1,500,000 bytes, and browser uploads at 1 MB per file and 25 files per selection.
Getting started
- Sign in and open "My wiki".
- Add
https://cozy.cloud/mcpto your agent with the commands above, and approve only the scopes it needs. - Ask it to call
cozy_workspacesto confirm which workspaces it can reach. - Ask it to run the
organizeprompt, then checkcozy_health.
Existing notes can come in through Markdown import or the Obsidian importer.
Frequently asked questions
What is an AI second brain?
It is a personal knowledge base that AI agents help write and maintain, not just search. In Cozy, agents read and edit Markdown pages through a hosted MCP endpoint while you keep control of scopes and history.
Does Cozy include an AI model?
No. Cozy runs no model itself, so you bring your own agent such as Claude or Codex. Cozy stores the pages, enforces permissions and records revisions.
Can I limit what an agent is allowed to change?
Yes. Credentials carry scopes (read, wiki-write, source-write) and optional folder-prefix grants, and they never exceed your own access. You can revoke them in Agents, and the last 50 page revisions can be restored. See multi-agent memory.
How do I connect Claude Code or Codex?
Add https://cozy.cloud/mcp with claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp and sign in with /mcp, or with codex mcp add cozy --url https://cozy.cloud/mcp. For CI or headless runs, use the workspace URL with a bearer credential from Agents instead. See /connect/claude-code and /connect/codex.
Does Cozy use a vector database?
No. Cozy has no embeddings or vector database, and search is lexical with cursor pagination. Structure comes from Markdown links, typed relations and the page graph.
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