@basicmemory/openclaw-basic-memory 0.1.3 → 0.1.4

package/skills/memory-lifecycle/SKILL.md

@@ -0,0 +1,182 @@
+---
+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."
+---
+
+# Memory Lifecycle
+
+Manage how entities move through status stages in Basic Memory. The core principle: **archive, never delete.** Completed work is valuable context — move it out of the active view, but keep it in the knowledge graph.
+
+## When to Use
+
+- User says something is "done", "finished", "completed", "submitted", "missed", or "cancelled"
+- Moving entities between status folders (active → archive, pipeline → active, etc.)
+- Reverting a mistaken completion
+- Periodic cleanup of stale active items
+
+## Core Principle: Archive, Never Delete
+
+Deleting a note removes it from the knowledge graph — all its observations, relations, and history disappear. Archiving preserves everything while signaling the entity is no longer active.
+
+```
+# Good — entity stays in the knowledge graph
+move_note → active/ to archive/
+
+# Bad — knowledge is lost
+delete_note
+```
+
+The only exception: notes created by mistake (typos, true duplicates) can be deleted.
+
+## Folder Conventions
+
+Organize entities by status using folders. The exact folder names depend on your domain, but follow a consistent pattern:
+
+```
+entities/
+  active/          # Currently relevant, in-progress
+  archive/         # Completed, no longer active, but worth keeping
+  pipeline/        # Future items, not yet started
+```
+
+For tasks specifically:
+
+```
+tasks/
+  active/          # Work in progress
+  completed/       # Finished work
+```
+
+For any entity type with a clear lifecycle:
+
+```
+[type]/
+  active/          # Current
+  [end-state]/     # Whatever "done" means for this type
+```
+
+Pick folder names that match your domain. The pattern matters more than the specific names.
+
+## Status Detection
+
+When the user mentions completion or status change, extract the intent:
+
+| Signal | Status | Action |
+|--------|--------|--------|
+| "finished", "done", "completed", "shipped" | Complete | Move to archive/completed folder |
+| "submitted", "sent", "delivered" | Complete | Move to archive/completed folder |
+| "missed", "passed", "skipped", "expired" | Missed | Move to archive or missed folder |
+| "cancelled", "abandoned", "killed" | Cancelled | Move to archive folder |
+| "paused", "on hold", "deferred" | Paused | Update frontmatter status, keep in place |
+| "restarting", "reopening", "reviving" | Reactivate | Move back to active folder |
+
+## Workflow
+
+### 1. Find the Entity
+
+Search Basic Memory with multiple variations to locate the entity:
+
+```python
+search_notes(query="quarterly report")
+search_notes(query="Q1 report")
+```
+
+If multiple matches come back, present options and ask which one.
+
+If no match is found, ask for clarification — don't guess.
+
+### 2. Move the File
+
+Use `move_note` to relocate the entity to the appropriate status folder:
+
+```python
+move_note(
+  identifier="tasks/active/quarterly-report",
+  destination_path="tasks/completed/quarterly-report.md"
+)
+```
+
+The permalink stays the same, so all existing `[[wiki-links]]` and `memory://` URLs continue to resolve.
+
+### 3. Update Frontmatter
+
+After moving, update the status in frontmatter to match:
+
+```python
+edit_note(
+  identifier="quarterly-report",
+  operation="find_replace",
+  find_text="status: active",
+  content="status: completed"
+)
+```
+
+If there's a completion date field, set it:
+
+```python
+edit_note(
+  identifier="quarterly-report",
+  operation="find_replace",
+  find_text="completed:",
+  content="completed: 2026-02-22"
+)
+```
+
+### 4. Confirm
+
+Report what was done concisely:
+
+```
+Marked complete: Quarterly Report
+  Moved to: tasks/completed/quarterly-report.md
+  Status: completed
+```
+
+## Edge Cases
+
+### Already Archived
+
+If the entity is already in an archive/completed folder, notify the user:
+
+> "Quarterly Report is already in tasks/completed/. Want me to update anything on it?"
+
+### Partial Completion
+
+Sometimes only part of an entity is done. Don't move it — instead, update observations or status notes within the entity to reflect partial progress.
+
+### Revert / Reactivate
+
+If something was archived by mistake, move it back:
+
+```python
+move_note(
+  identifier="tasks/completed/quarterly-report",
+  destination_path="tasks/active/quarterly-report.md"
+)
+
+edit_note(
+  identifier="quarterly-report",
+  operation="find_replace",
+  find_text="status: completed",
+  content="status: active"
+)
+```
+
+### Status Without Movement
+
+Some status changes don't require a folder move — "paused" or "blocked" items often stay in `active/` with just a frontmatter update. Reserve folder moves for terminal or major state transitions.
+
+## Relationship to Other Skills
+
+- **memory-tasks**: Tasks are a specific lifecycle case. This skill covers the general pattern; memory-tasks covers task-specific fields (steps, current_step, context).
+- **memory-notes**: Use search-before-create (from memory-notes) to find the entity before transitioning it.
+- **memory-defrag**: Periodic defrag can identify stale active items that should be archived.
+
+## Guidelines
+
+- **Archive, never delete.** The knowledge graph benefits from historical context.
+- **Move first, then update frontmatter.** This order ensures the file is in the right place even if the edit step fails.
+- **Permalinks survive moves.** Links to the entity keep working after a `move_note`.
+- **Be concise in confirmations.** The user knows their system — just report what changed.
+- **Ask when ambiguous.** If multiple entities match or the target folder isn't clear, ask rather than guess.
+- **Batch operations are fine.** If the user says "archive all completed tasks", find them all, confirm the list, then move them in sequence.

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

@@ -16,16 +16,9 @@ Find notes by their structured frontmatter fields instead of (or in addition to)
 - **Tag-based filtering** — find notes tagged with specific frontmatter tags
 - **Schema-aware queries** — filter by nested schema fields using dot notation
 
-## Tool
+## The Tool
 
-Use the `search_notes` tool with the optional `metadata_filters`, `tags`, and `status` parameters.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `query` | string | Text search query (can be empty for filter-only searches) |
-| `metadata_filters` | object | Filter by frontmatter fields (see filter syntax below) |
-| `tags` | string[] | Filter by frontmatter tags (all must match) |
-| `status` | string | Filter by frontmatter status field |
+All metadata searching uses `search_notes`. Pass filters via `metadata_filters`, or use the `tags` and `status` convenience shortcuts. Omit `query` (or pass `None`) for filter-only searches.
 
 ## Filter Syntax
 
@@ -87,71 +80,52 @@ Numeric values use numeric comparison; strings use lexicographic comparison.
 - `$in` and array-contains require non-empty lists
 - `$between` requires exactly `[min, max]`
 
-## Examples
-
-### Metadata-only search (empty query)
-
-```
-search_notes(query="", metadata_filters={"status": "in-progress", "type": "spec"})
-```
-
-### Text search narrowed by metadata
+## Using `search_notes` with Metadata
 
-```
-search_notes(query="authentication", metadata_filters={"status": "draft"})
-```
+Pass `metadata_filters`, `tags`, or `status` to `search_notes`. Omit `query` for filter-only searches, or combine text and filters together.
 
-### Filter by tags
+```python
+# Filter-only — find all notes with a given status
+search_notes(metadata_filters={"status": "in-progress"})
 
-```
-search_notes(query="", tags=["security", "oauth"])
-```
+# Filter-only — high-priority specs in a specific project
+search_notes(
+    metadata_filters={"type": "spec", "priority": {"$in": ["high", "critical"]}},
+    project="research",
+    page_size=10,
+)
 
-### Filter by status shortcut
+# Filter-only — notes with confidence above a threshold
+search_notes(metadata_filters={"confidence": {"$gt": 0.7}})
 
-```
-search_notes(query="planning", status="active")
-```
+# Convenience shortcuts for tags and status
+search_notes(status="active")
+search_notes(tags=["security", "oauth"])
 
-### Combined text + metadata + tags
+# Text search narrowed by metadata
+search_notes("authentication", metadata_filters={"status": "draft"})
 
-```
+# Mix text, tag shortcut, and advanced filter
 search_notes(
-    query="oauth flow",
-    metadata_filters={"confidence": {"$gt": 0.7}},
+    "oauth flow",
     tags=["security"],
-    status="in-progress",
-)
-```
-
-### High-priority notes in a specific project
-
-```
-search_notes(
-    query="",
-    metadata_filters={"priority": {"$in": ["high", "critical"]}},
-    project="research",
-    limit=10,
+    metadata_filters={"confidence": {"$gt": 0.7}},
 )
 ```
 
-### Numeric range query
-
-```
-search_notes(query="", metadata_filters={"score": {"$between": [0.3, 0.8]}})
-```
+**Merging rules:** `tags` and `status` are convenience shortcuts merged into `metadata_filters` via `setdefault`. If the same key exists in `metadata_filters`, the explicit filter wins.
 
 ## Tag Search Shorthand
 
 The `tag:` prefix in a query converts to a tag filter automatically:
 
-```
+```python
 # These are equivalent:
-search_notes(query="tag:tier1")
-search_notes(query="", tags=["tier1"])
+search_notes("tag:tier1")
+search_notes("", tags=["tier1"])
 
 # Multiple tags (comma or space separated) — all must match:
-search_notes(query="tag:tier1,alpha")
+search_notes("tag:tier1,alpha")
 ```
 
 ## Example: Custom Frontmatter in Practice
@@ -180,29 +154,29 @@ confidence: 0.85
 
 Queries that find it:
 
-```
+```python
 # By status and type
-search_notes(query="", metadata_filters={"status": "in-progress", "type": "spec"})
+search_notes(metadata_filters={"status": "in-progress", "type": "spec"})
 
 # By numeric threshold
-search_notes(query="", metadata_filters={"confidence": {"$gt": 0.7}})
+search_notes(metadata_filters={"confidence": {"$gt": 0.7}})
 
 # By priority set
-search_notes(query="", metadata_filters={"priority": {"$in": ["high", "critical"]}})
+search_notes(metadata_filters={"priority": {"$in": ["high", "critical"]}})
 
 # By tag shorthand
-search_notes(query="tag:security")
+search_notes("tag:security")
 
 # Combined text + metadata
-search_notes(query="OAuth", metadata_filters={"status": "in-progress"})
+search_notes("OAuth", metadata_filters={"status": "in-progress"})
 ```
 
 ## Guidelines
 
-- **Use metadata filters for structured queries.** If you're looking for notes by a known field value (status, priority, type), metadata filters are more precise than text search.
+- **Use metadata search for structured queries.** If you're looking for notes by a known field value (status, priority, type), metadata filters are more precise than text search.
 - **Use text search for content queries.** If you're looking for notes *about* something, text search is better. Combine both when you need precision.
 - **Custom fields are free.** Any YAML key you put in frontmatter becomes queryable — no schema or configuration required.
 - **Multiple filters are AND.** `{"status": "active", "priority": "high"}` requires both conditions.
-- **Use empty query for filter-only searches.** Pass `query=""` with `metadata_filters` when you only need structured filtering.
+- **Omit `query` for filter-only searches.** `search_notes(metadata_filters={"status": "active"})` works without a text query.
 - **Dot notation for nesting.** Access nested YAML structures with dots: `{"schema.version": "2"}` queries the `version` key inside a `schema` object.
-- **Tags and status are convenient shortcuts.** Use the dedicated `tags` and `status` parameters for common fields, or `metadata_filters` for anything else.
+- **Tags shortcut is convenient but limited.** `tags` and `status` are sugar for common fields. For anything else, use `metadata_filters` directly.

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