A second brain with AI agents that keep it tidy

Updated · By the Cozy team

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.

JobTools
Orientcozy_workspace, cozy_map, cozy_list, cozy_health
Findcozy_search, cozy_resolve, cozy_backlinks
Understandcozy_context, cozy_graph, cozy_read, cozy_read_many
Changecozy_write, cozy_edit, cozy_append, cozy_move, cozy_delete, cozy_ingest
Reviewcozy_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

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:

  1. Orient with cozy_health.
  2. Scope to cozy_changes since the last run, recorded in agents/dream/state.md.
  3. Verify claims against sources.
  4. Keep superseded values with dates and record CONFLICT: lines.
  5. Merge duplicates found with cozy_resolve and write typed relations.
  6. Keep wiki/index.md short 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

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

  1. Sign in and open "My wiki".
  2. Add https://cozy.cloud/mcp to your agent with the commands above, and approve only the scopes it needs.
  3. Ask it to call cozy_workspaces to confirm which workspaces it can reach.
  4. Ask it to run the organize prompt, then check cozy_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