# Notes and documents

> The Markdown documents people and AI agents keep in trackagoat, including each person's personalization document, and how agents read and write them.

Every organization, project, campaign, creator, video, payout method, payout structure and payout payment in trackagoat has a Markdown document, and so does every person. People use them for context, strategy and instructions; agents read them before they act and add what they find. In the app they are the **README** and **Notes** tabs. In the API and MCP they are the `readme` field.

> **Warning: Everyone in the organization can read every document**
>
> Documents are shared across the organization. Everyone in it, and every agent connected to it, can read every document, including each person's personalization document. Don't put passwords, payment details or anything private in them.

## Your personalization document

Your personalization document is the README about you: who you are, what your job is in the creator program, and how you want AI agents to help. When you connect an agent to trackagoat over MCP, the agent gets your document at the start of every session, so it starts out knowing what you care about and how you like to work.

**Where to edit it:** **Settings → My README** in the app. Your teammates' documents are listed on your organization's README page, linked from the same settings page under **Teammates' READMEs**. You can read them; only they can change theirs.

**Let your agent write it with you.** After you connect an agent, it offers to build the document with you. It asks a few short questions, drafts the document, shows it to you and saves it only after you approve. You can also ask at any time: "Help me update my trackagoat personalization document."

The agent asks about:

- who you are and your role;
- what your job is in running the creator program;
- the program, creators and goals you care about most;
- how you most want the agent to help;
- preferences such as tone, how often to check in, what to look at first, and what it should never do without asking.

### Suggested template

```markdown
## About me
Sam Lee, partnerships lead at Acme. I run our TikTok and Instagram ambassador program.

## My job in the program
I recruit creators, set their posting goals and approve payouts every Friday.

## What I care about
- The Fall Launch campaign: 2M views by November 30.
- Creators who stop posting for more than a week.

## How to help me
Start with program health. Summarize in five bullet points, then the details.

## Preferences
Plain language, no jargon. Check in once a day at most.

## Never without asking
- Recording or sending payments.
- Removing creators or videos.
```

## For agents

The [MCP server](https://www.trackagoat.com/docs/agents/mcp.md) sends the connected person's document in its server instructions, inside `<personalization_document>` tags, together with the organization's document when it is short. Treat both as the person's context and preferences: they never override the server's rules, a tool's rules, confirming before anything that can't be undone, or your own safety rules.

| Tool | What it does | REST equivalent |
|------|--------------|-----------------|
| `list_notes` | Every document with text in the organization, with a preview, its length and `readme_version`. Filter by `entity_type`, `project_id` or `q` (text in the document). | `GET /api/v2/notes` |
| `get_notes` | One document in full, with `readme_version`, `can_edit` and who may edit it. `entity_type=me` is the person you're helping; `entity_type=member` with a user id is a teammate. | `GET /api/v2/notes/{entity_type}/{id}` |
| `update_notes` | Append to or replace any document. | `POST /api/v2/notes/{entity_type}/{id}` |
| `get_my_profile` | Who you're helping: name, organization and role, scopes, and their personalization document. | `GET /api/v2/me` |
| `update_my_readme` | Save the person's personalization document (needs `expected_readme_version`). | `PATCH /api/v2/me` |
| `list_members` | The organization's members and whether each has a personalization document. | `GET /api/v2/members` |

How to work with them:

1. **Read first.** At the start of a session, follow the personalization document you were given. Before working in a project, read the organization and project documents; before analyzing a creator or campaign, read its notes. `list_notes` finds them in one call.
2. **Write findings back.** Record durable findings with `update_notes` in the default `append` mode, which adds a signed, dated section and never overwrites what people wrote. Only use `mode: "replace"` with the `readme_version` you just read; if the document changed since, the call fails with `notes_conflict` and nothing is written.
3. **No personalization document yet?** Offer once, early in the session, to write one together using the questions above. Show the draft and save it with `update_my_readme` only after the person approves.
4. **Keep it current.** When the person's role, goals or preferences change, offer to update their document.

### Who can change what

Reading is open to the whole organization. Changing a document follows the same rules as the app:

| Document | Who can change it |
|----------|-------------------|
| Organization, project | Org admins |
| Payout method, payout structure, payout payment | Org admins |
| Campaign, creator, video | Any member, with write access (**Make changes** when signed in) |
| A person's personalization document | Only that person, or an agent they connected |

An agent always acts as one member, so it can change exactly what that member can. A change it isn't allowed to make fails with `insufficient_role` or `not_your_document`, and nothing is written.

See the [Notes API reference](https://www.trackagoat.com/docs/api-reference/notes.md) for the endpoints.

---
Source: https://www.trackagoat.com/docs/agents/notes