# 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](/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:
```bash
npx skills add basicmachines-co/basic-memory/skills
```
That installs the full set. To start smaller, add just one: `npx skills add basicmachines-co/basic-memory/skills --skill memory-notes` — 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:
`search_notes`, then `build_context` on relevant `memory://` URLs.
- Capture important decisions, findings, and context as notes with
`write_note` 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 `edit_note` instead of creating duplicates.
- If the target project is ambiguous, ask once, then stick with it.
```
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, and a [condensed version](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md) ships as an MCP resource inside Basic Memory itself.
---
## 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](/concepts/vs-built-in-memory).
---
## What good usage looks like
- **Search before answering.** Questions like "what did we decide about X?" should trigger `search_notes`, 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.** `build_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 `edit_note`; new notes link back to what they extend.
For the full tool surface — parameters, aliases, defaults — see the [MCP Tools Reference](/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.