@basicmemory/openclaw-basic-memory 0.1.3 → 0.1.5

package/skills/memory-notes/SKILL.md

@@ -17,7 +17,10 @@ tags: [api, architecture, decisions]
 
 # API Design Decisions
 
-Background context explaining why this note exists and what it covers.
+The API team evaluated multiple approaches for the public API during Q1. After
+prototyping both REST and GraphQL, the team chose REST due to broader ecosystem
+support and simpler caching semantics. This note captures the key decisions and
+their rationale, along with open questions still to resolve.
 
 ## Observations
 - [decision] Use REST over GraphQL for simplicity #api
@@ -45,17 +48,20 @@ 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
-- The `permalink` is auto-generated from the title (e.g., "API Design Decisions" → `api-design-decisions`). It stays stable across file moves and is the basis for `memory://` URLs. You rarely need to set it manually.
+- 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.
+
+> **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`.
 
 ### Body / Context
 
-Free-form markdown between the heading and the Observations section. Use this for:
-- Background and motivation
-- Summary of the topic
-- Any prose that doesn't fit neatly into categorized observations
+Free-form markdown between the heading and the Observations section. This is the heart of the note — write generously here:
+- Background, motivation, and history
+- Detailed explanation of what happened and why it matters
+- Analysis, reasoning, and trade-offs considered
+- Context that someone (or an AI) needs to understand this note later
 
-This content is indexed for full-text search but isn't parsed into structured entities.
+Write complete, substantive prose. Basic Memory's search retrieves relevant chunks from note bodies, so longer, richer context makes notes more discoverable and more useful when found. Don't reduce everything to bullet points — tell the story.
 
 ## Observations
 
@@ -173,33 +179,88 @@ The first path segment is matched against known project names. If it matches, it
 
 Memory URLs work with `build_context` to assemble related knowledge by traversing relations:
 
-```
-// Get a note and its connected context
+```python
+# Get a note and its connected context
 build_context(url="memory://api-design-decisions")
 
-// Wildcard — gather all docs
+# Wildcard — gather all docs
 build_context(url="memory://docs/*")
 
-// Direct read by permalink
+# Direct read by permalink
 read_note(identifier="memory://api-design-decisions")
 ```
 
+## Before Creating a Note
+
+Always search Basic Memory before creating a new note. Duplicates fragment your knowledge graph — updating an existing note is almost always better than creating a second one.
+
+### Search with Multiple Variations
+
+A single search often misses. Try the full name, abbreviations, acronyms, and keywords:
+
+```python
+# Searching for an entity that might already exist
+search_notes(query="Kubernetes Migration")
+search_notes(query="k8s migration")
+search_notes(query="container migration")
+```
+
+For people, try full name and last name. For organizations, try the full name and common abbreviations.
+
+### Decision Tree
+
+- **Entity exists** → Update it with `edit_note` (append observations, add relations, find-and-replace outdated info)
+- **Entity doesn't exist** → Create it with `write_note`
+- **Unsure if it's the same entity** → Read the existing note first, then decide
+
+### Granular Updates with `edit_note`
+
+When a note already exists, make targeted edits instead of rewriting the whole file:
+
+```python
+# Append a new observation to an existing note
+edit_note(
+  identifier="API Design Decisions",
+  operation="append",
+  section="Observations",
+  content="- [decision] Switched to OpenAPI 3.1 for spec generation #api"
+)
+
+# Fix outdated information
+edit_note(
+  identifier="API Design Decisions",
+  operation="find_replace",
+  find_text="- [status] draft",
+  content="- [status] approved"
+)
+
+# Add a new relation
+edit_note(
+  identifier="API Design Decisions",
+  operation="append",
+  section="Relations",
+  content="- depends_on [[Rate Limiter]]"
+)
+```
+
+This preserves existing content and keeps the edit history clean.
+
 ## Writing Notes with Tools
 
 ### Creating a Note
 
-```
+```python
 write_note(
-    title="API Design Decisions",
-    folder="architecture",     // optional — organizes files on disk
-    content="---
-title: API Design Decisions
-tags: [api, architecture]
----
-
-# API Design Decisions
+  title="API Design Decisions",
+  directory="architecture",
+  tags=["api", "architecture"],
+  content="""# API Design Decisions
 
-Context about the API design process.
+The API team evaluated REST and GraphQL during Q1 planning. After prototyping
+both approaches, we chose REST for the public API — broader ecosystem support,
+simpler caching with HTTP semantics, and a lower learning curve for external
+consumers. GraphQL remains an option for internal services where query
+flexibility matters more.
 
 ## Observations
 - [decision] Use REST for public API #api
@@ -207,37 +268,52 @@ Context about the API design process.
 
 ## Relations
 - implements [[API Specification]]
-- relates_to [[Backend Architecture]]",
+- relates_to [[Backend Architecture]]"""
 )
 ```
 
+Basic Memory auto-generates frontmatter (including the permalink and memory URL) from the parameters. This note would get permalink `architecture/api-design-decisions` and be addressable at `memory://architecture/api-design-decisions`.
+
 ### Editing an Existing Note
 
 Use `edit_note` to append, prepend, or find-and-replace within a note:
 
-```
-// Append new observations
+```python
+# Append new observations
 edit_note(
-    identifier="API Design Decisions",
-    operation="append",
-    heading="Observations",
-    content="- [decision] Use OpenAPI 3.1 for spec generation #api",
+  identifier="API Design Decisions",
+  operation="append",
+  section="Observations",
+  content="- [decision] Use OpenAPI 3.1 for spec generation #api"
 )
 
-// Add a new relation
+# Add a new relation
 edit_note(
-    identifier="API Design Decisions",
-    operation="append",
-    heading="Relations",
-    content="- depends_on [[Rate Limiter]]",
+  identifier="API Design Decisions",
+  operation="append",
+  section="Relations",
+  content="- depends_on [[Rate Limiter]]"
 )
 ```
 
+### Moving a Note
+
+Use `move_note` to reorganize notes into different directories:
+
+```python
+move_note(
+  identifier="API Design Decisions",
+  destination_path="archive/api-design-decisions.md"
+)
+```
+
+The permalink stays the same after a move, so all `[[wiki-links]]` and `memory://` URLs continue to resolve.
+
 ## Best Practices
 
 1. **Start with context.** Before listing observations, explain *why* this note exists. Future-you (or your AI collaborator) will thank you.
 
-2. **Observations over prose.** Categorized observations are searchable and structured. A paragraph of text is not. Prefer `[decision] X because Y` over burying the same fact in a paragraph.
+2. **Favor completeness.** Write rich, substantive notes. Basic Memory's search pulls relevant chunks from note bodies, so longer notes with more context are *more* discoverable, not less. Use prose in the body to tell the full story — the background, the reasoning, the nuance. Then distill key facts into `[category] content` observations for structured queries. Both matter: prose gives meaning, observations give precision.
 
 3. **Build incrementally.** Add to existing notes rather than creating duplicates. Use `edit_note` to append new observations or relations as you learn more.
 

package/skills/memory-reflect/SKILL.md

@@ -19,10 +19,20 @@ Inspired by sleep-time compute — the idea that memory formation happens best *
 
 ### 1. Gather Recent Material
 
-Read the last 2-3 days of daily notes from `memory/YYYY-MM-DD.md`. Also check:
-- Recent conversation transcripts (if accessible)
-- Any files modified in `memory/` in the last 48 hours
-- Active tasks in `memory/tasks/`
+Find what changed recently, then read the relevant files:
+
+```python
+# Find recently modified notes — use json format for the complete list
+# (text format truncates to ~5 items in the summary)
+recent_activity(timeframe="2d", output_format="json")
+
+# Read specific daily notes
+read_note(identifier="memory/2026-02-27")
+read_note(identifier="memory/2026-02-26")
+
+# Check active tasks
+search_notes(note_types=["task"], status="active")
+```
 
 ### 2. Evaluate What Matters
 

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