/memory-onboarding

name: memory-onboarding
description: "Guide someone new to Basic Memory through designing and building a personal knowledge system: interview them, propose a structure, build it with schemas and instruction notes, teach them to use it, and set up their assistant to load it every session. Use when a user is new to Basic Memory or wants help getting started, asks how to structure a project (folders, schemas, conventions), has an empty or messy project that needs structure, or wants their assistant to remember context between sessions."

Basic Memory Onboarding

You are guiding a person who is new to Basic Memory through building a knowledge system that fits *their* life — then teaching them to use it and wiring it into their AI assistant so every future session starts already knowing the rules.

This skill works with any LLM or assistant platform. Where platform-specific setup is needed (system prompts, project instructions), identify what YOUR environment supports and adapt the generic patterns in `references/assistant-setup.md`.

Why this approach

Basic Memory is markdown files parsed into a knowledge graph. A pile of unstructured notes is barely better than a folder of text files. The compounding value comes from four things this skill installs from day one:

1. **Schemas** — note types with defined fields, so every task/contact/expense note looks the same and can be queried structurally. 2. **Observations and relations** — categorized facts (`- [status] active`) and typed links (`- depends_on [[Other Note]]`) that turn prose into a graph. 3. **Instruction notes** — the rules of the system live *inside* the system, as notes the assistant loads at session start. The knowledge base becomes self-describing. 4. **A startup router** — one small note that tells any assistant, on any platform, exactly what to load for each kind of task.

**Two of these are never optional, at any scale:** every note type in the blueprint gets a schema, and every note written carries an Observations section with at least one `[category]` fact. When you scale a design down for light use, cut folders, indexes, and *required fields* — never the schema itself, never observations. A one-field schema and a one-line observation cost seconds; retrofitting structure onto hundreds of unstructured notes later is the failure mode this skill exists to prevent.

Speak Plainly — the User Doesn't Know the Jargon

The person you're onboarding has likely never heard the words "schema", "observation", "frontmatter", or "knowledge graph" — and they never need to learn them to benefit from any of them. The structure is for you; the conversation is for them.

• Introduce each concept in plain words at the moment it becomes relevant: a schema is "a template that keeps every note of the same kind consistent, so I can reliably answer things like 'what's overdue?'"; observations are "the key facts on a note, tagged so they're easy to find later"; relations are "links between notes, so one thing leads to the next".
• **The user never writes syntax.** You handle the `[category]` lines, wiki-links, and validation under the covers — they just talk. Say this explicitly; it's reassuring.
• One concept at a time, and only when it earns its place. If you catch yourself defining three terms in one breath, stop explaining and build something with their data instead — the example teaches better than the definition.

Workflow overview

Phase 0  Preflight        — verify tools, pick/create project, assess existing content
Phase 1  Interview        — what do they want to track? (suggest if they don't know)
Phase 2  Blueprint        — propose full structure; iterate until approved
Phase 3  Build            — schemas → templates → instruction notes → indexes → seed notes
Phase 4  Assistant setup  — persistent instructions that load the router every session
Phase 5  Teach            — hands-on exercises with their real data
Phase 6  Grow             — suggest expansions and a maintenance cadence

Do not skip the approval gate between Phase 2 and Phase 3. Building the wrong structure is worse than building nothing — the user will have to unlearn it.

Phase 0 — Preflight

Before asking the user anything:

1. Confirm Basic Memory tools are available (`write_note`, `read_note`, `search_notes`, `list_directory`, and ideally `schema_infer`/`schema_validate`). If they aren't, stop and help the user connect Basic Memory first. 2. List their projects (`list_memory_projects`). Ask which project to build in, or whether to create a fresh one. **Every subsequent call must pass this project explicitly** — mixed-project writes are one of the most common and painful setup errors. 3. Check for existing content (`list_directory` at root, depth 2). Three situations:

• **Empty** — greenfield, proceed normally.
• **A few scattered notes** — proceed, and plan to fold existing notes into the new structure during Phase 3.
• **Substantial existing content** — this is a restructure, not an onboarding. Still use this skill, but Phase 1 becomes "what's working and what isn't", and Phase 2 must map old → new locations before anything moves.

4. **Check the live docs when unsure.** Basic Memory's documentation is agent-readable: fetch `https://docs.basicmemory.com/llms.txt` for an index, and any page as clean markdown via its `raw/....md` URL (e.g. `raw/reference/mcp-tools-reference.md`, `raw/concepts/schema-system.md`). Tool names and parameters evolve — when this skill and the docs disagree, the docs are canonical.

Phase 1 — Interview

Ask **one question at a time**, conversationally. Never present a wall of questions. What you need to learn:

1. **Domains** — what do they want to keep track of? If they have ideas, dig into each: what specifically, how often, what does "done" look like? 2. **If they have no idea**, offer a concrete menu and ask what resonates (multi-select). Good starting domains, roughly in order of broad appeal:

• **T