@basicmemory/openclaw-basic-memory 0.1.3 → 0.1.4

package/README.md

@@ -152,6 +152,7 @@ All tools accept an optional `project` parameter for cross-project operations.
 
 | Command | Description |
 |---------|-------------|
+| `/bm-setup` | Install or update the Basic Memory CLI |
 | `/remember <text>` | Save a quick note |
 | `/recall <query>` | Search the knowledge graph |
 | `/tasks [args]` | Create, track, resume structured tasks |

package/commands/skills.ts

@@ -5,39 +5,39 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const SKILLS_DIR = resolve(__dirname, "..", "skills")
+const MANIFEST_PATH = resolve(SKILLS_DIR, "manifest.json")
+
+interface ManifestEntry {
+  dir: string
+  name: string
+  description: string
+}
+
+function loadManifest(): ManifestEntry[] {
+  try {
+    const raw = readFileSync(MANIFEST_PATH, "utf-8")
+    return JSON.parse(raw) as ManifestEntry[]
+  } catch {
+    throw new Error(
+      "skills/manifest.json not found. Run `bun scripts/fetch-skills.ts` first.",
+    )
+  }
+}
 
 function loadSkill(dir: string): string {
   return readFileSync(resolve(SKILLS_DIR, dir, "SKILL.md"), "utf-8")
 }
 
-const SKILLS = [
-  { name: "tasks", dir: "memory-tasks", desc: "Task management workflow" },
-  {
-    name: "reflect",
-    dir: "memory-reflect",
-    desc: "Memory reflection workflow",
-  },
-  { name: "defrag", dir: "memory-defrag", desc: "Memory defrag workflow" },
-  { name: "schema", dir: "memory-schema", desc: "Schema management workflow" },
-  {
-    name: "notes",
-    dir: "memory-notes",
-    desc: "How to write well-structured notes",
-  },
-  {
-    name: "metadata-search",
-    dir: "memory-metadata-search",
-    desc: "Structured metadata search workflow",
-  },
-] as const
-
 export function registerSkillCommands(api: OpenClawPluginApi): void {
-  for (const skill of SKILLS) {
-    const content = loadSkill(skill.dir)
+  const manifest = loadManifest()
+
+  for (const entry of manifest) {
+    const commandName = entry.dir.replace(/^memory-/, "")
+    const content = loadSkill(entry.dir)
 
     api.registerCommand({
-      name: skill.name,
-      description: skill.desc,
+      name: commandName,
+      description: entry.description,
       acceptsArgs: true,
       requireAuth: true,
       handler: async (ctx: { args?: string }) => {

package/commands/slash.ts

@@ -1,11 +1,43 @@
+import { execSync } from "node:child_process"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
 export function registerCommands(
   api: OpenClawPluginApi,
   client: BmClient,
 ): void {
+  api.registerCommand({
+    name: "bm-setup",
+    description: "Install or update the Basic Memory CLI (requires uv)",
+    requireAuth: true,
+    handler: async () => {
+      const scriptPath = resolve(__dirname, "..", "scripts", "setup-bm.sh")
+      log.info(`/bm-setup: running ${scriptPath}`)
+
+      try {
+        const output = execSync(`bash "${scriptPath}"`, {
+          encoding: "utf-8",
+          timeout: 180_000,
+          stdio: "pipe",
+          env: { ...process.env },
+        })
+        return { text: output.trim() }
+      } catch (err: unknown) {
+        const execErr = err as { stderr?: string; stdout?: string }
+        const detail = execErr.stderr || execErr.stdout || String(err)
+        log.error("/bm-setup failed", err)
+        return {
+          text: `Setup failed:\n${detail.trim()}`,
+        }
+      }
+    },
+  })
+
   api.registerCommand({
     name: "remember",
     description: "Save something to the Basic Memory knowledge graph",

package/openclaw.plugin.json

@@ -2,12 +2,15 @@
   "id": "openclaw-basic-memory",
   "kind": "memory",
   "skills": [
-    "skills/memory-tasks",
-    "skills/memory-reflect",
     "skills/memory-defrag",
-    "skills/memory-schema",
+    "skills/memory-ingest",
+    "skills/memory-lifecycle",
     "skills/memory-metadata-search",
-    "skills/memory-notes"
+    "skills/memory-notes",
+    "skills/memory-reflect",
+    "skills/memory-research",
+    "skills/memory-schema",
+    "skills/memory-tasks"
   ],
   "uiHints": {
     "project": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "schema/task-schema.ts",
     "schema/conversation-schema.ts",
     "skills/",
+    "scripts/fetch-skills.ts",
     "scripts/setup-bm.sh",
     "openclaw.plugin.json",
     "README.md",
@@ -55,6 +56,8 @@
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
     "lint:fix": "bunx @biomejs/biome check --write .",
+    "fetch-skills": "bun scripts/fetch-skills.ts",
+    "prepack": "bun scripts/fetch-skills.ts",
     "test": "bun test",
     "test:int": "BM_INTEGRATION=1 BM_BIN=${BM_BIN:-./scripts/bm-local.sh} bun test integration --timeout 120000",
     "test:coverage": "bun test --coverage",

package/scripts/fetch-skills.ts

@@ -0,0 +1,133 @@
+/**
+ * Fetch all memory-* skills from basicmachines-co/basic-memory-skills.
+ *
+ * Auto-discovers skill directories via GitHub Contents API, downloads each
+ * SKILL.md, writes to skills/<dir>/SKILL.md, and generates skills/manifest.json.
+ *
+ * Env vars:
+ *   GITHUB_TOKEN   — optional, avoids 60 req/hr unauthenticated rate limit
+ *   SKILLS_BRANCH  — branch to fetch from (default: "main")
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SKILLS_DIR = resolve(__dirname, "..", "skills")
+
+const REPO = "basicmachines-co/basic-memory-skills"
+const BRANCH = process.env.SKILLS_BRANCH ?? "main"
+const TOKEN = process.env.GITHUB_TOKEN
+
+interface GitHubEntry {
+  name: string
+  type: "file" | "dir"
+}
+
+interface SkillManifestEntry {
+  dir: string
+  name: string
+  description: string
+}
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "openclaw-basic-memory/fetch-skills",
+  }
+  if (TOKEN) h.Authorization = `Bearer ${TOKEN}`
+  return h
+}
+
+async function fetchJSON<T>(url: string): Promise<T> {
+  const res = await fetch(url, { headers: headers() })
+  if (!res.ok) {
+    throw new Error(`GET ${url} → ${res.status} ${res.statusText}`)
+  }
+  return res.json() as Promise<T>
+}
+
+async function fetchText(url: string): Promise<string> {
+  const res = await fetch(url, { headers: headers() })
+  if (!res.ok) {
+    throw new Error(`GET ${url} → ${res.status} ${res.statusText}`)
+  }
+  return res.text()
+}
+
+function parseFrontmatter(md: string): { name: string; description: string } {
+  const match = md.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) throw new Error("SKILL.md missing YAML frontmatter")
+
+  const yaml = match[1]
+  const name = yaml
+    .match(/^name:\s*(.+)$/m)?.[1]
+    ?.trim()
+    .replace(/^["']|["']$/g, "")
+  const description = yaml
+    .match(/^description:\s*(.+)$/m)?.[1]
+    ?.trim()
+    .replace(/^["']|["']$/g, "")
+
+  if (!name) throw new Error("Frontmatter missing 'name'")
+  if (!description) throw new Error("Frontmatter missing 'description'")
+
+  return { name, description }
+}
+
+async function main() {
+  console.log(`Fetching skills from ${REPO}@${BRANCH}`)
+
+  // 1. Discover all memory-* directories
+  const contentsUrl = `https://api.github.com/repos/${REPO}/contents?ref=${BRANCH}`
+  const entries = await fetchJSON<GitHubEntry[]>(contentsUrl)
+  const skillDirs = entries
+    .filter((e) => e.type === "dir" && e.name.startsWith("memory-"))
+    .map((e) => e.name)
+    .sort()
+
+  if (skillDirs.length === 0) {
+    throw new Error("No memory-* directories found in repo")
+  }
+
+  console.log(`Found ${skillDirs.length} skills: ${skillDirs.join(", ")}`)
+
+  // 2. Download each SKILL.md and parse frontmatter
+  const manifest: SkillManifestEntry[] = []
+
+  const results = await Promise.all(
+    skillDirs.map(async (dir) => {
+      const rawUrl = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/${dir}/SKILL.md`
+      const content = await fetchText(rawUrl)
+      const meta = parseFrontmatter(content)
+      return { dir, content, meta }
+    }),
+  )
+
+  // 3. Write files and build manifest
+  for (const { dir, content, meta } of results) {
+    const outDir = resolve(SKILLS_DIR, dir)
+    mkdirSync(outDir, { recursive: true })
+    writeFileSync(resolve(outDir, "SKILL.md"), content)
+    manifest.push({ dir, name: meta.name, description: meta.description })
+    console.log(`  ✓ ${dir}`)
+  }
+
+  // Sort manifest by dir name for deterministic output
+  manifest.sort((a, b) => a.dir.localeCompare(b.dir))
+
+  // 4. Write manifest
+  mkdirSync(SKILLS_DIR, { recursive: true })
+  writeFileSync(
+    resolve(SKILLS_DIR, "manifest.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  )
+
+  console.log(`\nWrote ${manifest.length} skills + manifest.json to skills/`)
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err.message)
+  process.exit(1)
+})

package/skills/manifest.json

@@ -0,0 +1,47 @@
+[
+  {
+    "dir": "memory-defrag",
+    "name": "memory-defrag",
+    "description": "Defragment and reorganize agent memory files: split bloated files, merge duplicates, remove stale information, and restructure the memory hierarchy. Use when memory files have grown unwieldy, contain redundancies, or need reorganization. Run periodically (weekly) or on demand."
+  },
+  {
+    "dir": "memory-ingest",
+    "name": "memory-ingest",
+    "description": "Process unstructured external input (meeting transcripts, conversation logs, pasted documents) into structured Basic Memory entities. Extracts entities, searches for existing matches, proposes new entities with approval, creates notes with observations and relations, and captures action items."
+  },
+  {
+    "dir": "memory-lifecycle",
+    "name": "memory-lifecycle",
+    "description": "Manage entity status transitions in Basic Memory: archive completed work, move notes between status folders, update frontmatter, and handle edge cases. Use when marking items complete, archiving old entities, or managing any folder-based status workflow."
+  },
+  {
+    "dir": "memory-metadata-search",
+    "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."
+  },
+  {
+    "dir": "memory-notes",
+    "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."
+  },
+  {
+    "dir": "memory-reflect",
+    "name": "memory-reflect",
+    "description": "Sleep-time memory reflection: review recent conversations and daily notes, extract insights, and consolidate into long-term memory. Use when triggered by cron, heartbeat, or explicit request to reflect on recent activity. Runs as background processing to improve memory quality over time."
+  },
+  {
+    "dir": "memory-research",
+    "name": "memory-research",
+    "description": "Research an external subject using web search, synthesize findings into a structured Basic Memory entity. Use when asked to research a company, person, technology, or topic — or when a bare name or URL is provided that implies a research request."
+  },
+  {
+    "dir": "memory-schema",
+    "name": "memory-schema",
+    "description": "Schema lifecycle management for Basic Memory: discover unschemaed notes, infer schemas, create and edit schema definitions, validate notes, and detect drift. Use when working with structured note types (Task, Person, Meeting, etc.) to maintain consistency across the knowledge graph."
+  },
+  {
+    "dir": "memory-tasks",
+    "name": "memory-tasks",
+    "description": "Task management via Basic Memory schemas: create, track, and resume structured tasks that survive context compaction. Uses BM's schema system for uniform notes queryable through the knowledge graph."
+  }
+]

package/skills/memory-defrag/SKILL.md

@@ -78,7 +78,6 @@ After changes:
 
 ## Guidelines
 
-- **Back up first.** If git is available, commit before defragging. If not, note the pre-defrag state.
 - **Preserve raw daily notes.** Don't delete or modify `memory/YYYY-MM-DD.md` files — they're the audit trail.
 - **Target 15-25 focused files.** Too few means bloated files; too many means fragmentation. Aim for the sweet spot.
 - **File names should be scannable.** Use descriptive names: `people.md`, `project-status.md`, `competitive-landscape.md` — not `notes-2.md`.

package/skills/memory-ingest/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: memory-ingest
+description: "Process unstructured external input (meeting transcripts, conversation logs, pasted documents) into structured Basic Memory entities. Extracts entities, searches for existing matches, proposes new entities with approval, creates notes with observations and relations, and captures action items."
+---
+
+# Memory Ingest
+
+Turn raw, unstructured input into structured Basic Memory entities. Meeting transcripts, conversation logs, pasted documents, email threads — anything with information worth preserving gets parsed, cross-referenced against existing knowledge, and written as proper notes.
+
+## When to Use
+
+- User pastes a meeting transcript or conversation log
+- User says "process these notes" or "add this to Basic Memory"
+- User pastes a document, article, or email for knowledge extraction
+- Any time raw external text needs to become structured knowledge
+
+## Workflow Overview
+
+```
+1. Parse raw input           → identify structure, extract key info
+2. Extract entities          → people, orgs, topics, action items
+3. Search existing entities  → multi-variation queries
+4. Research new entities     → optional web research (see memory-research)
+5. Present entity proposal   → get approval before creating
+6. Create source note        → verbatim content + observations + relations
+7. Create approved entities  → structured notes for each new entity
+8. Extract action items      → follow-ups and commitments
+```
+
+## Step 1: Parse Raw Input
+
+Read the pasted content and identify its structure:
+
+- **Format**: Meeting transcript, email thread, conversation log, article, freeform notes
+- **Date**: When this happened (extract from content or ask)
+- **Participants**: Who was involved (names, roles, organizations)
+- **Sections**: Any existing structure (headings, speaker labels, timestamps)
+
+Don't rewrite or summarize the source content. Preserve it verbatim in the note — you'll add structured observations alongside it.
+
+## Step 2: Extract Entities
+
+Scan the content for entities worth tracking in the knowledge graph:
+
+| Entity Type | Signals |
+|-------------|---------|
+| **Person** | Names with roles, titles, or affiliations mentioned |
+| **Organization** | Company names, agencies, institutions |
+| **Topic/Concept** | Technical domains, methodologies, standards discussed substantively |
+| **Action Item** | Commitments, deadlines, "I'll do X by Y" statements |
+
+**Infer type from context.** If someone is introduced as "CTO of Acme Corp", that's both a Person and an Organization entity. If a technology is discussed in depth, it might warrant a Concept entity.
+
+**Exclude noise.** Not every name mentioned is worth an entity. Filter for:
+- People with substantive roles or interactions (not passing mentions)
+- Organizations discussed in business/technical context
+- Topics with enough detail to warrant their own note
+
+## Step 3: Search Existing Entities
+
+For each extracted entity, search Basic Memory with multiple query variations:
+
+```python
+# Person — try full name, last name
+search_notes(query="Sarah Chen")
+search_notes(query="Chen")
+
+# Organization — try full name, abbreviation, acronym
+search_notes(query="National Renewable Energy Laboratory")
+search_notes(query="NREL")
+
+# Topic — try the full term and keywords
+search_notes(query="edge computing")
+search_notes(query="edge inference")
+```
+
+Classify each entity as:
+- **Existing** — found in Basic Memory. Will link to it with `[[wiki-link]]`.
+- **Proposed** — not found. Will propose creation pending approval.
+
+## Step 4: Research New Entities (Optional)
+
+For proposed entities where more context would be valuable, do a brief web search (2-3 queries max per entity):
+
+- **Organizations**: What they do, size, public/private, key products
+- **People**: Current role, background, expertise
+- **Topics**: Brief definition, relevance
+
+Use hedging language ("appears to be", "estimated", "based on public information"). Never fabricate details.
+
+This step is optional — skip it if the source material provides enough context, or if the user is in a hurry. See the **memory-research** skill for deeper research workflows.
+
+## Step 5: Present Entity Proposal
+
+Before creating anything, present what you found and what you'd like to create:
+
+```
+Entities found in Basic Memory:
+  - [[Sarah Chen]] (Person — existing)
+  - [[Acme Corp]] (Organization — existing)
+
+Proposed new entities:
+  - Jordan Rivera (Person — VP Engineering at NovaTech, mentioned as project lead)
+  - NovaTech (Organization — SaaS platform, Series B, discussed as integration partner)
+  - Federated Learning (Concept — core technical topic of the discussion)
+
+Approve all / select individually / skip entity creation?
+```
+
+Include enough context with each proposed entity for the user to make a quick decision.
+
+## Step 6: Create the Source Note
+
+Create the primary note for the ingested content. This is the "record of what happened" — it preserves the raw material and adds structured metadata.
+
+### Meeting / Conversation Note
+
+```python
+write_note(
+  title="NovaTech Meeting - Jordan Rivera - Feb 22, 2026",
+  directory="meetings/2026",
+  note_type="meeting",
+  tags=["meeting", "novatech", "federated-learning"],
+  metadata={"date": "2026-02-22"},
+  content="""
+# NovaTech Meeting - Jordan Rivera - Feb 22, 2026
+
+Brief one-sentence summary of what this meeting was about.
+
+## Transcript
+[Preserve all source content verbatim — do not summarize or rewrite]
+
+## Observations
+- [opportunity] NovaTech interested in integration partnership
+- [insight] Their platform handles 10K concurrent sessions, relevant to our scale needs
+- [next_step] Send technical spec document by Friday
+- [sentiment] Strong enthusiasm from their engineering team
+- [decision] Agreed to start with a proof-of-concept integration
+
+## Relations
+- attended [[Jordan Rivera]]
+- with [[NovaTech]]
+- discussed [[Federated Learning]]
+- follow_up [[Send NovaTech Technical Spec]]
+"""
+)
+```
+
+### Document / Article Note
+
+```python
+write_note(
+  title="Edge Computing Architecture Whitepaper",
+  directory="references",
+  note_type="reference",
+  tags=["edge-computing", "architecture", "reference"],
+  metadata={"source": "https://example.com/whitepaper.pdf", "date_ingested": "2026-02-22"},
+  content="""
+# Edge Computing Architecture Whitepaper
+
+## Source Content
+[Preserve relevant content — for long documents, include key sections rather than the entire text]
+
+## Observations
+- [key_finding] Latency drops 40% with edge inference vs cloud-only
+- [technique] Model sharding across heterogeneous edge nodes
+- [limitation] Requires minimum 8GB RAM per edge node
+
+## Relations
+- relates_to [[Edge Computing]]
+- relates_to [[Model Optimization]]
+"""
+)
+```
+
+### Observation Categories
+
+Use categories that capture the nature of the information. Common categories for ingested content:
+
+| Category | Use For |
+|----------|---------|
+| `opportunity` | Business or collaboration opportunities identified |
+| `decision` | Decisions made or agreed upon |
+| `insight` | Non-obvious understanding gained |
+| `next_step` | Concrete action items or follow-ups |
+| `sentiment` | Enthusiasm, concerns, hesitations expressed |
+| `risk` | Risks or concerns identified |
+| `requirement` | Requirements or constraints discovered |
+| `key_finding` | Important facts from reference material |
+| `technique` | Methods, approaches, or patterns described |
+| `context` | Background information that may be useful later |
+
+Invent categories as needed — these are suggestions, not a fixed list.
+
+## Step 7: Create Approved Entities
+
+For each entity the user approved, create a structured note. Match the entity type to an appropriate template.
+
+### Person
+
+```python
+write_note(
+  title="Jordan Rivera",
+  directory="people",
+  note_type="person",
+  tags=["person", "novatech", "engineering"],
+  content="""
+# Jordan Rivera
+
+## Overview
+VP of Engineering at NovaTech. Met during integration partnership discussion.
+
+## Background
+[Role, expertise, context from meeting + any web research]
+
+## Observations
+- [role] VP Engineering at NovaTech
+- [expertise] Distributed systems, federated learning
+- [met] 2026-02-22 during integration discussion
+
+## Relations
+- works_at [[NovaTech]]
+- discussed_in [[NovaTech Meeting - Jordan Rivera - Feb 22, 2026]]
+"""
+)
+```
+
+### Organization
+
+```python
+write_note(
+  title="NovaTech",
+  directory="organizations",
+  note_type="organization",
+  tags=["organization", "saas", "integration-partner"],
+  content="""
+# NovaTech
+
+## Overview
+SaaS platform company. Series B stage.
+[Additional context from meeting + web research]
+
+## Products & Services
+[What they offer, if discussed or researched]
+
+## Observations
+- [stage] Series B, ~200 employees
+- [relevance] Potential integration partner for our platform
+- [first_contact] 2026-02-22
+
+## Relations
+- employs [[Jordan Rivera]]
+- discussed_in [[NovaTech Meeting - Jordan Rivera - Feb 22, 2026]]
+"""
+)
+```
+
+### Concept / Topic
+
+```python
+write_note(
+  title="Federated Learning",
+  directory="concepts",
+  note_type="concept",
+  tags=["concept", "machine-learning", "distributed-systems"],
+  content="""
+# Federated Learning
+
+## Overview
+[Brief description of the concept from the discussion context]
+
+## Observations
+- [definition] Machine learning approach where models train across decentralized data sources
+- [relevance] Core technique discussed in NovaTech integration
+
+## Relations
+- discussed_in [[NovaTech Meeting - Jordan Rivera - Feb 22, 2026]]
+"""
+)
+```
+
+Adapt templates to your domain. The key elements are: type and tags as parameters, an overview section, observations with categories, and relations linking back to the source.
+
+## Step 8: Extract Action Items
+
+Review the source content for commitments and follow-ups:
+
+```
+Action Items:
+  - Send NovaTech technical spec document by Friday (your commitment)
+  - Jordan will share their API documentation by next week (their commitment)
+
+Follow-Up Reminders:
+  - 1 week: Check if Jordan sent API docs
+  - 2 weeks: Schedule follow-up call to discuss POC scope
+```
+
+If using the **memory-tasks** skill, create Task notes for your action items. Otherwise, capture them as observations in the source note.
+
+## Guidelines
+
+- **Preserve source content verbatim.** The original text is the ground truth. Structure and observations are your interpretation layered on top.
+- **Search before creating.** Always check if entities already exist (see memory-notes search-before-create pattern). Update existing entities with new information rather than creating duplicates.
+- **Get approval for new entities.** Present proposed entities and let the user decide which to create. Don't silently populate the knowledge graph.
+- **Infer, don't interrogate.** Extract entity types and relationships from context. Only ask the user when genuinely ambiguous.
+- **Be selective about entities.** Not every name mentioned deserves its own note. Focus on entities the user will want to reference again.
+- **Use hedging for researched info.** Web research supplements — don't present it as fact. "Appears to be", "estimated", "based on public information".
+- **Link everything back.** Every created entity should relate back to the source note. The source note should link to all entities discussed.
+- **Prose and observations together.** Notes work best with both narrative context and structured observations. Prose gives meaning and tells the story; observations make individual facts searchable. Use the body for context, then distill key facts into categorized observations.