@basicmemory/openclaw-basic-memory 0.2.4 → 0.23.1

package/skills/memory-onboarding/references/assistant-setup.md

@@ -0,0 +1,64 @@
+# Assistant Setup — Loading Instructions Every Session
+
+The knowledge base is self-describing: its rules live in instruction notes inside it. But a fresh assistant session doesn't know those notes exist. This reference covers the last mile — a **persistent instruction stub** in whatever always-loaded mechanism the user's platform provides, pointing at the startup router.
+
+## The stub pattern
+
+The stub is deliberately tiny. It carries only:
+
+1. Which Basic Memory **project** to use (always, explicitly)
+2. The instruction to **read the startup router before any knowledge-base work** and follow its dispatch table
+3. The 3–5 rules that must hold **before** the router loads (because they govern the loading itself)
+
+Everything else — conventions, schemas, workflows, reference data — lives in the router and the notes it dispatches to. This keeps the always-loaded footprint small and means the user edits notes, not platform settings, when conventions change.
+
+### Stub template
+
+Adapt the wording; keep the shape:
+
+```
+You maintain my knowledge base in Basic Memory, project "{project-name}".
+
+Rules that apply before anything else:
+1. Every Basic Memory call (read, search, write, list) uses project "{project-name}" explicitly.
+2. At the start of every session, before any knowledge-base work, read the note
+   "Startup Router" (memory://instructions/startup-router) and follow its dispatch
+   table for the task at hand. If that reference doesn't resolve, search for the
+   note by title before doing anything else. Take no write actions until the
+   notes it lists are loaded.
+3. Folder paths use exact casing as given in the instruction notes.
+4. Before overwriting any existing note, read it in full first.
+5. When unsure where something belongs, ask me instead of guessing.
+```
+
+Rules 1, 3, 4 are in the stub rather than the router because they protect the system even if the router fails to load or has been corrupted.
+
+## Where the stub goes
+
+Determine what platform and mechanism **you** are running in, and give the user concrete steps for it. Common mechanisms, by shape rather than brand:
+
+| Mechanism shape | Typical examples | How to place the stub |
+|:--|:--|:--|
+| **Project-level instructions** | A "project" or "space" in a chat app with a custom-instructions field | Paste the stub into the project instructions. Best option when available — scoped, persistent, and editable. |
+| **Global custom instructions / personalization** | Account-level "how should I respond" settings | Works, but applies to every conversation — wrap the stub in "When I ask about my knowledge base: ...". |
+| **Agent context files** | A markdown file the agent auto-loads from the working directory or home directory (many CLI/desktop agents support one) | Add the stub as a section of that file. |
+| **System prompt** | Self-hosted assistants, API integrations, custom apps | Prepend the stub to the system prompt. |
+| **No persistent mechanism** | Bare chat with MCP tools | Fall back: create a note titled something unmissable like `START HERE — Assistant Instructions` at the KB root, and teach the user to open each session with "read Start Here first". Weakest option; say so honestly. |
+
+If you can't determine the platform, show the stub and this table and let the user place it. If the user runs the KB from multiple assistants/platforms (desktop app + CLI + phone), place the stub in each — the router being shared is exactly what keeps them consistent.
+
+## The router reference must be durable
+
+Inside the stub, give the router's **title and `memory://` path together, with a title-search fallback** — never a raw permalink string copied from a tool result. No single identifier is unconditionally durable: a retitled note breaks title lookups, a recreated note derives a fresh permalink, and a moved note's path changes when `update_permalinks_on_move` is enabled (it defaults to off). 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 carries both identifiers plus the fallback — that combination self-heals when any one of them goes stale.
+
+## Verification test
+
+Never call Phase 4 done without testing. With the user:
+
+1. **Simulate a fresh session** — new conversation on their platform (or in this session, deliberately act as if starting cold).
+2. Give a natural task from one of their domains: "add a task: call the dentist Tuesday."
+3. **Watch the order of operations.** Pass = the assistant reads the router, loads the dispatched instruction note(s), THEN writes — correct folder, correct schema fields, correct naming. Fail = it writes first or freelances the format.
+4. If it fails: is the stub actually saved? Does the router reference resolve (test with `read_note`)? Is the "before any knowledge-base work" wording strong enough? Fix and re-test.
+5. Also verify the **escape hatch**: ask something ambiguous ("save this somewhere") and confirm the assistant asks rather than guesses.
+
+Leave the user with this framing: the stub + router is the system's ignition. If future sessions ever start behaving inconsistently, the first diagnostic is always "did the router get loaded?"

package/skills/memory-onboarding/references/conventions.md

@@ -0,0 +1,118 @@
+# Conventions & Discipline
+
+The structural patterns that keep a Basic Memory knowledge base coherent as it grows. These are defaults, not laws — but each exists because its absence causes a specific, recurring failure. When you relax one for a light-use setup, tell the user what they're trading away.
+
+## Contents
+
+1. [The startup router](#the-startup-router)
+2. [Instruction notes](#instruction-notes)
+3. [Changelog tables](#changelog-tables)
+4. [Index notes](#index-notes)
+5. [Linking discipline](#linking-discipline)
+6. [Write discipline](#write-discipline)
+7. [Known failure modes](#known-failure-modes)
+
+---
+
+## The startup router
+
+One note — suggested location `Instructions/Startup Router` — that any assistant reads at the start of every session, before doing any knowledge-base work. It is the single entry point to the whole system. It contains:
+
+1. **A read-me-first banner** — "Read this note at the start of every session, before any task work."
+2. **Non-negotiable rules** — the handful of rules that apply to every task type and can't be overridden by anything else (e.g. "always search before creating", "always pass the project name explicitly"). Keep this list short — five to eight items. A rule that only matters for one domain belongs in that domain's instruction note instead.
+3. **A dispatch table** — task type → which notes to load, in order:
+
+   | Task type | Load in order |
+   |:--|:--|
+   | Task / project work | 1. `memory://instructions/task-instructions` · 2. `[[Task Board]]` |
+   | New contact / person update | 1. `memory://instructions/people-instructions` |
+   | Expense / subscription | 1. `memory://instructions/finance-instructions` · 2. `[[Subscriptions Index]]` |
+   | Anything else / ambiguous | load all instruction notes |
+
+4. **Known failure modes** — a running list of documented mistakes to check before writing (see below).
+5. **Canonical reference data** — if the system has a roster-like table (accounts, categories, family members, clients), keep the ONE canonical copy here and make other notes point to it. Duplicated rosters drift apart; nobody notices until something routes to the wrong place.
+
+**Why a router instead of one big rules note:** context is finite. The router is small and always loaded; everything else loads only when the task needs it. It also gives the system one place to grow — a new domain is a new dispatch row, not a rewrite.
+
+The router itself is a note, so it gets a changelog table and observations like any other. When the user changes a convention, the change lands here or in a domain instruction note — with a changelog row — so the system stays self-describing.
+
+## Instruction notes
+
+One note per domain (`Instructions/Task Instructions`, `Instructions/Finance Instructions`, ...) holding everything an assistant needs to work in that domain:
+
+- **Scope** — what this note covers and what it doesn't ("for vendor stuff, see [[Vendor Instructions]]")
+- **Folder map** — where each note type lives, with exact casing
+- **Schemas in play** — table of note types, their schema notes, and required observations
+- **Naming conventions** — title formats with examples, date formats, status vocabularies
+- **Workflows** — step-by-step for the recurring operations ("closing a task: 1. set `[status] done` 2. add close date 3. append row to [[Task Board]]")
+- **Domain-specific rules** — anything true here that isn't true globally
+
+Write instruction notes for a reader with zero context: the assistant loading it next month is effectively a stranger. Explain *why* behind rules that aren't obvious — an assistant that understands the reason applies the rule correctly in situations the rule didn't anticipate.
+
+## Changelog tables
+
+Every structural or long-lived note carries exactly one changelog table, immediately below the title:
+
+```markdown
+| Notes | Modification Date | Approved By |
+|:--|:--|:--|
+| Initial Document | July 12, 2026 | {user's name} |
+| Added renewal-date field to all subscription rows | August 3, 2026 | {user's name} |
+```
+
+Rules:
+- **Append, never edit.** Existing rows are history; new rows record change.
+- **One table per note.** Before overwriting any existing note, read the full note first, carry the existing changelog forward verbatim, and append your row. If you ever find two tables, merge them into one at the top before writing.
+- **Consistent date format** — pick one (`Month D, YYYY` works well) and use it everywhere.
+
+Why: an assistant (or the user) reading a note months later can see what changed, when, and on whose authority — without any external version control. It also forces the read-before-overwrite habit that prevents accidental content loss.
+
+For a light setup, changelogs on *instruction notes, schemas, and indexes* are the non-negotiable core; changelogs on every individual content note are optional.
+
+## Index notes
+
+An index is a note containing a table of contents for one domain — one row per note, with wiki-links and a few key columns (status, date, owner):
+
+```markdown
+# Task Board
+
+| Task | Status | Due |
+|:--|:--|:--|
+| [[Fix gutter downspout]] | in-progress | July 20, 2026 |
+| [[Renew car registration]] | open | August 1, 2026 |
+```
+
+Rules:
+- **Update the index as part of any change to its members** — a stale index is worse than none, because it gets trusted.
+- **Full overwrite, not section edits.** When updating an index with `write_note`, always rewrite the whole note (read → modify → overwrite). Piecemeal section edits on tables are easy to get wrong — duplicated or mis-scoped sections — while a full overwrite is deterministic.
+- Not every domain needs one. Indexes earn their keep where the user will ask "show me all X with status Y" or wants a glanceable board. Journals and reference notes usually don't need one — search covers them.
+
+## Linking discipline
+
+- **Bidirectional links for paired entities.** If a task note links its project, the project note links its tasks. If a device links its owner, the owner links the device. One-directional links rot: graph traversal from the unlinked side finds nothing. Make "both directions, always" a rule for whichever entity pairs the user's system has.
+- **Relations sections for typed links, inline wiki-links for prose.** `- part_of [[Kitchen Renovation]]` in Relations; "discussed with [[Dana Reyes]]" in the body. Both create graph edges.
+- **Reference notes by title or `memory://` path — never by raw permalink strings.** A permalink is derived from the note's title and location, so a note that gets recreated or re-derived ends up with a different one and hardcoded strings silently break. `[[Title]]` resolves by title and `memory://` URLs match on path, so both survive reorganization.
+- **Link targets may not exist yet.** `[[Future Note]]` is valid and resolves when the note is created — use this to sketch structure ahead of content.
+
+## Write discipline
+
+The habits that prevent 90% of knowledge-base corruption:
+
+1. **Search before create.** Always search (try 2–3 query variations: full name, abbreviation, keywords) before writing a new note. Duplicates fragment the graph. If the entity exists, `edit_note` it instead. For people and other proper nouns, use **title search** — semantic search is unreliable for names.
+2. **Exact casing, exact paths.** `Tasks/` and `tasks/` are different directories. Take folder paths from the instruction note, character for character. If a write would create a new top-level folder you didn't plan, that's a casing error — stop and fix.
+3. **Explicit project on every call.** In multi-project setups, pass the project explicitly on every read, search, and write. Writes to the wrong project are invisible until much later.
+4. **Read before overwrite.** Full-note overwrites must start from the current content — never reconstruct a note from memory of what it contained.
+5. **Watch write results.** If a write returns a permalink ending in `-1` or `-2`, you just created a duplicate: delete it and re-write the original with overwrite semantics.
+6. **Prefer targeted edits.** `edit_note` (append an observation, find-and-replace a status) over full overwrites wherever possible — smaller blast radius.
+
+## Known failure modes
+
+Keep a "Known Failure Modes" section in the startup router and **add to it whenever a mistake happens twice**. Documented mistakes stop recurring; undocumented ones don't. Seed it during onboarding with the universal ones:
+
+- Duplicate notes from skipping search-before-create (or from name-search using semantic instead of title matching)
+- Wrong-casing paths creating parallel folder trees
+- Piecemeal section edits mangling index tables (duplicated or mis-scoped sections)
+- Second changelog table created by overwriting without reading first
+- Writes landing in the wrong project when project isn't passed explicitly
+
+Each entry: the mistake, how to recognize it, what to do instead. This list is the system's immune memory — it's often the highest-value section in the whole knowledge base.

package/skills/memory-onboarding/references/domain-playbooks.md

@@ -0,0 +1,159 @@
+# Domain Playbooks
+
+Starter kits for the common things people track. Each gives folders, a schema sketch, naming, an index decision, and expansion ideas. These are starting points — adapt every one to the user's Phase 1 answers rather than installing verbatim. Statuses, folder names, and required fields should use the user's own vocabulary where they have one.
+
+Every domain also gets: an instruction note (`Instructions/{Domain} Instructions`), a row in the startup router's dispatch table, and templates for its note types.
+
+## Contents
+
+1. [Tasks & projects](#tasks--projects)
+2. [Notes & journal](#notes--journal)
+3. [People & contacts](#people--contacts)
+4. [Research](#research)
+5. [Finances](#finances)
+6. [Procedures](#procedures)
+7. [Health & habits](#health--habits)
+8. [Assets](#assets)
+
+---
+
+## Tasks & projects
+
+```
+Tasks/
+├── Task Board.md          ← index: open/in-progress tasks
+└── {task notes}
+Projects/
+├── {Project Name}/        ← one folder per active multi-step project
+│   └── {Project Name}.md  ← project note; links its tasks
+```
+
+- **Task schema:** `status(enum): [open, in-progress, blocked, done]` · `due?` · `priority?(enum)` · `project?: Project`
+- **Project schema:** `status(enum): [active, paused, done]` · `goal` · `target_date?`
+- **Naming:** tasks get short imperative titles (`Renew car registration`); completed tasks can be retitled with a date prefix (`2026-07-12 — Renew car registration`) when archived, so archives sort chronologically.
+- **Index:** yes — the Task Board is usually the single most-used note in the system. Open items only; done tasks drop off the board (search finds them).
+- **Bidirectional rule:** task ↔ project, both directions. The `project?: Project` field is a relation field — satisfied by `- project [[Project Name]]` in the task's Relations (the relation type must match the field name for validation).
+- **Key workflow to document:** closing a task (set status, add close date, update board, move to archive folder if using one).
+- **Expansions:** meeting notes with action items that become tasks; a weekly-review note; recurring-task conventions.
+
+## Notes & journal
+
+```
+Journal/
+└── {YYYY-MM-DD}.md        ← one note per day
+Notes/
+└── {topic notes}          ← ideas, things learned, free-form
+```
+
+- **Journal Entry schema (keep it tiny — one required field):** `date` · `mood?(enum)` · `highlight?`. Even the loosest domain gets a schema and observations — but here the observation load is deliberately one line (`- [date] 2026-07-12`, plus `[highlight]`/`[idea]`/`[mood]` when they apply), so capture stays frictionless.
+- **Note schema (topic notes):** `note_type?(enum): [idea, reference, learning]` — one optional field; the requirement is simply that every note carries at least one observation (`[idea]`, `[source]`, `[lesson]`...).
+- **Naming:** `YYYY-MM-DD` for journal (sorts itself); descriptive titles for topic notes.
+- **Index:** no. Date-named journals self-organize; topic notes are found by search.
+- **The one convention that matters:** when a journal entry mentions a person, project, or topic that has (or deserves) a note, wiki-link it. Journals become the connective tissue of the graph.
+- **Expansions:** weekly reflection summarizing the week's entries; automatic extraction of `[idea]` observations into topic notes.
+
+## People & contacts
+
+```
+People/
+└── {Full Name}.md         ← one note per person
+```
+
+- **Schema:** `relationship?(enum): [family, friend, coworker, professional, acquaintance]` · `email?` · `phone?` · `company?` · `last_contact?`
+- **Naming:** full name, consistently — `Dana Reyes`, never `dana` in one note and `Dana R.` in another. Titles are graph identifiers.
+- **Index:** optional — useful if the user wants a follow-up board (`last_contact` older than N months).
+- **Critical rule:** ALWAYS title-search (full name, then last name) before creating a person note — people are the most-duplicated entity type, and semantic search misses names.
+- **Body guidance:** this is where prose shines — how they met, what they care about, gift ideas, kids' names. Observations for the queryable bits (`- [birthday] March 12`).
+- **Expansions:** interaction log (`- [contact] July 12, 2026 — coffee, discussed job change` appended per touch); linking people to meetings, projects, gifts.
+
+## Research
+
+```
+Research/
+├── {Topic}/
+│   ├── {Topic}.md         ← topic hub: question, current understanding, links to sources
+│   └── {source notes}     ← one note per significant source
+```
+
+- **Topic schema:** `status(enum): [active, parked, concluded]` · `question` (what they're trying to answer)
+- **Source schema:** `source_type(enum): [article, paper, video, book, conversation]` · `url?` · `date_consumed?`
+- **Naming:** topic hubs by topic name; sources by title of the source.
+- **Index:** the topic hub IS the index for its sources.
+- **Key conventions:** every source note ends with `- part_of [[Topic]]`; the hub's "current understanding" section gets rewritten (with changelog row) as understanding evolves — the hub is a living synthesis, not an append-only log.
+- **Expansions:** a reading queue; `[claim]`/`[evidence]`/`[contradiction]` observation categories for contested topics; concluded-topic summaries.
+
+## Finances
+
+```
+Finances/
+├── Subscriptions Index.md ← index: every recurring charge, cost, renewal date
+├── Subscriptions/
+│   └── {Service}.md       ← one note per subscription/recurring bill
+├── Accounts/
+│   └── {Account}.md       ← one note per account (no credentials — see below)
+└── Records/
+    └── {YYYY-MM-DD} — {Description}.md   ← one-off: big purchases, tax docs, claims
+```
+
+- **Subscription schema:** `cost` · `billing_cycle(enum): [monthly, annual, quarterly]` · `renewal_date` · `payment_method?` · `status(enum): [active, cancelled, trial]`
+- **Naming:** records get `{YYYY-MM-DD} — {Description}`, dated by the document date, not the filing date.
+- **Index:** yes — the Subscriptions Index (name, cost, cycle, renewal, method) is the payoff note: total monthly spend at a glance, upcoming renewals visible.
+- **Two hard rules for the instruction note:** (1) **no secrets ever** — no account numbers beyond last-4, no passwords, no full card numbers; notes are plaintext markdown. (2) **amounts and payment methods come from the user or a document — never inferred or guessed.**
+- **Expansions:** annual-cost review workflow; warranty/receipt records linking to Assets; a renewals-this-month recurring check.
+
+## Procedures
+
+```
+Procedures/
+├── {area}/                ← optional grouping: Home/, Tech/, Work/
+└── {Procedure Name}.md    ← one note per how-to
+```
+
+- **Schema:** `procedure_type(enum): [how-to, troubleshooting, checklist, reference]` · `applies_to?` · `last_verified?`
+- **Naming:** descriptive, search-first titles — the phrase the user would actually say (`Reset the water softener`, not `Softener maintenance procedure v2`).
+- **Index:** optional per area once a folder exceeds ~15 notes.
+- **Key conventions:** numbered steps; prerequisites up front; `last_verified` observation updated whenever the procedure is confirmed still-correct — and when a procedure is used and found wrong, fixing the note is part of finishing the task.
+- **Expansions:** seasonal checklists; linking procedures to the assets they service.
+
+## Health & habits
+
+```
+Health/
+├── Log/
+│   └── {YYYY-MM-DD} — {type}.md    ← workouts, symptoms, appointments
+└── {condition/goal notes}          ← ongoing threads: an injury, a training goal
+```
+
+- **Log schema:** `entry_type(enum): [workout, symptom, appointment, measurement]` · `date`
+- **Index:** optional — a current-goals note works better than a full log index.
+- **Key conventions:** log entries are quick and low-friction (two observations and a sentence beats an unfilled template); ongoing threads link their log entries so `build_context` on "left knee" pulls the full history.
+- **Sensitivity note for the instruction file:** health data in plaintext markdown — the user should decide consciously what level of detail they're comfortable storing, and where the project syncs to.
+- **Expansions:** habit streaks; pre-appointment summaries generated from the log.
+
+## Assets
+
+```
+Assets/
+├── Asset Index.md         ← index: every asset, location, value band
+└── {Asset Name}.md        ← one note per significant item
+```
+
+- **Schema:** `asset_type(enum): [electronics, appliance, vehicle, furniture, tool, other]` · `serial_number?` · `purchase_date?` · `purchase_price?` · `warranty_until?` · `location?` · `status(enum): [in-use, stored, loaned, sold, disposed]`
+- **Naming:** `{Make} {Model}` or a distinguishing name (`Garage Freezer`); serial in observations, not the title.
+- **Index:** yes — this is the insurance-claim / "where is the..." note.
+- **Bidirectional rule:** if assets are assigned to people (family laptops), asset ↔ person, both directions.
+- **Expansions:** warranty-expiry checks; maintenance logs linking to Procedures; purchase records linking to Finances.
+
+---
+
+## Combining domains
+
+Domains compound through relations — mention these links when the user picks the pairs:
+
+- Tasks ↔ People (`waiting_on [[Dana Reyes]]`) · Tasks ↔ Projects
+- Finances ↔ Assets (purchase records ↔ asset notes)
+- Procedures ↔ Assets (`services [[Garage Freezer]]`)
+- Journal → everything (daily entries wiki-link whatever they mention)
+- Research ↔ Notes (ideas graduate into research topics)
+
+The cross-domain links are where a knowledge *graph* starts beating a folder of documents — surface one concrete example using the user's own notes during Phase 5.

package/skills/memory-onboarding/references/schema-guide.md

@@ -0,0 +1,136 @@
+# Schemas, Observations & Relations
+
+How to make notes structured enough to query and consistent enough to trust. This is the mechanical core of the system the onboarding builds.
+
+## Contents
+
+1. [Note anatomy](#note-anatomy)
+2. [Observations](#observations)
+3. [Relations](#relations)
+4. [Picoschema syntax](#picoschema-syntax)
+5. [Creating a schema](#creating-a-schema)
+6. [Validation & drift](#validation--drift)
+7. [Design guidelines](#design-guidelines)
+
+---
+
+## Note anatomy
+
+Every well-formed note has: frontmatter (title, type, tags — generated by `write_note` from its parameters), a **body** of substantive prose, an **Observations** section, and a **Relations** section.
+
+```markdown
+# Fix Gutter Downspout
+
+| Notes | Modification Date | Approved By |
+|:--|:--|:--|
+| Initial Document | July 12, 2026 | Dana Reyes |
+
+Back downspout detached during the June storm; water is pooling against the
+foundation on the north side. Needs a bracket and probably a new elbow section.
+Hardware store trip required — measure the downspout diameter first (looks like 3x4).
+
+## Observations
+- [status] open
+- [priority] high
+- [due] July 20, 2026
+- [context] home-maintenance
+
+## Relations
+- part_of [[House Projects]]
+- relates_to [[June Storm Damage]]
+```
+
+**Write the body generously.** Search retrieves chunks from note bodies, so richer prose makes notes *more* discoverable, not less. Prose carries meaning; observations carry precision. A note that is only bullet-point observations reads like a database row and loses the context that makes it useful a year later.
+
+## Observations
+
+Categorized, atomic facts: `- [category] content #optional-tag`
+
+- Categories are **free-form** — `[decision]`, `[status]`, `[symptom]`, `[cost]`, `[lesson]` — whatever fits. Consistency within a note type is what matters (and is what schemas enforce).
+- **One fact per line.** `- [decision] Use JWT with 15-minute expiry` not a paragraph of three decisions.
+- **Categories are queryable** — searching by category finds every note carrying that kind of fact.
+- Tags add cross-cutting findability: `- [risk] no SLA on the API #vendor #reliability`.
+
+In this system, observations do double duty: they're facts, and they're the **fields** schemas validate — for scalar, enum, and array fields. A Task schema requiring `status` means every task note carries `- [status] ...` as an observation. (Entity-reference fields validate against relations instead — see below.)
+
+## Relations
+
+Typed, directional links: `- relation_type [[Target Note Title]]`
+
+- relation_type is a descriptive snake_case verb: `part_of`, `depends_on`, `assigned_to`, `replaces`, `paid_by`. Invent freely.
+- Wiki-links in body prose also create edges (untyped `references`). Use the Relations section for the structural links, prose links for narrative mentions.
+- Targets may not exist yet — forward links resolve on creation.
+- `build_context` on a `memory://` URL walks these edges to assemble connected context — this is what makes the graph worth building.
+
+## Picoschema syntax
+
+Schemas are notes (conventionally in a `Schemas/` folder) whose frontmatter metadata defines fields:
+
+```yaml
+schema:
+  status(enum): "[open, in-progress, blocked, done], current state"
+  due?: string, due date if any (Month D, YYYY)
+  priority?(enum): "[low, medium, high], urgency"
+  project?: Project, parent project note
+  steps?(array): string, ordered sub-steps
+```
+
+- Types: `string`, `integer`, `number`, `boolean`
+- `?` suffix = optional field
+- `(enum)` = fixed value list — use for anything status-like
+- `(array)` = list field
+- A capitalized type name (`Person`, `Project`) makes it a **relation field**, validated against the note's Relations section (the relation type must equal the field name: `- project [[Target Note]]`) — it creates a graph edge, not an observation
+- Every field gets a comma-then-description: it's documentation the next assistant reads
+
+## Creating a schema
+
+```python
+write_note(
+  title="Task",
+  directory="Schemas",
+  note_type="schema",
+  metadata={
+    "entity": "Task",
+    "version": 1,
+    "schema": {
+      "status(enum)": "[open, in-progress, blocked, done], current state",
+      "due?": "string, due date (Month D, YYYY)",
+      "priority?(enum)": "[low, medium, high], urgency",
+      "project?": "Project, parent project"
+    },
+    "settings": {"validation": "warn"}
+  },
+  content="""# Task
+
+Schema for task notes. Tasks live in Tasks/, titled with a short imperative
+description. Status moves open → in-progress → done; blocked is a holding state.
+
+## Observations
+- [convention] Every task carries status as an observation
+- [convention] Done tasks get a close-date appended before archiving"""
+)
+```
+
+Key points:
+
+- **`validation: warn`, not `strict`** — the modes are `warn` and `strict`. Warn logs findings without blocking anything; `strict` escalates the same findings to errors. Start every schema on warn — a new user fighting rejected writes will abandon the system. Move a schema to `strict` only if something automated consumes the notes and malformed ones break it.
+- **Content notes declare their type** via `note_type` matching the schema's entity (e.g. `note_type="task"`).
+- **Scalar, enum, and array fields must appear as observations** in the note body (`- [status] open`) to satisfy validation — frontmatter-only values don't count. Putting them in both places gives you metadata search *and* schema validation. **Entity-reference fields are different**: they're satisfied by a relation, not an observation — a line in `## Relations` whose type matches the field name (`project?: Project` is satisfied by `- project [[Kitchen Renovation]]`).
+- **Version in metadata** — bump on breaking changes (new required field, removed field, type change). Additive optional fields don't need a bump.
+
+## Validation & drift
+
+- `schema_validate(note_type="task")` — check all notes of a type, or a single note via `identifier=`. It reports **missing required fields** and **invalid enum values** — that's the whole contract. Fields the schema doesn't declare are only counted as informational "unmatched" metadata (schemas are a subset, not a straitjacket), and scalar values are not type-checked, so a clean validate doesn't guarantee more than required-field presence and enum conformance. Use `schema_diff` to surface undeclared fields.
+- `schema_diff(note_type="task")` — finds drift: fields notes use that the schema doesn't define (candidates to add as optional), and schema fields nobody uses (candidates to drop).
+- `schema_infer(note_type="task")` — when notes of a type already exist without a schema, infer one from their actual structure instead of designing from scratch.
+
+Evolution loop: `schema_diff` → edit the schema note (append changelog row, bump version if breaking) → `schema_validate` → fix outliers. Suggest the user run this monthly-ish once the system has real volume.
+
+## Design guidelines
+
+- **Every note type gets a schema; every note gets observations.** These two are not scale-dependent. A domain the user wants "loose" gets a one-field schema and a one-observation minimum, not an exemption — unstructured notes can't be queried, validated, or trusted by a future assistant, and retrofitting structure later is far more expensive than carrying one line now.
+- **2–4 required fields, everything else optional.** Required fields are a tax on every note; each one must earn its place. Status almost always earns it. `notes_from_that_one_meeting` does not.
+- **Enums for anything status-like.** Free-text statuses drift (`done`, `Done`, `finished`, `complete ✓`) and become unqueryable. Define the vocabulary in the schema and list it in the domain instruction note.
+- **Schema per entity type, not per folder.** A `Person` schema serves contacts, family, and coworkers even if they live in different folders.
+- **Don't over-constrain.** A schema describes common structure; it is not a straitjacket. If the user fights a field during the first week, make it optional or delete it.
+- **Schemas are documentation.** Even at `warn` with validation never run, the schema note tells the next assistant exactly what a conforming note looks like. Write field descriptions accordingly.

package/skills/memory-schema/SKILL.md

@@ -47,14 +47,14 @@ Use `(enum)` with a list of allowed values:
 
 ```yaml
 schema:
-  status(enum): [active, blocked, done, abandoned], current state
+  status(enum, current state): [active, blocked, done, abandoned]
 ```
 
 Optional enum:
 
 ```yaml
 schema:
-  priority?(enum): [low, medium, high, critical], task priority
+  priority?(enum, task priority): [low, medium, high, critical]
 ```
 
 ### Arrays
@@ -83,9 +83,11 @@ Relations create edges in the knowledge graph, linking notes together.
 
 ```yaml
 settings:
-  validation: warn    # warn (log issues) or error (strict)
+  validation: warn    # warn (log issues) or strict (errors)
 ```
 
+Use `strict` as the canonical enforcing mode. `error` is accepted only as a compatibility alias.
+
 ### Complete Example
 
 ```yaml
@@ -100,7 +102,7 @@ schema:
   attendees?(array): Person, who attended
   decisions?(array): string, decisions made
   action_items?(array): string, follow-up tasks
-  status?(enum): [scheduled, completed, cancelled], meeting state
+  status?(enum, meeting state): [scheduled, completed, cancelled]
 settings:
   validation: warn
 ---
@@ -183,7 +185,7 @@ Validation reports:
 ### Handling Validation Results
 
 - **`warn` mode**: Review warnings periodically. Fix notes that are clearly wrong; add optional fields to the schema for legitimate new patterns.
-- **`error` mode**: Use for strict schemas where conformance matters (e.g., automated pipelines consuming notes).
+- **`strict` mode**: Use where conformance matters (e.g., automated pipelines consuming notes).
 
 ## Detecting Drift
 

package/skills/memory-tasks/SKILL.md

@@ -26,7 +26,7 @@ entity: Task
 version: 1
 schema:
   description: string, what needs to be done
-  status?(enum): [active, blocked, done, abandoned], current state
+  status?(enum, current state): [active, blocked, done, abandoned]
   assigned_to?: string, who is working on this
   steps?(array): string, ordered steps to complete
   current_step?: integer, which step number we're on (1-indexed)

package/tools/list-memory-projects.ts

@@ -11,6 +11,7 @@ function normalizeProject(project: ProjectListResult) {
     is_private: project.is_private === true,
     is_default: project.is_default === true || project.isDefault === true,
     workspace_name: project.workspace_name ?? null,
+    workspace_slug: project.workspace_slug ?? null,
     workspace_type: project.workspace_type ?? null,
     workspace_tenant_id: project.workspace_tenant_id ?? null,
   }
@@ -28,7 +29,7 @@ export function registerProjectListTool(
       parameters: Type.Object({
         workspace: Type.Optional(
           Type.String({
-            description: "Filter by workspace name or tenant_id",
+            description: "Filter by workspace name, slug, or tenant_id",
           }),
         ),
       }),