---
title: "About Agents"
description: "Basic Memory agents look after your notes in the cloud. You write their instructions as a note, they run on a schedule, on a new note, or when you ask, and you review what they changed."
canonical_url: "https://docs.basicmemory.com/agents/about"
---
# About Agents

> Basic Memory agents look after your notes in the cloud. You write their instructions as a note, they run on a schedule, on a new note, or when you ask, and you review what they changed.

**Basic Memory agents** are helpers that look after your notes in Basic Memory Cloud. You give an agent instructions in plain language. It runs on a note, reads what it needs, and changes notes the way you asked: it makes task notes from a meeting, links related notes, tidies a folder, or writes a weekly digest. Then you look at what it did and keep it or undo it.

<note icon="i-lucide-flask-conical">

Agents are in **beta**. Every change an agent makes can be reviewed and undone, so start with one agent on one folder and widen from there.

</note>

<theme-image alt="The Agents page for the Harbor launch project: a run in progress, notes changed, runs to review, and credits used" dark="/screenshots/cloud-app/agents-dashboard-dark.png" light="/screenshots/cloud-app/agents-dashboard-light.png">



</theme-image>

## What you need

- A workspace on a usage plan, **Cloud**, **Pro**, or **Business**, or in its free trial. Older seat plans don't run agents. See [Plans and Billing](https://docs.basicmemory.com/teams/seats-and-billing).
- Edit access to the project the agent works in.

Each plan runs a few agents at the same time: **2 on Cloud, 3 on Pro, 5 on Business**, and one on a trial without a card. More runs wait their turn and start when one finishes.

## An agent is a note

An agent is an ordinary note in your project with `type: agent` in its frontmatter. The note's text is its instructions. Agent notes live in the project's `agents/` folder.

```markdown
---
type: agent
title: Meeting follow-up
enabled: true
watch:
  paths: [meetings/]
---
Read the meeting note. Create a task note in tasks/ for each action item,
and link each task back to the meeting note. Then add a Summary section to
the meeting note with two or three sentences.
```

- **title**: the agent's name, shown everywhere the agent appears.
- **enabled**: `true` to let it run, `false` to turn it off. A turned-off agent doesn't run, from a folder or by hand.
- **watch** (optional): folders or patterns it watches for new notes. See [Watch folders and patterns](https://docs.basicmemory.com/agents/add-and-run#watch-folders-and-patterns).
- **schedule** (optional): when it runs on its own, like `"mondays at 8:00"`. See [Run on a schedule](https://docs.basicmemory.com/agents/add-and-run#run-on-a-schedule).
- **timezone** (optional): the time zone its schedule is in, like `America/Chicago`. UTC when left out.
- **web** (optional): `true` to let it search the web and read pages, or a list of the sites it may use. It works only when the workspace allows it. See [Read the web](https://docs.basicmemory.com/agents/add-and-run#read-the-web).

Without a watch or a schedule, the agent runs only when someone starts it.

Because an agent is a note, you can write and change one anywhere you edit notes: in the app, from Claude or another agent connected to Basic Memory, or in the frontmatter directly.

## The Agents page

The **Agents** page shows what your agents are doing and what needs you. Pick a project at the top, or see the whole workspace.

- **Working now**: agents running at this moment, and the note each is working on. **Watch** follows a run live.
- **Notes changed**, **Needs attention**, **To review**, and **Credits**: the last 14 days at a glance. Credits links to **Settings → Usage**.
- **To review**: the queue of agent work nobody has looked at yet. See [Review Agent Runs](https://docs.basicmemory.com/agents/review-runs).
- **Your agents**: every agent, grouped by project, with its folder, what starts it (a schedule says when it runs next), what its last run did, a bar for each of the last 14 days (red when a run failed), and **Run**.

## What agents can do, and what they cost

- An agent works only in its own project, and only as far as the people behind it could: both the person who last saved the agent note and the person who started the run must be able to edit the project.
- An agent can't overwrite a note someone changed while it worked. It rereads the note and tries again.
- Agents can delete and move notes when their instructions say to. Keep an agent that reads pasted or imported text in its own project.
- A run that finishes uses credits for the model's work and the time it ran. Most runs use under 10 credits (10 cents); a big job, like a weekly reflection over a busy project, uses about 20. **Failed and skipped runs use none.** **Settings → Usage** shows each agent as one line, with all of its runs. See [Usage and Credits](https://docs.basicmemory.com/cloud/usage-and-credits).
- A run has a time limit of a few minutes. A run that goes past it is stopped and marked as having run out of time.
- A run whose machine stops unexpectedly is tried again, unless it already changed notes. Then it isn't tried again, since a new try could make the same changes twice. It's marked as stopped partway, and its changes wait for you to keep or undo.
- Once your workspace reaches its spending limit, agents stop: you can't start a run, new notes in watched folders and schedules start nothing, and runs that were waiting are skipped with **Spending limit**. Raise the limit in **Settings → Billing**, then run them again.
- A workspace can have three runs waiting for each agent it runs at once (6 on Cloud, 9 on Pro, 15 on Business). Past that, starting a run tells you how many are already waiting, and new notes in watched folders start nothing until some of the waiting runs have run.

## Work with agents from your own AI

Claude, Codex, and other agents connected to Basic Memory can work with your Basic Memory agents through the `bm_agent` tool, one `command` at a time:

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        list
      </code>
    </td>
    
    <td>
      The project's agents, each one's schedule and next run, and how their recent runs went
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        run
      </code>
    </td>
    
    <td>
      Start an agent on a note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get
      </code>
    </td>
    
    <td>
      A run's status, the notes it changed, and what the agent said
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        runs
      </code>
    </td>
    
    <td>
      Recent runs; with <code>
        needs_review
      </code>
      
      , only the runs nobody has reviewed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mark
      </code>
    </td>
    
    <td>
      Mark a run kept, or dismiss one that failed
    </td>
  </tr>
</tbody>
</table>

Undo stays in the app, where you can see what goes back. For example: *"Go through my agent runs that need review and keep the ones whose changes look right."*

---

## Next Steps

<card-group>
<card icon="i-lucide-play" title="Add and Run Agents" to="https://docs.basicmemory.com/agents/add-and-run">

Ready-made agents, schedules, web access, and what starts a run.

</card>

<card icon="i-lucide-list-checks" title="Review Agent Runs" to="https://docs.basicmemory.com/agents/review-runs">

The review queue, a run's page, and what Undo puts back.

</card>
</card-group>


## Sitemap

See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.