--- title: "Add and Run Agents" description: "Add a ready-made agent or write your own, write instructions that work, run agents on a schedule or from a watched folder, let them read the web, and start runs by hand or from your own AI." canonical_url: "https://docs.basicmemory.com/agents/add-and-run" --- # Add and Run Agents > Add a ready-made agent or write your own, write instructions that work, run agents on a schedule or from a watched folder, let them read the web, and start runs by hand or from your own AI. ## Add an agent On the **Agents** page, choose **Add agent**. Pick a ready-made agent or write your own.
Agent What it does Starts
Inbox filer Files each note created in inbox/ : moves it to the folder it belongs in, sets its type, and links it to related notes. New notes in inbox/ ; arrives turned off
Meeting follow-up Makes a task note for each action item in a new meeting note and adds a summary. New notes in meetings/ ; arrives turned off
Decision extractor Writes each decision in a conversation, meeting, or document as its own note in decisions/ , with the reasoning, the alternatives, and a link back. By hand, on the note to read
Import digester Turns imported conversations into topic notes and decision notes, 20 at a time, newest first. Run it again to continue. By hand, on an import's index note
Agent briefing Keeps briefing.md at the project root current, for agents and people to read first: what the project is, where it stands, open decisions, conventions, and what changed. Daily at 8:00 UTC
Weekly reflection Writes a digest of the week's notes and folds lasting insights into the notes they belong to. Mondays at 8:00 UTC
Curator Links a neighborhood of notes: typed relations, orphans, hub links. Adds links only; merging is Cleanup's job. By hand, on a hub or folder note
Cleanup Tidies a part of the project: merges duplicates, archives finished work, removes stale facts. Changes notes directly and never deletes one: a merged duplicate moves to archive/ . By hand, on a hub or project index note
Contradiction check Finds facts that disagree across notes, stale statuses, and broken links, and writes a report in reports/ . Changes nothing else. Mondays at 8:00 UTC
Schema keeper Checks notes against the project's schemas and writes a drift report. Changes nothing else. By hand
Scheduled agents skip, free, when nothing in the project changed since their last run, so quiet days cost nothing. After a Claude or ChatGPT conversation import, Basic Memory writes an index note in `imports/`, named `Import `, that links each conversation the import brought in, newest first. That note is what the Import digester runs on. Pick the project first: an agent reads and changes notes in its own project only. When the project already has a ready-made agent, the list says **Already in this project**; **Add another** makes a second copy beside it. To write your own, give it a name under **Or write your own** and choose **Create**. The new agent opens on its own page with its instructions ready to edit. Read them, change what you like, and choose **Save**; **Done** closes the editor. A ready-made agent that watches a folder arrives **turned off**, so it doesn't start on its own before you've read it. Turn it on with the **Enabled** switch on its page. Ready-made agents with a schedule arrive **turned on**; the skip on quiet days keeps them free when nothing changes. ## Write good instructions - Say what to do with the note it runs on, step by step. - Name folders and section headings exactly (`tasks/`, `## Summary`). - Say what to skip. Agents that run out of time are often weighing two ways to do something; telling them which one to use fixes it. - Keep one job per agent. Two small agents are easier to review than one large one. ## Watch folders and patterns The `watch` paths in an agent's frontmatter decide which new notes start it. Each path is relative to the project, with no leading `/`. - **A folder** watches every new note under it, in subfolders too: `meetings/`. - **A pattern** matches the new note's whole path: `meetings/staff-*.md` watches staff meeting notes only. `*` matches any characters and `?` matches one. Patterns aren't regular expressions. - **Several paths**: list up to 20, for example `watch: [meetings/staff-*.md, interviews/]`. In the app, separate them with commas. ## Run on a schedule A `schedule` in an agent's frontmatter runs it on its own note at the times it names. Its instructions say what to work on, for example by linking the notes to read. ```markdown --- type: agent title: Weekly reflection enabled: true schedule: "mondays at 8:00" timezone: America/Chicago --- ``` Write the schedule in one of three ways: - **In words**: `hourly`, `daily at 9:00`, `weekdays at 9am`, `weekends at 10:00`, `mondays at 9:00`, `every monday and thursday at 17:30`, `weekly on friday at 5pm`, `monthly on the 1st at 8:00`. Times without `am` or `pm` are on the 24-hour clock, and `noon` and `midnight` work too. - **As an alias**: `@hourly`, `@daily`, `@weekly`, or `@monthly`. These run at midnight (`@weekly` on Sunday, `@monthly` on the 1st); for a morning run, write `daily at 8:00`. - **As cron**: five fields, like `"0 9 * * 1"`. Put the schedule in quotes: YAML reads `@` and some cron characters as its own syntax. `timezone` takes a name like `America/Chicago`; without it, times are UTC. - An agent runs at most once an hour. A schedule that would run more often, or that Basic Memory can't read, makes the agent note invalid, and its page says what to write instead. - A scheduled run is skipped when no note in the project changed since the agent's last run. Run logs and the agent's own changes don't count. A skipped run uses no credits and shows in the agent's run history as **Nothing new**. - When the agent's previous run is still waiting to start, the scheduled run joins it instead of queuing a second one. - A scheduled run acts for the person who last saved the agent note. - The Agents page and the agent's page show each schedule in words, with when it runs next. ## Read the web An agent can search the web and read pages when two things are on: 1. **The workspace allows it.** An owner or admin turns on **Allow agents to read the web** under **Settings → Workspaces**, in the workspace's **Agents** section. It's off until someone turns it on, other members can see it, and each change is in the workspace's audit log. 2. **The agent note asks for it**, with `web: true` for any site, or with a list of sites: ```markdown --- type: agent title: Link summarizer enabled: true web: allow: [docs.python.org, "*.pydantic.dev"] --- ``` - `docs.python.org` is that site only. `"*.pydantic.dev"` is `pydantic.dev` and every site under it. Search results from other sites are left out, and a page that redirects off the list isn't read. - A run can make **20 web searches and page reads** together, **50 on Business**. Past that, the agent is told to finish with what it has. - An agent reads text pages only, up to 100 KB of text each. It doesn't download files, fill in forms, or sign in, and it can't reach private or local network addresses. - Anyone can write a web page, so the agent reads pages as material and never takes instructions from them. Its own instructions decide what it does to your notes. - The run's page lists each search and each page the agent read. When the agent note asks for the web and the workspace doesn't allow it, the agent runs without it, and the run's page says so. - Search uses DuckDuckGo, which receives the agent's search queries. Searches and page reads cost no credits of their own; the model's work on what they return does. See the [Privacy Policy](https://basicmemory.com/privacy). ## How an agent starts An agent always runs on one note, the note it works from. - **When a note is created in a watched folder.** Create a note under one of the agent's `watch` paths and the agent starts on it. It waits until you stop typing: a run starts one to two minutes after the note's last save, so it sees what you ended with. - **On its schedule.** An agent with a `schedule` starts on its own note at the times it names. See [Run on a schedule](#run-on-a-schedule). - **By hand, on any note.** On the agent's page, choose **Run on a note** and pick the note. On the Agents page, **Run** on an agent's row does the same. In a note, use the note menu's **Run agent**. - **From your own agent.** Ask Claude or another agent connected to Basic Memory to run an agent on a note (the `bm_agent` tool, `command="run"`). Some things never start an agent: notes written by another agent, imports, and files synced from your computer. ## Questions **Why didn't my agent start on a new note?** Check that the agent is enabled, that the note was created inside one of its watched folders, and that the note was written by a person, not imported, synced, or written by another agent. It starts one to two minutes after the last save. Nothing starts once the workspace reaches its spending limit, or while too many runs are already waiting. **Why did a scheduled run say Nothing new?** No note in the project changed since the agent's last run, so it skipped, at no cost. It runs at its next time once something changes. **Why is a run waiting?** The run's page says why: the note is still settling, the workspace is already running as many agents as its plan allows, or the same agent is already running on that note. **How long are runs kept?** 30 days. The run's log note stays in your project after that. ## Sitemap See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.