memory-quest

Original：🇺🇸 English
Translated

Finish Memory Quest Mission 8: confirm this assistant reaches Basic Memory Cloud and starts from Basic Memory, then, with approval, save a Memory Master note with the user's verification code.

1installs
Sourcebasicmachines-co/basic-memory
Added on

NPX Install

npx skill4agent add basicmachines-co/basic-memory memory-quest

Tags

Translated version includes tags in frontmatter
basic-memorymemory-questmemory-masterassistant-verificationcloud-note-management

SKILL.md Content

View Translation Comparison →

Memory Quest

Memory Quest's last mission checks that this assistant is set up to use Basic Memory as a natural starting point for work. You complete it by saving one note — the user's Memory Master note — through Basic Memory, carrying a one-time code from the Basic Memory web app. The cloud recognizes that write and awards the mission.
The note write is the verification. There is no other endpoint to call and nothing to report afterwards.

Project scope

Discover projects in step 1, then use the cloud project selected in step 5. Pass a nonempty 
project
on every note, folder, context and schema call, even with one project or a qualified 
memory://
URL. Use the chosen project's name, 
workspace/project
, or external ID; 
<project>
below is a placeholder for it. Recent activity also requires 
project
. Search accepts 
project
for one project, 
projects
for selected projects, or 
all_projects=True
explicitly. Discovery and bundled manuals need no project. Keep the same scope when following returned paths, paginating, or recovering from a refusal.

When to Use

  • The user runs 
    /memory-quest
    (or 
    $memory-quest
    , or picks it from a skill menu)
  • The user asks to verify their assistant, finish Mission 8, or become a Memory Master
  • Memory Quest in the web app pointed them here
When you tell the user to run Memory Quest again, use their host's form: 
/memory-quest
in Claude Code, 
$memory-quest
in Codex, or just asking for it in a chat app.
Take no task context from the invocation. This skill checks setup; it does not need to find memory relevant to a task.

Steps

Work through these in order. Stop at the first step that fails, explain what's missing, and say how to fix it. Never skip ahead to the note write.

1. Confirm a cloud connection

Call 
bm_project(command="list", output_format="json")
and inspect the projects grouped by workspace.
  • If it fails, Basic Memory isn't connected to this assistant. Tell the user to connect it and run Memory Quest again.
  • If no project has 
    source: cloud
    or 
    source: local+cloud
    , this assistant has not demonstrated a cloud connection. Memory Quest lives in Basic Memory Cloud: tell the user to connect their cloud account (
    bm cloud login
    for the CLI, or the Basic Memory connector in a chat app) and try again.
  • Otherwise the connection works. You may show the user one line about what you can see, such as the workspace names. That is a courtesy, not evidence.

2. Confirm the guidance is active

Mission 8 is about Basic Memory being this assistant's starting point, so check that the guidance which makes that happen is actually loaded. It is active when either is true:
  • Your context contains the Basic Memory session briefing — a section headed 
    # Basic Memory — session context
    , injected at session start by the Basic Memory plugin for Claude Code or Codex.
  • Your persistent instructions (custom instructions, project instructions, or an agent context file) tell you to use Basic Memory at the start of tasks to find relevant context.
If neither is true, stop. Tell the user to install the Basic Memory plugin for their assistant, or to save the memory routine from the Memory Quest panel in their assistant's instructions, then start a fresh conversation and run Memory Quest again. Do not report the guidance as active when it isn't: that report is the one part of this check the server cannot see for itself.

3. Ask for the verification code

Ask the user to open https://app.basicmemory.com/memory-quest and paste the code it shows. Codes look like 
MQ-7HX2-K9QD-4TRM
and last 30 minutes.
Accept the code as the user gives it; case and separators don't matter. If what they paste is clearly not a code (wrong prefix, too short), ask again rather than guessing.

4. Ask before saving

Say plainly what you are about to do: save a note titled "Memory Master" to their Basic Memory, and that saving it is what completes Mission 8. Ask for approval.
If they decline, stop. Say that the mission stays incomplete and they can run Memory Quest again any time.

5. Save the Memory Master note

First choose a project that exists only in Basic Memory Cloud. Call 
bm_project(command="list")
with 
output_format: "json"
and pick a project whose 
source
is exactly 
cloud
: the default project if it qualifies, otherwise ask the user which to use. New cloud accounts usually have one, Getting Started. Write to it by its 
external_id
.
Don't use a project listed as 
local
or 
local+cloud
. When this machine has a local project with the same name as a cloud one, which is common because every local install creates 
main
, a local Basic Memory server writes the note to the local copy however you address it, by name, workspace-qualified name, or ID. The write reports success, but the cloud never sees it, so the mission stays incomplete. If no project is listed as 
cloud
, stop and tell the user to create one in Basic Memory Cloud (or connect their cloud account), then run Memory Quest again.
With approval, call 
bm_write
once:
  • title
    : 
    Memory Master
  • directory
    : 
    memory-quest
  • note_type
    : 
    memory_master
  • project
    : the chosen project's 
    external_id
  • metadata
    : 
    {"memory_quest_code": "<the code exactly as the user gave it>", "memory_quest_guidance": "active"}
  • content
    : the template below, unchanged except where it says to fill in
  • overwrite
    : 
    false
    . Always pass it: when it's omitted, 
    bm_write
    follows the user's 
    write_note_overwrite_default
    setting and could silently replace an existing note.
Pass the code and guidance in 
metadata
, never inside 
content
. They must arrive as frontmatter fields for the cloud to recognize the write.
If 
bm_write
reports that the note already exists, read it with 
bm_read
, using the exact path from the refusal and the same 
project
, 
output_format: "json"
and 
include_frontmatter: true
. The frontmatter is where an earlier attempt's markers live, and the JSON includes the note's 
checksum
. Only an earlier Memory Quest attempt — a note whose frontmatter has 
type: memory_master
and a 
memory_quest_code
field — may be replaced. Say so, then call 
bm_write
again using the read result's 
file_path
as 
identifier
instead of 
title
+ 
directory
, 
overwrite: true
, and 
expected_checksum
set to that checksum. If the note changed after you read it, the write fails instead of discarding the newer version. Read it again and repeat the check. If the existing note is anything else, don't overwrite it: tell the user what's there, and either save under a different title, such as 
Memory Master (Memory Quest)
, or let them choose.

6. Tell the user what happens next

Tell them the note is saved and to open Memory Quest in the web app, where Mission 8 shows complete once the cloud has processed it. You cannot see the award yourself, so don't claim it happened. If Memory Quest still shows Mission 8 as current after a minute, the usual cause is an expired or replaced code: get a new code and run Memory Quest again.

Memory Master template

Use this as the note's 
content
. Replace 
<today's date>
with today's date; leave everything else as written. The 
::bm-*
blocks are live views the Basic Memory web app renders from the user's own knowledge base each time the note is opened.
<!-- Maintainers: basic-memory-cloud parses a copy of this template (packages/comark-harness/src/memory-master.md) against the Comark profile. Update both together. -->
markdown
Memory Master since <today's date>. Every Memory Quest mission is complete.

## The quest

::bm-check{title="Memory Quest"}
- [x] Capture your first memory
- [x] Create a relationship
- [x] Build and explore the knowledge graph
- [x] Master advanced search
- [x] Structure knowledge with schemas
- [x] Share a note safely
- [x] Bring in knowledge you already have
- [x] Make Memory a Habit
::

## Your knowledge today

::bm-stat{operation="bm.search.metadata" aggregate="count" label="Notes in this project"}
::

::bm-kpi{operation="bm.activity.recent" metric="notes-updated" window="30d" title="Notes updated in the last 30 days"}
::

::bm-spark{operation="bm.activity.recent" metric="notes-updated" window="30d" interval="day" title="Updates per day"}
::

::bm-rank{operation="bm.search.metadata" aggregate="count" group-by="type" limit="5" title="Your most-used note types"}
::

## What changes now

Your assistant now starts from what you already know: it checks Basic Memory for relevant context when it begins work, and offers to save what's worth keeping when it's done.

Guidelines

  • One write, with approval. Never write the note before step 4, and never write a second note to retry. Overwrite the same one.
  • Report guidance honestly. Only send 
    memory_quest_guidance: "active"
    after step 2 passes.
  • Don't invent outcomes. You can't observe the award. Point the user to Memory Quest instead of announcing success.
  • Keep the code in metadata. A code in the note body verifies nothing.
  • Stay on task. This skill doesn't search for memory relevant to a task, and doesn't change the user's other notes or settings.