@basicmemory/openclaw-basic-memory 0.2.3 → 0.23.0

package/skills/memory-continue/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: memory-continue
+description: "Resume prior work by rebuilding context from the Basic Memory knowledge graph — pick up where you left off using memory:// URLs, recent activity, and search. Use when starting a session or when the user says 'continue with...', 'back to...', or 'where were we?'"
+---
+
+# Memory Continue
+
+Resume previous work by reconstructing context from the Basic Memory knowledge graph, so the assistant can pick up across sessions instead of starting cold.
+
+## When to Use
+
+- Starting a new session and you need to pick up where you left off
+- The user references earlier work: "continue with...", "back to...", "where were we on...?"
+- You need context about an ongoing project or spec
+- The user asks about something discussed in a previous conversation
+- You're working on a task that spans multiple sessions
+
+## Building Context
+
+### 1. Identify What to Continue
+
+If it's unclear, ask:
+- What topic or project should you resume?
+- What timeframe matters?
+- Any specific aspect to focus on?
+
+### 2. Gather Context with MCP Tools
+
+**Known topic — use `build_context`.** Navigate the graph from a starting point, following relations outward:
+
+```python
+build_context(
+    url="memory://topic-or-note-name",
+    depth=2,           # how many relation hops to follow
+    timeframe="7d",    # bias toward recent changes
+)
+```
+
+**No clear starting point — use `recent_activity`.** See what's changed and let it surface the thread:
+
+```python
+recent_activity(timeframe="3d", depth=1)
+```
+
+**Looking for something specific — use `search_notes`.** Find candidate notes by keyword:
+
+```python
+search_notes(query="async client refactor", page_size=10)
+```
+
+### 3. Read the Key Notes
+
+Once you've identified the relevant notes, read them in full:
+
+```python
+read_note(identifier="note-title-or-permalink")
+```
+
+### 4. Present Context to the User
+
+Summarize what you found, incrementally:
+- Current state of the work
+- Recent changes or progress
+- Open items and next steps
+- Related context that might help
+
+## Memory URL Reference
+
+`build_context` and `read_note` both accept `memory://` URLs, which address notes by permalink and support wildcards for gathering groups of notes.
+
+```
+memory://note-title            # a single note by permalink
+memory://folder/*              # all notes in a folder
+memory://specs/SPEC-24*        # pattern / prefix match
+memory://project/*/requirements # path wildcards
+```
+
+Use a specific note URL to anchor on one starting point; use a wildcard to pull in a whole folder or family of related notes at once.
+
+## Timeframe Reference
+
+`build_context` and `recent_activity` accept natural-language timeframes:
+
+| Timeframe | Meaning |
+|-----------|---------|
+| `"today"` | Current day |
+| `"yesterday"` | Previous day |
+| `"3d"` or `"3 days"` | Last 3 days |
+| `"1 week"` or `"7d"` | Last week |
+| `"2 weeks"` | Last 2 weeks |
+| `"1 month"` | Last month |
+
+## Scenario Playbooks
+
+### Resuming a Spec or Project
+
+```python
+# 1. Read the spec / project note
+read_note(identifier="SPEC-24: Postgres Database Migration")
+
+# 2. Pull in related context and recent changes via the graph
+build_context(url="memory://SPEC-24*", timeframe="7d")
+```
+
+Then summarize: the goals, what's completed, what's pending, and any blockers or open decisions.
+
+### Continuing General Work
+
+```python
+# 1. Check recent activity
+recent_activity(timeframe="3d")
+
+# 2. Read notes from the recent sessions it surfaces
+read_note(identifier="relevant-note")
+```
+
+Then list the modified notes with brief descriptions and ask which thread to dive into.
+
+### Following Up on a Topic
+
+```python
+# 1. Find the topic
+search_notes(query="topic keywords")
+
+# 2. Build context from the best match, following its relations
+build_context(url="memory://found-note-permalink", depth=2)
+```
+
+Then present the full picture — the note plus its connected context.
+
+## Project Discovery
+
+Project names are user-specific. To discover what's available before scoping a search or `memory://` URL:
+
+```python
+list_memory_projects()
+```
+
+In multi-project setups, prefix a `memory://` URL with the project name (e.g. `memory://research/papers/crdt`) to scope it.
+
+## Guidelines
+
+1. **Start broad, then narrow.** Get an overview with `recent_activity` or a wildcard `build_context`, then drill into specific notes.
+2. **Present incrementally.** Share what you find as you go rather than holding everything until the end.
+3. **Follow relations.** The graph's connections are the point — `build_context` with `depth` surfaces context you wouldn't find by reading one note.
+4. **Check multiple projects.** Specs may live separately from implementation notes; discover projects with `list_memory_projects`.
+5. **Confirm understanding.** Verify the reconstructed context is what the user actually needs before acting on it.
+6. **Capture new progress.** As the resumed work advances, write it back to the graph (see the **memory-notes** skill) so the next session can continue too.

package/skills/memory-curate/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: memory-curate
+description: "Curate the Basic Memory knowledge graph: find orphan notes and suggest links, propose typed relations, merge duplicates, audit tags and folders, and build hub notes. Use to organize, connect, and improve a knowledge base as notes accumulate."
+---
+
+# Memory Curate
+
+Maintain a healthy, well-connected knowledge graph. As notes accumulate, it pays to periodically organize, link, and curate the knowledge base so isolated notes become a connected graph.
+
+This skill curates the **knowledge graph** — the notes, relations, and tags that make up the knowledge base. (For hygiene on an agent's own memory *files* — splitting bloated files, pruning stale entries — see **memory-defrag**.)
+
+## When to Use
+
+- Asked to organize, clean up, or improve the knowledge base
+- Asked to find connections between notes, or what isn't linked yet
+- Orphan or unlinked notes are mentioned
+- Asked about duplicate or similar notes
+- Asked for help with folder organization or tag consistency
+- Phrases like "help me organize", "find related notes", "what's not linked", "clean up my notes"
+
+## Curation Capabilities
+
+### 1. Find Orphan Notes
+
+Orphans have no relations to other notes — they're islands in the graph.
+
+```python
+# List notes, then read each to inspect its Relations section
+search_notes(query="*", page_size=50)
+read_note(identifier="note-to-check")
+# Orphans have an empty (or missing) Relations section
+```
+
+**What to do with orphans:**
+- Suggest relations based on content similarity
+- Ask whether they should connect to existing topics
+- Propose hub notes to gather related orphans (see capability 6)
+
+### 2. Suggest Typed Relations
+
+Analyze a note's content and propose meaningful connections.
+
+```python
+read_note(identifier="note-to-analyze")
+# Pull out key terms, then search for related notes
+search_notes(query="key terms from the note")
+```
+
+Suggest relations based on shared topics, complementary content (problem/solution,
+question/answer), sequence (part 1 → part 2), or hierarchy (parent concept → detail).
+
+**Relation-type vocabulary:**
+- `relates_to` — general topical connection
+- `extends` — builds upon or elaborates
+- `implements` — realizes a concept or spec
+- `depends_on` — requires understanding of
+- `part_of` — hierarchy or composition
+- `contrasts_with` — presents an alternative view
+- `inspired_by` — source of insight
+- `enables` — makes something possible
+
+Custom relation types are fine — use whatever verb is descriptive.
+
+Add a confirmed relation with `edit_note`:
+
+```python
+edit_note(
+    identifier="API Design Decisions",
+    operation="append",
+    section="Relations",
+    content="- depends_on [[Rate Limiter]]",
+)
+```
+
+### 3. Identify Similar / Duplicate Notes
+
+Find notes that may cover the same ground.
+
+```python
+search_notes(query="topic keywords")
+# Compare results for: similar titles, overlapping observations,
+# shared tags, close-together timestamps
+```
+
+**Actions for duplicates:**
+- **Merge** into a single comprehensive note, then redirect the loser with a relation
+- Link with `supersedes` / `updates` when one revises the other
+- **Differentiate** by adding context that clarifies each note's distinct focus
+
+```python
+# Point an older note at the one that replaces it
+edit_note(
+    identifier="DB Schema v1",
+    operation="append",
+    section="Relations",
+    content="- updates [[DB Schema v2]]",
+)
+```
+
+### 4. Folder Organization Review
+
+```python
+list_directory(dir_name="/", depth=3)
+```
+
+Look for overcrowded folders, single-note folders, inconsistent naming, and notes
+that belong elsewhere. Suggest grouping related notes into topic folders, adding
+subfolders for large categories, and a consistent naming convention. Move misplaced
+notes with `move_note` — the permalink stays stable, so wiki-links keep resolving.
+
+```python
+move_note(
+    identifier="API Design Decisions",
+    destination_path="architecture/api-design-decisions.md",
+)
+```
+
+### 5. Tag Consistency
+
+```python
+search_notes(query="*", page_size=100)
+# Inspect tag patterns across results
+```
+
+Look for:
+- **Variant tags** — `architecture` vs `arch`; pick one and standardize
+- **Unused tags** — present on a single note, no longer carrying weight
+- **Over-used generic tags** — so broad they don't aid discovery
+- **Missing tags** — relevant notes lacking an obvious tag
+
+### 6. Create Index / Hub Notes
+
+After finding a cluster of related notes, build a navigation hub.
+
+```python
+write_note(
+    title="Architecture Decisions Index",
+    directory="indexes",
+    tags=["architecture", "index"],
+    note_type="index",
+    content="""# Architecture Decisions Index
+
+A hub linking architecture-related decisions and patterns.
+
+## Decisions
+- [[Database Selection Decision]]
+- [[API Design Patterns]]
+- [[Authentication Architecture]]
+
+## Patterns
+- [[Repository Pattern]]
+- [[Async Client Pattern]]
+
+## Observations
+- [index] Central hub for architecture knowledge #navigation
+
+## Relations
+- indexes [[Architecture]]""",
+)
+```
+
+### 7. Enrich Sparse Notes
+
+Find notes lacking structure and fill them in.
+
+```python
+read_note(identifier="sparse-note")
+```
+
+If the note is missing an Observations section, suggest categories. If it has no
+Relations, suggest links. If it has no tags, suggest relevant ones. If it lacks
+context, suggest adding background. Apply with `edit_note`.
+
+## Curation Workflows
+
+### Quick Health Check
+
+A fast overview of knowledge base status:
+
+1. Count total notes
+2. Identify orphan count
+3. List recently modified (`recent_activity`)
+4. Check for obvious duplicates
+5. Report folder distribution
+
+### Deep Organization Session
+
+Thorough review and improvement:
+
+1. **Audit** — catalog all notes, identify issues
+2. **Orphans** — address unlinked notes
+3. **Relations** — suggest new connections
+4. **Duplicates** — merge or differentiate similar notes
+5. **Structure** — reorganize folders if needed
+6. **Index** — create hub notes for major topics
+
+### Topic-Focused Organization
+
+Organize around a specific subject:
+
+1. Find all notes related to the topic (`search_notes`)
+2. Map existing relations with `build_context(url="memory://...")`
+3. Identify gaps in the topic graph
+4. Suggest new notes to fill them
+5. Create a topic index note
+
+## Best Practices
+
+1. **Work incrementally.** Don't reorganize everything at once.
+2. **Confirm before changing.** Always ask before moving, merging, or editing notes.
+3. **Preserve permalinks.** Moving a note is fine; changing its permalink breaks inbound links.
+4. **Explain suggestions.** Say *why* a relation or merge makes sense.
+5. **Respect the existing system.** Enhance the user's organization — don't impose a new taxonomy.
+6. **Show the graph.** Use `build_context` to help the user see how notes connect.
+
+## Example Conversations
+
+**User:** "Help me organize my notes"
+
+The assistant:
+1. Runs a health check on the knowledge base
+2. Reports: "You have 47 notes. I found 12 orphans and 3 potential duplicates."
+3. Asks: "Want to start by connecting the orphans, or review the duplicates first?"
+
+**User:** "Find notes that should link to my API design note"
+
+The assistant:
+1. Reads the API design note
+2. Searches for related content
+3. Suggests: "5 notes could relate —
+   - 'REST Best Practices' → `relates_to`
+   - 'Authentication Flow' → `implements`
+   - 'Rate Limiting Decision' → `extends`
+   Should I add any of these relations?"
+
+**User:** "Are there notes on similar topics?"
+
+The assistant:
+1. Analyzes titles and content for clusters
+2. Reports: "Possible overlaps —
+   - 'Auth Flow' and 'Authentication Design' cover similar ground
+   - 'DB Schema v1' and 'DB Schema v2' likely want a `supersedes` relation
+   Want to review either?"

package/skills/memory-literary-analysis/SKILL.md

@@ -23,7 +23,7 @@ Phase 1: Seed          → stub notes for known major entities
 Phase 2: Process       → chapter-by-chapter notes in batches
 Phase 3: Cross-ref     → enrich arcs, add parallels, write analysis
 Phase 4: Validate      → schema checks, drift detection, consistency
-Phase 5: Visualize     → canvas files for character webs, timelines
+Phase 5: Visualize     → Obsidian canvas files for character webs, timelines
 ```
 
 ## Phase 0: Setup
@@ -451,19 +451,22 @@ Spot-check bidirectional relations: if Chapter X `features [[Character]]`, does
 
 ## Phase 5: Visualization
 
-Generate canvas files for visual exploration:
-
-```python
-# Character relationship web
-canvas(query="type:Character AND role:protagonist OR role:antagonist OR role:supporting")
-
-# Theme connections
-canvas(query="type:Theme")
-
-# Chapter timeline with key events
-canvas(query="type:Chapter", layout="timeline")
+Write [JSON Canvas](https://jsoncanvas.org/) files (`.canvas`) into the project directory for visual exploration in Obsidian. Query the graph first (`search_notes`, `build_context`), then lay out the results as canvas nodes and edges:
+
+```json
+{
+  "nodes": [
+    {"id": "ahab", "type": "file", "file": "characters/captain-ahab.md", "x": 0, "y": 0, "width": 400, "height": 300},
+    {"id": "ishmael", "type": "file", "file": "characters/ishmael.md", "x": 500, "y": 0, "width": 400, "height": 300}
+  ],
+  "edges": [
+    {"id": "e1", "fromNode": "ishmael", "toNode": "ahab", "label": "narrates"}
+  ]
+}
 ```
 
+Useful canvases: character relationship web (protagonist/antagonist/supporting), theme connections, chapter timeline with key events.
+
 ## Adapting to Other Genres
 
 This pipeline works for any literary text. Adjust schemas for genre:

package/skills/memory-notes/SKILL.md

@@ -276,26 +276,42 @@ Basic Memory auto-generates frontmatter (including the permalink and memory URL)
 
 ### Editing an Existing Note
 
-Use `edit_note` to append, prepend, or find-and-replace within a note:
+Use `edit_note` to update a note in place — four operations:
 
 ```python
-# Append new observations
+# append / prepend — add to the end or start (use for time-ordered logs)
 edit_note(
   identifier="API Design Decisions",
   operation="append",
   section="Observations",
   content="- [decision] Use OpenAPI 3.1 for spec generation #api"
 )
+edit_note(
+  identifier="API Design Decisions",
+  operation="prepend",
+  content="> Updated 2026-05-28: auth approach finalized.\n"
+)
 
-# Add a new relation
+# replace_section — rewrite a named section (use for living content that stays current)
 edit_note(
   identifier="API Design Decisions",
-  operation="append",
-  section="Relations",
-  content="- depends_on [[Rate Limiter]]"
+  operation="replace_section",
+  section="Summary",
+  content="Concise, current summary of the decision and its rationale."
+)
+
+# find_replace — swap specific text
+edit_note(
+  identifier="API Design Decisions",
+  operation="find_replace",
+  find_text="OpenAPI 3.0",
+  content="OpenAPI 3.1"
 )
 ```
 
+When an edit is destructive (`replace_section`, `find_replace`), it's good practice to
+read the note first and confirm the change before applying it.
+
 ### Moving a Note
 
 Use `move_note` to reorganize notes into different directories:

package/skills/memory-onboarding/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: memory-onboarding
+description: "Guide someone new to Basic Memory through designing and building a complete personal knowledge system — interview them about what they want to track, propose a structure, build it with schemas and instruction notes, teach them to use it, and set up their AI assistant to load it automatically. Use this skill whenever a user says they're new to Basic Memory, wants to 'get started', 'set up', or 'onboard' with Basic Memory, doesn't know what to use it for, asks how to organize their memory project or knowledge base, wants help designing folders/schemas/conventions, or asks how to make their assistant remember context between sessions. Also use it when a user has an empty or messy Basic Memory project and wants structure."
+---
+
+# 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:
+   - **Tasks & projects** — todos, deadlines, multi-step projects
+   - **Notes & journal** — daily notes, ideas, things learned
+   - **People & contacts** — who they know, context per person, follow-ups
+   - **Research** — topics they're digging into, sources, findings
+   - **Finances** — subscriptions, expenses, accounts, renewals
+   - **Procedures** — how-tos they keep re-figuring-out (home, work, tech)
+   - **Health & habits** — workouts, symptoms, routines
+   - **Assets** — home inventory, devices, warranties, serial numbers
+   For each domain they pick, `references/domain-playbooks.md` has a starter kit: folders, a schema, naming conventions, and an example note. Read it before proposing the blueprint.
+3. **Volume and cadence** — a system for 5 notes a week looks different from one for 50. Light use → fewer folders, fewer required fields.
+4. **One real example per domain** — "tell me about a task on your plate right now" / "one subscription you pay for". These become the seed notes in Phase 3 and make every later phase concrete instead of hypothetical.
+5. **What they've tried before** — if a previous system failed, find out why. Design against that failure.
+
+Start with 2–3 domains even if they're excited about six. A small system that works grows; a sprawling empty scaffold dies. Note the deferred domains for Phase 6.
+
+## Phase 2 — Blueprint
+
+Read `references/conventions.md` and `references/schema-guide.md` now if you haven't. Then present ONE document (in chat, not yet written anywhere) containing:
+
+1. **Folder tree** — the full proposed directory structure with one-line purpose per folder. Include `Schemas/`, `Templates/`, and an `Instructions/` (or `Meta/`) folder alongside the domain folders.
+2. **Schemas table** — one row per note type: schema name, note_type, required observations, optional observations, status enum values.
+3. **Naming conventions** — title format per note type, date formats, status vocabularies.
+4. **Instruction notes** — the startup router plus one instruction note per domain (see `references/conventions.md` for anatomy).
+5. **The discipline rules** they'll live by — search before create, exact-casing paths, changelog rows, index updates, bidirectional links — each with a one-line "why".
+
+Walk through it, invite pushback, and iterate. Scale to their answers — but scaling means fewer folders, fewer indexes, and fewer *required* fields, never dropping schemas or observations (see the non-negotiables above). Get an explicit "yes, build it" before Phase 3.
+
+## Phase 3 — Build
+
+Build in this order — later items reference earlier ones:
+
+1. **Schemas** → `Schemas/` folder, one note per type, `validation: warn`. Syntax in `references/schema-guide.md`.
+2. **Templates** → `Templates/`, one per note type, matching the schema exactly.
+3. **Instruction notes** → per-domain rules notes, then the **startup router** last (it links everything). Full anatomy and a worked example in `references/conventions.md`.
+4. **Index notes** → one per domain that needs one (tables of contents; not every domain does).
+5. **Migrate existing notes** *(restructure path)* → execute the approved old→new mapping from Phase 2 before seeding anything: move each existing note to its new home, set its note type, add the observations its schema requires, and update indexes as notes land. Archive what doesn't fit — never delete. Phase 3 is not done while anything still sits unorganized at the root.
+6. **Seed notes** → 2–3 REAL notes per domain using the examples collected in Phase 1. Never seed with placeholder data — real notes teach the format and are immediately useful; fake ones are noise the user must delete.
+7. **Validate** → run `schema_validate` on the seed notes AND any migrated notes; fix anything it flags. Read back the router and one instruction note to confirm links resolve.
+
+Follow the write discipline in `references/conventions.md` throughout — most importantly: search before creating anything, use exact folder casing, and watch write results for duplicate-suffixed permalinks (`-1`, `-2`).
+
+## Phase 4 — Assistant setup
+
+The system only works if the assistant loads the rules every session — otherwise the user is the only one who knows the conventions, which defeats the point.
+
+Read `references/assistant-setup.md` and set up (or hand the user exact text for) a **persistent instruction stub**: a short block in whatever always-loaded mechanism their platform provides (project instructions, custom instructions, system prompt, agent context file) that says, in essence: *"Before any knowledge-base work, read the startup router note in project X and follow its dispatch table."*
+
+Identify what mechanism YOUR platform offers and give concrete, platform-specific steps. If you cannot determine the platform, present the generic stub and the common placements from the reference file. End Phase 4 with the verification test described there (simulate a fresh session; confirm the router gets loaded and followed).
+
+## Phase 5 — Teach
+
+Teach by doing, with their data — not by lecturing. Run short exercises:
+
+1. **Capture** — "Tell me something that came up today" → create the note together, narrating the schema fields and observations as you fill them.
+2. **Retrieve** — have them ask for something ("what's on my plate?", "what do I know about X?") → demonstrate `search_notes` and reading via `memory://` links; explain title-search vs semantic search for names.
+3. **Update** — change a status, append an observation, add a changelog row — showing `edit_note` for targeted changes vs full overwrites.
+4. **Connect** — add a relation between two of their notes; show how `build_context` walks the graph.
+
+Then write a **cheat-sheet note** into their KB (`Instructions/` folder): the phrases they can say, what happens for each, and the core rules. This note is theirs — written for a human, not an assistant.
+
+## Phase 6 — Grow
+
+Close the onboarding by opening doors:
+
+- **Suggest 2–3 specific expansions** drawn from their deferred Phase 1 domains or natural neighbors of what they built (built tasks → suggest meetings; built finances → suggest renewals calendar; built research → suggest a reading log). Frame each as "when you're ready" — never build unrequested.
+- **Maintenance cadence** — suggest a periodic (weekly/monthly) review: `schema_diff` for drift, scan for duplicate or orphaned notes, prune stale statuses. If their platform supports scheduled/recurring tasks, offer to set this up.
+- **Evolution rule** — when a convention starts to chafe, change the instruction note (with a changelog row), don't silently deviate. The system stays self-describing only if the rules in it stay true.
+
+## Reference files
+
+| File | Read when |
+|:--|:--|
+| `references/conventions.md` | Before Phase 2. Startup router anatomy, instruction notes, changelogs, indexes, linking, write discipline, failure modes. |
+| `references/schema-guide.md` | Before Phase 2. Picoschema syntax, observations, relations, validation workflow. |
+| `references/domain-playbooks.md` | Phase 1–2, for each domain the user picks. Starter folders, schemas, naming, example notes per domain. |
+| `references/assistant-setup.md` | Phase 4. Persistent-instruction stub patterns per platform + verification test. |
+
+## Related Skills
+
+When companion skills are installed alongside this one, hand off instead of duplicating: **memory-notes** and **memory-schema** for note-writing and schema mechanics, **memory-tasks** for agent-side task tracking, **memory-lifecycle** for archival on the restructure path, **memory-defrag** / **memory-curate** / **memory-reflect** for the Phase 6 maintenance cadence, and **memory-continue** for resuming work from the graph — a natural first thing to teach after onboarding.

package/skills/memory-onboarding/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "memory-onboarding",
+  "evals": [
+    {
+      "id": 0,
+      "eval_name": "no-idea-newbie",
+      "prompt": "I just connected Basic Memory to my assistant but honestly I have no idea what to actually use it for. People talk about 'second brains' but I don't know where to start. Can you help me get set up with something useful?",
+      "persona": "Sam, marketing coordinator. When offered suggestions, is drawn to: tasks (loses track of follow-ups) and subscriptions (pays for services they forgot about). Light volume — maybe 5-10 notes a week. Real examples when asked: task 'send the Q3 sponsorship deck to Rivera Media by Friday'; subscriptions: Netflix $15.49/mo, Adobe CC $59.99/mo renews annually in March, a gym membership $40/mo they keep meaning to cancel. Uses a chat assistant that supports projects with custom instructions. Never tried a note system before.",
+      "expected_output": "Interview → blueprint scaled small (2 domains) → built KB with Task + Subscription schemas, Task Board and Subscriptions Index, instruction notes + startup router, seed notes using Sam's real examples, assistant stub for project instructions, cheat-sheet.",
+      "files": []
+    },
+    {
+      "id": 1,
+      "eval_name": "freelance-photographer",
+      "prompt": "I want to use Basic Memory to run my freelance photography business — keeping track of my clients, upcoming shoots, what I've invoiced, and all my camera gear. Set me up with a good structure that my AI assistant can work with consistently.",
+      "persona": "Priya, wedding/portrait photographer. ~3 shoots a month. Clients: couples and a few corporate accounts. Wants per-client history. Invoices tracked simply: date, client, amount, paid/unpaid (accounting itself stays in her accounting software). Gear: 2 bodies (Canon R5 serial 0482xx, R6), 6 lenses, lighting kit — wants serials and purchase dates for insurance. Real examples: upcoming shoot 'Chen-Okafor wedding Sept 12 at Maple Grove Estate, second shooter booked'; unpaid invoice 'Hartley corporate headshots $850 sent July 2'. Uses a desktop AI app with per-project custom instructions.",
+      "expected_output": "Blueprint with Clients/People, Shoots (project-like), Invoices (finance playbook adapted: no secrets, amounts from user only), Gear (assets playbook: serials, insurance index), schemas + router + instruction notes, seeds from her real examples, stub for project instructions, bidirectional client↔shoot links.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "eval_name": "messy-restructure",
+      "prompt": "My Basic Memory project is a mess — like 30 random notes dumped in the root folder, no organization, half of them are ideas for my blog and the rest are random todos. I want an actual system: task tracking, and proper research organization for my blog posts. And I want my assistant to actually follow the same rules every session instead of doing something different each time.",
+      "persona": "Jordan, writes a woodworking blog. Existing project 'main' has ~30 root-level notes with inconsistent naming (some lowercase, some dated, e.g. 'bandsaw jig idea', '2026-05-02 misc', 'todo dump', 'japanese joinery links'). Wants: tasks, and blog research (topic → sources → draft outline). Blog posts monthly. Real examples: active research topic 'hand-cut dovetails vs router jigs' with 4 saved links; task 'edit the shop-tour video by end of July'. Uses a CLI assistant that auto-loads a context file from the home directory.",
+      "expected_output": "Restructure path: assess existing notes, propose old→new mapping BEFORE moving, build tasks + research structure (topic hubs), schemas + router with known-failure-modes seeded from their actual mess (casing, duplicates), stub written for an agent context file, verification test described.",
+      "files": []
+    }
+  ]
+}