--- title: "AI Assistant Guide" description: "Teach your AI assistant when and how to use Basic Memory — skills, project instructions, and CLAUDE.md/AGENTS.md." canonical_url: "https://docs.basicmemory.com/reference/ai-assistant-guide" --- # AI Assistant Guide > Teach your AI assistant when and how to use Basic Memory — skills, project instructions, and CLAUDE.md/AGENTS.md. Connecting Basic Memory over MCP gives your assistant the tools. It doesn't teach it *when* to reach for them. A few standing instructions are the difference between an assistant that occasionally writes a note and one that actually maintains your knowledge base — searching before it answers, capturing decisions as they happen, and linking new notes into the graph. There are three ways to give those instructions, from least to most effort. --- ## 1. Install Agent Skills (recommended) [Agent Skills](https://docs.basicmemory.com/integrations/skills) are packaged instructions that teach agents Basic Memory best practices — the note format, when to capture, how to search and resume work, schema workflows, and knowledge-base maintenance. If your client supports skills, this replaces hand-written guidance: - **Claude** (claude.ai and Claude Desktop) and **ChatGPT**: download the combined skill, `basic-memory.zip` for Claude or `basic-memory-chatgpt.zip` for ChatGPT, and upload it. The [Agent Skills guide](https://docs.basicmemory.com/integrations/skills) has the download links and where to upload. - **Coding agents** (Claude Code, Codex, Cursor, and others): install from the terminal. ```bash npx skills add basicmachines-co/basic-memory/skills -g ``` That installs the full set for your user account. To start smaller, add just one: `npx skills add basicmachines-co/basic-memory/skills --skill memory-notes -g` (the core note-writing skill), and add others as you need them. --- ## 2. Add project-level instructions If you'd rather write your own guidance — or your client doesn't support skills — put it where your assistant reads standing instructions: - **Claude Projects** — in Claude (web or desktop), open your project's settings and paste your guidance into the **project instructions**. Every conversation in that project starts with it. - **Claude Code** — add it to the repo's `CLAUDE.md`. Claude Code loads it automatically in that repository. - **Codex and other coding agents** — add it to `AGENTS.md` in the repo root, the convention most coding agents read. - **Other clients** — use the custom-instructions or system-prompt field your client provides. ### A starting instruction block Paste this and adapt it to your workflow: ```markdown ## Basic Memory You have persistent memory through Basic Memory's MCP tools. - Before answering questions about prior work or decisions, search first: `bm_search`, then `bm_context` on relevant identifiers. - Capture important decisions, findings, and context as notes with `bm_write` during the conversation — don't wait to be asked. - Structure notes semantically: observations as `- [category] fact #tag` and relations as `- relates_to [[Other Note]]`. Use exact titles of existing notes in wikilinks so they resolve. - Update existing notes with `bm_edit` instead of creating duplicates. If `bm_write` reports "Similar existing notes", decide whether to merge into one of them, link them, or keep the new note. - With several addressable projects, note and search calls require `project` or a project-qualified target. If the target project is ambiguous, ask once, then pass `project` on every call. - For quick navigation, use `bm_list`, `bm_find`, `bm_search`, and `bm_read` (sections and line ranges keep reads small). Read a tool's manual page (`memory://man/(3)`) when a call fails or its use is unclear. - A refused write is a tool error and nothing was written. Read the error before retrying. ``` Want more to work from? The [extended AI assistant guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) is a full instruction document you can download and customize. A [condensed version](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md) ships inside Basic Memory as the `memory://ai_assistant_guide` resource, and the built-in manual serves a page per tool at `memory://man`. --- ## 3. Say it in the conversation Instructions don't have to be configured up front. Basic Memory is designed so you can direct it naturally as you work: ```text "Make sure you add observations and relations to this note." "Search my notes before answering — what did we decide about auth?" "Record this decision in Basic Memory." ``` Your assistant can even write a note about *how you like your notes* — and find it again in the next conversation. **Using your tool's built-in memory too?** There's a paste-once routing rule that teaches the agent to treat built-in memory as the short-term cache and Basic Memory as the long-term store — see [Using Basic Memory with Built-in AI Memory](https://docs.basicmemory.com/concepts/vs-built-in-memory). --- ## What good usage looks like - **Search before answering.** Questions like "what did we decide about X?" should trigger `bm_search`, not a guess from the conversation so far. - **Capture as you go.** Decisions, requirements, and findings get recorded when they happen, structured with observations and relations. - **Build context on follow-ups.** `bm_context` with a `memory://` URL pulls in a note *and* its connected notes, so continuation conversations start warm. - **Edit, don't duplicate.** Existing notes grow with `bm_edit`; new notes link back to what they extend. When `bm_write` flags similar existing notes, that's the cue to merge or link. - **Read only what you need.** `bm_search(query="topic", compact=True)` and `bm_context(identifier="notes/topic", compact=True)` return identifiers without bodies so the agent can pick what to open. `bm_read` reads one section, a line range, or a token budget instead of a whole note. - **Name the project.** There's no session "active project" — unqualified note/search calls are refused when several projects are addressable. With several projects, pass `project` or use project-qualified paths like `research/notes/topic.md`. --- ## Preparing instructions for 1.0 - Use the twelve `bm_*` core tools. `bm_project(command="recent", since="7d")` replaces recent-activity calls; its JSON result contains a `results` array. - `bm_edit` requires an existing note. Create with `bm_write` after a `NOT_FOUND` refusal when creation is intended. - A JSON refusal has `error`, `message`, and optional `try_instead`. Re-read after `REVISION_CONFLICT`; inspect state before retrying `OUTCOME_UNKNOWN` or `PARTIAL_FAILURE`. - Pass `expected_checksum` from `bm_read` to guard changes. Metadata-only reads use `include_content=False`. - `bm_read` includes frontmatter by default. Use `section`, line bounds, or `max_tokens` for smaller reads. - Read `bm_man(page="bm-edit")` or `memory://man` for exact signatures. Moving instructions over from the earlier tools? See [Migrating to 1.0](https://docs.basicmemory.com/reference/migrating-to-1-0). For the full tool surface — parameters, aliases, defaults — see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference). --- ## Related Packaged instructions that teach agents Basic Memory best practices. Complete tool documentation with parameters and examples. The note structure your assistant should write. ## Sitemap See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.