@basicmemory/openclaw-basic-memory 0.1.3 → 0.1.4

package/skills/memory-research/SKILL.md

@@ -0,0 +1,235 @@
+---
+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."
+---
+
+# Memory Research
+
+Research an external subject, synthesize what you find, and create a structured Basic Memory entity — with the user's approval.
+
+## When to Use
+
+**Explicit triggers:**
+- "Research [subject]"
+- "Look up [subject]"
+- "What do you know about [subject]?"
+- "Evaluate [subject]"
+
+**Implicit triggers (also activate this skill):**
+- A bare name: "Terraform"
+- A URL: "https://example.com"
+- A name with context: "Acme Corp — saw them at the conference"
+
+## Workflow
+
+### Step 1: Web Research
+
+Search for current information across multiple sources. Aim for 3-5 searches to build a well-rounded picture:
+
+```
+[subject name] site
+[subject name] overview
+[subject name] news [current year]
+[subject name] [relevant domain keywords]
+```
+
+**What to gather by entity type:**
+
+| Entity Type | Key Information |
+|-------------|----------------|
+| **Organization** | What they do, products/services, stage (startup/growth/public), funding, leadership, headquarters, employee count, notable partnerships or contracts |
+| **Person** | Current role, organization, background, expertise, notable work, public presence |
+| **Technology** | What it does, who maintains it, maturity, ecosystem, alternatives, adoption |
+| **Topic/Domain** | Definition, current state, key players, trends, relevance to user's context |
+
+### Step 2: Check Existing Knowledge
+
+Before proposing a new entity, search Basic Memory:
+
+```python
+search_notes(query="Acme Corp")
+search_notes(query="acme")
+```
+
+Try name variations — full name, abbreviation, acronym, domain name.
+
+If the entity already exists:
+- Report what you found in Basic Memory alongside your web research
+- Offer to update the existing note with new information
+- Use `edit_note` to append new observations or update outdated ones
+
+If the entity doesn't exist, proceed to evaluation.
+
+### Step 3: Evaluate and Summarize
+
+Present your findings in a structured summary. Include all relevant information organized by section:
+
+```markdown
+## [Subject Name]
+
+**Type:** [Organization / Person / Technology / Topic]
+
+**Summary:** [2-4 sentences: what this is, why it matters, key distinguishing facts]
+
+**Key Details:**
+- [Organized by what's relevant for the entity type]
+- [Stage, funding, leadership for orgs]
+- [Role, expertise, affiliations for people]
+- [Maturity, ecosystem, alternatives for tech]
+
+**Relevance:** [Why this matters to the user — connection to their work, domain, or interests.
+If no obvious connection: "No specific connection identified."]
+
+**Sources:**
+- [URLs of key sources consulted]
+```
+
+### Evaluation Guidelines
+
+**Use hedging language.** Web research is a snapshot, not ground truth:
+- "Appears to be", "Based on public information", "Estimated"
+- "As of [date]", "According to [source]"
+- Never state funding amounts, employee counts, or revenue as exact unless citing a primary source
+
+**Don't fabricate.** If information isn't available, say so:
+- "Leadership information not publicly available"
+- "Funding details not disclosed"
+
+**Let the user define relevance.** Don't impose a fixed evaluation framework. Instead, highlight facts and let the user draw conclusions. If the user has a specific evaluation rubric (strategic fit, buy/partner/compete, etc.), they'll tell you — apply it when asked.
+
+### Step 4: Propose Entity Creation
+
+After presenting the summary, ask for approval:
+
+```
+Create Basic Memory entity for [Subject]?
+  Location: [suggested-folder]/[entity-name].md
+  Type: [entity type]
+
+  [yes / no / modify]
+```
+
+If the user provided context with their request ("saw them at the conference"), include that context in the proposed entity.
+
+### Step 5: Create the Entity
+
+After approval, create a structured note. Adapt the template to the entity type:
+
+#### Organization
+
+```python
+write_note(
+  title="Acme Corp",
+  directory="organizations",
+  note_type="organization",
+  tags=["organization", "relevant-tags"],
+  content="""# Acme Corp
+
+## Overview
+[2-3 sentence description from research]
+
+## Products & Services
+- [Key offerings discovered in research]
+
+## Background
+**Stage:** [Startup / Growth / Public]
+**Headquarters:** [Location]
+**Employees:** [Estimate, hedged]
+**Leadership:** [Key people if found]
+**Founded:** [Year if found]
+
+## Observations
+- [relevance] Why this entity matters in user's context
+- [source] Researched on YYYY-MM-DD
+- [additional observations from research findings]
+
+## Relations
+- [Link to related entities already in the knowledge graph]"""
+)
+```
+
+#### Person
+
+```python
+write_note(
+  title="Jane Smith",
+  directory="people",
+  note_type="person",
+  tags=["person", "relevant-tags"],
+  content="""# Jane Smith
+
+## Overview
+[Current role and affiliation. Brief background.]
+
+## Background
+**Role:** [Title at Organization]
+**Expertise:** [Key domains]
+**Notable:** [Publications, talks, projects if found]
+
+## Observations
+- [role] Title at Organization
+- [expertise] Key technical or domain expertise
+- [source] Researched on YYYY-MM-DD
+
+## Relations
+- works_at [[Organization]]"""
+)
+```
+
+#### Technology
+
+```python
+write_note(
+  title="Technology Name",
+  directory="concepts",
+  note_type="concept",
+  tags=["concept", "technology", "relevant-tags"],
+  content="""# Technology Name
+
+## Overview
+[What it is and what problem it solves]
+
+## Key Details
+**Maintained by:** [Organization or community]
+**Maturity:** [Experimental / Stable / Mature]
+**License:** [If applicable]
+**Alternatives:** [Comparable tools or approaches]
+
+## Observations
+- [definition] What this technology does in one sentence
+- [maturity] Current state and adoption level
+- [source] Researched on YYYY-MM-DD
+
+## Relations
+- [Link to related concepts, tools, or projects in the knowledge graph]"""
+)
+```
+
+Adapt these templates freely. The key elements are: note_type/tags parameters, an overview, structured details, observations with categories, and relations.
+
+### Step 6: Store Source Context
+
+If the user provided context with their request, capture it in the entity:
+
+```python
+# User said: "Acme Corp — saw their demo at the conference last week"
+edit_note(
+  identifier="Acme Corp",
+  operation="append",
+  section="Observations",
+  content="- [context] Saw their demo at conference, week of 2026-02-17"
+)
+```
+
+This context is often the most valuable part — it's the user's relationship to the entity, which web research can't provide.
+
+## Guidelines
+
+- **Always web search.** Don't rely on training data alone. Research should reflect current, verifiable information.
+- **Search Basic Memory first.** Check for existing entities before creating new ones. Update rather than duplicate.
+- **Hedge uncertain information.** Use qualifiers for estimates, unverified claims, and inferred details.
+- **Store source URLs.** Include the URLs you consulted, either in observations or a Sources section. This enables the user to verify and dig deeper.
+- **Get approval before creating.** Present your findings and let the user decide whether to create the entity and what to include.
+- **Capture user context.** If the user told you *why* they're researching (met at a conference, evaluating as a vendor, etc.), that context belongs in the entity.
+- **Don't over-research.** 3-5 web searches is usually enough. The goal is a useful knowledge graph entry, not an exhaustive report.
+- **Link to existing knowledge.** Relate the new entity to things already in the knowledge graph. Connections compound value.

package/skills/memory-schema/SKILL.md

@@ -113,9 +113,9 @@ Look for clusters of notes that share structure but have no schema:
 1. **Search by type**: `search_notes(query="type:Meeting")` — if many notes share a `type` but no `schema/Meeting.md` exists, it's a candidate.
 
 2. **Infer a schema**: Use `schema_infer` to analyze existing notes and generate a suggested schema:
-   ```
+   ```python
    schema_infer(noteType="Meeting")
-   schema_infer(noteType="Meeting", threshold=0.5)  // fields in 50%+ of notes
+   schema_infer(noteType="Meeting", threshold=0.5)  # fields in 50%+ of notes
    ```
    The threshold (0.0–1.0) controls how common a field must be to be included. Default is usually fine; lower it to catch rarer fields.
 
@@ -125,57 +125,57 @@ Look for clusters of notes that share structure but have no schema:
 
 Write the schema note to `schema/<EntityName>`:
 
-```
+```python
 write_note(
-    title="Meeting",
-    folder="schema",
-    content="---
-title: Meeting
-type: schema
-entity: Meeting
-version: 1
-schema:
-  topic: string, what was discussed
-  date: string, when it happened
-  attendees?(array): Person, who attended
-  decisions?(array): string, decisions made
-settings:
-  validation: warn
----
-
-# Meeting
+  title="Meeting",
+  directory="schema",
+  note_type="schema",
+  metadata={
+    "entity": "Meeting",
+    "version": 1,
+    "schema": {
+      "topic": "string, what was discussed",
+      "date": "string, when it happened",
+      "attendees?(array)": "Person, who attended",
+      "decisions?(array)": "string, decisions made"
+    },
+    "settings": {"validation": "warn"}
+  },
+  content="""# Meeting
 
 Schema for meeting notes.
 
 ## Observations
 - [convention] Meeting notes live in memory/meetings/ or as daily entries
 - [convention] Always include date and topic
-- [convention] Action items should become tasks when complex",
+- [convention] Action items should become tasks when complex"""
 )
 ```
 
 ### Key Principles
 
 - **Schema notes live in `schema/`** — one note per entity type
-- **`type: schema`** in frontmatter marks it as a schema definition
-- **`entity: Meeting`** names the type it applies to
-- **`version: 1`** — increment when making breaking changes
+- **`note_type="schema"`** marks it as a schema definition
+- **`entity: Meeting`** in metadata names the type it applies to
+- **`version: 1`** in metadata — increment when making breaking changes
 - **`settings.validation: warn`** is recommended to start — it logs issues without blocking writes
 
 ## Validating Notes
 
 Check how well existing notes conform to their schema:
 
-```
-// Validate all notes of a type
+```python
+# Validate all notes of a type
 schema_validate(noteType="Meeting")
 
-// Validate a single note
+# Validate a single note
 schema_validate(identifier="meetings/2026-02-10-standup")
 ```
 
+**Important:** `schema_validate` checks for schema fields as **observation categories** in the note body — e.g., a `status` field expects `- [status] active` as an observation. Fields stored only in frontmatter metadata won't satisfy validation. To pass cleanly, include schema fields as both frontmatter values (for metadata search) and observations (for schema validation).
+
 Validation reports:
-- **Missing required fields** — the note lacks a field the schema requires
+- **Missing required fields** — the note lacks a field the schema requires (as an observation category)
 - **Unknown fields** — the note has fields the schema doesn't define
 - **Type mismatches** — a field value doesn't match the expected type
 - **Invalid enum values** — a value isn't in the allowed set
@@ -189,7 +189,7 @@ Validation reports:
 
 Over time, notes evolve and schemas lag behind. Use `schema_diff` to find divergence:
 
-```
+```python
 schema_diff(noteType="Meeting")
 ```
 
@@ -204,13 +204,13 @@ When note structure changes:
 
 1. **Run diff** to see current state: `schema_diff(noteType="Meeting")`
 2. **Update the schema note** via `edit_note`:
-   ```
+   ```python
    edit_note(
-       identifier="schema/Meeting",
-       operation="find_replace",
-       find_text="version: 1",
-       content="version: 2",
-       expected_replacements=1,
+     identifier="schema/Meeting",
+     operation="find_replace",
+     find_text="version: 1",
+     content="version: 2",
+     expected_replacements=1
    )
    ```
 3. **Add/remove/modify fields** in the `schema:` block

package/skills/memory-tasks/SKILL.md

@@ -42,24 +42,26 @@ settings:
 
 ## Creating a Task
 
-When work qualifies, create a note in `memory/tasks/YYYY-MM-DD-short-name.md`:
-
-```markdown
----
-title: Descriptive task name
-type: Task
-status: active
-created: YYYY-MM-DD
-current_step: 1
----
-
-# Descriptive task name
+When work qualifies, create a task note. Use `write_note` with `note_type="Task"` and put queryable fields in `metadata`:
+
+```python
+write_note(
+  title="Descriptive task name",
+  directory="tasks",
+  note_type="Task",
+  metadata={
+    "status": "active",
+    "priority": "high",
+    "current_step": 1,
+    "steps": ["First step", "Second step", "Third step"]
+  },
+  tags=["task"],
+  content="""# Descriptive task name
 
 ## Observations
 - [description] What needs to be done, concisely
 - [status] active
-- [assigned_to] claw
-- [started] YYYY-MM-DD
+- [assigned_to] claude
 - [current_step] 1
 
 ## Steps
@@ -72,23 +74,27 @@ What future-you needs to pick up this work. Include:
 - Key file paths and repos involved
 - Decisions already made and why
 - What was tried and what worked/didn't
-- Where to look for related context
+- Where to look for related context"""
+)
 ```
 
+**Why both frontmatter and observations?** Fields in `metadata` (stored as frontmatter) power `search_notes` with `metadata_filters`. Fields as observations (`- [status] active`) power `schema_validate`. Include queryable fields in both places for full coverage.
+
 ### Key Principles
 
 - **Steps are concrete and checkable** — "Implement X in file Y", not "figure out stuff"
 - **Context is for post-amnesia resumption** — Write it as if explaining to a smart person who knows nothing about what you've been doing
-- **Use observations for BM-queryable fields** — `[status]`, `[description]`, `[assigned_to]` etc. become searchable in the knowledge graph
 - **Relations link to other entities** — `parent_task [[Other Task]]`, `related_to [[Some Note]]`
+- **`note_types` is case-sensitive** — `write_note(note_type="Task")` stores the type as lowercase `task` in frontmatter. Use `note_types=["task"]` (lowercase) in search queries.
 
 ## Resuming After Compaction
 
 On session start or after compaction:
 
 1. **Search for active tasks:**
-   - Via BM: `search_notes("type:Task status:active")` or `search_notes("[status] active")`
-   - Via memory_search: query "active tasks" (composited search includes task scanning)
+   ```python
+   search_notes(note_types=["task"], status="active")
+   ```
 
 2. **Read the task note** to get full context
 
@@ -129,7 +135,7 @@ Add a brief summary of what was accomplished and any follow-up needed.
 
 When a compaction event is imminent:
 
-1. Find all active tasks: `search_notes("type:Task status:active")`
+1. Find all active tasks: `search_notes(note_types=["task"], status="active")`
 2. For each, update:
    - `current_step` to reflect actual progress
    - `context` with everything needed to resume
@@ -142,16 +148,14 @@ With BM's schema system, tasks are fully queryable:
 
 | Query | What it finds |
 |-------|--------------|
-| `search_notes("type:Task")` | All tasks |
-| `search_notes("[status] active")` | Active tasks |
-| `search_notes("[status] blocked")` | Blocked tasks |
-| `search_notes("[assigned_to] claw")` | My tasks |
-| `search_notes("type:Task [blockers]")` | Tasks with blockers |
+| `search_notes(note_types=["task"])` | All tasks |
+| `search_notes(note_types=["task"], status="active")` | Active tasks |
+| `search_notes(note_types=["task"], status="blocked")` | Blocked tasks |
+| `search_notes(note_types=["task"], metadata_filters={"assigned_to": "claude"})` | My tasks |
+| `search_notes("blockers", note_types=["task"])` | Tasks with blockers |
 | `schema_validate(noteType="Task")` | Validate all tasks against schema |
 | `schema_diff(noteType="Task")` | Detect drift between schema and actual task notes |
 
-> **Plugin tools vs BM CLI**: The `schema_validate`, `schema_infer`, and `schema_diff` tools are available when using the `@openclaw/basic-memory` plugin. The raw `search_notes(...)` queries also work and are useful for ad-hoc filtering. `memory_search` composites results from all sources including active task scanning.
-
 ## Guidelines
 
 - **One task per unit of work** — Don't cram multiple projects into one task
@@ -159,4 +163,4 @@ With BM's schema system, tasks are fully queryable:
 - **Context > steps** — Steps tell you what to do; context tells you why and how
 - **Close finished tasks** — Don't leave completed work as `active`
 - **Link related tasks** — Use `parent_task [[X]]` or relations to connect related work
-- **Schema validation is your friend** — Run `bm schema validate Task` periodically to catch incomplete tasks
+- **Schema validation is your friend** — Run `schema_validate(noteType="Task")` periodically to catch incomplete tasks