@basicmemory/openclaw-basic-memory 0.1.0-alpha.1

package/skills/memory-notes/SKILL.md

@@ -0,0 +1,250 @@
+---
+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."
+---
+
+# Memory Notes
+
+Write well-structured notes that Basic Memory can parse into a searchable knowledge graph. Every note is a markdown file with three key sections: frontmatter, observations, and relations.
+
+## Note Anatomy
+
+```markdown
+---
+title: API Design Decisions
+tags: [api, architecture, decisions]
+---
+
+# API Design Decisions
+
+Background context explaining why this note exists and what it covers.
+
+## Observations
+- [decision] Use REST over GraphQL for simplicity #api
+- [requirement] Must support versioning from day one
+- [risk] Rate limiting needed for public endpoints
+
+## Relations
+- implements [[API Specification]]
+- depends_on [[Authentication System]]
+- relates_to [[Performance Requirements]]
+```
+
+### Frontmatter
+
+Every note starts with YAML frontmatter:
+
+```yaml
+---
+title: Note Title          # required — becomes the entity name in the knowledge graph
+tags: [tag1, tag2]         # optional — for organization and filtering
+type: note                 # optional — defaults to "note", use custom types with schemas
+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.
+
+### 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
+
+This content is indexed for full-text search but isn't parsed into structured entities.
+
+## Observations
+
+Observations are categorized facts — the atomic units of knowledge. Each one becomes a searchable entity in the knowledge graph.
+
+### Syntax
+
+```
+- [category] Content of the observation #optional-tag
+```
+
+- **Square brackets** define the semantic category
+- **Content** is the fact, decision, insight, or note
+- **Hash tags** (optional) add extra metadata for filtering
+
+### Categories Are Arbitrary
+
+The category in brackets is free-form — use whatever label makes sense for the observation. There is no fixed list. The only rule is the `[category] content` syntax. Consistency within a project helps searchability, but invent categories freely.
+
+A few examples to illustrate the range:
+
+```
+- [decision] Use PostgreSQL for primary data store
+- [risk] Third-party API has no SLA guarantee
+- [technique] Exponential backoff for retry logic #resilience
+- [question] Should we support multi-tenancy at the DB level?
+- [preference] Use Bun over Node for new projects
+- [lesson] Always validate webhook signatures server-side
+- [status] active
+- [flavor] Ethiopian beans work best with lighter roasts
+```
+
+### Observation Tips
+
+- **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.
+
+## Relations
+
+Relations create edges in the knowledge graph, linking notes to each other. They're how you build structure beyond individual notes.
+
+### Syntax
+
+```
+- relation_type [[Target Note Title]]
+```
+
+- **relation_type** is a descriptive verb or phrase (snake_case by convention)
+- **Double brackets** `[[...]]` identify the target note by title or permalink
+- Relations are directional: this note → target note
+
+### Relation Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `implements` | One thing implements another | `- implements [[Auth Spec]]` |
+| `requires` | Dependencies | `- requires [[Database Setup]]` |
+| `relates_to` | General connection | `- relates_to [[Performance Notes]]` |
+| `part_of` | Hierarchy/composition | `- part_of [[Backend Architecture]]` |
+| `extends` | Enhancement or elaboration | `- extends [[Base Config]]` |
+| `pairs_with` | Things that work together | `- pairs_with [[Frontend Client]]` |
+| `inspired_by` | Source material | `- inspired_by [[CRDT Research Paper]]` |
+| `replaces` | Supersedes another note | `- replaces [[Old Auth Design]]` |
+| `depends_on` | Runtime/build dependency | `- depends_on [[MCP SDK]]` |
+| `contrasts_with` | Alternative approaches | `- contrasts_with [[GraphQL Approach]]` |
+
+### Inline Relations
+
+Wiki-links anywhere in the note body — not just the Relations section — also create graph edges:
+
+```markdown
+We evaluated [[GraphQL Approach]] but decided against it because
+the team has more experience with REST. See [[API Specification]]
+for the full contract.
+```
+
+These create `references` relations automatically. Use the Relations section for explicit, typed relationships; use inline links for natural prose references.
+
+### Relation Tips
+
+- **Link liberally.** Relations are what turn isolated notes into a knowledge graph. When in doubt, add the link.
+- **Create target notes if they don't exist yet.** `[[Future Topic]]` is valid — BM will resolve it when that note is created.
+- **Use `build_context` to traverse.** `build_context(url="memory://note-title")` follows relations to gather connected knowledge.
+- **Custom relation types are fine.** `taught_by`, `blocks`, `tested_in` — use whatever is descriptive.
+
+## Memory URLs
+
+Every note is addressable via a `memory://` URL, built from its permalink. These URLs are how you navigate the knowledge graph programmatically.
+
+### URL Patterns
+
+```
+memory://api-design-decisions          # by permalink (title → kebab-case)
+memory://docs/authentication           # by file path
+memory://docs/authentication.md        # with extension (also works)
+memory://auth*                         # wildcard prefix
+memory://docs/*                        # wildcard suffix
+memory://project/*/requirements        # path wildcards
+```
+
+### Project-Scoped URLs
+
+In multi-project setups, prefix with the project name:
+
+```
+memory://main/specs/api-design         # "main" project, "specs/api-design" path
+memory://research/papers/crdt          # "research" project
+```
+
+The first path segment is matched against known project names. If it matches, it's used as the project scope. Otherwise the URL resolves in the default project.
+
+### Using Memory URLs
+
+Memory URLs work with `build_context` to assemble related knowledge by traversing relations:
+
+```
+// Get a note and its connected context
+build_context(url="memory://api-design-decisions")
+
+// Wildcard — gather all docs
+build_context(url="memory://docs/*")
+
+// Direct read by permalink
+read_note(identifier="memory://api-design-decisions")
+```
+
+## Writing Notes with Tools
+
+### Creating a Note
+
+```
+write_note(
+    title="API Design Decisions",
+    folder="architecture",     // optional — organizes files on disk
+    content="---
+title: API Design Decisions
+tags: [api, architecture]
+---
+
+# API Design Decisions
+
+Context about the API design process.
+
+## Observations
+- [decision] Use REST for public API #api
+- [requirement] Support API versioning from v1
+
+## Relations
+- implements [[API Specification]]
+- relates_to [[Backend Architecture]]",
+)
+```
+
+### Editing an Existing Note
+
+Use `edit_note` to append, prepend, or find-and-replace within a note:
+
+```
+// Append new observations
+edit_note(
+    identifier="API Design Decisions",
+    operation="append",
+    heading="Observations",
+    content="- [decision] Use OpenAPI 3.1 for spec generation #api",
+)
+
+// Add a new relation
+edit_note(
+    identifier="API Design Decisions",
+    operation="append",
+    heading="Relations",
+    content="- depends_on [[Rate Limiter]]",
+)
+```
+
+## 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.
+
+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.
+
+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.
+
+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.

package/skills/memory-reflect/SKILL.md

@@ -0,0 +1,63 @@
+---
+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."
+---
+
+# Memory Reflect
+
+Review recent activity and consolidate valuable insights into long-term memory.
+
+Inspired by sleep-time compute — the idea that memory formation happens best *between* active sessions, not during them.
+
+## When to Run
+
+- **Cron/heartbeat**: Schedule as a periodic background task (recommended: 1-2x daily)
+- **On demand**: User asks to reflect, consolidate, or review recent memory
+- **Post-compaction**: After context window compaction events
+
+## Process
+
+### 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/`
+
+### 2. Evaluate What Matters
+
+For each piece of information, ask:
+- Is this a **decision** that affects future work? → Keep
+- Is this a **lesson learned** or mistake to avoid? → Keep
+- Is this a **preference** or working style insight? → Keep
+- Is this a **relationship** detail (who does what, contact info)? → Keep
+- Is this **transient** (weather checked, heartbeat ran, routine task)? → Skip
+- Is this **already captured** in MEMORY.md or another long-term file? → Skip
+
+### 3. Update Long-Term Memory
+
+Write consolidated insights to `MEMORY.md` following its existing structure:
+- Add new sections or update existing ones
+- Use concise, factual language
+- Include dates for temporal context
+- Remove or update outdated entries that the new information supersedes
+
+### 4. Log the Reflection
+
+Append a brief entry to today's daily note:
+```markdown
+## Reflection (HH:MM)
+- Reviewed: [list of files reviewed]
+- Added to MEMORY.md: [brief summary of what was consolidated]
+- Removed/updated: [anything cleaned up]
+```
+
+## Guidelines
+
+- **Be selective.** The goal is distillation, not duplication. MEMORY.md should be curated wisdom, not a copy of daily notes.
+- **Preserve voice.** If the agent has a personality/soul file, reflections should match that voice.
+- **Don't delete daily notes.** They're the raw record. Reflection extracts from them; it doesn't replace them.
+- **Merge, don't append.** If MEMORY.md already has a section about a topic, update it in place rather than adding a duplicate entry.
+- **Flag uncertainty.** If something seems important but you're not sure, add it with a note like "(needs confirmation)" rather than skipping it entirely.
+- **Restructure over time.** If MEMORY.md is a chronological dump, restructure it into topical sections during reflection. Curated knowledge > raw logs.
+- **Check for filesystem issues.** Look for recursive nesting (memory/memory/memory/...), orphaned files, or bloat while gathering material.

package/skills/memory-schema/SKILL.md

@@ -0,0 +1,237 @@
+---
+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."
+---
+
+# Memory Schema
+
+Manage structured note types using Basic Memory's Picoschema system. Schemas define what fields a note type should have, making notes uniform, queryable, and validatable.
+
+## When to Use
+
+- **New note type emerging** — you notice several notes share the same structure (meetings, people, decisions)
+- **Validation check** — confirm existing notes conform to their schema
+- **Schema drift** — detect fields that notes use but the schema doesn't define (or vice versa)
+- **Schema evolution** — add/remove/change fields as requirements evolve
+- **On demand** — user asks to create, check, or manage schemas
+
+## Picoschema Syntax Reference
+
+Schemas are defined in YAML frontmatter using Picoschema — a compact notation for describing note structure.
+
+### Basic Types
+
+```yaml
+schema:
+  name: string, person's full name
+  age: integer, age in years
+  score: number, floating-point rating
+  active: boolean, whether currently active
+```
+
+Supported types: `string`, `integer`, `number`, `boolean`.
+
+### Optional Fields
+
+Append `?` to the field name:
+
+```yaml
+schema:
+  title: string, required field
+  subtitle?: string, optional field
+```
+
+### Enums
+
+Use `(enum)` with a list of allowed values:
+
+```yaml
+schema:
+  status(enum): [active, blocked, done, abandoned], current state
+```
+
+Optional enum:
+
+```yaml
+schema:
+  priority?(enum): [low, medium, high, critical], task priority
+```
+
+### Arrays
+
+Use `(array)` for list fields:
+
+```yaml
+schema:
+  tags(array): string, categorization labels
+  steps?(array): string, ordered steps to complete
+```
+
+### Relations
+
+Reference other entity types directly:
+
+```yaml
+schema:
+  parent_task?: Task, parent task if this is a subtask
+  attendees?(array): Person, people who attended
+```
+
+Relations create edges in the knowledge graph, linking notes together.
+
+### Validation Settings
+
+```yaml
+settings:
+  validation: warn    # warn (log issues) or error (strict)
+```
+
+### Complete Example
+
+```yaml
+---
+title: Meeting
+type: schema
+entity: Meeting
+version: 1
+schema:
+  topic: string, what was discussed
+  date: string, when it happened (YYYY-MM-DD)
+  attendees?(array): Person, who attended
+  decisions?(array): string, decisions made
+  action_items?(array): string, follow-up tasks
+  status?(enum): [scheduled, completed, cancelled], meeting state
+settings:
+  validation: warn
+---
+```
+
+## Discovering Unschemaed Notes
+
+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:
+   ```
+   schema_infer(noteType="Meeting")
+   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.
+
+3. **Review the suggestion** — the inferred schema shows field names, types, and frequency. Decide which fields to keep, make optional, or drop.
+
+## Creating a Schema
+
+Write the schema note to `schema/<EntityName>`:
+
+```
+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
+
+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",
+)
+```
+
+### 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
+- **`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
+schema_validate(noteType="Meeting")
+
+// Validate a single note
+schema_validate(identifier="meetings/2026-02-10-standup")
+```
+
+Validation reports:
+- **Missing required fields** — the note lacks a field the schema requires
+- **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
+
+### Handling Validation Results
+
+- **`warn` mode**: Review warnings periodically. Fix notes that are clearly wrong; add optional fields to the schema for legitimate new patterns.
+- **`error` mode**: Use for strict schemas where conformance matters (e.g., automated pipelines consuming notes).
+
+## Detecting Drift
+
+Over time, notes evolve and schemas lag behind. Use `schema_diff` to find divergence:
+
+```
+schema_diff(noteType="Meeting")
+```
+
+Diff reports:
+- **Fields in notes but not in schema** — candidates for adding to the schema (as optional)
+- **Schema fields rarely used** — consider making optional or removing
+- **Type inconsistencies** — fields used as different types across notes
+
+## Schema Evolution
+
+When note structure changes:
+
+1. **Run diff** to see current state: `schema_diff(noteType="Meeting")`
+2. **Update the schema note** via `edit_note`:
+   ```
+   edit_note(
+       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
+4. **Re-validate** to confirm existing notes still pass: `schema_validate(noteType="Meeting")`
+5. **Fix outliers** — update notes that don't conform to the new schema
+
+### Evolution Guidelines
+
+- **Additive changes** (new optional fields) are safe — no version bump needed
+- **Breaking changes** (new required fields, removed fields, type changes) should bump `version`
+- **Prefer optional over required** — most fields should be optional to start
+- **Don't over-constrain** — schemas should describe common structure, not enforce rigid templates
+- **Schema as documentation** — even if validation is set to `warn`, the schema serves as living documentation for what notes of that type should contain
+
+## Workflow Summary
+
+```
+1. Notice repeated note structure → infer schema (schema_infer)
+2. Review + create schema note   → write to schema/ (write_note)
+3. Validate existing notes       → check conformance (schema_validate)
+4. Fix outliers                  → edit non-conforming notes (edit_note)
+5. Periodically check drift      → detect divergence (schema_diff)
+6. Evolve schema as needed       → update schema note (edit_note)
+```