@basicmemory/openclaw-basic-memory 0.23.1 → 0.24.0

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

@@ -1,11 +1,11 @@
 ---
 name: memory-literary-analysis
-description: "Analyze a complete literary work into a structured Basic Memory knowledge graph. Covers schema design, entity seeding, chapter-by-chapter processing, cross-referencing, validation, and visualization."
+description: "Analyze a complete literary work into a structured Basic Memory knowledge graph: schema design, entity seeding, chapter-by-chapter processing, cross-referencing, and validation."
 ---
 
 # Memory Literary Analysis
 
-Transform a complete literary work into a structured knowledge graph. Characters, themes, chapters, locations, symbols, and literary devices become interconnected notes — searchable, validatable, and visualizable.
+Transform a complete literary work into a structured knowledge graph. Characters, themes, chapters, locations, symbols, and literary devices become interconnected notes — searchable, validatable, and traversable.
 
 ## When to Use
 
@@ -23,15 +23,56 @@ 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     → Obsidian canvas files for character webs, timelines
+Phase 5: Explore       → traverse the graph, write synthesis notes
 ```
 
+## Tools
+
+Writing always goes through `write_note` and `edit_note`. For *reading* — which is most of
+the work in a long analysis — prefer the POSIX read verbs where they are available
+(the MCP `cat`, `find`, `grep`, and `ls` tools are on by default; the `bm` CLI verbs are always
+available):
+
+| Need | Use | Instead of |
+|------|-----|-----------|
+| A section of a long note | `cat <note> --section Observations` | reading the whole note |
+| A line range of the source text | `cat <source>.txt --lines 4200-4890` | pulling the whole book into context |
+| Notes matching frontmatter | `find --meta status=active` | reading notes to check fields |
+| Fields across many notes | `find --meta ... --fields pov,setting` | one read per note |
+| Where something lives | `ls`, `tree`, `find --name '*.md'` | listing everything |
+
+The two rules that matter across a 100+ chapter run:
+
+- **Never read a note to check a field.** That is what `--meta` predicates and `--fields`
+  projection are for — one call answers what a read-per-note loop would cost.
+- **Never pull a whole file into context to reach one part of it.** Sections and line ranges
+  slice the *output*: the full note is still fetched, then cut down before it is returned. What
+  they save is context, not I/O — a long chapter or a full source text costs you the tokens of
+  the relevant part, not of the whole file.
+
+Two sharp edges to know before you write a query. The first fails *quietly* — a short
+answer, exit 0, no warning — so learn it here rather than from a graph you thought you had
+audited:
+
+- **`find` pages, and the default page is 10.** Any query whose answer is "all N chapters"
+  needs `--page-size 200` (the maximum) — see [Coverage Checks](#coverage-checks).
+- **`--name` cannot combine with `--meta`.** The metadata search has no filename glob. Scope a
+  `--meta` query with the positional path instead: `find /characters --meta
+  'note_type=character'`. That path is matched on a directory boundary against the *file path*
+  a note is indexed under — where the note actually lives, not its permalink, which stops
+  mirroring the file path once a note pins `permalink:` in frontmatter or is moved. So
+  `/characters` reaches everything filed under `characters/` (including `characters/major/`),
+  and never `characters-cut/`.
+
+If the POSIX verbs are unavailable, every step below still works with `search_notes`,
+`read_note`, and `list_directory` — it just costs more.
+
 ## Phase 0: Setup
 
 ### Create the Project
 
 ```python
-create_memory_project(name="<work-name>", path="~/basic-memory/<work-name>")
+create_memory_project(project_name="<work-name>", project_path="~/basic-memory/<work-name>")
 ```
 
 Use a kebab-case slug of the work's title (e.g., `great-gatsby`, `hamlet`, `beloved`).
@@ -212,6 +253,7 @@ Schema for literary technique and device notes.
 
 ```
 <project>/
+  <work>.txt         # the source text, verbatim (see Phase 2)
   schema/            # 6 schema definitions
   chapters/          # one note per chapter/section + prologue/epilogue
   characters/
@@ -271,6 +313,46 @@ Stubs don't need to be complete — they give `[[wiki-link]]` targets and will b
 
 Obtain the full text and identify chapter/section boundaries. For public domain works, Project Gutenberg is a good source. For copyrighted works, work from a physical or licensed digital copy.
 
+**Put the source text inside the project directory, as `.txt`, and index it once.** `bm cat`
+resolves a *note identifier*, not a filesystem path — it can only reach a file the project
+index has observed. A one-time index pass gives the raw text an entity row, after which the
+line-range slice works against it:
+
+```bash
+cp ~/Downloads/moby-dick.txt ~/basic-memory/moby-dick/moby-dick.txt
+bm reindex --search -p moby-dick          # one pass; the .txt becomes readable
+```
+
+Two constraints that make this the right shape, both worth respecting:
+
+- **Keep it `.txt`, do not convert it to `.md`.** Basic Memory injects frontmatter into
+  markdown notes, which shifts every line number by the height of that block — an offset map
+  built from the original file would then be silently wrong. A `.txt` is stored verbatim, so
+  its line numbers stay 1:1 with the file on disk.
+- **Keep it inside the project.** A source text elsewhere on disk is not an entity, and
+  `bm cat` answers `Error: Entity not found`. If you must leave it outside, drop the BM verbs
+  for the source and use plain shell (`sed -n '4200,4890p' <path>`) — the notes still get the
+  BM verbs, only the raw source falls back to the shell.
+
+**Then build a chapter offset map once, before processing.** Scan the text for chapter
+headings and record the line range of each chapter, then read chapters by range rather than
+re-reading the whole book into context:
+
+```bash
+grep -n '^CHAPTER ' ~/basic-memory/moby-dick/moby-dick.txt   # heading -> line number
+bm cat moby-dick/moby-dick.txt --lines 4200-4890 --plain   # one chapter, not the whole text
+```
+
+`grep -n` here is the shell's grep on a filesystem path (this is the map-building step, and
+it needs the file). `bm cat` then takes the *note identifier* and returns exactly that slice plus a
+`lines 4200-4890 of N` footer. Spell the identifier project-qualified
+(`<work>/<work>.txt`) so it routes to the right project. `bm head moby-dick/moby-dick.txt -n 40` is the cheap
+way to eyeball the heading format before writing the grep pattern.
+
+Store the map in the project (a note or a small JSON file) so later batches — and a resumed
+run after context compaction — do not have to rediscover it. On a long work this is the
+single largest context saving in the pipeline.
+
 ### Batching Strategy
 
 Process ~10 chapters per batch to balance depth with progress. Group by narrative arc or thematic focus:
@@ -289,7 +371,9 @@ Adjust batch size based on chapter length and density. Short, action-heavy chapt
 
 For each chapter:
 
-**1. Read the chapter carefully.** If working from a source text file, read the relevant section.
+**1. Read the chapter carefully.** Read the chapter's line range from the offset map
+(`bm cat <source>.txt --lines <start>-<end>`), not the whole file. Read the actual text —
+never work from memory or a summary; textual evidence is the entire point.
 
 **2. Create the chapter note:**
 
@@ -332,13 +416,17 @@ write_note(
 ```python
 edit_note(
   identifier="characters/major/<character-slug>",
-  operation="append",
-  heading="Observations",
+  operation="insert_after_section",
+  section="Observations",
   content="""- [arc] Ch.<N>: <What happens to this character>
 - [quote] "<Attributed quote>" (Ch.<N>)"""
 )
 ```
 
+`append` and `prepend` do not target a section — they write at the end of the note and the
+start of the body. Use `insert_after_section` / `insert_before_section` to land lines under a
+heading; they fail loudly if the heading is missing.
+
 **4. Track progress** using the memory-tasks skill to create a processing task that survives context compaction.
 
 ### What to Capture Per Chapter
@@ -364,7 +452,7 @@ As each chapter is processed, append observations to relevant entities:
 
 ### Adding Prose and Interpretation
 
-After the structured observations are in place, consider adding interpretive prose to major entity notes. Prepend 2-4 paragraphs of critical essay before the Observations section using `edit_note(operation="prepend")`. This prose should:
+After the structured observations are in place, consider adding interpretive prose to major entity notes. Insert 2-4 paragraphs of critical essay before the Observations section with `edit_note(operation="insert_before_section", section="Observations", content=...)`. This prose should:
 
 - Argue for a reading of the character, theme, or symbol — not just describe it
 - Connect the entity to the work's larger concerns and to literary tradition
@@ -377,6 +465,25 @@ The prose adds the interpretive texture that structured observations alone canno
 
 After all chapters are processed:
 
+### Find What Needs Enriching
+
+Do not re-read every note to decide what is thin. Query for it:
+
+```bash
+bm find --meta 'note_type=chapter' --fields chapter_number,pov,setting --page-size 200
+bm find --meta 'note_type=character' --fields role,status --page-size 200   # who is still a stub
+bm find --meta 'chapter_number>100' --fields pov --page-size 200           # late-book POV drift
+```
+
+A field a note never set comes back as a blank cell (`null` under `--json`), so rows with
+blanks are the work queue. This turns "audit the graph" from a read of every note into one
+call per question.
+
+`write_note` snake-cases `note_type` (`Chapter` is stored as `chapter`), and `--meta`
+type predicates are normalized the same way, so either spelling matches. `--page-size 200`
+is not decoration: without it these return the first 10 rows and the work queue looks ten
+items long.
+
 ### Character Arcs
 For each major character, write a full `[arc]` summary observation covering their trajectory across the work.
 
@@ -426,18 +533,18 @@ During chapter processing, new minor characters, locations, and symbols will eme
 
 ```python
 # Validate each entity type
-schema_validate(noteType="Character")
-schema_validate(noteType="Theme")
-schema_validate(noteType="Chapter")
-schema_validate(noteType="Location")
-schema_validate(noteType="Symbol")
-schema_validate(noteType="LiteraryDevice")
+schema_validate(note_type="Character")
+schema_validate(note_type="Theme")
+schema_validate(note_type="Chapter")
+schema_validate(note_type="Location")
+schema_validate(note_type="Symbol")
+schema_validate(note_type="LiteraryDevice")
 ```
 
 ### Drift Detection
 
 ```python
-schema_diff(noteType="Character")
+schema_diff(note_type="Character")
 # ... for each type
 ```
 
@@ -446,26 +553,147 @@ Fix issues found — common fixes:
 - Enum values outside allowed set → correct metadata
 - Fields in notes but not schema → add as optional to schema if legitimate
 
+### Coverage Checks
+
+Schema validation proves notes match their shape. These prove the graph is *complete*:
+
+```bash
+bm find --meta 'note_type=chapter' --fields chapter_number --page-size 200   # every chapter present?
+bm find --meta 'note_type=chapter' --fields pov,setting --page-size 200      # missing context?
+bm find /characters --meta 'note_type=character' --fields role --page-size 200  # inventory vs. seed list
+```
+
+**A coverage check that pages is not a coverage check.** `bm find` defaults to
+`--page-size 10`, so the un-sized form of the first query "proves" a 138-chapter work has 10
+chapters. 200 is the maximum page size; past that, iterate with `--page 2`, `--page 3`, … .
+Scope a `--meta` query with the positional path (`/characters`), never `--name` — the two
+options are mutually exclusive, because the metadata search has no filename glob. The
+positional path scopes by the *file path* a note is indexed under, matched on a directory
+boundary: `/characters` admits `characters/major/ahab.md` but never `characters-cut/`. It is
+not a permalink match, so a note that pins its own `permalink:` is still found where its file
+lives.
+
+Read the count off the footer, not off the rows you can see. In a terminal every `find`
+result reports `page 1 • total 138`, and appends `• more available (--page)` when the page
+truncated the answer — that suffix appearing is the check *failing*, whatever the visible
+rows say. **The footer is a TTY feature.** Piped output without `--plain` is JSON, which
+carries `total` and `has_more`; with `--plain` the rows go to stdout and a has-more notice
+goes to stderr. For scripts, read `has_more` from `--json`.
+
+For the sequence gap — the failure that a count alone cannot catch — take the numbers from
+`--json`, which carries `total`, `total_is_exact`, and `has_more`:
+
+```bash
+expected=138; page=1; rows='[]'
+while :; do
+  resp=$(bm find --meta 'note_type=chapter' --fields chapter_number \
+           --page-size 200 --page $page --project <work> --json)
+  rows=$(jq -n --argjson acc "$rows" --argjson r "$resp" \
+           '$acc + [$r.results[] | {title, n: .fields.chapter_number}]')
+  [ "$(jq -r '.has_more' <<<"$resp")" = "true" ] || break
+  page=$((page + 1))
+done
+jq -n --argjson rows "$rows" --argjson expected "$expected" '
+  ([$rows[] | select(.n != null and (.n | tostring | test("^[0-9]+$"))) | .n | tonumber]) as $n
+  | { total:        ($rows | length),
+      unnumbered:   [$rows[] | select(.n == null or (.n | tostring | test("^[0-9]+$") | not))
+                             | .title],
+      missing:      ([range(1; $expected + 1)] - $n),
+      duplicates:   ($n | group_by(.) | map(select(length > 1) | .[0])),
+      out_of_range: ($n | map(select(. < 1 or . > $expected)) | unique) }'
+```
+
+The loop is not ceremony. `--page-size` caps at 200, so a single call cannot inventory a work
+with more than 200 chapters — and rerunning it with `--page 2` *replaces* the numbers rather
+than accumulating them, which reports chapters 1-200 as missing on a corpus that is complete.
+Walk until `has_more` is false and check the union.
+
+`--fields` returns YAML-native types, so `chapter_number: 63` comes back as `63`. The
+`tostring | test(...) | tonumber` guard still catches hand-typed values such as `"63"` or
+`"12a"`.
+
+Pass the work's **actual** chapter count as `$expected` — deriving the range from the highest
+number found lets an incomplete graph pass. With 138 rows numbered 1..137 plus one duplicate,
+a max-derived check reports `missing: []` while a chapter is genuinely absent: the duplicate
+keeps the count right and the missing tail moves the goalpost. The check passes on
+`unnumbered: []`, `missing: []`, `duplicates: []`, **and** `out_of_range: []` together, over
+the combined pages.
+
+`unnumbered` is not decoration either. A `chapter` note that never got a `chapter_number` comes
+back as `null`, and feeding that straight to `tonumber` aborts the whole pipeline with `null
+cannot be parsed as a number` — so the check *crashes on exactly the malformed inventory it
+exists to find*. Partitioning first turns that into a named row.
+
+`out_of_range` is not hypothetical: a prologue or epilogue typed as `chapter` lands at 0 or at
+`$expected + 1`, and without that key the report reads clean — every expected number present,
+none repeated — while the inventory holds a note the numbering does not account for. Type
+front and back matter as its own note type, or widen `$expected` deliberately.
+
+A gap in the middle of a batch is the most common processing failure and the easiest to miss
+by eye; a duplicated chapter number is the second, and it hides the first.
+
 ### Relation Consistency
 Spot-check bidirectional relations: if Chapter X `features [[Character]]`, does Character have observations referencing Chapter X? Fix gaps.
 
-## Phase 5: Visualization
+Orphans are the other half of this check — a note with no inbound or outbound relations is
+either genuinely isolated or was never linked back into the graph:
+
+```bash
+bm orphans          # entities with no relations in the graph
+```
+
+`orphans` finds notes with no relations. It does not find a `[[target]]` that resolves to
+nothing — a misspelled or renamed entity name. Check a chapter's links with `bm tool build-context memory://chapters/<slug> --depth 1
+--project <work> --json` and look for relations whose `to_entity_id` is `null`; fix the
+spelling or add the alias, then re-run the chapter.
+
+Graph quality is relation *density*, not note count. A pass that adds notes while leaving
+orphans behind has made the graph worse.
+
+## Phase 5: Explore the Graph
 
-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:
+With the graph complete, traverse it to find what the chapter-by-chapter pass could not see:
 
-```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"}
-  ]
-}
+```bash
+bm grep "features [[" --page-size 200 --project <work> --json   # every chapter's cast, one call
+bm find --meta 'note_type=theme' --fields prevalence --page-size 200  # thematic weight
+bm grep "doubloon" --page-size 100 --project <work>                # every mention of a symbol
 ```
 
-Useful canvases: character relationship web (protagonist/antagonist/supporting), theme connections, chapter timeline with key events.
+"Which characters share the most chapters" is the first line plus a local parse of each
+row's `content` for `features [[...]]` — one call instead of a read per chapter. Do not
+reach for `bm tool build-context 'memory://characters/major/*'` here: a
+wildcard context is capped at 100 related rows across all primaries and returns one primary
+row per indexed observation, so it neither enumerates the cast nor walks the web.
+`build-context` on a *single* note is the right tool for a different question, below.
+`build-context` takes its URL as a positional argument — there is no `--url` option.
+
+`grep` matches keywords and returns a page of 10, which quietly truncates "where does this
+appear?" — a symbol in 40 chapters comes back as 10. For symbol tracing, raise
+`--page-size`; the meaning shifts you are hunting are usually in the later occurrences, which
+the default page would have dropped. `--semantic` ranks by meaning instead, which answers
+"what is this about?" rather than "where does this word appear?".
+
+Two more facts about `grep` rows. Matching is case-insensitive and note-level: a hit is a
+note, not a line, and there is no `-n` or context. And each row's `content` is capped at
+4000 characters; `content_truncated: true` marks a cut row, so a long note's tail (such as a
+final chapter's `follows`/`precedes` relations) may be missing from a grep-driven scan.
+When a parse depends on the end of a note, `cat` that note.
+
+`--page-size` raises the ceiling, it does not remove it. A symbol in a long work can exceed
+even 100, so check whether the last page was full and walk `--page 2`, `--page 3` until it is
+not. A truncated symbol search fails the same silent way as an unpaginated `find`: a plausible
+answer, exit 0, and no sign that the tail is missing.
+
+And `grep` searches **your notes, not the source**. The `<work>.txt` is indexed as an entity,
+but its body is not in the searchable text, so an occurrence you never carried into a note is
+unreachable: a word present only in the source returns `total: 0`. So this answers "where have I written about the doubloon", not
+"where does the doubloon appear in the book". For the latter, search the file itself and use
+the [chapter offset map](#source-text-preparation) to turn a hit into a chapter.
+
+Traversal is where second-order questions get answered — which characters share the most
+chapters, which themes converge in the final act, where a symbol's meaning shifts. Capture
+what you find as `analysis/` notes; those syntheses are the payoff of having built the graph.
 
 ## Adapting to Other Genres
 
@@ -504,6 +732,8 @@ This pipeline works for any literary text. Adjust schemas for genre:
 - **Seed before processing.** Create entity stubs first so wiki-links resolve immediately during chapter processing.
 - **Batch for sanity.** Processing ~10 chapters at a time balances depth with momentum. Track progress with a Task note.
 - **Read the source text.** Don't rely on memory or summaries. Read (or re-read) the actual text for each batch before creating notes. Textual evidence is everything.
+- **Read narrowly.** Keep the source text in the project as `.txt`, index it once, build the chapter offset map once, then read chapters by line range and notes by section. On a long work, whole files landing in context are the largest avoidable cost in the pipeline.
+- **Query, don't scan.** When you need to know which notes have a field, ask with `--meta` predicates and `--fields` projection. Reading notes to check frontmatter is the mistake this pipeline makes at scale. One way these queries lie quietly: `find` returns 10 rows unless you pass `--page-size`.
 - **Observations are your index.** The knowledge graph's value comes from categorized observations. Be generous with categories and specific with content.
 - **Relations are your web.** Every chapter should link to characters, themes, locations, and devices. Every entity should link back to chapters where it appears.
 - **Enrich iteratively.** Entity notes grow richer with each chapter. Don't try to write the perfect character note upfront — append as you go.

package/skills/memory-metadata-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-metadata-search
-description: "Structured metadata search for Basic Memory: query notes by custom frontmatter fields using equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any custom YAML field rather than free-text content."
+description: "Search Basic Memory notes by custom frontmatter fields with equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any YAML field, not free text."
 ---
 
 # Memory Metadata Search
@@ -56,6 +56,17 @@ Numeric values use numeric comparison; strings use lexicographic comparison.
 {"score": {"$between": [0.3, 0.8]}}
 ```
 
+### Null (field missing or explicitly null)
+
+```json
+{"owner": null}
+```
+
+Matches notes with no `owner` key and notes whose `owner` is explicitly null.
+Null works only as a plain equality value — inside `$in`, `$between`, an
+array-contains list, or a comparison it is rejected, because those compare
+against the value and a comparison with null is never true.
+
 ### Nested Access (dot notation)
 
 ```json
@@ -67,20 +78,34 @@ Numeric values use numeric comparison; strings use lexicographic comparison.
 | Operator | Syntax | Example |
 |----------|--------|---------|
 | Equality | `{"field": "value"}` | `{"status": "active"}` |
+| Is null | `{"field": null}` | `{"owner": null}` |
 | Array contains | `{"field": ["a", "b"]}` | `{"tags": ["security", "oauth"]}` |
 | `$in` | `{"field": {"$in": [...]}}` | `{"priority": {"$in": ["high", "critical"]}}` |
 | `$gt` / `$gte` | `{"field": {"$gt": N}}` | `{"confidence": {"$gt": 0.7}}` |
 | `$lt` / `$lte` | `{"field": {"$lt": N}}` | `{"score": {"$lt": 0.5}}` |
 | `$between` | `{"field": {"$between": [lo, hi]}}` | `{"score": {"$between": [0.3, 0.8]}}` |
+| `$contains` | `{"field": {"$contains": value}}` | `{"tags": {"$contains": "security"}}` |
+| `$exists` | `{"field": {"$exists": true}}` | `{"owner": {"$exists": false}}` |
 | Nested | `{"a.b": "value"}` | `{"schema.version": "2"}` |
 
 **Rules:**
 - Keys must match `[A-Za-z0-9_-]+` (dots separate nesting levels)
-- Operator dicts must contain exactly one operator
+- Several operators on one field AND together: `{"started": {"$gte": "2026-01-01", "$lt": "2026-02-01"}}`
 - `$in` and array-contains require non-empty lists
 - `$between` requires exactly `[min, max]`
-
-> **Warning:** Operators MUST include the `$` prefix — write `$gte`, not `gte`. Without the prefix the filter is treated as an exact-match key and will silently return no results. Correct: `{"confidence": {"$gte": 0.7}}`. Wrong: `{"confidence": {"gte": 0.7}}`.
+- `null` is an is-null match and only valid as a plain equality value
+- Comparison and `$between` bounds must be finite numbers — a magnitude no float
+  can hold (a 400-digit integer, which JSON keeps as an ordinary `int`) is
+  refused rather than compared against an infinite bound
+- Metadata filters match Markdown notes only — indexed PDFs, images and other
+  regular files carry no frontmatter and are never hits, not even for `null`
+
+> The leading `$` is optional (`gte` works), but write it for clarity.
+
+Frontmatter fields say when a note was filed or reviewed. To ask what a note
+*claims was true* on a date, use observation qualifiers (see **memory-notes**)
+and `search_notes(valid_at="2026-07-01")` or
+`search_notes(valid_overlaps="[2026-07-01,2026-08-01)")`.
 
 ## Using `search_notes` with Metadata
 

package/skills/memory-notes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-notes
-description: "How to write well-structured Basic Memory notes: frontmatter, observations with semantic categories, relations with wiki-links, and best practices for building a rich knowledge graph. Use when creating or improving notes."
+description: "How to write well-structured Basic Memory notes: frontmatter, categorized observations, wiki-link relations, and knowledge-graph best practices. Use when creating or improving notes."
 ---
 
 # Memory Notes
@@ -49,7 +49,7 @@ permalink: custom-path     # optional — auto-generated from title if omitted
 - The `title` must match the `# Heading` in the body
 - Tags are searchable and help with discovery
 - Custom `type` values (Task, Meeting, Person, etc.) work with the schema system. See the **memory-schema** skill for defining schemas, validating notes against them, and detecting drift.
-- The `permalink` is auto-generated from the `title` and `directory`. For example, title "API Design Decisions" in directory "specs" produces permalink `specs/api-design-decisions` and memory URL `memory://specs/api-design-decisions`. If no directory is specified, the permalink is just the kebab-cased title. Permalinks stay stable across file moves. You rarely need to set one manually.
+- The `permalink` is auto-generated from the `title` and `directory`. For example, title "API Design Decisions" in directory "specs" produces permalink `specs/api-design-decisions` and memory URL `memory://specs/api-design-decisions`. If no directory is specified, the permalink is just the kebab-cased title. By default permalinks stay stable across file moves (unless the project enables `update_permalinks_on_move`). You rarely need to set one manually.
 
 > **Note:** When using `write_note`, you don't write frontmatter yourself. The `title`, `tags`, `note_type`, and `metadata` are separate parameters — Basic Memory generates the frontmatter automatically. Your `content` parameter is just the markdown body starting with `# Heading`.
 
@@ -99,7 +99,42 @@ A few examples to illustrate the range:
 - **One fact per observation.** Don't pack multiple ideas into one line.
 - **Be specific.** `[decision] Use JWT` is less useful than `[decision] Use JWT with 15-minute expiry for API auth`.
 - **Use tags for cross-cutting concerns.** `[risk] Rate limiting needed #api #security` makes this findable under both topics.
-- **Categories are queryable.** `search_notes("[decision]")` finds all decisions across your knowledge base.
+- **Categories are queryable.** `search_notes(entity_types=["observation"], categories=["decision"])` returns every decision observation across your knowledge base.
+
+### When a Claim Holds
+
+An observation can say when it is true. Put a qualifier after the category:
+
+```
+- [decision] @effective:2026-06-10 The cache layer uses Redis
+- [event] @occurred:2026-10-14 Launch sync moved the date to Thursday
+- [deadline] @due:2026-10-20 Draft ready for review
+- [stage] @valid:2026-10 Series B, about 200 employees
+- [decision] @effective[2026-06-10,2026-10-14) Launch on Friday
+```
+
+- **Kinds**: `effective` (a decision or rule takes effect), `occurred` (an
+  event happened), `due` (a commitment), `mentioned` (when it was said), and
+  `valid`, the default (`@2026-06-10` means `@valid:2026-06-10`).
+- **Points** cover the span their precision names: `@2026` is that year,
+  `@2026-06` that month, and `@2026-06-10` from that date onward.
+- **Ranges** use `[start,end)`, and either end can be open: `@effective[2026-06-10,)`.
+- **Dates** are written out. An unquoted date is one token (`@occurred:2026-06-10`).
+  Quote anything longer: `@occurred:"June 10, 2026"`. A relative date like
+  `yesterday` is never read as a qualifier; it stays in the text.
+- **When a fact changes**, close the old one's range and start the new one,
+  instead of deleting the old one. Both stay searchable by date.
+
+Search by what notes say was true, rather than by when they were edited:
+
+```python
+search_notes(valid_at="2026-07-01")                              # true on that date
+search_notes(time_kind="due", valid_overlaps="[2026-10-14,2026-10-21)")  # due this week
+```
+
+A valid-time filter returns only dated observations; drop it to search
+everything. Day points run "from that date onward", so a due-date window also
+returns items that are already overdue.
 
 ## Relations
 
@@ -218,10 +253,10 @@ For people, try full name and last name. For organizations, try the full name an
 When a note already exists, make targeted edits instead of rewriting the whole file:
 
 ```python
-# Append a new observation to an existing note
+# Add a new observation under the existing Observations heading
 edit_note(
   identifier="API Design Decisions",
-  operation="append",
+  operation="insert_after_section",
   section="Observations",
   content="- [decision] Switched to OpenAPI 3.1 for spec generation #api"
 )
@@ -237,7 +272,7 @@ edit_note(
 # Add a new relation
 edit_note(
   identifier="API Design Decisions",
-  operation="append",
+  operation="insert_after_section",
   section="Relations",
   content="- depends_on [[Rate Limiter]]"
 )
@@ -276,16 +311,20 @@ Basic Memory auto-generates frontmatter (including the permalink and memory URL)
 
 ### Editing an Existing Note
 
-Use `edit_note` to update a note in place — four operations:
+Use `edit_note` to update a note in place — six operations: `append`, `prepend`,
+`find_replace`, `replace_section`, `insert_before_section`, `insert_after_section`.
 
 ```python
-# append / prepend — add to the end or start (use for time-ordered logs)
+# insert_after_section / insert_before_section — add lines at an existing heading
 edit_note(
   identifier="API Design Decisions",
-  operation="append",
+  operation="insert_after_section",
   section="Observations",
   content="- [decision] Use OpenAPI 3.1 for spec generation #api"
 )
+
+# append / prepend — add to the end of the note or the start of the body
+# (use for time-ordered logs; neither one targets a section)
 edit_note(
   identifier="API Design Decisions",
   operation="prepend",
@@ -309,8 +348,23 @@ edit_note(
 )
 ```
 
-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.
+When an edit is destructive (`replace_section`, `find_replace`), read the note first
+and pass its checksum, so the edit applies only to the revision you read:
+
+```python
+note = read_note(identifier="API Design Decisions", output_format="json")
+edit_note(
+  identifier="API Design Decisions",
+  operation="replace_section",
+  section="Summary",
+  content="Concise, current summary of the decision and its rationale.",
+  expected_checksum=note["checksum"]
+)
+```
+
+A checksum conflict means someone changed the note after you read it. Read it
+again and redo the edit against the new text. `write_note(overwrite=True)` takes
+`expected_checksum` the same way.
 
 ### Moving a Note
 
@@ -323,7 +377,7 @@ move_note(
 )
 ```
 
-The permalink stays the same after a move, so all `[[wiki-links]]` and `memory://` URLs continue to resolve.
+By default the permalink stays the same after a move, so links keep resolving. Projects with `update_permalinks_on_move` enabled rewrite it from the new path.
 
 ## Best Practices
 
@@ -333,10 +387,8 @@ The permalink stays the same after a move, so all `[[wiki-links]]` and `memory:/
 
 3. **Build incrementally.** Add to existing notes rather than creating duplicates. Use `edit_note` to append new observations or relations as you learn more.
 
-4. **Review AI-generated content.** When an AI writes notes for you, review them for accuracy. The AI captures structure well but may miss nuance.
-
-5. **Use consistent titles.** Note titles are identifiers in the knowledge graph. `API Design Decisions` and `Api Design decisions` are different entities. Pick a convention and stick with it.
+4. **Use consistent titles.** Note titles are identifiers in the knowledge graph. `API Design Decisions` and `Api Design decisions` are different entities. Pick a convention and stick with it.
 
-6. **Link related concepts.** The value of a knowledge graph compounds with connections. A note with zero relations is an island — useful, but not as powerful as a connected one.
+5. **Link related concepts.** The value of a knowledge graph compounds with connections. A note with zero relations is an island — useful, but not as powerful as a connected one.
 
-7. **Let the graph grow naturally.** Don't try to design a perfect taxonomy upfront. Write notes as you work, add relations as connections emerge, and periodically use `/reflect` or `/defrag` to consolidate.
+6. **Let the graph grow naturally.** Don't try to design a perfect taxonomy upfront. Write notes as you work, add relations as connections emerge, and periodically use the **memory-reflect** or **memory-defrag** skills to consolidate.