From 4311814e9c7c610d2cd8f74d8639ecbe58f292b9 Mon Sep 17 00:00:00 2001 From: Tyler Raber Date: Mon, 20 Apr 2026 07:03:09 -0400 Subject: [PATCH 1/6] feat: add targeted skill improvements and Copilot CLI install docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - memory-tasks: formalize Resume/Pause protocols with SEARCH→READ→VALIDATE→CONTINUE sequence - memory-tasks: add "Why Both Frontmatter and Observations?" subsection - memory-defrag: add resolved error traces as explicit cleanup target with example - memory-schema: add dual-location rationale (why fields in both frontmatter and observations) - memory-metadata-search: add consistency-enables-filtering guideline - README: add GitHub Copilot CLI to Compatible Agents and install examples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ++ memory-defrag/SKILL.md | 36 ++++++++++++++- memory-metadata-search/SKILL.md | 1 + memory-schema/SKILL.md | 9 +++- memory-tasks/SKILL.md | 77 ++++++++++++++++++++++++--------- 5 files changed, 104 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 469791e..3253082 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,9 @@ npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks # Install all skills for a specific agent npx skills add basicmachines-co/basic-memory-skills --agent claude +# Install for GitHub Copilot CLI +npx skills add basicmachines-co/basic-memory-skills -a github-copilot + # List available skills without installing npx skills add basicmachines-co/basic-memory-skills --list @@ -102,6 +105,7 @@ All 9 skills are also bundled in the [`@basicmemory/openclaw-basic-memory`](http These skills work with any AI coding agent that supports the SKILL.md format: +- **GitHub Copilot CLI** — `npx skills add basicmachines-co/basic-memory-skills -a github-copilot` installs to `~/.copilot/skills/` - **Claude Desktop** — upload skill ZIPs via Settings > Capabilities - **Claude Code** — loads skills from `~/.claude/skills/` or `.claude/skills/` - **Cursor** — AI-powered coding with skill support diff --git a/memory-defrag/SKILL.md b/memory-defrag/SKILL.md index e079a67..0cc8248 100644 --- a/memory-defrag/SKILL.md +++ b/memory-defrag/SKILL.md @@ -35,17 +35,46 @@ Look for these common issues: | **Bloated file** | >300 lines, covers many topics | Split into focused files | | **Duplicate info** | Same fact in multiple places | Consolidate to one location | | **Stale entries** | References to completed work, old dates, resolved issues | Remove or archive | +| **Resolved error traces** | Debugging logs, failed-attempt history, closed-issue workarounds | Remove — context noise once resolved | | **Orphan files** | Files in memory/ never referenced or updated | Review, merge, or remove | | **Inconsistencies** | Contradictory information across files | Resolve to ground truth | | **Poor organization** | Related info scattered across files | Restructure by topic | | **Recursive nesting** | `memory/memory/memory/...` directories | Delete nested dirs (indexer bug artifact) | +### Resolved Error Traces + +Resolved error traces deserve special attention: +- Debugging step-by-step logs from incidents that are now closed +- "Tried X, failed because Y" histories where the issue is resolved +- Workaround instructions for bugs that have been fixed +- Error symptoms and their old diagnoses when the root cause is gone + +**Why they're harmful:** When retrieved as context, they look like current problems. A fresh agent reading "reconnect loop crashes the server — workaround: restart manually" doesn't know it was fixed last week. This creates false alerts and wastes context budget on phantom issues. + +**The rule:** Once an issue is resolved and the fix is documented or deployed, remove the error trace. If there's a lesson worth preserving, distill it to a `[lesson]` observation — one line, not a log. + +```python +# Before: three lines of stale error context +# - [issue] MCP server crashes on reconnect — repro: disconnect and reconnect rapidly +# - [workaround] Restart the MCP server manually after each disconnect +# - [status] investigating + +# After: one line of distilled lesson +edit_note( + identifier="MEMORY", + operation="find_replace", + find_text="- [issue] MCP server crashes on reconnect...\n- [workaround]...\n- [status] investigating", + content="- [lesson] MCP reconnect stability: fixed in v2.1.0 — upgrade if seeing crashes #mcp" +) +``` + ### 3. Plan Changes Before making edits, write a brief plan: ```markdown ## Defrag Plan - [ ] Split MEMORY.md "Key People" section → memory/people.md +- [ ] Remove resolved error traces from MEMORY.md - [ ] Remove completed tasks older than 30 days from memory/tasks/ - [ ] Merge memory/bm-marketing-ideas.md into memory/competitive/ - [ ] Update stale project status entries in MEMORY.md @@ -59,11 +88,12 @@ Apply changes one at a time: - **Prune**: Remove information that is no longer relevant or accurate - **Restructure**: Move files to appropriate directories, rename for clarity - **Update**: Fix outdated facts, dates, statuses +- **Strip error traces**: Remove resolved debugging history — leave only lessons ### 5. Verify & Log After changes: -- Verify no information was lost (compare before/after) +- Verify no valuable information was lost (compare before/after) - Update any cross-references between files - Log what was done in today's daily note: @@ -73,6 +103,7 @@ After changes: - Split: [list] - Merged: [list] - Pruned: [list] +- Error traces removed: [count] - Net result: X files, Y total lines (was Z lines) ``` @@ -82,5 +113,6 @@ After changes: - **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`. - **Don't over-organize.** One level of directories is usually enough. `memory/tasks/` and `memory/competitive/` are fine; `memory/work/projects/active/basic-memory/notes/` is not. -- **Completed tasks**: Tasks with `status: done` older than 14 days can be removed. Their insights should already be in MEMORY.md via reflection. +- **Completed tasks**: Tasks with `status: done` older than 14 days should be archived (not deleted). Their insights should already be in MEMORY.md via reflection. - **Ask before destructive changes.** If uncertain whether information is still relevant, keep it with a `(review needed)` tag rather than deleting. +- **Distill, don't just remove.** When pruning error traces or stale observations, ask if there's a one-line lesson worth keeping before deleting entirely. diff --git a/memory-metadata-search/SKILL.md b/memory-metadata-search/SKILL.md index f045600..4a907b6 100644 --- a/memory-metadata-search/SKILL.md +++ b/memory-metadata-search/SKILL.md @@ -182,3 +182,4 @@ search_notes("OAuth", metadata_filters={"status": "in-progress"}) - **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 shortcut is convenient but limited.** `tags` and `status` are sugar for common fields. For anything else, use `metadata_filters` directly. +- **Consistency enables filtering.** Metadata filters require consistent values across notes. If you use `status: active` sometimes and `status: in-progress` other times for the same concept, filters break. Use schemas to enforce consistency. diff --git a/memory-schema/SKILL.md b/memory-schema/SKILL.md index a47f326..aa57a19 100644 --- a/memory-schema/SKILL.md +++ b/memory-schema/SKILL.md @@ -172,7 +172,14 @@ schema_validate(noteType="Meeting") 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). +### Why Notes Need Fields in Both Frontmatter and Observations + +Basic Memory has two querying modes that access notes differently: + +- **`search_notes` with `metadata_filters`** — reads frontmatter. This is how you find notes by status, priority, etc. +- **`schema_validate`** — checks for fields as observation categories in the note body (e.g., `- [status] active`). + +A field stored only in frontmatter fails schema validation. A field stored only in observations can't be metadata-filtered. For fields you need both to query and to validate (like `status`, `current_step`), keep them in both places and keep them in sync. For fields only needed for one purpose, one location is fine. Validation reports: - **Missing required fields** — the note lacks a field the schema requires (as an observation category) diff --git a/memory-tasks/SKILL.md b/memory-tasks/SKILL.md index 3f44ed9..4e0c8a3 100644 --- a/memory-tasks/SKILL.md +++ b/memory-tasks/SKILL.md @@ -78,29 +78,46 @@ What future-you needs to pick up this work. Include: ) ``` -**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. +### Why Both Frontmatter and Observations? + +Frontmatter and observations serve different access patterns: + +- **Frontmatter** (`metadata`) → powers `search_notes` with `metadata_filters`. This is how agents find tasks by status, priority, etc. +- **Observations** (`- [status] active`) → powers `schema_validate`. This is how the schema system checks conformance. + +Keep `status` and `current_step` in both. For all other fields, pick the location that makes semantic sense and be consistent. Don't let the two diverge — if frontmatter says `status: done` but observations say `[status] active`, you have a split-brain state. ### 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 - **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. +- **`note_type` is case-sensitive** — `write_note(note_type="Task")` stores the type as lowercase `task` in frontmatter. Use `note_types=["task"]` (lowercase) in search queries. + +## Resume Protocol -## Resuming After Compaction +On session start or after compaction, follow this sequence: -On session start or after compaction: +``` +1. SEARCH → search_notes(note_types=["task"], status="active") +2. READ → read_note(identifier="") +3. VALIDATE → confirm current_step matches the step checkboxes +4. CONTINUE → execute the next unchecked step +``` -1. **Search for active tasks:** - ```python - search_notes(note_types=["task"], status="active") - ``` +Cross-check `current_step` against the checkbox list — the checkboxes are the ground truth. Context compaction can leave step counts stale. -2. **Read the task note** to get full context +```python +# Step 1: Find active work +search_notes(note_types=["task"], status="active") -3. **Resume from `current_step`** using the `context` field +# Step 2: Read the full task +read_note(identifier="tasks/my-active-task") -4. **Update as you progress** — increment `current_step`, update context, check off steps +# Step 3: Validate — last checked box matches current_step +# If current_step=3 but steps 1, 2, 3 are all checked → update current_step to 4 +# If steps 1, 2 are checked but current_step=3 → correct, continue with step 3 +``` ## Updating Tasks @@ -131,16 +148,36 @@ completed: YYYY-MM-DD Add a brief summary of what was accomplished and any follow-up needed. -## Pre-Compaction Flush +## Pause Protocol -When a compaction event is imminent: +Before any `/compact` event, end of session, or context-threatening operation: + +``` +1. FIND ALL → search_notes(note_types=["task"], status="active") +2. FOR EACH → update current_step, context, and step checkboxes +3. VERIFY → read_note to confirm the update landed correctly +``` + +What to write in `context` before pausing: +- What you just completed (1 sentence) +- What the next step requires (key inputs, file paths, decisions) +- Any blockers discovered +- Anything that would be frustrating to re-discover + +```python +edit_note( + identifier="tasks/my-active-task", + operation="find_replace", + find_text="## Context\nWhat future-you needs...", + content="""## Context +Completed: Implemented the database migration script at db/migrate/001.py. +Next: Run migration against staging. Need DATABASE_URL env var (check .env.staging). +Blocker: None. +Note: The migration is idempotent — safe to re-run if interrupted.""" +) +``` -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 - - Step checkboxes to show what's done -3. This is **critical** — context not written down is context lost +Context not written before `/compact` is context permanently lost. ## Querying Tasks @@ -159,7 +196,7 @@ With BM's schema system, tasks are fully queryable: ## Guidelines - **One task per unit of work** — Don't cram multiple projects into one task -- **Externalize early** — If you think "I should remember this", write it down NOW +- **Externalize early** — If you think "I should remember this", write it down NOW — not after the next tool call - **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 From 344af421721dcde7eefef1d4f2e4a9247c950d3a Mon Sep 17 00:00:00 2001 From: Tyler Raber Date: Mon, 20 Apr 2026 08:23:49 -0400 Subject: [PATCH 2/6] fix: address PR review comments - Clarify note_type is normalized to lowercase, not case-sensitive (memory-tasks) - Use --agent flag consistently instead of -a shorthand (README) - Update skill count from 9 to 10 to include memory-literary-analysis (README) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 6 +++--- memory-tasks/SKILL.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3253082..137ff9e 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks npx skills add basicmachines-co/basic-memory-skills --agent claude # Install for GitHub Copilot CLI -npx skills add basicmachines-co/basic-memory-skills -a github-copilot +npx skills add basicmachines-co/basic-memory-skills --agent github-copilot # List available skills without installing npx skills add basicmachines-co/basic-memory-skills --list @@ -99,13 +99,13 @@ cp -r memory-tasks / ### Bundled with OpenClaw plugin -All 9 skills are also bundled in the [`@basicmemory/openclaw-basic-memory`](https://github.com/basicmachines-co/openclaw-basic-memory) plugin — no extra install step needed if you use OpenClaw. +All 10 skills are also bundled in the [`@basicmemory/openclaw-basic-memory`](https://github.com/basicmachines-co/openclaw-basic-memory) plugin — no extra install step needed if you use OpenClaw. ## Compatible Agents These skills work with any AI coding agent that supports the SKILL.md format: -- **GitHub Copilot CLI** — `npx skills add basicmachines-co/basic-memory-skills -a github-copilot` installs to `~/.copilot/skills/` +- **GitHub Copilot CLI** — `npx skills add basicmachines-co/basic-memory-skills --agent github-copilot` installs to `~/.copilot/skills/` - **Claude Desktop** — upload skill ZIPs via Settings > Capabilities - **Claude Code** — loads skills from `~/.claude/skills/` or `.claude/skills/` - **Cursor** — AI-powered coding with skill support diff --git a/memory-tasks/SKILL.md b/memory-tasks/SKILL.md index 4e0c8a3..0b42eaa 100644 --- a/memory-tasks/SKILL.md +++ b/memory-tasks/SKILL.md @@ -92,7 +92,7 @@ Keep `status` and `current_step` in both. For all other fields, pick the locatio - **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 - **Relations link to other entities** — `parent_task [[Other Task]]`, `related_to [[Some Note]]` -- **`note_type` is case-sensitive** — `write_note(note_type="Task")` stores the type as lowercase `task` in frontmatter. Use `note_types=["task"]` (lowercase) in search queries. +- **`note_type` is normalized to lowercase** — `write_note(note_type="Task")` stores the type as lowercase `task` in frontmatter. Use lowercase values such as `note_types=["task"]` in search queries. ## Resume Protocol From 5c79b62d32711f4fb14cd8afea6cb4c54fc61ae2 Mon Sep 17 00:00:00 2001 From: Tyler Raber Date: Mon, 20 Apr 2026 08:35:26 -0400 Subject: [PATCH 3/6] fix: address second round of PR review comments - Clarify current_step semantics in Resume Protocol (memory-tasks) - Nuance frontmatter-only field validation behavior (memory-schema) - Use archive language instead of remove for completed tasks (memory-defrag) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- memory-defrag/SKILL.md | 2 +- memory-schema/SKILL.md | 2 +- memory-tasks/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/memory-defrag/SKILL.md b/memory-defrag/SKILL.md index 0cc8248..fe4ede1 100644 --- a/memory-defrag/SKILL.md +++ b/memory-defrag/SKILL.md @@ -75,7 +75,7 @@ Before making edits, write a brief plan: ## Defrag Plan - [ ] Split MEMORY.md "Key People" section → memory/people.md - [ ] Remove resolved error traces from MEMORY.md -- [ ] Remove completed tasks older than 30 days from memory/tasks/ +- [ ] Move completed tasks older than 30 days from memory/tasks/ to archive - [ ] Merge memory/bm-marketing-ideas.md into memory/competitive/ - [ ] Update stale project status entries in MEMORY.md ``` diff --git a/memory-schema/SKILL.md b/memory-schema/SKILL.md index aa57a19..67dfb49 100644 --- a/memory-schema/SKILL.md +++ b/memory-schema/SKILL.md @@ -179,7 +179,7 @@ Basic Memory has two querying modes that access notes differently: - **`search_notes` with `metadata_filters`** — reads frontmatter. This is how you find notes by status, priority, etc. - **`schema_validate`** — checks for fields as observation categories in the note body (e.g., `- [status] active`). -A field stored only in frontmatter fails schema validation. A field stored only in observations can't be metadata-filtered. For fields you need both to query and to validate (like `status`, `current_step`), keep them in both places and keep them in sync. For fields only needed for one purpose, one location is fine. +A field stored only in frontmatter is not checked by `schema_validate`. If that field is required by the schema, it must also appear as an observation category or validation will report it as missing. A field stored only in observations can't be metadata-filtered. For fields you need both to query and to validate (like `status`, `current_step`), keep them in both places and keep them in sync. For fields only needed for one purpose, one location is fine. Validation reports: - **Missing required fields** — the note lacks a field the schema requires (as an observation category) diff --git a/memory-tasks/SKILL.md b/memory-tasks/SKILL.md index 0b42eaa..4256626 100644 --- a/memory-tasks/SKILL.md +++ b/memory-tasks/SKILL.md @@ -114,7 +114,7 @@ search_notes(note_types=["task"], status="active") # Step 2: Read the full task read_note(identifier="tasks/my-active-task") -# Step 3: Validate — last checked box matches current_step +# Step 3: Validate — current_step is the next step to execute, so the last checked box should be current_step - 1 # If current_step=3 but steps 1, 2, 3 are all checked → update current_step to 4 # If steps 1, 2 are checked but current_step=3 → correct, continue with step 3 ``` From 5162bd1a221265593b7f6c4fe3e9dc637565f008 Mon Sep 17 00:00:00 2001 From: Tyler Raber Date: Mon, 20 Apr 2026 09:02:43 -0400 Subject: [PATCH 4/6] fix: address remaining PR #7 review comments and apply context engineering principles - Fix type casing: Task -> task for consistency with normalization (memory-tasks) - Fix stale section reference: Pre-compaction flush -> Pause protocol (memory-tasks) - Clarify schema-required fields must exist as observations (memory-tasks) - Update skill count from 9 to 10 in README tip - Add context engineering connections: context rot/distraction (memory-defrag), Select principle (memory-metadata-search), task note density (memory-tasks) - CE references link to tyler555g/best-practices context-engineering.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- memory-defrag/SKILL.md | 2 +- memory-metadata-search/SKILL.md | 2 +- memory-tasks/SKILL.md | 9 ++++++--- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 137ff9e..d89081a 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ Claude Desktop loads skills through **Settings > Capabilities**: Repeat for each skill you want. Custom uploaded skills are private to your account. -> **Tip:** Start with **memory-notes** (core note-writing patterns) and add others as needed. You don't need all 9 at once. +> **Tip:** Start with **memory-notes** (core note-writing patterns) and add others as needed. You don't need all 10 at once. See [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude) for more details. diff --git a/memory-defrag/SKILL.md b/memory-defrag/SKILL.md index fe4ede1..0fb8309 100644 --- a/memory-defrag/SKILL.md +++ b/memory-defrag/SKILL.md @@ -5,7 +5,7 @@ description: "Defragment and reorganize agent memory files: split bloated files, # Memory Defrag -Reorganize memory files for clarity, efficiency, and relevance. Like filesystem defragmentation but for knowledge. +Reorganize memory files for clarity, efficiency, and relevance. Defrag combats [context rot and context distraction](https://github.com/tyler555g/best-practices/blob/main/packages/content/technology_and_information/data_science_and_ai/context-engineering.md) — stale or noisy entries that degrade agent behavior when notes are retrieved. ## When to Run diff --git a/memory-metadata-search/SKILL.md b/memory-metadata-search/SKILL.md index 4a907b6..abb9d7e 100644 --- a/memory-metadata-search/SKILL.md +++ b/memory-metadata-search/SKILL.md @@ -175,7 +175,7 @@ search_notes("OAuth", metadata_filters={"status": "in-progress"}) ## Guidelines -- **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. +- **Precision retrieval over broad loading.** If you're looking for notes by a known field value (status, priority, type), metadata filters are more precise than text search. This aligns with the [Select principle](https://github.com/tyler555g/best-practices/blob/main/packages/content/technology_and_information/data_science_and_ai/context-engineering.md) — retrieve only what's needed for the current step. - **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. diff --git a/memory-tasks/SKILL.md b/memory-tasks/SKILL.md index 4256626..07529a4 100644 --- a/memory-tasks/SKILL.md +++ b/memory-tasks/SKILL.md @@ -5,13 +5,13 @@ description: "Task management via Basic Memory schemas: create, track, and resum # Memory Tasks -Manage work-in-progress using Basic Memory's schema system. Tasks are just notes with `type: Task` — they live in the knowledge graph, validate against a schema, and survive context compaction. +Manage work-in-progress using Basic Memory's schema system. Tasks are just notes with `type: task` — they live in the knowledge graph, validate against a schema, and survive context compaction. ## When to Use - **Starting multi-step work** (3+ steps, or anything that might outlast the context window) - **After compaction/restart** — search for active tasks to resume -- **Pre-compaction flush** — update all active tasks with current state +- **Pause protocol** — update all active tasks with current state before compaction - **On demand** — user asks to create, check, or manage tasks ## Task Schema @@ -85,7 +85,9 @@ Frontmatter and observations serve different access patterns: - **Frontmatter** (`metadata`) → powers `search_notes` with `metadata_filters`. This is how agents find tasks by status, priority, etc. - **Observations** (`- [status] active`) → powers `schema_validate`. This is how the schema system checks conformance. -Keep `status` and `current_step` in both. For all other fields, pick the location that makes semantic sense and be consistent. Don't let the two diverge — if frontmatter says `status: done` but observations say `[status] active`, you have a split-brain state. +Any schema-required fields must exist as observations, because `schema_validate` only recognizes required fields when they appear as observation categories. For Task notes, that includes `description` and any other non-optional schema fields. + +Duplicate only the subset of fields you want to metadata-filter (like `status` and `current_step`) into frontmatter, and keep those duplicated values in sync with the observations. Don't let the two diverge — if frontmatter says `status: done` but observations say `[status] active`, you have a split-brain state. ### Key Principles @@ -201,3 +203,4 @@ With BM's schema system, tasks are fully queryable: - **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 `schema_validate(noteType="Task")` periodically to catch incomplete tasks +- **Keep task notes dense** — Task notes compete for context window space. Every token should earn its place: concrete steps, essential context, no filler. Stale context in a task note is [context distraction](https://github.com/tyler555g/best-practices/blob/main/packages/content/technology_and_information/data_science_and_ai/context-engineering.md) — it dilutes signal when the task is retrieved From 918178982e3d1fc4048e839a55f920b2e30933a5 Mon Sep 17 00:00:00 2001 From: tyler555g Date: Mon, 20 Apr 2026 17:41:36 -0400 Subject: [PATCH 5/6] fix: use exact find_text strings in find_replace examples Replace ellipsis placeholders in edit_note find_replace examples with exact text that matches the corresponding before/template content shown earlier in each file. Ellipsis strings would fail to match real note content at runtime. - memory-tasks: match the Context header line from the Creating a Task template - memory-defrag: match the three error trace lines shown in the Before block Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- memory-defrag/SKILL.md | 2 +- memory-tasks/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/memory-defrag/SKILL.md b/memory-defrag/SKILL.md index 0fb8309..fdf34c7 100644 --- a/memory-defrag/SKILL.md +++ b/memory-defrag/SKILL.md @@ -63,7 +63,7 @@ Resolved error traces deserve special attention: edit_note( identifier="MEMORY", operation="find_replace", - find_text="- [issue] MCP server crashes on reconnect...\n- [workaround]...\n- [status] investigating", + find_text="- [issue] MCP server crashes on reconnect — repro: disconnect and reconnect rapidly\n- [workaround] Restart the MCP server manually after each disconnect\n- [status] investigating", content="- [lesson] MCP reconnect stability: fixed in v2.1.0 — upgrade if seeing crashes #mcp" ) ``` diff --git a/memory-tasks/SKILL.md b/memory-tasks/SKILL.md index 07529a4..e827ec9 100644 --- a/memory-tasks/SKILL.md +++ b/memory-tasks/SKILL.md @@ -170,7 +170,7 @@ What to write in `context` before pausing: edit_note( identifier="tasks/my-active-task", operation="find_replace", - find_text="## Context\nWhat future-you needs...", + find_text="## Context\nWhat future-you needs to pick up this work. Include:", content="""## Context Completed: Implemented the database migration script at db/migrate/001.py. Next: Run migration against staging. Need DATABASE_URL env var (check .env.staging). From dcf12df6f6d70789a564453c01152a4a2a55b986 Mon Sep 17 00:00:00 2001 From: tyler555g Date: Mon, 20 Apr 2026 20:01:46 -0400 Subject: [PATCH 6/6] fix: expand find_replace target to full Context block; fix grammar MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - memory-tasks: find_text now covers the full Context template block including all four bullet lines, so replacement doesn't leave the original scaffold behind - memory-defrag: fix grammar in orphan files table row ('never referenced' → 'that are never referenced') Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- memory-defrag/SKILL.md | 2 +- memory-tasks/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/memory-defrag/SKILL.md b/memory-defrag/SKILL.md index fdf34c7..9200c38 100644 --- a/memory-defrag/SKILL.md +++ b/memory-defrag/SKILL.md @@ -36,7 +36,7 @@ Look for these common issues: | **Duplicate info** | Same fact in multiple places | Consolidate to one location | | **Stale entries** | References to completed work, old dates, resolved issues | Remove or archive | | **Resolved error traces** | Debugging logs, failed-attempt history, closed-issue workarounds | Remove — context noise once resolved | -| **Orphan files** | Files in memory/ never referenced or updated | Review, merge, or remove | +| **Orphan files** | Files in memory/ that are never referenced or updated | Review, merge, or remove | | **Inconsistencies** | Contradictory information across files | Resolve to ground truth | | **Poor organization** | Related info scattered across files | Restructure by topic | | **Recursive nesting** | `memory/memory/memory/...` directories | Delete nested dirs (indexer bug artifact) | diff --git a/memory-tasks/SKILL.md b/memory-tasks/SKILL.md index e827ec9..f40e9d0 100644 --- a/memory-tasks/SKILL.md +++ b/memory-tasks/SKILL.md @@ -170,7 +170,7 @@ What to write in `context` before pausing: edit_note( identifier="tasks/my-active-task", operation="find_replace", - find_text="## Context\nWhat future-you needs to pick up this work. Include:", + find_text="## Context\nWhat future-you needs to pick up this work. Include:\n- Key file paths and repos involved\n- Decisions already made and why\n- What was tried and what worked/didn't\n- Where to look for related context", content="""## Context Completed: Implemented the database migration script at db/migrate/001.py. Next: Run migration against staging. Need DATABASE_URL env var (check .env.staging).