feat(skills): add memory-onboarding skill#1050
Conversation
Guided onboarding for people new to Basic Memory. Interviews the user about what they want to track (with a domain menu when they have no idea), proposes a blueprint behind an approval gate, then builds the system: schemas (validation: warn), templates, per-domain instruction notes, a startup router with a dispatch table and known-failure-modes list, indexes, and seed notes from the user's real data. Finishes with assistant-agnostic persistent-instruction setup plus a verification test, hands-on teaching, and a maintenance path that hands off to memory-defrag, memory-curate, and memory-reflect. Structure: SKILL.md plus references/ (conventions, schema guide, domain playbooks, assistant setup) loaded progressively, and evals/evals.json with three persona-based test prompts. Schemas and observation syntax are non-negotiable at any scale, but the skill directs the agent to explain them in plain language and handle all syntax under the covers — the user never writes it. Points agents at docs.basicmemory.com/llms.txt (raw markdown endpoints) for current tool reference. Validated with scripts/validate_skills.py (15 skills OK). Signed-off-by: Cody Faust <cody@luminarysol.com>
|
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b857a3db55
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The schema_validate/schema_diff/schema_infer examples used noteType=, but the registered MCP tool contract exposes note_type (src/basic_memory/mcp/tools/schema.py). Assistants copying the reference calls during Phase 3/6 would fail to bind. Signed-off-by: Cody Faust <cody@luminarysol.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b53b771f71
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…xamples Two Codex review fixes in memory-onboarding's schema guide: - Quote enum field values in the Picoschema YAML example — an unquoted flow list with a trailing description is not valid YAML, so copying the block produced schema notes that fail to parse. - Use the stored lower-case note type in schema_validate/schema_diff/ schema_infer examples: the live API matches Entity.note_type exactly, so note_type="Task" would find none of the seed notes written with note_type="task". Signed-off-by: Cody Faust <cody@luminarysol.com>
|
@codex review again |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 46984fb2ed
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…chema guidance Per the validator contract (schema/validator.py, schema/parser.py): scalar, enum, and array fields validate against [field] observations, while capitalized entity-reference fields validate against relations whose type equals the field name (project?: Project -> project [[Target]]). The guide previously told agents to encode every schema field as an observation, so required entity-ref fields would never validate and no graph edges would be created. Clarified in the observation/relation sections and the Task playbook example. Signed-off-by: Cody Faust <cody@luminarysol.com>
On the restructure path, the build sequence went straight from indexes to fresh seed notes without ever executing the approved old-to-new mapping — an assistant could finish onboarding with the original messy root notes untouched. Added migration as step 5 (move, retype, add required observations, archive-never-delete) and extended validation to cover migrated notes as well as seeds. Signed-off-by: Cody Faust <cody@luminarysol.com>
|
@codex review and make @cfaust990 cry |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f534870357
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…plementation Grounded against schema/parser.py and schema/validator.py: - Validation modes are warn/strict/off — there is no 'error' mode, so the escalation guidance now says strict. - schema_validate reports missing required fields and enum mismatches only; undeclared fields are informational unmatched metadata and scalar values are not type-checked. Narrowed the claim and pointed drift discovery at schema_diff. - Softened behavioral claims about section edits on index tables and permalink regeneration to what's actually reliable. Signed-off-by: Cody Faust <cody@luminarysol.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ab814950ff
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…onboarding fetch-skills.ts only copied each skill's SKILL.md into the generated package, so multi-file skills (memory-onboarding ships references/ and evals/) would point at files absent from the OpenClaw bundle. The fetcher now copies every entry in the skill directory alongside SKILL.md — single-file skills are unaffected, and the skills dist packager already copies full directories (shutil.copytree). Also adds skills/memory-onboarding to the openclaw.plugin.json skills array per the documented new-skill step. Verified by running the fetcher: all 15 skills copy, memory-onboarding lands with its references/ and evals/ intact. Signed-off-by: Cody Faust <cody@luminarysol.com>
|
@codex review like the wind |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c2544d3ab5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…stale generated dirs Two follow-ups for multi-file skill support: - commands/skills.ts served only SKILL.md text, so bundled commands for multi-file skills directed the assistant to references/ files it was never given. Each command now appends a 'Bundled resource files' section mapping every relative resource path to its absolute installed location, so the assistant can read them with its own file tools. Single-file skills are unchanged (no section emitted); evals/ is excluded as test fixtures. - fetch-skills.ts merged into existing output dirs on rerun, so files deleted or renamed in a source skill survived as stale artifacts in the published package. The generated skill dir is now removed before copying. Verified: fetcher rerun clears planted stale files; mock-API command registration shows the /onboarding text mapping all four references with evals excluded, and single-file skills emitting no section. Signed-off-by: Cody Faust <cody@luminarysol.com>
Signed-off-by: Cody Faust <cody@luminarysol.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5a3fa1a4c9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## The router reference must be durable | ||
|
|
||
| Inside the stub, reference the router by **title** or **`memory://` path** — never paste a raw permalink string copied from a tool result. A recreated note derives a fresh permalink, and the stub is the one piece of the system that isn't a note and won't be caught by note-level maintenance — so it must use the most durable reference form available. |
There was a problem hiding this comment.
When the startup router is later moved or reorganized, a persisted stub that stores memory://instructions/startup-router becomes stale: move_note can update the note's permalink on move, and read_note/LinkResolver treat a slash-containing memory://... value as a path/permalink rather than the title. That breaks the fresh-session load path this onboarding flow depends on, so the durable stub should prefer the title (or another stable identifier) and not present memory:// paths as equally durable.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Partly disagree: update_permalinks_on_move defaults to False (config.py:379), so a memory:// path survives moves on a default install... and title references have their own failure mode (rename). Since no single identifier is unconditionally durable, 3dd43b8 makes the stub carry both the title and the path with an explicit fall-back-to-title-search instruction, which self-heals whichever one goes stale.
…one identifier Codex suggested preferring title references because move_note can change a permalink — but update_permalinks_on_move defaults to False, so memory:// paths survive moves on a default install, and titles have their own failure mode (rename). No single identifier is unconditionally durable. The stub template now carries the router's title and memory:// path together with an explicit fall-back-to-title-search instruction, which self-heals when any one identifier goes stale. Signed-off-by: Cody Faust <cody@luminarysol.com>
|
Codex Review: Didn't find any major issues. 🚀 Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
3 participants
What this adds
A new skill,
skills/memory-onboarding/— guided onboarding for people who are new to Basic Memory. It walks an assistant through:validation: warn), templates, per-domain instruction notes, a startup router with a dispatch table and known-failure-modes list, indexes, and seed notes from the user's real data (never placeholders)Structure (progressive disclosure — the agent loads only what the task needs):
Design choices worth flagging:
[category]lines or learns the word "Picoschema".docs.basicmemory.com/llms.txtand theraw/*.mdendpoints when the skill and current tool behavior might disagree, so the skill ages gracefully.Also adds a row to the Skills table in
skills/README.md.Why
The existing skills teach an agent how to use Basic Memory well, but nothing takes a brand-new user from "I connected the MCP, now what?" to a working, self-describing system their assistant follows consistently across sessions. This fills that gap, and the router/instruction-note pattern it installs makes every other skill in the collection land better.
How it was tested
python3 scripts/validate_skills.py skills/— 15 skills validated OKevals/evals.json.