# Memory, notes and lessons

> Save notes for later, see what works for an X account by post format, how Xholic turns due notes into drafts, the spotlight creators it follows and tests, the account's sub-topics and the weekly plan.

Source: https://docs.xholic.ai/api/memory/

Every AI tool forgets once you leave it. Xholic keeps what matters about an X account: what the user wants to do later, and what has actually worked for them, measured against their own normal.

## Notes

A note is something to act on later: a post to make ("something like this Thursday"), a plan, a test to run, a finding, or work another agent finished that is worth posting about.

- `add_note` (`POST /v1/notes/add`, `xholic notes add`) saves one. Pass `due` for a date, or `trigger` to wait for an event, and `posts` for the X posts it is about. Xholic adds those posts' numbers and why they worked.
- `find_notes` (`GET /v1/notes/find`) searches open notes, or `status: "DONE"`, `"STALE"` or `"DROPPED"` for history.
- `update_note` changes text, due date or trigger, or marks a note `DONE` or `DROPPED`. `delete_note` removes one; `add_note` can be undone.

Notes need only the default read and write access. Use `remember` for lasting facts and preferences about the user, and `add_note` for things to do.

**Writing from a note.** Pass the note's id as `noteId` to `show_drafts`, `save_draft` (`POST /v1/drafts/save`) or `schedule_post`. The post carries a "Why this?" link back to the note, the note never writes duplicate drafts for that idea, and it closes as soon as the post is scheduled or posted, from any surface. Before a fired note writes drafts, Xholic also checks the queue and the last 7 days of posts for the same idea and links that post instead.

**Drafts your AI shows are saved.** `show_drafts` saves each draft to the user's Xholic drafts (nothing is posted), labelled with the app that wrote it. Scheduling or posting from the card replaces the saved draft instead of copying it (`fromDraftId`). Pass `save: false` to preview options the user hasn't picked from.

```json
{
  "title": "Our version of the \"who's in?\" post for AI founders",
  "body": "User loved this one-line call for AI people: 164 replies on 197 likes.",
  "due": "2026-10-30",
  "posts": ["https://x.com/NickpxJ/status/1850000000000000000"]
}
```

### Triggers

| `trigger.type` | Fires when |
|---|---|
| `OWN_SPIKE` | The account's best follower day this month, or a post at 3× its normal or more |
| `MILESTONE` | Followers cross `followers` (the next round number when left out), or posts cross `posts` |
| `TRACKED_POSTS` | One of `handles` posts, optionally about `topic` |
| `TOPIC_HEATS` | `topic` shows up in the account's trends |

A note with `due` fires about two hours early, so its drafts are ready on time. Drafts are only written between 9 AM and 10 PM in the user's timezone; a trigger that fires at night gets its drafts at 9 AM.

### What happens when a note fires

When a note links a post, Xholic writes two drafts from it through Remix: the format and idea, never the other author's claims, with real numbers from the trigger. It uses the usual draft credits. The drafts go to the user's queue as drafts, and the note shows on Home. **Nothing ever posts by itself.** Each draft carries a "Why this?" line back to its note.

Once a post made from a note settles (24 hours), the result is written back into the note, for example "1.8× your normal replies", and the note moves to History.

Bookmarks, likes and saved links become notes on their own when the saved post is a format worth adapting, so the user never has to write one.

## Lessons

`whats_worked_for_me` (`GET /v1/lessons/list`) returns what works for the account by post format. Every own post is compared with the median of the account's comparable posts (same weekday or weekend, within two hours of the time of day, last 60 days) on the metric its format is built for: replies for questions and takes, bookmarks for lists and frameworks, total engagement for the rest.

| Strength | Means |
|---|---|
| Being tested | Fewer than 3 tries, or not working yet |
| Early sign | 2 of the latest 4 tries above normal (a win is 1.2× or more) |
| Seems to work | 3 of the latest 4 |
| Works consistently | 4 of the latest 5, at a median of 1.5× or more |
| Faded | No new result for 60 days |

Until the account has its own lessons, niche lessons come from similar accounts and say so. Lessons are evidence, never rules. `rate_lesson` records the user's "that's right" or "that's wrong"; a wrong one stops being used.

`get_me` includes the strongest lessons and the notes coming up, so every agent starts from the same picture.

## Spotlight creators

Besides the up to 3 creators the user picks themselves, Xholic keeps its own list of up to 30 creators worth learning from. It adds them from the user's saves (X bookmarks weigh most), the people they talk with, and accounts rising on their topics. It then tests each one against the user's own results: a post built from a spotlight creator's post, or shaped like one the user saved, is compared with the account's normal.

| Status | Means |
|---|---|
| New | Just added; not tested yet |
| Testing | Being tried in drafts, reply targets and the posts Xholic watches |
| Works for you | 2 or more wins, at least one from a post built directly from theirs |
| Removed | Posts built on their style didn't beat the user's normal, they stopped posting, the user stopped saving or replying to them, or stronger creators took their place; can come back after 30 days |

The list updates once a day, adding and removing at most 5 creators each (up to 10 adds on an account's first day). Every change goes into the memory timeline with its reason, and the session brief (`get_brief`) mentions what changed since the last session.

- `get_spotlight` (`GET /v1/spotlight/list`, `xholic spotlight list`) returns the user's picks, Xholic's list with each creator's status, reason and record, and, with `includeRemoved`, the recently removed ones. `get_me` carries the top 10.
- `pin_spotlight_creator` (`POST /v1/spotlight/pin`) makes one of them a user pick, when a pick slot is free.
- `hide_spotlight_creator` (`POST /v1/spotlight/hide`) takes one off for good: Xholic never adds them back on its own. `restore_spotlight_creator` (`POST /v1/spotlight/restore`) undoes a hide or brings back a removed creator, who then stays until the user hides them again.

Pin, hide and restore only when the user asks; the list keeps itself up to date. The user's own picks are never removed automatically.

## Sub-topics

Inside the account's niche (say, lifestyle) Xholic keeps 5 to 8 sub-topics, such as home, outfits, travel, fitness and festivals. It proposes them from what the user says they post about and from what they reply to, save and post, and the user approves them once. Posts then rotate across them, inside the niche and never outside it. Each sub-topic shows how often it was posted in the last 14 days, how its posts did against the account's normal, and what's beating its authors' usual right now among the user's creators and peers (stored data only).

- `subtopics.list` (`GET /v1/subtopics/list`, `xholic subtopics list`) returns the sub-topics with status (suggested, active, removed), coverage, lesson and trend items.
- `subtopics.save` (`POST /v1/subtopics/save`, `xholic subtopics save`) approves, removes, restores, adds, edits or weights them. Call it only when the user asks.

## The weekly plan

Xholic keeps one plan per week: post slots by day and time, each with a sub-topic, the reason people would respond, a format, a draft and a why, plus the week's test (one open question, such as afternoon against evening posts, tested on specific slots). It's built early on Monday in the user's timezone and again after they change direction. Nothing is posted until the user approves each post.

- `get_week_plan` (`GET /v1/plan/week`, `xholic plan week`) returns this week's plan, building it if missing.
- `update_plan_slot` (`POST /v1/plan/update-slot`) changes a slot's sub-topic, reason, time or text.
- `approve_plan_slot` (`POST /v1/plan/approve-slot`) schedules one slot after the user approves it; the week's test starts with its first approved slot.
- `rebuild_week_plan` (`POST /v1/plan/rebuild`) rebuilds the unapproved slots.

`check_draft` also checks every draft against the account's own writing rules (`RULE_CONFLICT`, blocking) and flags details nothing Xholic knows backs, such as a named outfit, a trip or a number (`UNVERIFIED_SPECIFIC`, advice; blocking when the rules say never to invent them).

## Cost

Reading notes, lessons and the spotlight is free, and learning is never charged in credits. Only the drafts a fired note writes use the usual draft credits.
