# A second brain with AI agents that keep it tidy

> How to run a second brain your AI agents maintain over MCP: plain Markdown pages, cited sources, typed links, health checks and scoped credentials, hosted on Cozy.

Updated 2026-11-09. Canonical: https://cozy.cloud/second-brain-ai

> 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](/mcp-server) for the full surface.

For Claude Code, run this once, then sign in with `/mcp`:

```bash
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`:

```bash
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](/connect/claude-code) and [/connect/codex](/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 and `index.md`.
- `sources/` holds evidence from connectors and importers, with stable IDs, URLs and timestamps. Agents treat it as untrusted data.
- `skills/` holds editable `SKILL.md` files 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](/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](/memory-consolidation) 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](/wiki-health).

## Where other tools are better

- **Obsidian** is local-first and human-edited, with a large plugin ecosystem. Its [pricing page](https://obsidian.md/pricing) 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](https://forum.obsidian.md/t/remote-mcp-server-for-obsidian/117941), 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](/compare/obsidian).
- **Notion** has richer human collaboration and databases. Its [MCP guide](https://developers.notion.com/guides/mcp/get-started-with-mcp) says headless MCP tokens are limited to Business and Enterprise plans. See [Cozy vs Notion](/compare/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

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](/import/markdown) or the [Obsidian](/import/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](/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](/connect/claude-code) and [/connect/codex](/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.
